CosmosQL

Type-safe, zero-dependency client for Azure Cosmos DB. Partition keys are enforced by the type checker, so the expensive query never ships.

npm install cosmosql

import { createClient, container, field } from "cosmosql";

const users = container("users", {
  id: field.string(),
  email: field.string(),
  name: field.string(),
}).partitionKey("email");

const db = await createClient({
  connectionString: process.env.COSMOS_CONNECTION_STRING!,
  database: "myapp",
}).withContainers({ users });

const user = await db.users.findUnique({
  where: { id: "user_123", email: "ada@example.com" },
});

Documentation · Package README · Changelog

Repository

Path	Contents
packages/cosmosql	The library published to npm as cosmosql
apps/docs	cosmosql.dev, built with Next.js and Fumadocs

Development

Requires Bun 1.2 or newer. Running the Vitest tests also requires Node.js 22.12 or newer.

bun install          # install every workspace
bun run dev          # docs site on http://localhost:3000
bun run test         # library unit tests
bun run type-check   # type-check every workspace
bun run build        # build every workspace
bun run lint         # Biome across the repo

Run a script in one workspace with bun run --filter <name> <script>, for example bun run --filter cosmosql test:integration.

Releasing

Publishing a GitHub release publishes packages/cosmosql to npm with provenance.

License

MIT