{"id":42548,"library":"cosmox","title":"Cosmox","description":"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.","status":"active","version":"1.0.4","language":"javascript","source_language":"en","source_url":"https://github.com/Mingyang-Li/cosmox","tags":["javascript","cosmosdb","prisma","orm","sdk","nosql","typescript"],"install":[{"cmd":"npm install cosmox","lang":"bash","label":"npm"},{"cmd":"yarn add cosmox","lang":"bash","label":"yarn"},{"cmd":"pnpm add cosmox","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency: Cosmox builds on the official Azure CosmosDB SDK for connection and query execution.","package":"@azure/cosmos","optional":false}],"imports":[{"note":"ESM-only package. Do not use require().","wrong":"const { createClient } = require('cosmox')","symbol":"createClient","correct":"import { createClient } from 'cosmox'"},{"note":"The type is exported as a type, not a value. Use type import for TypeScript.","wrong":"import { CosmoxClient } from 'cosmox'","symbol":"CosmoxClient","correct":"import type { CosmoxClient } from 'cosmox'"},{"note":"There is no default export; only named exports are available.","wrong":"","symbol":"default","correct":"import cosmox from 'cosmox'"}],"quickstart":{"code":"import { createClient } from 'cosmox';\n\ntype User = {\n  id: string;\n  firstName: string;\n  lastName: string;\n  age: number;\n  createdAt: Date;\n  isSuperAdmin: boolean;\n};\n\ntype Post = {\n  id: string;\n  title: string;\n  content: string;\n  createdBy: string;\n};\n\nconst orm = createClient({\n  database: 'MyDatabase',\n  connectionString: process.env.COSMOS_CONNECTION_STRING ?? '',\n  models: (t) => ({\n    user: t.createModel<User>({ container: 'Users' }),\n    post: t.createModel<Post>({ container: 'Posts' }),\n  }),\n});\n\nasync function main() {\n  const users = await orm.user.findMany({\n    where: { age: { gte: 18 } },\n    select: { id: true, firstName: true, age: true },\n    orderBy: { createdAt: 'desc' },\n    take: 10,\n  });\n  console.log(users);\n}\n\nmain().catch(console.error);","lang":"typescript","description":"Shows how to define types, initialize a Cosmox client with two models, and query users with filters, field selection, sorting, and pagination."},"warnings":[{"fix":"Run: npm install @azure/cosmos@latest","message":"cosmox requires @azure/cosmos v3 or later as a peer dependency. Older versions cause runtime errors.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Provide only connectionString or only endpoint and key in the options.","message":"The createClient function expects either connectionString or endpoint+key, not both. Passing both may lead to ambiguous behavior.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Upgrade to v1.0.3+ and use t.createModel inside the models callback.","message":"t.createModel was added in v1.0.3. In v1.0.0-1.0.2, the models configuration used a different (now removed) approach.","severity":"deprecated","affected_versions":">=1.0.0 <1.0.3"},{"fix":"Use import syntax or dynamic import(). If using Node.js, set \"type\": \"module\" in package.json.","message":"The package is ESM-only. Using require() (CommonJS) results in a runtime error: ERR_REQUIRE_ESM.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'1.0.4':14 'abstract':61 'activ':16 'api':26 'automat':59 'azur':7 'azure/cosmos':28,66 'built':31 'built-in':30 'cosmosdb':8,48,68 'cosmox':1 'develop':17 'differenti':43 'elimin':44 'enforc':49 'field':37 'filter':36 'fluent':25 'generat':56 'github':19 'input':41 'inspir':10 'javascript':67 'lightweight':60 'like':24 'nosql':9,72 'optim':57 'orm':5,70 'pagin':39 'prisma':12,23,69 'prisma-lik':22 'provid':20 'queri':53,58 'raw':45 'replac':64 'safe':4,35 'sdk':71 'select':38 'sql':46 'stabl':15 'time':54 'type':3,34,51 'type-saf':2,33 'typescript':50,73 'valid':42 'version':13","created_at":"2026-06-05T16:55:30.698213+00:00","updated_at":"2026-06-05T16:55:30.698213+00:00","problems":[{"fix":"Run: npm install @azure/cosmos","cause":"@azure/cosmos is a peer dependency that must be installed separately.","error":"Cannot find module '@azure/cosmos'"},{"fix":"Switch to import syntax or use dynamic import(). Ensure your project is configured for ESM.","cause":"Attempting to require() an ESM-only package.","error":"ERR_REQUIRE_ESM"},{"fix":"Use: import { createClient } from 'cosmox'","cause":"Importing incorrectly: maybe using default import when only named export exists.","error":"TypeError: cosmox.createClient is not a function"},{"fix":"Upgrade to cosmox v1.0.3 or later.","cause":"Using an older version of cosmox (<1.0.3) that does not have createModel.","error":"Property 'createModel' does not exist on type '...'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/Mingyang-Li/cosmox#readme","github":"https://github.com/Mingyang-Li/cosmox","docs":null,"changelog":null,"pypi":null,"npm":"cosmox","openapi_spec":null,"status_page":null,"smithery":null,"categories":["database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-05","next_check":"2026-09-03","install_tag":null}}