zydecodb 0.9.0-beta.2

package/README.md

@@ -0,0 +1,100 @@
+# ZydecoDB TypeScript / Node driver
+
+Official TypeScript/Node client for [ZydecoDB](../../README.md) — a MongoDB-style
+document store without the fluff. Built on Node's standard library (`node:net`),
+no runtime dependencies.
+
+## Install
+
+```bash
+npm install zydecodb
+```
+
+Requires Node.js 20+. (Working from a checkout of this repo:
+`npm install file:clients/typescript`.)
+
+## Quick start
+
+```ts
+import { Client } from "zydecodb";
+
+// Plain TCP (localhost). For TLS: { apiKey: "YOUR_KEY", tls: true }
+const db = new Client("127.0.0.1:9470", { apiKey: "YOUR_KEY" });
+try {
+  const users = db.collection("users");
+  await users.createIndex(["email"], true);
+
+  const id = await users.insertOne({ email: "ada@example.com", name: "Ada", age: 30 });
+
+  const adults = await users.find({ age: { $gte: 18 } }, { sort: [{ field: "age", ascending: true }] });
+  for (const u of adults) console.log(u.name, u.age);
+
+  await users.updateOne({ _id: id }, { $inc: { age: 1 } });
+  console.log(await users.countDocuments());
+} finally {
+  db.close();
+}
+```
+
+## What you get
+
+- **Connection pooling.** `Client` owns a bounded pool (`poolSize`, default 8)
+  and is safe to share across the whole process.
+- **Automatic retries with backoff.** Transient transport failures and server
+  `EngineBusy` responses are retried (full-jitter exponential backoff) for
+  operations that are safe to repeat. Operator updates and deletes are never
+  retried automatically.
+- **Keepalive.** Idle pooled connections are validated with a `ping` on
+  checkout and transparently replaced if dead.
+- **Typed error taxonomy.** Non-OK responses throw a specific subclass:
+  `ConflictError` (unique-index violation), `AuthError`, `ServerBusyError`,
+  `InvalidRequestError`, or the base `ServerError` — each carrying the wire
+  `status` byte. Transport problems throw `ConnectionError`.
+- **MongoDB-style `Collection` API.** `insertOne/Many`, `find`/`findOne`,
+  `updateOne/Many`, `deleteOne/Many`, `countDocuments`, `distinct`, and
+  `createIndex`, with `$`-operators, sort, projection, and skip/limit.
+  Pagination is repeatable-read across pages.
+- **Raw KV with TTL.** Side-channel `put` (with `expiresAt`), `get`, and `delete` methods on `Client` for session data that needs a time-to-live.
+- **TLS.** Pass `tls: true` for system CA defaults, or a `tls.ConnectionOptions`
+  object for custom roots / SNI / `rejectUnauthorized`.
+
+## Durability
+
+Writes are durable (fsync-on-commit) by default. For latency-sensitive,
+loss-tolerant writes, pass `relaxed = true` on any write to acknowledge before
+the fsync.
+
+```ts
+await users.insertOne(doc, true);
+await users.updateOne({ _id: "ada" }, { $inc: { hits: 1 } }, true);
+```
+
+## Examples
+
+- [`examples/quickstart.ts`](examples/quickstart.ts) — end-to-end collection demo.
+- [`examples/user_backend.ts`](examples/user_backend.ts) — a small `node:http`
+  users API sharing one pooled client across concurrent requests.
+
+With Node 22.18+ you can run the TypeScript directly:
+
+```bash
+node examples/quickstart.ts
+node examples/user_backend.ts
+```
+
+Both read `ZYDECODB_ADDR` (default `127.0.0.1:9470`) and `ZYDECODB_API_KEY`.
+
+## Development
+
+```bash
+npm install        # dev deps: typescript, @types/node
+npm run typecheck  # tsc --noEmit
+npm run build      # emit dist/ (ESM + .d.ts)
+npm test           # node --test (native type stripping; no transpiler)
+```
+
+The codec is verified byte-for-byte against the shared
+[conformance vectors](../conformance) — no server required. The live
+integration tests run against a server selected by `ZYDECODB_TEST_HOST` /
+`ZYDECODB_TEST_PORT` (and optional `ZYDECODB_TEST_API_KEY`) and are skipped when
+it is unreachable.

package/dist/client.d.ts

@@ -0,0 +1,62 @@
+import { Collection } from "./collection.ts";
+import { type Projection, type SortKey } from "./protocol.ts";
+export interface ClientOptions {
+    apiKey?: string;
+    /** Per-request I/O timeout in ms (default 5000). */
+    timeoutMs?: number;
+    /** Maximum pooled connections (default 8). */
+    poolSize?: number;
+    /** Retries for idempotent operations on transient failures (default 2). */
+    maxRetries?: number;
+    backoffBaseMs?: number;
+    backoffCapMs?: number;
+}
+export interface FindOptions {
+    sort?: SortKey[];
+    projection?: Projection;
+    skip?: number;
+    limit?: number;
+    pageSize?: number;
+}
+export interface UpdateResult {
+    matched: number;
+    modified: number;
+}
+/**
+ * A pooled, retrying ZydecoDB client. Safe to share across the whole process.
+ * Transient transport failures and server EngineBusy responses are retried with
+ * full-jitter exponential backoff for operations that are safe to repeat;
+ * operator updates and deletes are never retried automatically.
+ */
+export declare class Client {
+    private readonly pool;
+    private readonly maxRetries;
+    private readonly backoffBaseMs;
+    private readonly backoffCapMs;
+    constructor(address?: string, options?: ClientOptions);
+    close(): void;
+    private backoff;
+    private execute;
+    ping(): Promise<void>;
+    stats(): Promise<Record<string, unknown>>;
+    get(key: Buffer): Promise<Buffer | null>;
+    put(key: Buffer, value: Buffer, expiresAt?: number | bigint): Promise<bigint>;
+    delete(key: Buffer): Promise<boolean>;
+    defineIndex(collection: string, index: string, fields: string[], unique: boolean, ifNotExists?: boolean): Promise<boolean>;
+    putDocument(collection: string, docId: string, body: Buffer, relaxed: boolean): Promise<bigint>;
+    deleteDocument(collection: string, docId: string): Promise<boolean>;
+    getDocument(collection: string, docId: string): Promise<Buffer | null>;
+    /** Returns the raw JSON bodies of matching documents, auto-paginating. */
+    find(collection: string, filter: Buffer, opts?: FindOptions): Promise<Buffer[]>;
+    update(collection: string, filter: Buffer, update: Buffer, multi: boolean, relaxed: boolean): Promise<UpdateResult>;
+    deleteByFilter(collection: string, filter: Buffer, multi: boolean, relaxed: boolean): Promise<number>;
+    count(collection: string, filter: Buffer): Promise<number>;
+    distinct(collection: string, field: string, filter: Buffer): Promise<unknown[]>;
+    collection(name: string): Collection;
+}
+/**
+ * A time-ordered id (UUIDv7-style): a 48-bit millisecond timestamp followed by
+ * 80 random bits, hex-encoded. Sorts lexicographically by creation time.
+ */
+export declare function generateId(): string;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/client.js

@@ -0,0 +1,202 @@
+import { randomBytes } from "node:crypto";
+import { Collection } from "./collection.js";
+import { ConnectionError, fromStatus, ServerBusyError, ZydecoError } from "./errors.js";
+import { ConnectionPool } from "./pool.js";
+import { Cmd, decodePage, encodeCount, encodeDelete, encodeDistinct, encodeDocDel, encodeDocPut, encodeFind, encodeIndexDef, encodeQueryById, encodeUpdate, encodePut, encodeKey, Proj, Status, } from "./protocol.js";
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * A pooled, retrying ZydecoDB client. Safe to share across the whole process.
+ * Transient transport failures and server EngineBusy responses are retried with
+ * full-jitter exponential backoff for operations that are safe to repeat;
+ * operator updates and deletes are never retried automatically.
+ */
+export class Client {
+    pool;
+    maxRetries;
+    backoffBaseMs;
+    backoffCapMs;
+    constructor(address = "127.0.0.1:9470", options = {}) {
+        const { host, port } = parseAddress(address);
+        this.pool = new ConnectionPool({
+            host,
+            port,
+            apiKey: options.apiKey ?? null,
+            timeoutMs: options.timeoutMs ?? 5000,
+            maxSize: options.poolSize ?? 8,
+        });
+        this.maxRetries = Math.max(0, options.maxRetries ?? 2);
+        this.backoffBaseMs = options.backoffBaseMs ?? 50;
+        this.backoffCapMs = options.backoffCapMs ?? 2000;
+    }
+    close() {
+        this.pool.close();
+    }
+    backoff(attempt) {
+        const ceiling = Math.min(this.backoffCapMs, this.backoffBaseMs * 2 ** attempt);
+        return Math.random() * ceiling;
+    }
+    async execute(command, payload, op, eo) {
+        let lastErr = null;
+        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+            const conn = await this.pool.acquire();
+            let res;
+            try {
+                res = await conn.request(command, payload);
+            }
+            catch (err) {
+                this.pool.discard(conn);
+                lastErr = err;
+                if (eo.retryable && attempt < this.maxRetries) {
+                    await sleep(this.backoff(attempt));
+                    continue;
+                }
+                throw err;
+            }
+            this.pool.release(conn);
+            if (res.status === Status.Ok)
+                return res.body;
+            if (eo.notFoundNull && res.status === Status.NotFound)
+                return null;
+            if (res.status === Status.EngineBusy && eo.retryable && attempt < this.maxRetries) {
+                console.warn(`[Client] EngineBusy on ${op}, attempt ${attempt}`);
+                lastErr = new ServerBusyError(op, res.status, "");
+                await sleep(this.backoff(attempt));
+                continue;
+            }
+            throw fromStatus(res.status, op, res.body);
+        }
+        throw lastErr ?? new ZydecoError(`${op}: retries exhausted`);
+    }
+    // --- health / introspection ---
+    async ping() {
+        await this.execute(Cmd.Ping, Buffer.alloc(0), "Ping", { retryable: true });
+    }
+    async stats() {
+        const body = await this.execute(Cmd.Stats, Buffer.alloc(0), "Stats", { retryable: true });
+        return JSON.parse(body.toString("utf8"));
+    }
+    // --- document layer (raw bytes; Collection adds JSON ergonomics) ---
+    async get(key) {
+        return this.execute(Cmd.Get, encodeKey(key), "Get", { retryable: true, notFoundNull: true });
+    }
+    async put(key, value, expiresAt = 0) {
+        const out = await this.execute(Cmd.Put, encodePut(key, value, expiresAt), "Put", { retryable: true });
+        return decodeU64(out, "Put");
+    }
+    async delete(key) {
+        const out = await this.execute(Cmd.Del, encodeKey(key), "Delete", { retryable: false });
+        return out !== null && out.length > 0 && out[0] !== 0;
+    }
+    async defineIndex(collection, index, fields, unique, ifNotExists = true) {
+        const payload = encodeIndexDef(collection, index, fields, unique);
+        const conn = await this.pool.acquire();
+        let res;
+        try {
+            res = await conn.request(Cmd.IndexDef, payload);
+        }
+        catch (err) {
+            this.pool.discard(conn);
+            throw err;
+        }
+        this.pool.release(conn);
+        if (ifNotExists && res.status === Status.Conflict)
+            return false;
+        if (res.status !== Status.Ok)
+            throw fromStatus(res.status, "IndexDef", res.body);
+        return true;
+    }
+    async putDocument(collection, docId, body, relaxed) {
+        const out = await this.execute(Cmd.DocPut, encodeDocPut(collection, Buffer.from(docId, "utf8"), body, relaxed), "DocPut", { retryable: true });
+        return decodeU64(out, "DocPut");
+    }
+    async deleteDocument(collection, docId) {
+        const out = await this.execute(Cmd.DocDel, encodeDocDel(collection, Buffer.from(docId, "utf8")), "DocDel", { retryable: false });
+        return out !== null && out.length > 0 && out[0] !== 0;
+    }
+    async getDocument(collection, docId) {
+        return this.execute(Cmd.Query, encodeQueryById(collection, Buffer.from(docId, "utf8")), "Query", { retryable: true, notFoundNull: true });
+    }
+    /** Returns the raw JSON bodies of matching documents, auto-paginating. */
+    async find(collection, filter, opts = {}) {
+        const pageSize = opts.pageSize && opts.pageSize > 0 ? opts.pageSize : 100;
+        const limit = opts.limit ?? 0;
+        const projection = opts.projection ?? { mode: Proj.None, fields: [] };
+        const sort = opts.sort ?? [];
+        let skip = opts.skip ?? 0;
+        let cursor = Buffer.alloc(0);
+        let yielded = 0;
+        const results = [];
+        for (;;) {
+            let want = pageSize;
+            if (limit !== 0) {
+                const remaining = limit - yielded;
+                if (remaining <= 0)
+                    return results;
+                want = Math.min(want, remaining);
+            }
+            const payload = encodeFind(collection, filter, sort, projection, skip, want, cursor);
+            const body = await this.execute(Cmd.Find, payload, "Find", { retryable: true });
+            const page = decodePage(body);
+            skip = 0; // applied on the first page; the cursor carries it onward
+            for (const row of page.rows) {
+                results.push(row.body);
+                yielded++;
+                if (limit !== 0 && yielded >= limit)
+                    return results;
+            }
+            if (page.cursor === null)
+                return results;
+            cursor = page.cursor;
+        }
+    }
+    async update(collection, filter, update, multi, relaxed) {
+        const body = await this.execute(Cmd.Update, encodeUpdate(collection, filter, update, multi, relaxed), "Update", { retryable: false });
+        return JSON.parse(body.toString("utf8"));
+    }
+    async deleteByFilter(collection, filter, multi, relaxed) {
+        const body = await this.execute(Cmd.Delete, encodeDelete(collection, filter, multi, relaxed), "Delete", { retryable: false });
+        return JSON.parse(body.toString("utf8")).deleted;
+    }
+    async count(collection, filter) {
+        const body = await this.execute(Cmd.Count, encodeCount(collection, filter), "Count", {
+            retryable: true,
+        });
+        return JSON.parse(body.toString("utf8"));
+    }
+    async distinct(collection, field, filter) {
+        const body = await this.execute(Cmd.Count, encodeDistinct(collection, filter, field), "Distinct", { retryable: true });
+        return JSON.parse(body.toString("utf8"));
+    }
+    collection(name) {
+        return new Collection(this, name);
+    }
+}
+/**
+ * A time-ordered id (UUIDv7-style): a 48-bit millisecond timestamp followed by
+ * 80 random bits, hex-encoded. Sorts lexicographically by creation time.
+ */
+export function generateId() {
+    const buf = Buffer.alloc(16);
+    const ms = BigInt(Date.now()) & ((1n << 48n) - 1n);
+    buf.writeUIntBE(Number(ms), 0, 6);
+    randomBytes(10).copy(buf, 6);
+    return buf.toString("hex");
+}
+function parseAddress(address) {
+    const idx = address.lastIndexOf(":");
+    if (idx < 0)
+        throw new ZydecoError(`invalid address ${address}: expected host:port`);
+    const host = address.slice(0, idx) || "127.0.0.1";
+    const port = Number(address.slice(idx + 1));
+    if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+        throw new ZydecoError(`invalid port in address ${address}`);
+    }
+    return { host, port };
+}
+function decodeU64(body, op) {
+    if (!body || body.length !== 8) {
+        throw new ZydecoError(`${op}: expected 8-byte sequence, got ${body?.length ?? 0}`);
+    }
+    return body.readBigUInt64BE(0);
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/collection.d.ts

@@ -0,0 +1,47 @@
+import type { Client, UpdateResult } from "./client.ts";
+import { type SortKey } from "./protocol.ts";
+/** A JSON document. The "_id" field is the document's string primary key. */
+export type Document = Record<string, unknown>;
+export interface QueryOptions {
+    sort?: SortKey[];
+    /** Include only these fields (mutually exclusive with `exclude`). */
+    include?: string[];
+    /** Exclude these fields. */
+    exclude?: string[];
+    skip?: number;
+    limit?: number;
+    pageSize?: number;
+}
+/**
+ * The product surface: a MongoDB-inspired collection of JSON documents over the
+ * binary client. Filters and updates use the familiar $-operators; the server
+ * plans the access path and re-checks the full filter.
+ */
+export declare class Collection {
+    private readonly client;
+    readonly name: string;
+    constructor(client: Client, name: string);
+    /**
+     * Create a secondary index over one or more dotted field paths. Returns false
+     * if the index already existed.
+     */
+    createIndex(fields: string[], unique?: boolean): Promise<boolean>;
+    /** Insert a document, generating "_id" if absent. Returns the id. */
+    insertOne(document: Document, relaxed?: boolean): Promise<string>;
+    insertMany(documents: Document[]): Promise<string[]>;
+    /** Insert or fully replace the document at docId. */
+    replaceOne(docId: string, document: Document, relaxed?: boolean): Promise<bigint>;
+    updateOne(filter: Document, update: Document, relaxed?: boolean): Promise<UpdateResult>;
+    updateMany(filter: Document, update: Document, relaxed?: boolean): Promise<UpdateResult>;
+    deleteOne(filter: Document, relaxed?: boolean): Promise<number>;
+    deleteMany(filter: Document, relaxed?: boolean): Promise<number>;
+    /** Return all matching documents, decoded as objects. */
+    find(filter: Document | null, opts?: QueryOptions): Promise<Document[]>;
+    /** Return the first matching document, or null if none match. */
+    findOne(filter: Document | null, opts?: QueryOptions): Promise<Document | null>;
+    /** Fetch one document directly by id (fast path), or null if absent. */
+    get(docId: string): Promise<Document | null>;
+    countDocuments(filter?: Document | null): Promise<number>;
+    distinct(field: string, filter?: Document | null): Promise<unknown[]>;
+}
+//# sourceMappingURL=collection.d.ts.map

package/dist/collection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collection.d.ts","sourceRoot":"","sources":["../src/collection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAGxD,OAAO,EAAyB,KAAK,OAAO,EAAE,MAAM,eAAe,CAAC;AAEpE,6EAA6E;AAC7E,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE/C,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,OAAO,EAAE,CAAC;IACjB,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,4BAA4B;IAC5B,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAID;;;;GAIG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;IAKxC;;;OAGG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,MAAM,UAAQ,GAAG,OAAO,CAAC,OAAO,CAAC;IAK/D,qEAAqE;IAC/D,SAAS,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,UAAQ,GAAG,OAAO,CAAC,MAAM,CAAC;IAO/D,UAAU,CAAC,SAAS,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAM1D,qDAAqD;IACrD,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,UAAQ,GAAG,OAAO,CAAC,MAAM,CAAC;IAK/E,SAAS,CAAC,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,UAAQ,GAAG,OAAO,CAAC,YAAY,CAAC;IAIrF,UAAU,CAAC,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,UAAQ,GAAG,OAAO,CAAC,YAAY,CAAC;IAItF,SAAS,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,UAAQ,GAAG,OAAO,CAAC,MAAM,CAAC;IAI7D,UAAU,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,UAAQ,GAAG,OAAO,CAAC,MAAM,CAAC;IAI9D,yDAAyD;IACnD,IAAI,CAAC,MAAM,EAAE,QAAQ,GAAG,IAAI,EAAE,IAAI,GAAE,YAAiB,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAWjF,iEAAiE;IAC3D,OAAO,CAAC,MAAM,EAAE,QAAQ,GAAG,IAAI,EAAE,IAAI,GAAE,YAAiB,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAKzF,wEAAwE;IAClE,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAKlD,cAAc,CAAC,MAAM,GAAE,QAAQ,GAAG,IAAW,GAAG,OAAO,CAAC,MAAM,CAAC;IAI/D,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,GAAE,QAAQ,GAAG,IAAW,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;CAG5E"}

package/dist/collection.js

@@ -0,0 +1,102 @@
+import { generateId } from "./client.js";
+import { ZydecoError } from "./errors.js";
+import { Proj } from "./protocol.js";
+const EMPTY = Buffer.alloc(0);
+/**
+ * The product surface: a MongoDB-inspired collection of JSON documents over the
+ * binary client. Filters and updates use the familiar $-operators; the server
+ * plans the access path and re-checks the full filter.
+ */
+export class Collection {
+    client;
+    name;
+    constructor(client, name) {
+        this.client = client;
+        this.name = name;
+    }
+    /**
+     * Create a secondary index over one or more dotted field paths. Returns false
+     * if the index already existed.
+     */
+    createIndex(fields, unique = false) {
+        const indexName = "by_" + fields.map((f) => f.replaceAll(".", "_")).join("_");
+        return this.client.defineIndex(this.name, indexName, fields, unique);
+    }
+    /** Insert a document, generating "_id" if absent. Returns the id. */
+    async insertOne(document, relaxed = false) {
+        const id = typeof document._id === "string" && document._id ? document._id : generateId();
+        const doc = { ...document, _id: id };
+        await this.client.putDocument(this.name, id, jsonBytes(doc), relaxed);
+        return id;
+    }
+    async insertMany(documents) {
+        const ids = [];
+        for (const d of documents)
+            ids.push(await this.insertOne(d));
+        return ids;
+    }
+    /** Insert or fully replace the document at docId. */
+    replaceOne(docId, document, relaxed = false) {
+        const doc = { ...document, _id: docId };
+        return this.client.putDocument(this.name, docId, jsonBytes(doc), relaxed);
+    }
+    updateOne(filter, update, relaxed = false) {
+        return this.client.update(this.name, filterBytes(filter), jsonBytes(update), false, relaxed);
+    }
+    updateMany(filter, update, relaxed = false) {
+        return this.client.update(this.name, filterBytes(filter), jsonBytes(update), true, relaxed);
+    }
+    deleteOne(filter, relaxed = false) {
+        return this.client.deleteByFilter(this.name, filterBytes(filter), false, relaxed);
+    }
+    deleteMany(filter, relaxed = false) {
+        return this.client.deleteByFilter(this.name, filterBytes(filter), true, relaxed);
+    }
+    /** Return all matching documents, decoded as objects. */
+    async find(filter, opts = {}) {
+        const bodies = await this.client.find(this.name, filterBytes(filter), {
+            sort: opts.sort,
+            projection: projection(opts),
+            skip: opts.skip,
+            limit: opts.limit,
+            pageSize: opts.pageSize,
+        });
+        return bodies.map((b) => (b.length ? JSON.parse(b.toString("utf8")) : {}));
+    }
+    /** Return the first matching document, or null if none match. */
+    async findOne(filter, opts = {}) {
+        const docs = await this.find(filter, { ...opts, limit: 1 });
+        return docs.length ? docs[0] : null;
+    }
+    /** Fetch one document directly by id (fast path), or null if absent. */
+    async get(docId) {
+        const body = await this.client.getDocument(this.name, docId);
+        return body === null ? null : JSON.parse(body.toString("utf8"));
+    }
+    countDocuments(filter = null) {
+        return this.client.count(this.name, filterBytes(filter));
+    }
+    distinct(field, filter = null) {
+        return this.client.distinct(this.name, field, filterBytes(filter));
+    }
+}
+function projection(opts) {
+    if (opts.include?.length && opts.exclude?.length) {
+        throw new ZydecoError("projection cannot mix include and exclude fields");
+    }
+    if (opts.include?.length)
+        return { mode: Proj.Include, fields: opts.include };
+    if (opts.exclude?.length)
+        return { mode: Proj.Exclude, fields: opts.exclude };
+    return { mode: Proj.None, fields: [] };
+}
+function jsonBytes(value) {
+    return Buffer.from(JSON.stringify(value), "utf8");
+}
+/** A nil/empty filter is "match all" (empty bytes on the wire). */
+function filterBytes(filter) {
+    if (!filter || Object.keys(filter).length === 0)
+        return EMPTY;
+    return jsonBytes(filter);
+}
+//# sourceMappingURL=collection.js.map

package/dist/collection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collection.js","sourceRoot":"","sources":["../src/collection.ts"],"names":[],"mappings":"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"}

package/dist/connection.d.ts

@@ -0,0 +1,37 @@
+/** A decoded response: a status byte and (possibly empty) payload. */
+export interface Response {
+    status: number;
+    body: Buffer;
+}
+/**
+ * A single TCP connection to a ZydecoDB server. Safe for concurrent use:
+ * requests are pipelined. The writer queue respects OS backpressure (drain),
+ * and the reader loop continuously consumes frames to resolve promises in FIFO order.
+ */
+export declare class Connection {
+    private socket;
+    private inFlight;
+    private writeQueue;
+    private writing;
+    private dead;
+    lastUsed: number;
+    private readonly host;
+    private readonly port;
+    private readonly timeoutMs;
+    private readonly apiKey;
+    constructor(host: string, port: number, timeoutMs: number, apiKey: string | null);
+    get connected(): boolean;
+    connect(): Promise<void>;
+    private lastError;
+    private sessionInit;
+    /** Send one framed request and resolve with the framed response. */
+    request(command: number, payload?: Buffer): Promise<Response>;
+    private pumpWrites;
+    private readLoop;
+    /** Tear down the connection and reject any in-flight requests. */
+    private fail;
+    close(): void;
+    /** Send a keepalive; resolves true if the server answered OK. */
+    ping(): Promise<boolean>;
+}
+//# sourceMappingURL=connection.d.ts.map

package/dist/connection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../src/connection.ts"],"names":[],"mappings":"AAMA,sEAAsE;AACtE,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd;AAaD;;;;GAIG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,MAAM,CAA2B;IACzC,OAAO,CAAC,QAAQ,CAAiB;IACjC,OAAO,CAAC,UAAU,CAAmB;IACrC,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,IAAI,CAAS;IACrB,QAAQ,SAAK;IAEb,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;gBAE3B,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAOhF,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IA+BxB,OAAO,CAAC,SAAS;YAIH,WAAW;IAOzB,oEAAoE;IACpE,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,MAAwB,GAAG,OAAO,CAAC,QAAQ,CAAC;YAkBhE,UAAU;YAgCV,QAAQ;IAgCtB,kEAAkE;IAClE,OAAO,CAAC,IAAI;IAeZ,KAAK,IAAI,IAAI;IAQb,iEAAiE;IAC3D,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC;CAQ/B"}