camusdb 0.1.0

package/dist/transport/branch-statements.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch-statements.js","sourceRoot":"","sources":["../../src/transport/branch-statements.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAGrD;;;;;;;;;;;GAWG;AAEH,uDAAuD;AACvD,MAAM,UAAU,uBAAuB,CACrC,UAAkB,EAClB,kBAA0B,EAC1B,WAAoB;IAEpB,MAAM,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC,gCAAgC,CAAC,CAAC,CAAC,kBAAkB,CAAC;IAEnF,OAAO,GAAG,MAAM,GAAG,KAAK,CAAC,UAAU,CAAC,gBAAgB,KAAK,CAAC,kBAAkB,CAAC,EAAE,CAAC;AAClF,CAAC;AAED,gCAAgC;AAChC,MAAM,UAAU,iBAAiB,CAAC,QAAgB,EAAE,WAAoB;IACtE,MAAM,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC,gCAAgC,CAAC,CAAC,CAAC,kBAAkB,CAAC;IAEnF,OAAO,GAAG,MAAM,GAAG,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;AACvC,CAAC;AAED,8BAA8B;AAC9B,MAAM,UAAU,eAAe,CAAC,QAAgB;IAC9C,OAAO,iBAAiB,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;AAC5C,CAAC;AAED,mCAAmC;AACnC,MAAM,UAAU,eAAe,CAAC,QAAgB;IAC9C,OAAO,sBAAsB,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;AACjD,CAAC;AAED,oCAAoC;AACpC,MAAM,UAAU,gBAAgB,CAAC,QAAgB;IAC/C,OAAO,uBAAuB,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;AAClD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,MAAsB;IAClD,MAAM,KAAK,GAAG,IAAI,GAAG,EAAkB,CAAC;IAExC,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,QAAQ,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC;IAE1E,MAAM,IAAI,GAAqB,EAAE,CAAC;IAElC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,QAAQ,EAAE,CAAC,EAAE,EAAE,CAAC;QACzC,MAAM,IAAI,GAAG,CAAC,IAAY,EAAsB,EAAE;YAChD,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAC/B,IAAI,MAAM,KAAK,SAAS;gBAAE,OAAO,SAAS,CAAC;YAE3C,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,QAAQ,IAAI,SAAS,CAAC;QACtD,CAAC,CAAC;QAEF,MAAM,WAAW,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAEvC,IAAI,CAAC,IAAI,CAAC;YACR,QAAQ,EAAE,IAAI,CAAC,UAAU,CAAC;YAC1B,EAAE,EAAE,IAAI,CAAC,IAAI,CAAC;YACd,KAAK,EAAE,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC,SAAS,IAAI,EAAE,CAAC;YAC1F,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC;YACtB,aAAa,EAAE,IAAI,CAAC,gBAAgB,CAAC;SACtC,CAAC,CAAC;IACL,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,KAAK,CAAC,IAAY;IACzB,OAAO,iBAAiB,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AACzC,CAAC"}

package/dist/transport/error-text.d.ts

@@ -0,0 +1,26 @@
+/**
+ * This file is part of CamusDB
+ *
+ * For the full copyright and license information, please view the LICENSE.txt
+ * file that was distributed with this source code.
+ */
+/**
+ * Cleans the text that becomes a `CamusError` message.
+ *
+ * The message is built from whatever the far end returned: a server error body, a gRPC status
+ * detail, an HTTP client's own exception text. Applications log it almost without exception, so
+ * three properties of that text matter, and the sender guarantees none of them. It must not carry
+ * a credential. It must not carry line breaks, which let a sender forge a second log entry. It
+ * must not be unbounded.
+ *
+ * Only the error path pays for this, so the scan is one plain pass rather than a set of regular
+ * expressions.
+ */
+/** The longest message kept. A server error body is a sentence; anything longer is echoed content. */
+export declare const MAX_ERROR_MESSAGE_LENGTH = 2048;
+/**
+ * The text with control characters folded to spaces, credential-shaped runs masked, and the length
+ * bounded.
+ */
+export declare function sanitizeErrorText(text: string | undefined | null): string;
+//# sourceMappingURL=error-text.d.ts.map

package/dist/transport/error-text.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-text.d.ts","sourceRoot":"","sources":["../../src/transport/error-text.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;;;GAWG;AAEH,sGAAsG;AACtG,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAY7C;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,CAyBzE"}

package/dist/transport/error-text.js

@@ -0,0 +1,75 @@
+/**
+ * This file is part of CamusDB
+ *
+ * For the full copyright and license information, please view the LICENSE.txt
+ * file that was distributed with this source code.
+ */
+/**
+ * Cleans the text that becomes a `CamusError` message.
+ *
+ * The message is built from whatever the far end returned: a server error body, a gRPC status
+ * detail, an HTTP client's own exception text. Applications log it almost without exception, so
+ * three properties of that text matter, and the sender guarantees none of them. It must not carry
+ * a credential. It must not carry line breaks, which let a sender forge a second log entry. It
+ * must not be unbounded.
+ *
+ * Only the error path pays for this, so the scan is one plain pass rather than a set of regular
+ * expressions.
+ */
+/** The longest message kept. A server error body is a sentence; anything longer is echoed content. */
+export const MAX_ERROR_MESSAGE_LENGTH = 2048;
+const ELIDED = '…';
+const MASKED = '***';
+/** Prefixes shaped like a credential. The token that follows one is masked. */
+const SECRET_PREFIXES = ['bearer ', 'password=', 'password":', 'pwd=', 'accesstoken=', 'token":'];
+/** Characters that end the value a credential-shaped prefix introduces. */
+const VALUE_TERMINATORS = new Set([' ', '"', "'", ',', ';', '}', ')', '\n', '\r']);
+/**
+ * The text with control characters folded to spaces, credential-shaped runs masked, and the length
+ * bounded.
+ */
+export function sanitizeErrorText(text) {
+    if (text === undefined || text === null || text.length === 0)
+        return '';
+    const lower = text.toLowerCase();
+    let clean = '';
+    let index = 0;
+    while (index < text.length && clean.length < MAX_ERROR_MESSAGE_LENGTH) {
+        const prefixLength = matchSecretPrefix(lower, index);
+        if (prefixLength !== undefined) {
+            clean += text.slice(index, index + prefixLength) + MASKED;
+            index = skipSecretValue(text, index + prefixLength);
+            continue;
+        }
+        const character = text[index];
+        index++;
+        // A newline in a logged message lets the sender forge a second log entry, and another control
+        // character can rewrite a terminal. Both become a plain space.
+        clean += isControl(character) ? ' ' : character;
+    }
+    return index < text.length ? clean + ELIDED : clean;
+}
+function matchSecretPrefix(lowercase, index) {
+    for (const prefix of SECRET_PREFIXES) {
+        if (lowercase.startsWith(prefix, index))
+            return prefix.length;
+    }
+    return undefined;
+}
+/**
+ * Skips the value a credential-shaped prefix introduces: leading quotes and spaces, then
+ * everything up to the first character that cannot be part of a token or a quoted value.
+ */
+function skipSecretValue(text, index) {
+    while (index < text.length && (text[index] === ' ' || text[index] === '"' || text[index] === "'")) {
+        index++;
+    }
+    while (index < text.length && !VALUE_TERMINATORS.has(text[index]))
+        index++;
+    return index;
+}
+function isControl(character) {
+    const code = character.codePointAt(0);
+    return code < 0x20 || (code >= 0x7f && code <= 0x9f);
+}
+//# sourceMappingURL=error-text.js.map

package/dist/transport/error-text.js.map

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

package/dist/transport/grpc/batcher.d.ts

@@ -0,0 +1,127 @@
+/**
+ * This file is part of CamusDB
+ *
+ * For the full copyright and license information, please view the LICENSE.txt
+ * file that was distributed with this source code.
+ */
+import type { GrpcBatchOptions } from '../../config.js';
+import type { GrpcBatchExecuteRequest, GrpcBatchExecuteResponse, GrpcResultRow, GrpcResultSchema, GrpcSqlRequest, GrpcTxnHandle } from './messages.js';
+import type { CamusCacheMetadata } from '../../cache.js';
+import type { CamusRoutingAdvice } from '../../routing/advice.js';
+/** The hybrid-logical-clock token a reply carried. All three components are load-bearing. */
+export interface BatchCausalToken {
+    readonly n: number;
+    readonly l: bigint;
+    readonly c: bigint;
+}
+export declare const EMPTY_CAUSAL_TOKEN: BatchCausalToken;
+/** One query, decoded from the schema, rows, and terminator that shared a request id. */
+export interface BatchQueryResult {
+    readonly schema: GrpcResultSchema | undefined;
+    readonly rows: GrpcResultRow[];
+    readonly token: BatchCausalToken;
+    readonly cacheMetadata: CamusCacheMetadata | undefined;
+    readonly routing: CamusRoutingAdvice | undefined;
+}
+/** One write statement's reply. */
+export interface BatchNonQueryResult {
+    readonly affectedRows: number;
+    readonly token: BatchCausalToken;
+    readonly routing: CamusRoutingAdvice | undefined;
+}
+/** A prepared statement registered on one stream: the handle, and which stream minted it. */
+export interface PreparedSlotEntry {
+    readonly transportId: number;
+    readonly statementId: number;
+    readonly parameterNames: string[];
+}
+/**
+ * Raised when a prepared execution is about to be written to a stream that is not the one its
+ * handle was registered on. The handle died with the stream that minted it, so sending it would
+ * only earn an "unknown statement" reply.
+ */
+export declare class PreparedStatementStaleError extends Error {
+    readonly name = "PreparedStatementStaleError";
+    constructor();
+}
+/** One `BatchExecute` duplex call, behind an interface a test can substitute for. */
+export interface BatchStream {
+    /** Identifies this stream. A handle registered on it is invalid on any other. */
+    readonly id: number;
+    send(request: GrpcBatchExecuteRequest): void;
+    /** Registers the callbacks that drive the reader loop. Called once, right after construction. */
+    listen(handlers: {
+        onMessage: (response: GrpcBatchExecuteResponse) => void;
+        onClose: (error: Error) => void;
+    }): void;
+    close(): void;
+}
+/**
+ * Pipelines many statements over a small pool of long-lived `BatchExecute` streams.
+ *
+ * A unary call per statement costs a round trip per statement, and an application that issues six
+ * statements per unit of work pays six. Here every message carries a client-monotonic request id,
+ * replies for different ids interleave, and this class demultiplexes them by id. Statements that
+ * share a transaction go to one stream, in arrival order, so the server sees them in the order the
+ * caller wrote them; autocommit statements are free to use any stream.
+ *
+ * A stream that faults is rebuilt by the next write, and every operation that was in flight on the
+ * old one is failed so its caller can decide whether to replay it. Prepared statements are scoped
+ * to the stream that registered them, and a handle from a stream that is gone is refused at the
+ * last moment before it would be written.
+ */
+export declare class GrpcBatcher {
+    private readonly options;
+    private readonly streamFactory;
+    private readonly slots;
+    private readonly pending;
+    private requestIdSeq;
+    private roundRobin;
+    private transportIdSeq;
+    private disposed;
+    constructor(options: GrpcBatchOptions, streamFactory: (id: number) => BatchStream);
+    /** Reserves a stream for a transaction, so all of its operations land in one ordering chain. */
+    reserveSlot(): number;
+    enqueueQuery(request: GrpcSqlRequest, slotIndex: number | undefined, signal: AbortSignal | undefined, expectedTransportId?: number): Promise<BatchQueryResult>;
+    enqueueNonQuery(request: GrpcSqlRequest, slotIndex: number | undefined, signal: AbortSignal | undefined, expectedTransportId?: number): Promise<BatchNonQueryResult>;
+    enqueueStart(request: GrpcSqlRequest, slotIndex: number, signal: AbortSignal | undefined): Promise<GrpcTxnHandle>;
+    enqueueCommit(request: GrpcSqlRequest, slotIndex: number, signal: AbortSignal | undefined): Promise<BatchCausalToken>;
+    enqueueRollback(request: GrpcSqlRequest, slotIndex: number, signal: AbortSignal | undefined): Promise<void>;
+    /**
+     * The registration for a statement on one stream, creating it when there is none.
+     *
+     * A registration whose stream has since been rebuilt is dropped and made again: the handle died
+     * with the stream, and the server would not know it.
+     */
+    ensurePrepared(slotIndex: number, database: string, sql: string, signal: AbortSignal | undefined): Promise<PreparedSlotEntry>;
+    private registerPrepared;
+    /** Drops a registration the server no longer honours, but only if it is still the current one. */
+    invalidatePrepared(slotIndex: number, database: string, sql: string, stale: PreparedSlotEntry): void;
+    /** Removes and reports every stream's registration of one statement, so each can be released. */
+    takePrepared(database: string, sql: string): Promise<{
+        slotIndex: number;
+        entry: PreparedSlotEntry;
+    }[]>;
+    /** Releases one registration on the stream that minted it. Best-effort. */
+    closePrepared(slotIndex: number, entry: PreparedSlotEntry, signal: AbortSignal | undefined): Promise<void>;
+    private enqueue;
+    private enqueueTracked;
+    /**
+     * Drains one slot's queue onto its stream.
+     *
+     * Only one pump runs per slot, so the slot's stream has exactly one writer and needs no lock.
+     */
+    private pump;
+    private writeItem;
+    private reconnect;
+    private demux;
+    private complete;
+    private fault;
+    private settle;
+    /** Fails every operation still in flight on a stream that closed, so its caller can replay. */
+    private failStreamPending;
+    private nextRoundRobin;
+    /** Closes every stream and fails everything still in flight. */
+    dispose(): Promise<void>;
+}
+//# sourceMappingURL=batcher.d.ts.map

package/dist/transport/grpc/batcher.d.ts.map

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

package/dist/transport/grpc/batcher.js

@@ -0,0 +1,399 @@
+/**
+ * This file is part of CamusDB
+ *
+ * For the full copyright and license information, please view the LICENSE.txt
+ * file that was distributed with this source code.
+ */
+import { CamusError } from '../../errors.js';
+import { CamusErrorCode } from '../../error-codes.js';
+import { sanitizeErrorText } from '../error-text.js';
+import { decodeCacheMetadata, decodeRoutingAdvice, fromWire } from './codec.js';
+import { GrpcBatchStatementKind } from './messages.js';
+export const EMPTY_CAUSAL_TOKEN = Object.freeze({ n: 0, l: 0n, c: 0n });
+/**
+ * Raised when a prepared execution is about to be written to a stream that is not the one its
+ * handle was registered on. The handle died with the stream that minted it, so sending it would
+ * only earn an "unknown statement" reply.
+ */
+export class PreparedStatementStaleError extends Error {
+    name = 'PreparedStatementStaleError';
+    constructor() {
+        super("The prepared statement's stream was rebuilt before this execution could be written.");
+    }
+}
+/**
+ * Pipelines many statements over a small pool of long-lived `BatchExecute` streams.
+ *
+ * A unary call per statement costs a round trip per statement, and an application that issues six
+ * statements per unit of work pays six. Here every message carries a client-monotonic request id,
+ * replies for different ids interleave, and this class demultiplexes them by id. Statements that
+ * share a transaction go to one stream, in arrival order, so the server sees them in the order the
+ * caller wrote them; autocommit statements are free to use any stream.
+ *
+ * A stream that faults is rebuilt by the next write, and every operation that was in flight on the
+ * old one is failed so its caller can decide whether to replay it. Prepared statements are scoped
+ * to the stream that registered them, and a handle from a stream that is gone is refused at the
+ * last moment before it would be written.
+ */
+export class GrpcBatcher {
+    options;
+    streamFactory;
+    slots;
+    pending = new Map();
+    requestIdSeq = 0;
+    roundRobin = -1;
+    transportIdSeq = 0;
+    disposed = false;
+    constructor(options, streamFactory) {
+        this.options = options;
+        this.streamFactory = streamFactory;
+        const poolSize = Math.max(1, options.channelPoolSize);
+        this.slots = new Array(poolSize);
+        for (let i = 0; i < poolSize; i++) {
+            this.slots[i] = { index: i, inbox: [], pumping: false, stream: undefined, prepared: new Map() };
+        }
+    }
+    /** Reserves a stream for a transaction, so all of its operations land in one ordering chain. */
+    reserveSlot() {
+        return this.nextRoundRobin();
+    }
+    // ─── The enqueue surface ──────────────────────────────────────────────────
+    enqueueQuery(request, slotIndex, signal, expectedTransportId) {
+        return this.enqueue(GrpcBatchStatementKind.Query, request, slotIndex, signal, expectedTransportId);
+    }
+    enqueueNonQuery(request, slotIndex, signal, expectedTransportId) {
+        return this.enqueue(GrpcBatchStatementKind.NonQuery, request, slotIndex, signal, expectedTransportId);
+    }
+    enqueueStart(request, slotIndex, signal) {
+        return this.enqueue(GrpcBatchStatementKind.Start, request, slotIndex, signal);
+    }
+    enqueueCommit(request, slotIndex, signal) {
+        return this.enqueue(GrpcBatchStatementKind.Commit, request, slotIndex, signal);
+    }
+    async enqueueRollback(request, slotIndex, signal) {
+        await this.enqueue(GrpcBatchStatementKind.Rollback, request, slotIndex, signal);
+    }
+    // ─── Prepared statements ──────────────────────────────────────────────────
+    /**
+     * The registration for a statement on one stream, creating it when there is none.
+     *
+     * A registration whose stream has since been rebuilt is dropped and made again: the handle died
+     * with the stream, and the server would not know it.
+     */
+    async ensurePrepared(slotIndex, database, sql, signal) {
+        const slot = this.slots[slotIndex];
+        const key = statementKey(database, sql);
+        for (;;) {
+            const existing = slot.prepared.get(key);
+            if (existing !== undefined) {
+                let entry;
+                try {
+                    entry = await existing.pending;
+                }
+                catch {
+                    // Whoever created it already reported the failure to its own caller. Drop the poisoned
+                    // entry and take a fresh turn rather than failing every later execution.
+                    forget(slot, key, existing);
+                    continue;
+                }
+                if (entry.transportId === slot.stream?.id)
+                    return entry;
+                // The slot's stream was rebuilt since this was registered, so the handle died with it.
+                forget(slot, key, existing);
+                continue;
+            }
+            const pending = this.registerPrepared(slotIndex, database, sql, signal);
+            const registration = { pending, resolved: undefined };
+            slot.prepared.set(key, registration);
+            try {
+                const entry = await pending;
+                registration.resolved = entry;
+                return entry;
+            }
+            catch (error) {
+                forget(slot, key, registration);
+                throw error;
+            }
+        }
+    }
+    async registerPrepared(slotIndex, database, sql, signal) {
+        const { result, transportId } = await this.enqueueTracked(GrpcBatchStatementKind.Prepare, { database, sql }, slotIndex, signal, undefined);
+        return { transportId, statementId: result.statementId, parameterNames: [...result.parameterNames] };
+    }
+    /** Drops a registration the server no longer honours, but only if it is still the current one. */
+    invalidatePrepared(slotIndex, database, sql, stale) {
+        const slot = this.slots[slotIndex];
+        const key = statementKey(database, sql);
+        const existing = slot.prepared.get(key);
+        if (existing?.resolved?.statementId === stale.statementId &&
+            existing.resolved.transportId === stale.transportId) {
+            forget(slot, key, existing);
+        }
+    }
+    /** Removes and reports every stream's registration of one statement, so each can be released. */
+    async takePrepared(database, sql) {
+        const key = statementKey(database, sql);
+        const taken = [];
+        for (const slot of this.slots) {
+            const registration = slot.prepared.get(key);
+            if (registration === undefined)
+                continue;
+            slot.prepared.delete(key);
+            try {
+                taken.push({ slotIndex: slot.index, entry: await registration.pending });
+            }
+            catch {
+                // A registration that never succeeded has no handle to release.
+            }
+        }
+        return taken;
+    }
+    /** Releases one registration on the stream that minted it. Best-effort. */
+    async closePrepared(slotIndex, entry, signal) {
+        try {
+            await this.enqueue(GrpcBatchStatementKind.Close, { statementId: entry.statementId }, slotIndex, signal, entry.transportId);
+        }
+        catch {
+            // The stream is already gone, and the handle was released with it.
+        }
+    }
+    // ─── Enqueue and pump ─────────────────────────────────────────────────────
+    async enqueue(kind, request, slotIndex, signal, expectedTransportId) {
+        const { result } = await this.enqueueTracked(kind, request, slotIndex, signal, expectedTransportId);
+        return result;
+    }
+    enqueueTracked(kind, request, slotIndex, signal, expectedTransportId) {
+        if (this.disposed) {
+            return Promise.reject(new CamusError(CamusErrorCode.Generic, 'This gRPC transport is closed.'));
+        }
+        const slot = this.slots[slotIndex ?? this.nextRoundRobin()];
+        const requestId = ++this.requestIdSeq;
+        return new Promise((resolve, reject) => {
+            const op = {
+                requestId,
+                settled: false,
+                transportId: 0,
+                resolve: (value) => resolve({ result: value, transportId: op.transportId }),
+                reject,
+            };
+            if (signal !== undefined) {
+                if (signal.aborted) {
+                    reject(signal.reason);
+                    return;
+                }
+                op.signal = signal;
+                op.onAbort = () => this.fault(op, signal.reason);
+                signal.addEventListener('abort', op.onAbort, { once: true });
+            }
+            this.pending.set(requestId, op);
+            slot.inbox.push({ request: { requestId, kind, request }, op, expectedTransportId });
+            void this.pump(slot);
+        });
+    }
+    /**
+     * Drains one slot's queue onto its stream.
+     *
+     * Only one pump runs per slot, so the slot's stream has exactly one writer and needs no lock.
+     */
+    async pump(slot) {
+        if (slot.pumping)
+            return;
+        slot.pumping = true;
+        try {
+            for (;;) {
+                let drained = 0;
+                for (;;) {
+                    const item = slot.inbox.shift();
+                    if (item === undefined)
+                        break;
+                    this.writeItem(slot, item);
+                    drained++;
+                }
+                // Coalescing: after writing a small burst, pause briefly so more operations accumulate
+                // before the next drain writes them together. It applies only after a drain of two or
+                // more. A one-item drain is a request-and-reply exchange — one caller, whose next
+                // statement cannot arrive until this one is answered — and sleeping there would add the
+                // whole delay to every round trip while gaining nothing.
+                if (drained >= 2 &&
+                    this.options.coalescingThreshold > 1 &&
+                    drained < this.options.coalescingThreshold &&
+                    this.options.coalescingDelayMs > 0) {
+                    await sleep(this.options.coalescingDelayMs);
+                }
+                if (slot.inbox.length === 0)
+                    return;
+            }
+        }
+        finally {
+            slot.pumping = false;
+            // An item queued while the pump was finishing must not be left waiting for the next caller.
+            if (slot.inbox.length > 0 && !this.disposed)
+                void this.pump(slot);
+        }
+    }
+    writeItem(slot, item) {
+        try {
+            const stream = slot.stream ?? this.reconnect(slot);
+            // A prepared execution names a handle that exists only on the stream that registered it.
+            // This is the last moment the two can be compared — check any earlier and the stream could
+            // still be rebuilt in between — so refuse here rather than send an operation the server can
+            // only answer with "unknown statement".
+            if (item.expectedTransportId !== undefined && stream.id !== item.expectedTransportId) {
+                throw new PreparedStatementStaleError();
+            }
+            item.op.transportId = stream.id;
+            stream.send(item.request);
+        }
+        catch (error) {
+            this.fault(item.op, error instanceof Error ? error : new Error(String(error)));
+        }
+    }
+    reconnect(slot) {
+        const stream = this.streamFactory(++this.transportIdSeq);
+        slot.stream = stream;
+        stream.listen({
+            onMessage: (response) => this.demux(response),
+            onClose: (error) => {
+                // Only clear the slot when this stream is still the current one: a later reconnect must
+                // not be undone by an older stream's close event.
+                if (slot.stream === stream)
+                    slot.stream = undefined;
+                this.failStreamPending(stream.id, error);
+            },
+        });
+        return stream;
+    }
+    // ─── Demultiplex ──────────────────────────────────────────────────────────
+    demux(response) {
+        const op = this.pending.get(response.requestId);
+        // Cancelled, timed out, or already settled. Drop it.
+        if (op === undefined)
+            return;
+        switch (response.payload) {
+            case 'schema':
+                op.schema = response.schema;
+                return;
+            case 'row':
+                (op.rows ??= []).push(response.row);
+                return;
+            case 'queryComplete': {
+                const complete = response.queryComplete;
+                this.complete(op, {
+                    schema: op.schema,
+                    rows: op.rows ?? [],
+                    token: {
+                        n: complete.causalTokenN,
+                        l: fromWire(complete.causalTokenL),
+                        c: fromWire(complete.causalTokenC),
+                    },
+                    cacheMetadata: decodeCacheMetadata(complete.cacheMetadata),
+                    routing: decodeRoutingAdvice(complete.routing),
+                });
+                return;
+            }
+            case 'nonQuery': {
+                const reply = response.nonQuery;
+                this.complete(op, {
+                    affectedRows: reply.affectedRows,
+                    token: {
+                        n: reply.causalTokenN,
+                        l: fromWire(reply.causalTokenL),
+                        c: fromWire(reply.causalTokenC),
+                    },
+                    routing: decodeRoutingAdvice(reply.routing),
+                });
+                return;
+            }
+            case 'startReply':
+                this.complete(op, response.startReply);
+                return;
+            case 'commitReply': {
+                const reply = response.commitReply;
+                this.complete(op, {
+                    n: reply.causalTokenN,
+                    l: fromWire(reply.causalTokenL),
+                    c: fromWire(reply.causalTokenC),
+                });
+                return;
+            }
+            case 'prepareReply':
+                this.complete(op, response.prepareReply);
+                return;
+            case 'rollbackReply':
+            case 'closeReply':
+                this.complete(op, undefined);
+                return;
+            case 'error':
+                this.fault(op, new CamusError(response.error.code, sanitizeErrorText(response.error.message)));
+                return;
+            default:
+                return;
+        }
+    }
+    complete(op, result) {
+        if (!this.settle(op))
+            return;
+        op.resolve(result);
+    }
+    fault(op, error) {
+        if (!this.settle(op))
+            return;
+        op.reject(error);
+    }
+    settle(op) {
+        if (op.settled)
+            return false;
+        op.settled = true;
+        this.pending.delete(op.requestId);
+        if (op.onAbort !== undefined)
+            op.signal?.removeEventListener('abort', op.onAbort);
+        return true;
+    }
+    /** Fails every operation still in flight on a stream that closed, so its caller can replay. */
+    failStreamPending(transportId, error) {
+        for (const op of [...this.pending.values()]) {
+            if (op.transportId === transportId)
+                this.fault(op, error);
+        }
+    }
+    nextRoundRobin() {
+        this.roundRobin = (this.roundRobin + 1) % this.slots.length;
+        return this.roundRobin;
+    }
+    /** Closes every stream and fails everything still in flight. */
+    async dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        for (const slot of this.slots) {
+            const stream = slot.stream;
+            slot.stream = undefined;
+            slot.inbox.length = 0;
+            try {
+                stream?.close();
+            }
+            catch {
+                // Best effort: the stream may already be broken.
+            }
+        }
+        const closed = new CamusError(CamusErrorCode.Generic, 'This gRPC transport is closed.');
+        for (const op of [...this.pending.values()])
+            this.fault(op, closed);
+        await Promise.resolve();
+    }
+}
+function forget(slot, key, expected) {
+    if (slot.prepared.get(key) === expected)
+        slot.prepared.delete(key);
+}
+// A newline cannot appear in a database name, so it separates the two parts without ambiguity.
+function statementKey(database, sql) {
+    return `${database}\n${sql}`;
+}
+function sleep(milliseconds) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, milliseconds);
+        timer.unref?.();
+    });
+}
+//# sourceMappingURL=batcher.js.map