cosmos-orm

library0.4.0jsnpmunverified

A TypeScript ORM for Azure Cosmos DB, version 0.4.0. Provides a Lucid-inspired API (all, find, findMany, query) for Cosmos DB NoSQL, with automatic ID generation and timestamps. Requires @azure/cosmos ^4.2.0 and Azure Functions extension bundle [4.0.0,5.0.0). Ships types. Active development.

database

npm install cosmos-orm

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · COSMOS-ORM

cosmos-orm

databasejavascriptv0.4.0

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 'cosmos-orm'

✗ const createClient = require('cosmos-orm')

ESM-only package; CommonJS require will fail.

orm

✓ const orm = createClient({...})

✗ const orm = new createClient({...})

createClient is a factory function, not a class constructor.

Query types (parameters)

✓ interface Query { query: string; parameters?: {name: string; value: any}[] }

✗ const query = { query: '...', params: [...] }

Use 'parameters' not 'params' for named parameters.

Creates a Cosmos DB client with typed models for user and post containers, queries all posts and finds a user by ID.

import { createClient } from 'cosmos-orm'; interface Post { title: string; author: string; slug: string; } const orm = createClient({ connectionStringSetting: 'COSMOS_CONNECTION_STRING', database: 'my-db', models: (t) => ({ user: t.createModel<{ name: string; email: string }>('users'), post: t.createModel<Post>('posts', { fields: { id: true, timestamp: false } }) }) }); async function main() { const user = await orm.user.find('abc123'); const posts = await orm.post.all(); const sortedPosts = await orm.post.query('SELECT * FROM P ORDER BY P.title ASC'); console.log(user, posts, sortedPosts); } main();

Debug

Known issues

breakingRequires Azure Functions extension bundle version [4.0.0, 5.0.0). Using a different bundle version will cause runtime errors.

fix

Set extensionBundle version in host.json to "[4.0.0, 5.0.0)".

affects: 0.4.0

gotchacreateClient does not immediately establish a connection; it constructs models lazily. Connection errors occur only on first query.

fix

Ensure COSMOS_CONNECTION_STRING env is set and database exists before calling model methods.

affects: >=0.4.0

gotchaThe default ID generation uses ULID via ulidx, which may cause ordering issues if you rely on timestamp-based sorting.

fix

Disable auto-generated IDs by setting fields: { id: false } in createModel options if you want to provide custom IDs.

affects: >=0.4.0

deprecatedThe query method with string parameter may change in future versions to require an object with query and optional parameters.

fix

Use object syntax: query({ query: '...', parameters: [] }) for forward compatibility.

affects: 0.4.0

Errors

Common errors & fixes

Cannot find module 'cosmos-orm'

Package not installed or import path incorrect.

fix

Run npm install cosmos-orm and ensure import matches: import { createClient } from 'cosmos-orm'

TypeError: createClient is not a function

CommonJS require used instead of ESM import.

fix

Switch to ES module syntax: import { createClient } from 'cosmos-orm'

Property 'parameters' does not exist on type '{ query: string; params: any[] }'

Using 'params' instead of 'parameters' in query object.

fix

Use { query: '...', parameters: [...] }

Upgrade

Version history

0.4.0latest on npm

Audit

Dependencies

@azure/cosmosrequiredPeer dependency: Cosmos DB SDK for database operations

@azure/functionsrequiredPeer dependency: required for Azure Functions bindings support

ulidxrequiredPeer dependency: used for generating unique IDs

Agent activity

8 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/wind-apps/cosmos-orm ↗

packagecosmos-orm ↗

homepagehttps://github.com/wind-apps/cosmos-orm#readme ↗