Cosmoose

A type-safe ODM for Azure Cosmos DB.
Define schemas, query with a fluent API, and sync containers automatically.

pnpm add @cosmoose/core

Quick start

import { Cosmoose, Schema, Type } from '@cosmoose/core';

// Connect
const cosmoose = new Cosmoose({
  endpoint: process.env.COSMOS_ENDPOINT!,
  key: process.env.COSMOS_KEY!,
  databaseName: 'my-app',
});
await cosmoose.connect();

// Define a schema
const userSchema = new Schema({
  name: { type: Type.STRING },
  email: { type: Type.EMAIL },
  age: { type: Type.NUMBER },
}, { timestamps: true, container: { partitionKey: '/email' } });

// Register a model & sync containers
const User = cosmoose.model('users', userSchema);
await cosmoose.syncContainers();

// Create a document
const user = await User.create({
  name: 'Alice',
  email: 'alice@example.com',
  age: 30,
});

Type-safe schemas

Define document shapes with rich field types and full TypeScript inference.

Fluent query builder

Filter, sort, paginate, and iterate with a chainable API.

Container sync

Auto-create and update Cosmos DB containers from your schemas.

Batch operations

Bulk create and upsert with automatic retry support.

Patch operators

$set, $incr, $unset, $add for efficient partial updates.

UUID v7 IDs

Sortable, unique identifiers generated automatically.