Cosmos DB

Lightweight, dependency-free fake of Azure Cosmos DB that speaks the real Cosmos DB SQL (Core) REST API, so application code using the @azure/cosmos client can run against it with zero cost and zero side effects.

Quick Start

Start the server:

import { CosmosdbServer } from "./services/cosmosdb/src/server.js";

const server = new CosmosdbServer(4591);
await server.start();
// ... use it ...
await server.stop();

Connect with the real Cosmos DB client. The fake never validates the authorization header, so any key works — the well-known Cosmos emulator key is convenient. Disable endpoint discovery so all traffic is routed to the single parlel endpoint.

import { CosmosClient } from "@azure/cosmos";

const client = new CosmosClient({
  endpoint: "http://127.0.0.1:4591/",
  key: "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==",
  // Single-region fake: skip multi-region endpoint discovery.
  connectionPolicy: { enableEndpointDiscovery: false },
});

// Create a database + container
const { database } = await client.databases.createIfNotExists({ id: "appdb" });
const { container } = await database.containers.createIfNotExists({
  id: "users",
  partitionKey: { paths: ["/pk"] },
});

// Write
await container.items.create({ id: "alice", pk: "tenant-1", name: "Alice", age: 30 });

// Read (id + partition key)
const { resource } = await container.item("alice", "tenant-1").read();
console.log(resource.name); // "Alice"

// Query (cross-partition by default)
const { resources } = await container.items
  .query("SELECT * FROM c WHERE c.age >= 18 ORDER BY c.age DESC")
  .fetchAll();

// Parameterized query
const { resources: bobs } = await container.items
  .query({
    query: "SELECT * FROM c WHERE c.name = @name",
    parameters: [{ name: "@name", value: "Bob" }],
  })
  .fetchAll();

// Patch
await container.item("alice", "tenant-1").patch([{ op: "incr", path: "/age", value: 1 }]);

Reset all state between tests:

await fetch("http://127.0.0.1:4591/_parlel/reset", { method: "POST" });

Environment variables

The manifest exposes:

Implemented operations

All paths are resource-link addressed exactly like the real service.

Database account

• GET / — database account (consistency policy, read/write locations, query engine config). Powers client.getDatabaseAccount(), getReadEndpoints(), getWriteEndpoints().

Databases (client.databases / client.database(id))

• create, createIfNotExists
• read, delete
• readAll (list), query
• readOffer (database-level shared throughput)

Containers (database.containers / database.container(id))

• create, createIfNotExists
• read, replace, delete
• readAll (list), query
• readOffer, getFeedRanges / readPartitionKeyRanges
• deleteAllItemsForPartitionKey

Items (container.items / container.item(id, pk))

• create, upsert
• read, replace, delete, patch
• readAll (list)
• query (with query-plan negotiation, partition-key range routing, paging)
• changeFeed (incremental, partition-scoped, continuation-aware)
• batch (transactional batch, atomic with rollback)
• bulk (grouped per-partition operations)

Query language (subset)

• SELECT *, SELECT VALUE expr, SELECT a, b [AS alias]
• WHERE with AND / OR / NOT, comparisons (= != <> < > <= >=), IN (...)
• ORDER BY expr [ASC|DESC] (multi-column)
• TOP n, OFFSET n LIMIT m, DISTINCT
• Aggregates: COUNT, SUM, AVG, MIN, MAX
• Built-in functions: CONTAINS, STARTSWITH, ENDSWITH, UPPER, LOWER, LENGTH/STRLEN, CONCAT, ABS, FLOOR, CEILING, ROUND, IS_DEFINED, IS_NULL, IS_STRING, IS_NUMBER, IS_BOOL, IS_ARRAY, IS_OBJECT, ARRAY_CONTAINS, ARRAY_LENGTH, TOSTRING
• Parameterized queries (@param)

Stored procedures / triggers / UDFs (container.scripts)

• StoredProcedures: create, read, replace, delete, readAll, query, execute (a constrained JS runtime provides getContext(), getResponse().setBody(), and a getCollection() shim supporting createDocument / replaceDocument / queryDocuments)
• Triggers: create, read, replace, delete, readAll, query
• UserDefinedFunctions: create, read, replace, delete, readAll, query

Users & permissions (database.users / database.user(id))

• Users: create, upsert, read, replace, delete, readAll, query
• Permissions: create, upsert, read, replace, delete, readAll, query (returns a synthetic _token resource token)

Offers / throughput (client.offers / client.offer(id))

• readAll, query (by resource link)
• read, replace (change provisioned throughput)

Conflicts (container.conflicts)

• readAll, query, single read, delete (empty by default — the fake has no multi-master replication, so conflicts never arise organically)

Control plane (parlel-only)

• GET /_parlel/health — { status, service, databases }
• POST /_parlel/reset — wipe all state

Surface coverage

This emulator faithfully replicates the API surface most application code and agents exercise. Anything below the supported lines is either an intentional design choice for a fast, zero-cost local emulator (✓ By design) or a candidate for a future release (⟳ Roadmap) — never a silent inaccuracy.

Legend: ✅ fully supported · ◐ accepted (stored, not strictly enforced) · ✓ by design · ⟳ on the roadmap.

Error codes & shapes

Errors are returned as JSON { "code": "<string>", "message": "<string>" } with the matching HTTP status and Cosmos headers (x-ms-activity-id, x-ms-request-charge, x-ms-session-token, and x-ms-substatus where relevant). The @azure/cosmos client surfaces error.code as the HTTP status number.

Per-operation batch/bulk results carry { statusCode, requestCharge, resourceBody?, eTag? }. A failed atomic batch returns each subsequent operation as 424 (Failed Dependency) and rolls back all applied mutations.

Configuration — test.env

Copy these into your test.env (used by the bridge sidecar flow). Tokens are Parlel's seeded test credentials — any non-empty value is accepted by the emulator, so you rarely need to change them. Swap in real credentials only when pointing at the live service in prod.env.

COSMOS_ENDPOINT=http://parlel-bridge:4591/
COSMOS_KEY=C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==
COSMOS_CONNECTION_STRING=AccountEndpoint=http://127.0.0.1:4591/;AccountKey=C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==;