camusdb 0.1.0

package/dist/options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.js","sourceRoot":"","sources":["../src/options.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,+FAA+F;IAC/F,aAAa,EAAE,eAAe;IAE9B;;;OAGG;IACH,YAAY,EAAE,cAAc;CACpB,CAAC;AAIX,uCAAuC;AACvC,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,+DAA+D;IAC/D,SAAS,EAAE,WAAW;IAEtB;;;OAGG;IACH,QAAQ,EAAE,UAAU;CACZ,CAAC;AAIX,yFAAyF;AACzF,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B;;;OAGG;IACH,WAAW,EAAE,aAAa;IAE1B;;;;;OAKG;IACH,UAAU,EAAE,YAAY;CAChB,CAAC;AA0BX,oEAAoE;AACpE,MAAM,CAAC,MAAM,2BAA2B,GAA4B,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;AAEtF,wEAAwE;AACxE,MAAM,CAAC,MAAM,8BAA8B,GAA4B,MAAM,CAAC,MAAM,CAAC;IACnF,OAAO,EAAE,YAAY,CAAC,UAAU;CACjC,CAAC,CAAC;AAEH,mEAAmE;AACnE,MAAM,CAAC,MAAM,4BAA4B,GAA4B,MAAM,CAAC,MAAM,CAAC;IACjF,cAAc,EAAE,mBAAmB,CAAC,YAAY;IAChD,IAAI,EAAE,oBAAoB,CAAC,QAAQ;CACpC,CAAC,CAAC;AAEH,+DAA+D;AAC/D,MAAM,UAAU,YAAY,CAC1B,OAAgC,EAChC,QAA6C;IAE7C,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,OAAO,CAAC;IAE3C,OAAO;QACL,cAAc,EAAE,OAAO,CAAC,cAAc,IAAI,QAAQ,CAAC,cAAc;QACjE,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,QAAQ,CAAC,IAAI;QACnC,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,QAAQ,CAAC,OAAO;QAC5C,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,QAAQ,CAAC,QAAQ;KAChD,CAAC;AACJ,CAAC"}

package/dist/prepared/binder.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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 { ColumnValue } from '../column-value.js';
+/**
+ * Orders a call's parameter values the way a prepared statement binds them.
+ *
+ * The server publishes the statement's placeholder names in binding order when it registers the
+ * statement. Every later execution then sends only values, positionally, so neither the SQL nor
+ * the names travel again. This function is where a named map becomes that ordered list.
+ *
+ * A placeholder with no bound value is an error rather than a null. The statement declares it, so
+ * a missing value is a mistake in the call, and sending a null would run the statement against a
+ * value the caller never wrote.
+ */
+export declare function bindPositional(parameterNames: readonly string[], parameters: ReadonlyMap<string, ColumnValue> | undefined): ColumnValue[];
+//# sourceMappingURL=binder.d.ts.map

package/dist/prepared/binder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"binder.d.ts","sourceRoot":"","sources":["../../src/prepared/binder.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAItD;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAC5B,cAAc,EAAE,SAAS,MAAM,EAAE,EACjC,UAAU,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,SAAS,GACvD,WAAW,EAAE,CAkBf"}

package/dist/prepared/binder.js

@@ -0,0 +1,32 @@
+/**
+ * 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';
+/**
+ * Orders a call's parameter values the way a prepared statement binds them.
+ *
+ * The server publishes the statement's placeholder names in binding order when it registers the
+ * statement. Every later execution then sends only values, positionally, so neither the SQL nor
+ * the names travel again. This function is where a named map becomes that ordered list.
+ *
+ * A placeholder with no bound value is an error rather than a null. The statement declares it, so
+ * a missing value is a mistake in the call, and sending a null would run the statement against a
+ * value the caller never wrote.
+ */
+export function bindPositional(parameterNames, parameters) {
+    const values = new Array(parameterNames.length);
+    for (let i = 0; i < parameterNames.length; i++) {
+        const name = parameterNames[i];
+        const value = parameters?.get(name);
+        if (value === undefined) {
+            throw new CamusError(CamusErrorCode.InvalidParameter, `The prepared statement declares the parameter '${name}' but no value was bound for it.`);
+        }
+        values[i] = value;
+    }
+    return values;
+}
+//# sourceMappingURL=binder.js.map

package/dist/prepared/binder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"binder.js","sourceRoot":"","sources":["../../src/prepared/binder.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEnD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,cAAc,CAC5B,cAAiC,EACjC,UAAwD;IAExD,MAAM,MAAM,GAAkB,IAAI,KAAK,CAAc,cAAc,CAAC,MAAM,CAAC,CAAC;IAE5E,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,cAAc,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAC/C,MAAM,IAAI,GAAG,cAAc,CAAC,CAAC,CAAE,CAAC;QAChC,MAAM,KAAK,GAAG,UAAU,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;QAEpC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,MAAM,IAAI,UAAU,CAClB,cAAc,CAAC,gBAAgB,EAC/B,kDAAkD,IAAI,kCAAkC,CACzF,CAAC;QACJ,CAAC;QAED,MAAM,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC;IACpB,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/prepared/policy.d.ts

@@ -0,0 +1,81 @@
+/**
+ * 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.
+ */
+/** What the policy decided about one execution of a statement. */
+export declare const PrepareDecision: {
+    /** Run it inline. It is not hot enough yet, or it cannot be prepared. */
+    readonly No: "no";
+    /** Register it now, then run this execution prepared. */
+    readonly Register: "register";
+    /** It is already registered. Run this execution prepared. */
+    readonly Yes: "yes";
+};
+export type PrepareDecision = (typeof PrepareDecision)[keyof typeof PrepareDecision];
+/** A statement the policy evicted, so the server can stop holding a handle nobody uses. */
+export interface EvictedStatement {
+    readonly database: string;
+    readonly sql: string;
+}
+/**
+ * Which statements a client prepares.
+ *
+ * Preparing costs one extra round trip and saves the SQL text and the parameter names on every
+ * execution after it, so it pays for a statement that runs many times and wastes a round trip for
+ * one that runs once. The policy is that counting: a statement is registered once it has been seen
+ * `minUsages` times, and the `maxAutoPrepare` most recently used registrations are kept.
+ *
+ * The policy is shared per deployment and settings rather than owned by one client. Which
+ * statements a workload repeats is a property of the workload, and an application that builds a
+ * client per request would restart the counting every time and never conclude anything.
+ *
+ * Recency is a `Map`, which preserves insertion order: re-inserting a key moves it to the end, so
+ * the first key the map yields is the least recently used one.
+ */
+export declare class CamusPreparedStatementPolicy {
+    static readonly DEFAULT_MAX_AUTO_PREPARE = 128;
+    static readonly DEFAULT_MIN_USAGES = 2;
+    private static readonly shared;
+    /** The process-wide policy for a deployment-and-settings key. */
+    static forKey(key: string, factory: () => CamusPreparedStatementPolicy): CamusPreparedStatementPolicy;
+    /** @internal Test hook: drops every shared policy. */
+    static resetShared(): void;
+    readonly maxAutoPrepare: number;
+    readonly minUsages: number;
+    private readonly entries;
+    private disabled;
+    constructor(maxAutoPrepare: number, minUsages: number);
+    /** True when automatic preparation is off, either by configuration or because a server refused. */
+    get isDisabled(): boolean;
+    /** How many statements are currently kept prepared. */
+    get preparedCount(): number;
+    /** Whether one statement is currently kept prepared. */
+    isPrepared(database: string, sql: string): boolean;
+    /** Decides what this execution should do, and reports a statement the decision evicted. */
+    decide(database: string, sql: string): {
+        decision: PrepareDecision;
+        evicted?: EvictedStatement;
+    };
+    /**
+     * Marks a statement for registration because the caller asked for it directly.
+     *
+     * An explicit request overrides an earlier refusal: the caller may well have fixed whatever made
+     * it fail, and it is asking rather than being guessed at.
+     */
+    pin(database: string, sql: string): {
+        decision: PrepareDecision;
+        evicted?: EvictedStatement;
+    };
+    /** Records that the server registered a statement. */
+    markPrepared(database: string, sql: string): void;
+    /** Records that this statement should not be offered for registration again. */
+    markRefused(database: string, sql: string): void;
+    /** Stops offering any statement for registration. Used when a server has no support at all. */
+    disable(): void;
+    /** Drops what is known about a statement, so it is reconsidered from the start. */
+    forget(database: string, sql: string): void;
+    private touch;
+}
+//# sourceMappingURL=policy.d.ts.map

package/dist/prepared/policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../src/prepared/policy.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,kEAAkE;AAClE,eAAO,MAAM,eAAe;IAC1B,yEAAyE;;IAEzE,yDAAyD;;IAEzD,6DAA6D;;CAErD,CAAC;AAEX,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,OAAO,eAAe,CAAC,CAAC;AAkBrF,2FAA2F;AAC3F,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,4BAA4B;IACvC,MAAM,CAAC,QAAQ,CAAC,wBAAwB,OAAO;IAE/C,MAAM,CAAC,QAAQ,CAAC,kBAAkB,KAAK;IAEvC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAsD;IAEpF,iEAAiE;IACjE,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,4BAA4B,GAAG,4BAA4B;IAIrG,sDAAsD;IACtD,MAAM,CAAC,WAAW,IAAI,IAAI;IAI1B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAEhC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4B;IAEpD,OAAO,CAAC,QAAQ,CAAU;gBAEd,cAAc,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;IAMrD,mGAAmG;IACnG,IAAI,UAAU,IAAI,OAAO,CAExB;IAED,uDAAuD;IACvD,IAAI,aAAa,IAAI,MAAM,CAQ1B;IAED,wDAAwD;IACxD,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO;IAIlD,2FAA2F;IAC3F,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG;QAAE,QAAQ,EAAE,eAAe,CAAC;QAAC,OAAO,CAAC,EAAE,gBAAgB,CAAA;KAAE;IA2BhG;;;;;OAKG;IACH,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG;QAAE,QAAQ,EAAE,eAAe,CAAC;QAAC,OAAO,CAAC,EAAE,gBAAgB,CAAA;KAAE;IAa7F,sDAAsD;IACtD,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAKjD,gFAAgF;IAChF,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAKhD,+FAA+F;IAC/F,OAAO,IAAI,IAAI;IAIf,mFAAmF;IACnF,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAI3C,OAAO,CAAC,KAAK;CAiCd"}

package/dist/prepared/policy.js

@@ -0,0 +1,164 @@
+/**
+ * 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 { SharedRegistry } from '../shared-registry.js';
+/** What the policy decided about one execution of a statement. */
+export const PrepareDecision = {
+    /** Run it inline. It is not hot enough yet, or it cannot be prepared. */
+    No: 'no',
+    /** Register it now, then run this execution prepared. */
+    Register: 'register',
+    /** It is already registered. Run this execution prepared. */
+    Yes: 'yes',
+};
+const EntryState = {
+    Counting: 0,
+    Registering: 1,
+    Prepared: 2,
+    Refused: 3,
+};
+/**
+ * Which statements a client prepares.
+ *
+ * Preparing costs one extra round trip and saves the SQL text and the parameter names on every
+ * execution after it, so it pays for a statement that runs many times and wastes a round trip for
+ * one that runs once. The policy is that counting: a statement is registered once it has been seen
+ * `minUsages` times, and the `maxAutoPrepare` most recently used registrations are kept.
+ *
+ * The policy is shared per deployment and settings rather than owned by one client. Which
+ * statements a workload repeats is a property of the workload, and an application that builds a
+ * client per request would restart the counting every time and never conclude anything.
+ *
+ * Recency is a `Map`, which preserves insertion order: re-inserting a key moves it to the end, so
+ * the first key the map yields is the least recently used one.
+ */
+export class CamusPreparedStatementPolicy {
+    static DEFAULT_MAX_AUTO_PREPARE = 128;
+    static DEFAULT_MIN_USAGES = 2;
+    static shared = new SharedRegistry();
+    /** The process-wide policy for a deployment-and-settings key. */
+    static forKey(key, factory) {
+        return CamusPreparedStatementPolicy.shared.get(key, factory);
+    }
+    /** @internal Test hook: drops every shared policy. */
+    static resetShared() {
+        CamusPreparedStatementPolicy.shared.clear();
+    }
+    maxAutoPrepare;
+    minUsages;
+    entries = new Map();
+    disabled;
+    constructor(maxAutoPrepare, minUsages) {
+        this.maxAutoPrepare = maxAutoPrepare;
+        this.minUsages = Math.max(1, minUsages);
+        this.disabled = maxAutoPrepare <= 0;
+    }
+    /** True when automatic preparation is off, either by configuration or because a server refused. */
+    get isDisabled() {
+        return this.disabled;
+    }
+    /** How many statements are currently kept prepared. */
+    get preparedCount() {
+        let count = 0;
+        for (const entry of this.entries.values()) {
+            if (entry.state === EntryState.Prepared)
+                count++;
+        }
+        return count;
+    }
+    /** Whether one statement is currently kept prepared. */
+    isPrepared(database, sql) {
+        return this.entries.get(key(database, sql))?.state === EntryState.Prepared;
+    }
+    /** Decides what this execution should do, and reports a statement the decision evicted. */
+    decide(database, sql) {
+        if (this.disabled)
+            return { decision: PrepareDecision.No };
+        const { entry, evicted } = this.touch(database, sql);
+        switch (entry.state) {
+            case EntryState.Prepared:
+                return { decision: PrepareDecision.Yes, ...(evicted ? { evicted } : {}) };
+            case EntryState.Refused:
+                return { decision: PrepareDecision.No, ...(evicted ? { evicted } : {}) };
+            case EntryState.Registering:
+                // A registration is already in flight. Running inline meanwhile is correct rather than
+                // merely tolerable: the statement is not registered yet.
+                return { decision: PrepareDecision.No, ...(evicted ? { evicted } : {}) };
+            default:
+                if (++entry.usages < this.minUsages) {
+                    return { decision: PrepareDecision.No, ...(evicted ? { evicted } : {}) };
+                }
+                entry.state = EntryState.Registering;
+                return { decision: PrepareDecision.Register, ...(evicted ? { evicted } : {}) };
+        }
+    }
+    /**
+     * Marks a statement for registration because the caller asked for it directly.
+     *
+     * An explicit request overrides an earlier refusal: the caller may well have fixed whatever made
+     * it fail, and it is asking rather than being guessed at.
+     */
+    pin(database, sql) {
+        const { entry, evicted } = this.touch(database, sql);
+        if (entry.state === EntryState.Prepared) {
+            return { decision: PrepareDecision.Yes, ...(evicted ? { evicted } : {}) };
+        }
+        entry.state = EntryState.Registering;
+        entry.usages = Math.max(entry.usages, this.minUsages);
+        return { decision: PrepareDecision.Register, ...(evicted ? { evicted } : {}) };
+    }
+    /** Records that the server registered a statement. */
+    markPrepared(database, sql) {
+        const entry = this.entries.get(key(database, sql));
+        if (entry !== undefined)
+            entry.state = EntryState.Prepared;
+    }
+    /** Records that this statement should not be offered for registration again. */
+    markRefused(database, sql) {
+        const entry = this.entries.get(key(database, sql));
+        if (entry !== undefined)
+            entry.state = EntryState.Refused;
+    }
+    /** Stops offering any statement for registration. Used when a server has no support at all. */
+    disable() {
+        this.disabled = true;
+    }
+    /** Drops what is known about a statement, so it is reconsidered from the start. */
+    forget(database, sql) {
+        this.entries.delete(key(database, sql));
+    }
+    touch(database, sql) {
+        const entryKey = key(database, sql);
+        const existing = this.entries.get(entryKey);
+        if (existing !== undefined) {
+            // Re-inserting moves the key to the end of the map's order, which is the recency list.
+            this.entries.delete(entryKey);
+            this.entries.set(entryKey, existing);
+            return { entry: existing };
+        }
+        let evicted;
+        if (this.entries.size >= this.maxAutoPrepare) {
+            const oldestKey = this.entries.keys().next().value;
+            if (oldestKey !== undefined) {
+                const oldest = this.entries.get(oldestKey);
+                this.entries.delete(oldestKey);
+                // Only a registered statement is worth telling the caller about. The rest were never more
+                // than a counter.
+                if (oldest.state === EntryState.Prepared) {
+                    evicted = { database: oldest.database, sql: oldest.sql };
+                }
+            }
+        }
+        const entry = { database, sql, usages: 0, state: EntryState.Counting };
+        this.entries.set(entryKey, entry);
+        return { entry, ...(evicted ? { evicted } : {}) };
+    }
+}
+// A newline cannot appear in a database name, so it separates the two parts without ambiguity.
+function key(database, sql) {
+    return `${database}\n${sql}`;
+}
+//# sourceMappingURL=policy.js.map

package/dist/prepared/policy.js.map

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

package/dist/query-stream.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 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 { CamusColumn } from './result-set.js';
+import type { CamusRowSource } from './row-source.js';
+import type { DecodeOptions } from './values/decode.js';
+/**
+ * Rows delivered one at a time, as an async iterable.
+ *
+ * Iterate it with `for await`. The iteration owns the underlying response, and releases it when it
+ * ends — whether it ran to the last row, was left early with `break`, or was ended by a `throw`.
+ * A stream that is never iterated must be released with `close`, or with `await using`.
+ *
+ * ```ts
+ * const stream = await client.queryStream<Robot>('SELECT * FROM robots');
+ *
+ * for await (const robot of stream) {
+ *   console.log(robot.name);
+ * }
+ * ```
+ *
+ * The schema is known before the first row, so `columns` can be read straight away.
+ *
+ * The streaming path gives up the buffered path's transparent retry of a serializable conflict.
+ * Rows can reach this side before the statement's own short transaction commits, so a conflict
+ * that surfaces late is raised from the iteration rather than retried. Use `query` — or drive an
+ * explicit transaction and retry it yourself — when you need that retry.
+ */
+export declare class CamusQueryStream<T = Record<string, unknown>> implements AsyncIterable<T>, AsyncDisposable {
+    private readonly source;
+    private readonly mapper;
+    private consumed;
+    private closed;
+    /** @internal Built by `CamusClient.queryStream`. */
+    constructor(source: CamusRowSource, options: DecodeOptions);
+    /** The output columns, known before the first row. */
+    get columns(): CamusColumn[];
+    /**
+     * The property names each row object carries, in column order.
+     *
+     * They match `columns` except where a query projected the same column name twice: the leftmost
+     * keeps the name, and the ones after it take `name_2`, `name_3`, and so on.
+     */
+    get columnKeys(): readonly string[];
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+    /** Reads every remaining row into an array. Convenient when the result is known to be small. */
+    toArray(): Promise<T[]>;
+    /** Releases the underlying response. Safe to call more than once. */
+    close(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+}
+//# sourceMappingURL=query-stream.d.ts.map

package/dist/query-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-stream.d.ts","sourceRoot":"","sources":["../src/query-stream.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAGxD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,gBAAgB,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAE,YAAW,aAAa,CAAC,CAAC,CAAC,EAAE,eAAe;IACrG,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiB;IAExC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAY;IAEnC,OAAO,CAAC,QAAQ,CAAS;IAEzB,OAAO,CAAC,MAAM,CAAS;IAEvB,oDAAoD;gBACxC,MAAM,EAAE,cAAc,EAAE,OAAO,EAAE,aAAa;IAK1D,sDAAsD;IACtD,IAAI,OAAO,IAAI,WAAW,EAAE,CAM3B;IAED;;;;;OAKG;IACH,IAAI,UAAU,IAAI,SAAS,MAAM,EAAE,CAElC;IAEM,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,aAAa,CAAC,CAAC,CAAC;IAoBjD,gGAAgG;IAC1F,OAAO,IAAI,OAAO,CAAC,CAAC,EAAE,CAAC;IAQ7B,qEAAqE;IAC/D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAOtB,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7C"}

package/dist/query-stream.js

@@ -0,0 +1,94 @@
+/**
+ * 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 { RowMapper } from './result-set.js';
+import { columnTypeName } from './column-type.js';
+/**
+ * Rows delivered one at a time, as an async iterable.
+ *
+ * Iterate it with `for await`. The iteration owns the underlying response, and releases it when it
+ * ends — whether it ran to the last row, was left early with `break`, or was ended by a `throw`.
+ * A stream that is never iterated must be released with `close`, or with `await using`.
+ *
+ * ```ts
+ * const stream = await client.queryStream<Robot>('SELECT * FROM robots');
+ *
+ * for await (const robot of stream) {
+ *   console.log(robot.name);
+ * }
+ * ```
+ *
+ * The schema is known before the first row, so `columns` can be read straight away.
+ *
+ * The streaming path gives up the buffered path's transparent retry of a serializable conflict.
+ * Rows can reach this side before the statement's own short transaction commits, so a conflict
+ * that surfaces late is raised from the iteration rather than retried. Use `query` — or drive an
+ * explicit transaction and retry it yourself — when you need that retry.
+ */
+export class CamusQueryStream {
+    source;
+    mapper;
+    consumed = false;
+    closed = false;
+    /** @internal Built by `CamusClient.queryStream`. */
+    constructor(source, options) {
+        this.source = source;
+        this.mapper = new RowMapper(source.columnNames, options);
+    }
+    /** The output columns, known before the first row. */
+    get columns() {
+        return this.source.columnNames.map((name, index) => ({
+            name,
+            type: this.source.columnTypes[index],
+            typeName: columnTypeName(this.source.columnTypes[index]),
+        }));
+    }
+    /**
+     * The property names each row object carries, in column order.
+     *
+     * They match `columns` except where a query projected the same column name twice: the leftmost
+     * keeps the name, and the ones after it take `name_2`, `name_3`, and so on.
+     */
+    get columnKeys() {
+        return this.mapper.columnKeys;
+    }
+    async *[Symbol.asyncIterator]() {
+        if (this.consumed) {
+            throw new Error('This query stream was already iterated. Run the query again for a second pass.');
+        }
+        this.consumed = true;
+        try {
+            for (;;) {
+                const cells = await this.source.next();
+                if (cells === undefined)
+                    return;
+                yield this.mapper.map(cells);
+            }
+        }
+        finally {
+            // Reached on a normal end, on `break`, and on a throw, so the response is never left open.
+            await this.close();
+        }
+    }
+    /** Reads every remaining row into an array. Convenient when the result is known to be small. */
+    async toArray() {
+        const rows = [];
+        for await (const row of this)
+            rows.push(row);
+        return rows;
+    }
+    /** Releases the underlying response. Safe to call more than once. */
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        await this.source.close();
+    }
+    async [Symbol.asyncDispose]() {
+        await this.close();
+    }
+}
+//# sourceMappingURL=query-stream.js.map

package/dist/query-stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-stream.js","sourceRoot":"","sources":["../src/query-stream.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAG5C,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,OAAO,gBAAgB;IACV,MAAM,CAAiB;IAEvB,MAAM,CAAY;IAE3B,QAAQ,GAAG,KAAK,CAAC;IAEjB,MAAM,GAAG,KAAK,CAAC;IAEvB,oDAAoD;IACpD,YAAY,MAAsB,EAAE,OAAsB;QACxD,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,MAAM,GAAG,IAAI,SAAS,CAAC,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;IAC3D,CAAC;IAED,sDAAsD;IACtD,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;YACnD,IAAI;YACJ,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,KAAK,CAAE;YACrC,QAAQ,EAAE,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,KAAK,CAAE,CAAC;SAC1D,CAAC,CAAC,CAAC;IACN,CAAC;IAED;;;;;OAKG;IACH,IAAI,UAAU;QACZ,OAAO,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC;IAChC,CAAC;IAED,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC;QAC3B,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAClB,MAAM,IAAI,KAAK,CAAC,gFAAgF,CAAC,CAAC;QACpG,CAAC;QAED,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QAErB,IAAI,CAAC;YACH,SAAS,CAAC;gBACR,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;gBACvC,IAAI,KAAK,KAAK,SAAS;oBAAE,OAAO;gBAEhC,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAI,KAAK,CAAC,CAAC;YAClC,CAAC;QACH,CAAC;gBAAS,CAAC;YACT,2FAA2F;YAC3F,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC;QACrB,CAAC;IACH,CAAC;IAED,gGAAgG;IAChG,KAAK,CAAC,OAAO;QACX,MAAM,IAAI,GAAQ,EAAE,CAAC;QAErB,IAAI,KAAK,EAAE,MAAM,GAAG,IAAI,IAAI;YAAE,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAE7C,OAAO,IAAI,CAAC;IACd,CAAC;IAED,qEAAqE;IACrE,KAAK,CAAC,KAAK;QACT,IAAI,IAAI,CAAC,MAAM;YAAE,OAAO;QAExB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACnB,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;IAC5B,CAAC;IAED,KAAK,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC;QACzB,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;CACF"}

package/dist/result-set.d.ts

@@ -0,0 +1,62 @@
+/**
+ * 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 { ColumnType } from './column-type.js';
+import type { ColumnValue } from './column-value.js';
+import type { DecodeOptions } from './values/decode.js';
+/** One output column of a query. */
+export interface CamusColumn {
+    /** The column name, in the case the query wrote it. */
+    readonly name: string;
+    /** The declared wire type. */
+    readonly type: ColumnType;
+    /** The type's name, for display. */
+    readonly typeName: string;
+}
+/**
+ * The rows of one query, held positionally.
+ *
+ * Cells live in a single flat array, row-major: cell `(row, column)` is at
+ * `row * columnCount + column`. The column names and declared types come from the response's
+ * authoritative schema, so the shape is known even when there are no rows — which is what lets a
+ * caller read `columns` before reading a row, and what makes an empty result still describe
+ * itself.
+ */
+export declare class CamusResultSet {
+    /** An empty result: no rows and no columns. Shared, so a count-only reply allocates nothing. */
+    static readonly EMPTY: CamusResultSet;
+    readonly columnNames: readonly string[];
+    readonly columnTypes: readonly ColumnType[];
+    readonly rowCount: number;
+    private readonly cells;
+    constructor(columnNames: readonly string[], columnTypes: readonly ColumnType[], cells: readonly ColumnValue[], rowCount: number);
+    get columnCount(): number;
+    /** The output columns, in order. */
+    get columns(): CamusColumn[];
+    /** One raw cell. */
+    cell(row: number, column: number): ColumnValue;
+    /** One row as raw cells. */
+    rawRow(row: number): ColumnValue[];
+}
+/**
+ * Turns positional cells into a plain object, keyed by column name.
+ *
+ * A duplicate column name — which a join projection can produce — keeps the leftmost column, and
+ * the ones after it are reachable at `name_2`, `name_3`, and so on. Silently dropping a column
+ * would lose data the query asked for.
+ */
+export declare class RowMapper {
+    private readonly keys;
+    private readonly options;
+    constructor(columnNames: readonly string[], options: DecodeOptions);
+    /** The object keys this mapper writes, in column order. */
+    get columnKeys(): readonly string[];
+    /** One row as an object. */
+    map<T>(cells: readonly ColumnValue[]): T;
+    /** Every row of a result set as objects. */
+    mapAll<T>(resultSet: CamusResultSet): T[];
+}
+//# sourceMappingURL=result-set.d.ts.map

package/dist/result-set.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result-set.d.ts","sourceRoot":"","sources":["../src/result-set.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,UAAU,EAAkB,MAAM,kBAAkB,CAAC;AAC9D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAGxD,oCAAoC;AACpC,MAAM,WAAW,WAAW;IAC1B,uDAAuD;IACvD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,8BAA8B;IAC9B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAE1B,oCAAoC;IACpC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;GAQG;AACH,qBAAa,cAAc;IACzB,gGAAgG;IAChG,MAAM,CAAC,QAAQ,CAAC,KAAK,iBAAqC;IAE1D,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IAExC,QAAQ,CAAC,WAAW,EAAE,SAAS,UAAU,EAAE,CAAC;IAE5C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAyB;gBAG7C,WAAW,EAAE,SAAS,MAAM,EAAE,EAC9B,WAAW,EAAE,SAAS,UAAU,EAAE,EAClC,KAAK,EAAE,SAAS,WAAW,EAAE,EAC7B,QAAQ,EAAE,MAAM;IAQlB,IAAI,WAAW,IAAI,MAAM,CAExB;IAED,oCAAoC;IACpC,IAAI,OAAO,IAAI,WAAW,EAAE,CAM3B;IAED,oBAAoB;IACpB,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,WAAW;IAI9C,4BAA4B;IAC5B,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,EAAE;CAInC;AAED;;;;;;GAMG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAW;IAEhC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgB;gBAE5B,WAAW,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,EAAE,aAAa;IAelE,2DAA2D;IAC3D,IAAI,UAAU,IAAI,SAAS,MAAM,EAAE,CAElC;IAED,4BAA4B;IAC5B,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,WAAW,EAAE,GAAG,CAAC;IAUxC,4CAA4C;IAC5C,MAAM,CAAC,CAAC,EAAE,SAAS,EAAE,cAAc,GAAG,CAAC,EAAE;CAgB1C"}

package/dist/result-set.js

@@ -0,0 +1,100 @@
+/**
+ * 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 { ColumnType, columnTypeName } from './column-type.js';
+import { NULL_VALUE } from './column-value.js';
+import { decodeValue } from './values/decode.js';
+/**
+ * The rows of one query, held positionally.
+ *
+ * Cells live in a single flat array, row-major: cell `(row, column)` is at
+ * `row * columnCount + column`. The column names and declared types come from the response's
+ * authoritative schema, so the shape is known even when there are no rows — which is what lets a
+ * caller read `columns` before reading a row, and what makes an empty result still describe
+ * itself.
+ */
+export class CamusResultSet {
+    /** An empty result: no rows and no columns. Shared, so a count-only reply allocates nothing. */
+    static EMPTY = new CamusResultSet([], [], [], 0);
+    columnNames;
+    columnTypes;
+    rowCount;
+    cells;
+    constructor(columnNames, columnTypes, cells, rowCount) {
+        this.columnNames = columnNames;
+        this.columnTypes = columnTypes;
+        this.cells = cells;
+        this.rowCount = rowCount;
+    }
+    get columnCount() {
+        return this.columnNames.length;
+    }
+    /** The output columns, in order. */
+    get columns() {
+        return this.columnNames.map((name, index) => ({
+            name,
+            type: this.columnTypes[index] ?? ColumnType.Null,
+            typeName: columnTypeName(this.columnTypes[index] ?? ColumnType.Null),
+        }));
+    }
+    /** One raw cell. */
+    cell(row, column) {
+        return this.cells[row * this.columnCount + column] ?? NULL_VALUE;
+    }
+    /** One row as raw cells. */
+    rawRow(row) {
+        const start = row * this.columnCount;
+        return this.cells.slice(start, start + this.columnCount);
+    }
+}
+/**
+ * Turns positional cells into a plain object, keyed by column name.
+ *
+ * A duplicate column name — which a join projection can produce — keeps the leftmost column, and
+ * the ones after it are reachable at `name_2`, `name_3`, and so on. Silently dropping a column
+ * would lose data the query asked for.
+ */
+export class RowMapper {
+    keys;
+    options;
+    constructor(columnNames, options) {
+        this.options = options;
+        this.keys = new Array(columnNames.length);
+        const used = new Map();
+        for (let i = 0; i < columnNames.length; i++) {
+            const name = columnNames[i] ?? `column_${String(i + 1)}`;
+            const seen = used.get(name) ?? 0;
+            used.set(name, seen + 1);
+            this.keys[i] = seen === 0 ? name : `${name}_${String(seen + 1)}`;
+        }
+    }
+    /** The object keys this mapper writes, in column order. */
+    get columnKeys() {
+        return this.keys;
+    }
+    /** One row as an object. */
+    map(cells) {
+        const row = {};
+        for (let i = 0; i < this.keys.length; i++) {
+            row[this.keys[i]] = decodeValue(cells[i] ?? NULL_VALUE, this.options);
+        }
+        return row;
+    }
+    /** Every row of a result set as objects. */
+    mapAll(resultSet) {
+        const columnCount = resultSet.columnCount;
+        const rows = new Array(resultSet.rowCount);
+        for (let r = 0; r < resultSet.rowCount; r++) {
+            const row = {};
+            for (let c = 0; c < columnCount; c++) {
+                row[this.keys[c]] = decodeValue(resultSet.cell(r, c), this.options);
+            }
+            rows[r] = row;
+        }
+        return rows;
+    }
+}
+//# sourceMappingURL=result-set.js.map