cosmox

library1.0.4jsnpmunverified

Type-safe ORM for Azure CosmosDB NoSQL, inspired by Prisma. Version 1.0.4 (stable). Active development on GitHub. Provides a Prisma-like, fluent API over @azure/cosmos with built-in type-safe filtering, field selection, pagination, and input validation. Differentiator: eliminates raw SQL for CosmosDB, enforces TypeScript types at query time, and generates optimized queries automatically. Lightweight abstraction — not a replacement for @azure/cosmos.

database

npm install cosmox

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · COSMOX

cosmox

databasejavascriptv1.0.4

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

createClient

✓ import { createClient } from 'cosmox'

✗ const { createClient } = require('cosmox')

ESM-only package. Do not use require().

CosmoxClient

✓ import type { CosmoxClient } from 'cosmox'

✗ import { CosmoxClient } from 'cosmox'

The type is exported as a type, not a value. Use type import for TypeScript.

default

✓ import cosmox from 'cosmox'

There is no default export; only named exports are available.

Shows how to define types, initialize a Cosmox client with two models, and query users with filters, field selection, sorting, and pagination.

import { createClient } from 'cosmox'; type User = { id: string; firstName: string; lastName: string; age: number; createdAt: Date; isSuperAdmin: boolean; }; type Post = { id: string; title: string; content: string; createdBy: string; }; const orm = createClient({ database: 'MyDatabase', connectionString: process.env.COSMOS_CONNECTION_STRING ?? '', models: (t) => ({ user: t.createModel<User>({ container: 'Users' }), post: t.createModel<Post>({ container: 'Posts' }), }), }); async function main() { const users = await orm.user.findMany({ where: { age: { gte: 18 } }, select: { id: true, firstName: true, age: true }, orderBy: { createdAt: 'desc' }, take: 10, }); console.log(users); } main().catch(console.error);

Debug

Known issues

breakingcosmox requires @azure/cosmos v3 or later as a peer dependency. Older versions cause runtime errors.

fix

Run: npm install @azure/cosmos@latest

affects: >=1.0.0

gotchaThe createClient function expects either connectionString or endpoint+key, not both. Passing both may lead to ambiguous behavior.

fix

Provide only connectionString or only endpoint and key in the options.

affects: >=1.0.0

deprecatedt.createModel was added in v1.0.3. In v1.0.0-1.0.2, the models configuration used a different (now removed) approach.

fix

Upgrade to v1.0.3+ and use t.createModel inside the models callback.

affects: >=1.0.0 <1.0.3

gotchaThe package is ESM-only. Using require() (CommonJS) results in a runtime error: ERR_REQUIRE_ESM.

fix

Use import syntax or dynamic import(). If using Node.js, set "type": "module" in package.json.

affects: >=1.0.0

Errors

Common errors & fixes

Cannot find module '@azure/cosmos'

@azure/cosmos is a peer dependency that must be installed separately.

fix

Run: npm install @azure/cosmos

ERR_REQUIRE_ESM

Attempting to require() an ESM-only package.

fix

Switch to import syntax or use dynamic import(). Ensure your project is configured for ESM.

TypeError: cosmox.createClient is not a function

Importing incorrectly: maybe using default import when only named export exists.

fix

Use: import { createClient } from 'cosmox'

Property 'createModel' does not exist on type '...'

Using an older version of cosmox (<1.0.3) that does not have createModel.

fix

Upgrade to cosmox v1.0.3 or later.

Upgrade

Version history

1.0.4latest on npm

Audit

Dependencies

@azure/cosmosrequiredPeer dependency: Cosmox builds on the official Azure CosmosDB SDK for connection and query execution.

Agent activity

11 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/Mingyang-Li/cosmox ↗

packagecosmox ↗

homepagehttps://github.com/Mingyang-Li/cosmox#readme ↗