camusdb 0.6.0 → 0.8.0

package/dist/pipeline.d.ts

@@ -0,0 +1,136 @@
+/**
+ * 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 { ExecuteResult, QueryResult } from './client.js';
+import type { ClientRuntime } from './runtime.js';
+import type { CamusTransaction } from './transaction.js';
+import type { Int64Mode } from './values/decode.js';
+import type { Parameters } from './values/encode.js';
+/** What one queued read may override for itself. */
+export interface PipelineQueryOptions {
+    /** How an `int64` column reaches the caller, for this statement alone. */
+    readonly int64?: Int64Mode | undefined;
+}
+/**
+ * Several statements of one `CamusTransaction`, sent together as one exchange and answered
+ * together.
+ *
+ * A transaction that awaits each statement pays one round trip per statement: six for a bank
+ * transfer (`BEGIN`, two reads, two writes, `COMMIT`). At high concurrency those round trips, and
+ * not the statements, set its latency. A pipeline queues the statements whose inputs are known,
+ * sends them as one stream message, and settles each statement's promise from its own answer.
+ *
+ * ```ts
+ * const txn = await client.beginTransaction({ deferBegin: true });
+ * const pipeline = txn.pipeline();
+ *
+ * // Exchange 1: [BEGIN, SELECT a, SELECT b]
+ * const readA = pipeline.query<{ balance: number }>('SELECT balance FROM accounts WHERE id = @id', { id: a });
+ * const readB = pipeline.query<{ balance: number }>('SELECT balance FROM accounts WHERE id = @id', { id: b });
+ * await pipeline.send();
+ *
+ * const from = (await readA).rows[0]!.balance;
+ * const to = (await readB).rows[0]!.balance;
+ *
+ * // Exchange 2: [UPDATE a, UPDATE b, COMMIT]. The commit happens only if both updates succeed.
+ * pipeline.execute('UPDATE accounts SET balance = @v WHERE id = @id', { v: from - amount, id: a });
+ * pipeline.execute('UPDATE accounts SET balance = @v WHERE id = @id', { v: to + amount, id: b });
+ * await pipeline.commit();
+ * ```
+ *
+ * **Shape.** Queue with `query` and `execute`. Each returns the promise for that statement's result.
+ * Then call `send` to run what is queued, or `commit` to run it and commit the transaction in the
+ * same exchange. That commit happens only when every statement of the transaction succeeded. A
+ * transaction begun with `deferBegin`, or with learned routing on, sends its `BEGIN` inside the
+ * first exchange too.
+ *
+ * **Failure.** Every queued promise settles with its own result or its own `CamusError`, as a lone
+ * statement does. The statements after a failed one in the same exchange still get an answer. The
+ * transaction has ended, so they fail too. The send itself rejects with the first failure, so a
+ * caller that awaits only the send still learns of it. A queued promise that nobody awaits is never
+ * reported as an unhandled rejection. After a failed `commit`, the server has rolled the
+ * transaction back, and `rollback` is a harmless call. To retry, run the whole transaction again
+ * from `BEGIN`.
+ *
+ * **Order and reuse.** The queued statements run in queue order, after every statement of the
+ * transaction sent before them. So a pipeline can be sent more than once on one transaction, and an
+ * ordinary statement can run between two sends. One send at a time per pipeline. `exchanges`
+ * reports the round trips used. It is one per send over gRPC to a server that reads the pipeline
+ * contract. Over REST, with `requestFrames` off, or against an older server, it is one per
+ * statement, with the same results.
+ */
+export declare class CamusPipeline {
+    private readonly transactionValue;
+    private readonly runtime;
+    private readonly queued;
+    private exchangesValue;
+    private sending;
+    /** @internal Use `CamusTransaction.pipeline`. */
+    constructor(transaction: CamusTransaction, runtime: ClientRuntime);
+    /** The transaction that every queued statement runs in. */
+    get transaction(): CamusTransaction;
+    /** How many statements are queued and not sent yet. */
+    get size(): number;
+    /**
+     * The round trips this pipeline has cost so far. A send that travelled as one stream message
+     * costs one. A send that did not costs one for each step: the `BEGIN`, each statement, and the
+     * commit.
+     */
+    get exchanges(): number;
+    /**
+     * Queues a statement that returns rows, and reports the promise for them. That is a `SELECT`, or
+     * an `INSERT`, `UPDATE`, or `DELETE` with a `RETURNING` list. A write reports its written-row
+     * count in `affectedRows`. A `CALL` is also accepted: it has no rows, and it reports in
+     * `affectedRows` the number of rows that the procedure's SQL changed. The promise settles when the pipeline is sent and the statement is
+     * answered.
+     *
+     * @throws {CamusError} at once, for a statement that cannot run inside the transaction (DDL and
+     * `TRUNCATE`), and while a send is in progress.
+     */
+    query<T = Record<string, unknown>>(sql: string, parameters?: Parameters, options?: PipelineQueryOptions): Promise<QueryResult<T>>;
+    /**
+     * Queues a write, and reports the promise for its affected-row count. For a write with
+     * `RETURNING`, the server sends the count only. The promise settles when the pipeline is sent
+     * and the statement is answered.
+     *
+     * @throws {CamusError} at once, for a statement that cannot run inside the transaction (DDL and
+     * `TRUNCATE`), and while a send is in progress.
+     */
+    execute(sql: string, parameters?: Parameters): Promise<ExecuteResult>;
+    /**
+     * Queues `CALL procedure(@a, @b, ...)` for a procedure that a C# extension on the server defines,
+     * and reports the promise for the number of rows that the procedure's SQL changed. The arguments
+     * follow the order of the parameter object's keys, as in `CamusClient.call`.
+     *
+     * @throws {TypeError} at once, when `procedure` is not a plain identifier.
+     * @throws {CamusError} at once, while a send is in progress.
+     */
+    call(procedure: string, parameters?: Parameters): Promise<ExecuteResult>;
+    /**
+     * Sends the queued statements as one exchange, and waits for every answer. It rejects with the
+     * first failure, if any. Each statement's own promise carries its own outcome.
+     */
+    send(signal?: AbortSignal): Promise<void>;
+    /**
+     * Sends the queued statements and the transaction's commit as one exchange.
+     *
+     * The commit happens only when every statement of the transaction succeeded, in this send and
+     * before it. If not, the server rolls the transaction back, and this rejects with the first
+     * failure. After a success the transaction is committed, and `CamusTransaction.commit` must not
+     * be called again.
+     */
+    commit(signal?: AbortSignal): Promise<void>;
+    private add;
+    private flush;
+    private exchange;
+    /**
+     * Where a transaction that has not begun yet begins: the first statement's learned route when
+     * the client routes, and the pool's rotation if not. That is the choice a lone first statement
+     * makes.
+     */
+    private chooseEndpoint;
+}
+//# sourceMappingURL=pipeline.d.ts.map

package/dist/pipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../src/pipeline.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAQ9D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAIlD,OAAO,KAAK,EAAE,gBAAgB,EAAc,MAAM,kBAAkB,CAAC;AAOrE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAGrD,oDAAoD;AACpD,MAAM,WAAW,oBAAoB;IACnC,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;CACxC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAmB;IAEpD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgB;IAExC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAyB;IAEhD,OAAO,CAAC,cAAc,CAAK;IAE3B,OAAO,CAAC,OAAO,CAAS;IAExB,iDAAiD;gBACrC,WAAW,EAAE,gBAAgB,EAAE,OAAO,EAAE,aAAa;IAKjE,2DAA2D;IAC3D,IAAI,WAAW,IAAI,gBAAgB,CAElC;IAED,uDAAuD;IACvD,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;;OAIG;IACH,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED;;;;;;;;;OASG;IACH,KAAK,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,GAAG,EAAE,MAAM,EACX,UAAU,CAAC,EAAE,UAAU,EACvB,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IAM1B;;;;;;;OAOG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,aAAa,CAAC;IAMrE;;;;;;;OAOG;IACH,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,aAAa,CAAC;IAIxE;;;OAGG;IACH,IAAI,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAIzC;;;;;;;OAOG;IACH,MAAM,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAI3C,OAAO,CAAC,GAAG;YA2CG,KAAK;YAwBL,QAAQ;IAuHtB;;;;OAIG;IACH,OAAO,CAAC,cAAc;CAYvB"}

package/dist/pipeline.js

@@ -0,0 +1,375 @@
+/**
+ * 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 { shouldPrepare } from './prepared/auto-prepare.js';
+import { CamusResultSet, RowMapper } from './result-set.js';
+import { ROUTING_ACCEPT_VERSION } from './routing/advice.js';
+import { CamusRouteOpKind } from './routing/route-cache.js';
+import { callStatement, isDdlStatement, isDmlStatement, runsInOwnTransaction } from './statements.js';
+import { traced } from './telemetry.js';
+import { firstPipelineFailure } from './transport/transport.js';
+import { encodeParameters } from './values/encode.js';
+/**
+ * Several statements of one `CamusTransaction`, sent together as one exchange and answered
+ * together.
+ *
+ * A transaction that awaits each statement pays one round trip per statement: six for a bank
+ * transfer (`BEGIN`, two reads, two writes, `COMMIT`). At high concurrency those round trips, and
+ * not the statements, set its latency. A pipeline queues the statements whose inputs are known,
+ * sends them as one stream message, and settles each statement's promise from its own answer.
+ *
+ * ```ts
+ * const txn = await client.beginTransaction({ deferBegin: true });
+ * const pipeline = txn.pipeline();
+ *
+ * // Exchange 1: [BEGIN, SELECT a, SELECT b]
+ * const readA = pipeline.query<{ balance: number }>('SELECT balance FROM accounts WHERE id = @id', { id: a });
+ * const readB = pipeline.query<{ balance: number }>('SELECT balance FROM accounts WHERE id = @id', { id: b });
+ * await pipeline.send();
+ *
+ * const from = (await readA).rows[0]!.balance;
+ * const to = (await readB).rows[0]!.balance;
+ *
+ * // Exchange 2: [UPDATE a, UPDATE b, COMMIT]. The commit happens only if both updates succeed.
+ * pipeline.execute('UPDATE accounts SET balance = @v WHERE id = @id', { v: from - amount, id: a });
+ * pipeline.execute('UPDATE accounts SET balance = @v WHERE id = @id', { v: to + amount, id: b });
+ * await pipeline.commit();
+ * ```
+ *
+ * **Shape.** Queue with `query` and `execute`. Each returns the promise for that statement's result.
+ * Then call `send` to run what is queued, or `commit` to run it and commit the transaction in the
+ * same exchange. That commit happens only when every statement of the transaction succeeded. A
+ * transaction begun with `deferBegin`, or with learned routing on, sends its `BEGIN` inside the
+ * first exchange too.
+ *
+ * **Failure.** Every queued promise settles with its own result or its own `CamusError`, as a lone
+ * statement does. The statements after a failed one in the same exchange still get an answer. The
+ * transaction has ended, so they fail too. The send itself rejects with the first failure, so a
+ * caller that awaits only the send still learns of it. A queued promise that nobody awaits is never
+ * reported as an unhandled rejection. After a failed `commit`, the server has rolled the
+ * transaction back, and `rollback` is a harmless call. To retry, run the whole transaction again
+ * from `BEGIN`.
+ *
+ * **Order and reuse.** The queued statements run in queue order, after every statement of the
+ * transaction sent before them. So a pipeline can be sent more than once on one transaction, and an
+ * ordinary statement can run between two sends. One send at a time per pipeline. `exchanges`
+ * reports the round trips used. It is one per send over gRPC to a server that reads the pipeline
+ * contract. Over REST, with `requestFrames` off, or against an older server, it is one per
+ * statement, with the same results.
+ */
+export class CamusPipeline {
+    transactionValue;
+    runtime;
+    queued = [];
+    exchangesValue = 0;
+    sending = false;
+    /** @internal Use `CamusTransaction.pipeline`. */
+    constructor(transaction, runtime) {
+        this.transactionValue = transaction;
+        this.runtime = runtime;
+    }
+    /** The transaction that every queued statement runs in. */
+    get transaction() {
+        return this.transactionValue;
+    }
+    /** How many statements are queued and not sent yet. */
+    get size() {
+        return this.queued.length;
+    }
+    /**
+     * The round trips this pipeline has cost so far. A send that travelled as one stream message
+     * costs one. A send that did not costs one for each step: the `BEGIN`, each statement, and the
+     * commit.
+     */
+    get exchanges() {
+        return this.exchangesValue;
+    }
+    /**
+     * Queues a statement that returns rows, and reports the promise for them. That is a `SELECT`, or
+     * an `INSERT`, `UPDATE`, or `DELETE` with a `RETURNING` list. A write reports its written-row
+     * count in `affectedRows`. A `CALL` is also accepted: it has no rows, and it reports in
+     * `affectedRows` the number of rows that the procedure's SQL changed. The promise settles when the pipeline is sent and the statement is
+     * answered.
+     *
+     * @throws {CamusError} at once, for a statement that cannot run inside the transaction (DDL and
+     * `TRUNCATE`), and while a send is in progress.
+     */
+    query(sql, parameters, options = {}) {
+        const statement = this.add(sql, parameters, true, options.int64);
+        return statement.promise;
+    }
+    /**
+     * Queues a write, and reports the promise for its affected-row count. For a write with
+     * `RETURNING`, the server sends the count only. The promise settles when the pipeline is sent
+     * and the statement is answered.
+     *
+     * @throws {CamusError} at once, for a statement that cannot run inside the transaction (DDL and
+     * `TRUNCATE`), and while a send is in progress.
+     */
+    execute(sql, parameters) {
+        const statement = this.add(sql, parameters, false, undefined);
+        return statement.promise;
+    }
+    /**
+     * Queues `CALL procedure(@a, @b, ...)` for a procedure that a C# extension on the server defines,
+     * and reports the promise for the number of rows that the procedure's SQL changed. The arguments
+     * follow the order of the parameter object's keys, as in `CamusClient.call`.
+     *
+     * @throws {TypeError} at once, when `procedure` is not a plain identifier.
+     * @throws {CamusError} at once, while a send is in progress.
+     */
+    call(procedure, parameters) {
+        return this.execute(callStatement(procedure, parameters), parameters);
+    }
+    /**
+     * Sends the queued statements as one exchange, and waits for every answer. It rejects with the
+     * first failure, if any. Each statement's own promise carries its own outcome.
+     */
+    send(signal) {
+        return this.flush(false, signal);
+    }
+    /**
+     * Sends the queued statements and the transaction's commit as one exchange.
+     *
+     * The commit happens only when every statement of the transaction succeeded, in this send and
+     * before it. If not, the server rolls the transaction back, and this rejects with the first
+     * failure. After a success the transaction is committed, and `CamusTransaction.commit` must not
+     * be called again.
+     */
+    commit(signal) {
+        return this.flush(true, signal);
+    }
+    add(sql, parameters, asReader, int64) {
+        if (this.sending) {
+            throw new CamusError(CamusErrorCode.Generic, 'A send is in progress on this pipeline. Queue the statement after it completes.');
+        }
+        if (runsInOwnTransaction(sql)) {
+            throw new CamusError(CamusErrorCode.StatementNotAllowedInTransaction, 'This statement runs in its own transaction and cannot be pipelined.');
+        }
+        if (isDdlStatement(sql)) {
+            throw new CamusError(CamusErrorCode.Generic, 'A DDL statement cannot be pipelined, because it does not run inside the transaction.');
+        }
+        const dml = isDmlStatement(sql);
+        const statement = new QueuedStatement(sql, encodeParameters(parameters), asReader, asReader && !dml ? 'query' : 'nonQuery', asReader && !dml ? CamusRouteOpKind.Query : CamusRouteOpKind.NonQuery, int64 ?? this.runtime.config.decode.int64);
+        this.queued.push(statement);
+        return statement;
+    }
+    async flush(commit, signal) {
+        if (this.sending) {
+            throw new CamusError(CamusErrorCode.Generic, 'A send is already in progress on this pipeline.');
+        }
+        if (this.queued.length === 0 && !commit)
+            return;
+        const batch = this.queued.splice(0);
+        this.sending = true;
+        try {
+            // One span for the exchange. Its statements get no spans of their own: they travel together,
+            // and the server answers them together.
+            await traced(this.runtime, { operationName: 'BATCH', batchSize: batch.length }, (operation) => {
+                operation?.setAttribute('camusdb.pipeline.commit', commit);
+                return this.exchange(batch, commit, signal, operation);
+            });
+        }
+        finally {
+            this.sending = false;
+        }
+    }
+    async exchange(batch, commit, signal, operation) {
+        const transaction = this.transactionValue;
+        const runtime = this.runtime;
+        let claim;
+        try {
+            if (transaction.isFinalized) {
+                throw new CamusError(CamusErrorCode.Generic, 'This transaction was already committed or rolled back.');
+            }
+            // The `BEGIN` rides this exchange when nothing has begun the transaction yet. When a
+            // statement is beginning it at this moment, wait for that instead: one `BEGIN` per
+            // transaction.
+            if (!transaction.isStarted) {
+                const start = transaction.claimStart();
+                claim = start.claim;
+                if (start.pending !== undefined)
+                    await start.pending;
+            }
+            const endpoint = transaction.endpoint ?? this.chooseEndpoint(batch);
+            const database = runtime.database;
+            operation?.setEndpoint(endpoint);
+            const router = runtime.router;
+            // Each statement's route entry is read before the exchange, pinned or not, for the reason a
+            // lone statement reads it: the reply's advice refreshes the route only if the entry has not
+            // moved since, so a late reply never overwrites what a faster one learned.
+            const observed = [];
+            const statements = [];
+            for (const statement of batch) {
+                statements.push({
+                    kind: statement.kind,
+                    sql: statement.sql,
+                    parameters: statement.parameters,
+                    prepared: await shouldPrepare(runtime, statement.sql, endpoint, { signal }),
+                    routingAcceptVersion: router !== undefined ? ROUTING_ACCEPT_VERSION : 0,
+                    ...(statement.kind === 'nonQuery' && !statement.asReader ? { discardReturningRows: true } : {}),
+                });
+                observed.push(router?.selectEndpoint(database, statement.sql, statement.routeKind).revision ?? 0);
+            }
+            const result = await runtime.transport.executePipeline({
+                endpoint,
+                database,
+                start: claim !== undefined ? transaction.options : undefined,
+                ...(claim === undefined
+                    ? {
+                        txnIdPT: transaction.txnIdPT,
+                        txnIdCounter: transaction.txnIdCounter,
+                        streamSlot: transaction.streamSlot,
+                    }
+                    : {}),
+                statements,
+                commit,
+                timeoutSeconds: runtime.timeoutSeconds,
+                signal,
+            });
+            this.exchangesValue += result.exchanges;
+            if (claim !== undefined) {
+                if (result.started !== undefined) {
+                    claim.resolve(result.started, endpoint);
+                }
+                else {
+                    claim.reject(result.startFailure ?? new CamusError(CamusErrorCode.Generic, 'The transaction did not begin.'));
+                }
+                claim = undefined;
+            }
+            batch.forEach((statement, i) => {
+                const outcome = result.statements[i] ?? {};
+                statement.settle(outcome);
+                // A pipelined statement teaches the router what a lone one would. Without this, the first
+                // exchange of every deferred transaction starts on the pool's rotation, most of them on a
+                // follower, and every statement of the transaction is forwarded from there.
+                const advice = outcome.query?.routing ?? outcome.nonQuery?.routing;
+                if (advice !== undefined) {
+                    router?.learn(database, statement.sql, statement.routeKind, advice, observed[i]);
+                }
+            });
+            if (commit && result.committed)
+                transaction.markCommittedByPipeline();
+            const first = firstPipelineFailure(result);
+            if (first !== undefined)
+                throw first;
+        }
+        catch (error) {
+            const failure = error instanceof Error ? error : new Error(String(error));
+            // A failure before the exchange, or of the exchange itself: nothing was settled. So settle it
+            // all with the one failure, the claim included, so that no caller waits forever.
+            claim?.reject(failure);
+            for (const statement of batch)
+                statement.fail(failure);
+            throw error;
+        }
+    }
+    /**
+     * Where a transaction that has not begun yet begins: the first statement's learned route when
+     * the client routes, and the pool's rotation if not. That is the choice a lone first statement
+     * makes.
+     */
+    chooseEndpoint(batch) {
+        const router = this.runtime.router;
+        const first = batch[0];
+        if (router !== undefined && first !== undefined) {
+            const learned = router.selectEndpoint(this.runtime.database, first.sql, first.routeKind);
+            if (learned.endpoint !== undefined)
+                return learned.endpoint;
+        }
+        return this.runtime.nextEndpoint();
+    }
+}
+/** One queued statement, and the promise its caller holds. */
+class QueuedStatement {
+    sql;
+    parameters;
+    asReader;
+    kind;
+    routeKind;
+    int64;
+    promise;
+    resolve;
+    reject;
+    settled = false;
+    constructor(sql, parameters, asReader, kind, routeKind, int64) {
+        this.sql = sql;
+        this.parameters = parameters;
+        this.asReader = asReader;
+        this.kind = kind;
+        this.routeKind = routeKind;
+        this.int64 = int64;
+        this.promise = new Promise((resolve, reject) => {
+            this.resolve = resolve;
+            this.reject = reject;
+        });
+        // A caller that awaits only the send, which rejects with the same failure, must not be charged
+        // with an unhandled rejection. A caller that awaits this promise still sees the failure.
+        this.promise.catch(() => undefined);
+    }
+    settle(outcome) {
+        if (outcome.failure !== undefined) {
+            this.fail(outcome.failure);
+            return;
+        }
+        if (this.asReader) {
+            if (outcome.query !== undefined) {
+                const { resultSet, cacheMetadata, routing } = outcome.query;
+                this.succeed({
+                    ...this.mapRows(resultSet),
+                    cacheMetadata,
+                    routingAdvice: routing,
+                });
+                return;
+            }
+            if (outcome.nonQuery !== undefined) {
+                const { returning, affectedRows, routing } = outcome.nonQuery;
+                this.succeed({
+                    ...this.mapRows(returning ?? CamusResultSet.EMPTY),
+                    affectedRows,
+                    routingAdvice: routing,
+                });
+                return;
+            }
+        }
+        else {
+            if (outcome.nonQuery !== undefined) {
+                this.succeed({
+                    affectedRows: outcome.nonQuery.affectedRows,
+                    routingAdvice: outcome.nonQuery.routing,
+                });
+                return;
+            }
+            if (outcome.query !== undefined) {
+                this.succeed({
+                    affectedRows: outcome.query.resultSet.rowCount,
+                    routingAdvice: outcome.query.routing,
+                });
+                return;
+            }
+        }
+        this.fail(new CamusError(CamusErrorCode.Generic, 'The statement was not answered.'));
+    }
+    fail(error) {
+        if (this.settled)
+            return;
+        this.settled = true;
+        this.reject(error);
+    }
+    succeed(value) {
+        if (this.settled)
+            return;
+        this.settled = true;
+        this.resolve(value);
+    }
+    mapRows(resultSet) {
+        const mapper = new RowMapper(resultSet.columnNames, { int64: this.int64 });
+        return { rows: mapper.mapAll(resultSet), columns: resultSet.columns, rowCount: resultSet.rowCount };
+    }
+}
+//# sourceMappingURL=pipeline.js.map

package/dist/pipeline.js.map

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

package/dist/prepared/auto-prepare.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 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 { ClientRuntime } from '../runtime.js';
+import type { EvictedStatement } from './policy.js';
+/** What one statement's prepare step reads from its caller. */
+export interface PrepareCallOptions {
+    readonly signal?: AbortSignal | undefined;
+    readonly timeoutSeconds?: number | undefined;
+}
+/**
+ * Whether this execution should name a prepared statement instead of carrying its SQL,
+ * registering it first when this is the execution that tips it over the threshold.
+ *
+ * The registration is awaited rather than started in the background, because the whole point is
+ * that this execution and the ones after it are cheap. Firing it off and running inline anyway
+ * would leave a busy statement racing its own warm-up. It costs one extra round trip, once per
+ * statement per endpoint.
+ *
+ * The caller passes the endpoint it already resolved. A REST handle is node-local and the pool
+ * rotates, so registering against a freshly drawn endpoint would routinely prepare on one node
+ * and execute on another — correct, because the transport re-registers where it lands, but a
+ * wasted round trip every single time.
+ */
+export declare function shouldPrepare(runtime: ClientRuntime, sql: string, endpoint: string, options: PrepareCallOptions): Promise<boolean>;
+/**
+ * Registers a statement and records what happened, reporting whether it may now run prepared.
+ *
+ * A registration failure never reaches the caller: preparing is an optimization, and the
+ * statement runs inline exactly as it would have if the driver had not tried. What the failure
+ * does decide is whether to ask again. A refusal specific to this statement stops asking for that
+ * statement; anything that says the node has no prepared-statement support at all stops asking
+ * for every statement, because one round trip per distinct SQL to relearn that is worse than not
+ * trying. A failure that never reached a verdict — a timeout, an unreachable node — drops the
+ * entry instead, so one network blip does not cost this statement its registration for the life
+ * of the process.
+ */
+export declare function registerStatement(runtime: ClientRuntime, endpoint: string, database: string, sql: string, options: PrepareCallOptions): Promise<boolean>;
+/**
+ * Releases a statement the policy evicted, so the server stops holding a handle this client has
+ * stopped using.
+ *
+ * It is best effort and off the caller's path: it is bookkeeping, not part of the statement being
+ * run. It takes the endpoint the caller already resolved rather than drawing a new one, which
+ * would rotate the pool as a side effect of housekeeping.
+ */
+export declare function releaseEvicted(runtime: ClientRuntime, endpoint: string, evicted: EvictedStatement | undefined): void;
+//# sourceMappingURL=auto-prepare.d.ts.map

package/dist/prepared/auto-prepare.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-prepare.d.ts","sourceRoot":"","sources":["../../src/prepared/auto-prepare.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AASnD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD,+DAA+D;AAC/D,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC9C;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,aAAa,EACtB,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,OAAO,CAAC,CAyBlB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,aAAa,EACtB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,OAAO,CAAC,CAyClB;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,aAAa,EACtB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,gBAAgB,GAAG,SAAS,GACpC,IAAI,CAMN"}