camusdb 0.1.0

package/dist/row-source.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 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 { ColumnType } from './column-type.js';
+import type { ColumnValue } from './column-value.js';
+import type { CamusResultSet } from './result-set.js';
+/**
+ * Where a query's rows come from.
+ *
+ * It abstracts the delivery mode so the row mapper is written once and works for both:
+ *
+ * - A buffered source over a whole `CamusResultSet` — what the ordinary query endpoint returns,
+ *   and what a write statement's affected-row count is wrapped in.
+ * - The streaming NDJSON source, which pulls rows off the network one line at a time as the caller
+ *   advances, so a result of many thousands of rows never fully materializes on this side.
+ *
+ * The schema is always known up front. The streaming source reads the NDJSON header line before
+ * the caller sees a row, so column names and types are reportable before, and independently of,
+ * the first row.
+ */
+export interface CamusRowSource extends AsyncDisposable {
+    /** Output column names, aligned with `columnTypes`. */
+    readonly columnNames: readonly string[];
+    /** Declared column types, aligned with `columnNames`. */
+    readonly columnTypes: readonly ColumnType[];
+    /** The affected-row count for a write statement, or -1 for a query. */
+    readonly recordsAffected: number;
+    /** Advances to the next row and reports its cells, or `undefined` at the end of the result. */
+    next(): Promise<readonly ColumnValue[] | undefined>;
+    /** Releases the underlying response. Safe to call more than once. */
+    close(): Promise<void>;
+}
+/** A source over a result set that is already in memory. */
+export declare class BufferedRowSource implements CamusRowSource {
+    private readonly resultSet;
+    private position;
+    readonly recordsAffected: number;
+    constructor(resultSet: CamusResultSet, recordsAffected?: number);
+    get columnNames(): readonly string[];
+    get columnTypes(): readonly ColumnType[];
+    next(): Promise<readonly ColumnValue[] | undefined>;
+    close(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+}
+//# sourceMappingURL=row-source.d.ts.map

package/dist/row-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"row-source.d.ts","sourceRoot":"","sources":["../src/row-source.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEtD;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,cAAe,SAAQ,eAAe;IACrD,uDAAuD;IACvD,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IAExC,yDAAyD;IACzD,QAAQ,CAAC,WAAW,EAAE,SAAS,UAAU,EAAE,CAAC;IAE5C,uEAAuE;IACvE,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IAEjC,+FAA+F;IAC/F,IAAI,IAAI,OAAO,CAAC,SAAS,WAAW,EAAE,GAAG,SAAS,CAAC,CAAC;IAEpD,qEAAqE;IACrE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,4DAA4D;AAC5D,qBAAa,iBAAkB,YAAW,cAAc;IACtD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAiB;IAE3C,OAAO,CAAC,QAAQ,CAAM;IAEtB,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;gBAErB,SAAS,EAAE,cAAc,EAAE,eAAe,SAAK;IAK3D,IAAI,WAAW,IAAI,SAAS,MAAM,EAAE,CAEnC;IAED,IAAI,WAAW,IAAI,SAAS,UAAU,EAAE,CAEvC;IAED,IAAI,IAAI,OAAO,CAAC,SAAS,WAAW,EAAE,GAAG,SAAS,CAAC;IAQnD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAIhB,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7C"}

package/dist/row-source.js

@@ -0,0 +1,35 @@
+/**
+ * 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.
+ */
+/** A source over a result set that is already in memory. */
+export class BufferedRowSource {
+    resultSet;
+    position = -1;
+    recordsAffected;
+    constructor(resultSet, recordsAffected = -1) {
+        this.resultSet = resultSet;
+        this.recordsAffected = recordsAffected;
+    }
+    get columnNames() {
+        return this.resultSet.columnNames;
+    }
+    get columnTypes() {
+        return this.resultSet.columnTypes;
+    }
+    next() {
+        this.position++;
+        if (this.position >= this.resultSet.rowCount)
+            return Promise.resolve(undefined);
+        return Promise.resolve(this.resultSet.rawRow(this.position));
+    }
+    close() {
+        return Promise.resolve();
+    }
+    async [Symbol.asyncDispose]() {
+        await this.close();
+    }
+}
+//# sourceMappingURL=row-source.js.map

package/dist/row-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"row-source.js","sourceRoot":"","sources":["../src/row-source.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAqCH,4DAA4D;AAC5D,MAAM,OAAO,iBAAiB;IACX,SAAS,CAAiB;IAEnC,QAAQ,GAAG,CAAC,CAAC,CAAC;IAEb,eAAe,CAAS;IAEjC,YAAY,SAAyB,EAAE,eAAe,GAAG,CAAC,CAAC;QACzD,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,eAAe,GAAG,eAAe,CAAC;IACzC,CAAC;IAED,IAAI,WAAW;QACb,OAAO,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC;IACpC,CAAC;IAED,IAAI,WAAW;QACb,OAAO,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC;IACpC,CAAC;IAED,IAAI;QACF,IAAI,CAAC,QAAQ,EAAE,CAAC;QAEhB,IAAI,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,SAAS,CAAC,QAAQ;YAAE,OAAO,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QAEhF,OAAO,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC/D,CAAC;IAED,KAAK;QACH,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;IAC3B,CAAC;IAED,KAAK,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC;QACzB,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;CACF"}

package/dist/runtime.d.ts

@@ -0,0 +1,58 @@
+/**
+ * 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 { CamusTokenProvider } from './auth/token-provider.js';
+import type { ResolvedConfig } from './config.js';
+import { CamusEndpointPool } from './endpoint-pool.js';
+import { CamusPreparedStatementPolicy } from './prepared/policy.js';
+import { CamusStatementRouter } from './routing/router.js';
+import type { CamusTransport } from './transport/transport.js';
+/**
+ * Everything a client runs on, assembled from its configuration.
+ *
+ * Four of these five objects are shared process-wide, keyed by what they actually depend on — see
+ * `SharedRegistry` for why. The runtime is the one place that resolves those keys, so a client
+ * never has to know which of its collaborators it owns and which it borrows.
+ */
+export declare class ClientRuntime {
+    readonly config: ResolvedConfig;
+    /** The endpoint rotation, shared by every client with the same endpoint list. */
+    readonly pool: CamusEndpointPool;
+    /** The bearer token, shared by every client presenting the same identity to this deployment. */
+    readonly auth: CamusTokenProvider;
+    /** The wire transport, shared by deployment, identity, and stream tuning. */
+    readonly transport: CamusTransport;
+    /** Which statements to prepare, shared by deployment and prepare settings. */
+    readonly preparedStatements: CamusPreparedStatementPolicy;
+    /** Learned routing, or `undefined` when routing is off — which is the default. */
+    readonly router: CamusStatementRouter | undefined;
+    /** The database statements run against. `changeDatabase` moves it. */
+    database: string;
+    constructor(config: ResolvedConfig);
+    /** The request timeout in seconds. */
+    get timeoutSeconds(): number;
+    /** The next endpoint in the rotation. */
+    nextEndpoint(): string;
+    /** Where the backup admin API lives for this client. */
+    backupEndpoint(): string;
+    /**
+     * Who performs the credential exchange.
+     *
+     * A gRPC client uses the `CamusAuth` service on the transport's own channel; a REST client posts
+     * to `/login`. Either way the token is obtained over the same protocol and endpoint that carries
+     * the statements: there is no second port to configure and no hop between protocols.
+     */
+    private loginClient;
+    /**
+     * The router for this configuration, or `undefined` when routing is off.
+     *
+     * `learned` needs at least one mapped endpoint. `auto` — the default — needs at least two
+     * distinct ones, because one destination is not a routing decision. So a configuration with no
+     * trust map behaves exactly as `off`, and its requests are identical to a pre-routing driver's.
+     */
+    private buildRouter;
+}
+//# sourceMappingURL=runtime.d.ts.map

package/dist/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,4BAA4B,EAAE,MAAM,sBAAsB,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAI3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAG/D;;;;;;GAMG;AACH,qBAAa,aAAa;IACxB,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAEhC,iFAAiF;IACjF,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IAEjC,gGAAgG;IAChG,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAElC,6EAA6E;IAC7E,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC;IAEnC,8EAA8E;IAC9E,QAAQ,CAAC,kBAAkB,EAAE,4BAA4B,CAAC;IAE1D,kFAAkF;IAClF,QAAQ,CAAC,MAAM,EAAE,oBAAoB,GAAG,SAAS,CAAC;IAElD,sEAAsE;IACtE,QAAQ,EAAE,MAAM,CAAC;gBAEL,MAAM,EAAE,cAAc;IAuClC,sCAAsC;IACtC,IAAI,cAAc,IAAI,MAAM,CAE3B;IAED,yCAAyC;IACzC,YAAY,IAAI,MAAM;IAItB,wDAAwD;IACxD,cAAc,IAAI,MAAM;IAIxB;;;;;;OAMG;IACH,OAAO,CAAC,WAAW;IAOnB;;;;;;OAMG;IACH,OAAO,CAAC,WAAW;CA+BpB"}

package/dist/runtime.js

@@ -0,0 +1,137 @@
+/**
+ * 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 { RestLoginClient } from './auth/rest-login-client.js';
+import { CamusTokenProvider } from './auth/token-provider.js';
+import { CamusProtocol, CamusRoutingMode, deploymentKey, resolveBackupEndpoint } from './config.js';
+import { CamusEndpointPool } from './endpoint-pool.js';
+import { CamusPreparedStatementPolicy } from './prepared/policy.js';
+import { CamusStatementRouter } from './routing/router.js';
+import { AuthenticatingTransport } from './transport/authenticating-transport.js';
+import { GrpcTransport } from './transport/grpc/grpc-transport.js';
+import { RestTransport } from './transport/rest-transport.js';
+import { CamusTransportPool } from './transport/transport-pool.js';
+/**
+ * Everything a client runs on, assembled from its configuration.
+ *
+ * Four of these five objects are shared process-wide, keyed by what they actually depend on — see
+ * `SharedRegistry` for why. The runtime is the one place that resolves those keys, so a client
+ * never has to know which of its collaborators it owns and which it borrows.
+ */
+export class ClientRuntime {
+    config;
+    /** The endpoint rotation, shared by every client with the same endpoint list. */
+    pool;
+    /** The bearer token, shared by every client presenting the same identity to this deployment. */
+    auth;
+    /** The wire transport, shared by deployment, identity, and stream tuning. */
+    transport;
+    /** Which statements to prepare, shared by deployment and prepare settings. */
+    preparedStatements;
+    /** Learned routing, or `undefined` when routing is off — which is the default. */
+    router;
+    /** The database statements run against. `changeDatabase` moves it. */
+    database;
+    constructor(config) {
+        this.config = config;
+        this.database = config.database;
+        this.pool = CamusEndpointPool.forEndpoints(config.endpointList);
+        const deployment = deploymentKey(config);
+        this.auth = CamusTokenProvider.forKey(CamusTokenProvider.sharingKey(config.credentials, deployment), () => new CamusTokenProvider({
+            credentials: config.credentials,
+            resolveLoginClient: () => this.loginClient(),
+            resolveEndpoint: () => this.pool.next(),
+            resolveTimeoutSeconds: () => config.timeoutSeconds,
+            lifetimeMs: config.tokenLifetimeMs,
+        }));
+        this.transport = CamusTransportPool.forKey(transportKey(config, deployment), () => {
+            const inner = config.protocol === CamusProtocol.Grpc
+                ? new GrpcTransport(this.auth, config.batch)
+                : new RestTransport(this.pool, this.auth);
+            // Wrapped unconditionally. With no credentials configured the wrapper is inert, and wrapping
+            // every transport means a client that authenticates later is covered too.
+            return new AuthenticatingTransport(inner, this.auth);
+        });
+        this.preparedStatements = CamusPreparedStatementPolicy.forKey(`${deployment}|${config.database}|${String(config.maxAutoPrepare)}|${String(config.autoPrepareMinUsages)}`, () => new CamusPreparedStatementPolicy(config.maxAutoPrepare, config.autoPrepareMinUsages));
+        this.router = this.buildRouter(deployment);
+    }
+    /** The request timeout in seconds. */
+    get timeoutSeconds() {
+        return this.config.timeoutSeconds;
+    }
+    /** The next endpoint in the rotation. */
+    nextEndpoint() {
+        return this.pool.next();
+    }
+    /** Where the backup admin API lives for this client. */
+    backupEndpoint() {
+        return resolveBackupEndpoint(this.config, this.pool);
+    }
+    /**
+     * Who performs the credential exchange.
+     *
+     * A gRPC client uses the `CamusAuth` service on the transport's own channel; a REST client posts
+     * to `/login`. Either way the token is obtained over the same protocol and endpoint that carries
+     * the statements: there is no second port to configure and no hop between protocols.
+     */
+    loginClient() {
+        const transport = this.transport;
+        const inner = transport instanceof AuthenticatingTransport ? transport.inner : transport;
+        return isLoginClient(inner) ? inner : new RestLoginClient();
+    }
+    /**
+     * The router for this configuration, or `undefined` when routing is off.
+     *
+     * `learned` needs at least one mapped endpoint. `auto` — the default — needs at least two
+     * distinct ones, because one destination is not a routing decision. So a configuration with no
+     * trust map behaves exactly as `off`, and its requests are identical to a pre-routing driver's.
+     */
+    buildRouter(deployment) {
+        const mode = this.config.routingMode;
+        if (mode === CamusRoutingMode.Off)
+            return undefined;
+        const nodes = this.config.routingNodes;
+        const enabled = mode === CamusRoutingMode.Learned
+            ? nodes.size > 0
+            : new Set([...nodes.values()].map((address) => address.toLowerCase())).size >= 2;
+        if (!enabled)
+            return undefined;
+        const maxHintAge = this.config.routingMaxHintAgeMs;
+        const routerKey = [
+            deployment,
+            mode,
+            String(maxHintAge),
+            [...nodes]
+                .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+                .map(([nodeId, address]) => `${nodeId}=${address}`)
+                .join(','),
+        ].join('|');
+        return CamusStatementRouter.forKey(routerKey, () => new CamusStatementRouter(nodes, this.pool, maxHintAge));
+    }
+}
+/**
+ * Which transport a configuration may share: the deployment and the identity presented to it, so a
+ * transport is never reused across servers, protocols, or users, plus the stream tuning, which
+ * sizes a gRPC transport's pool and so cannot be applied to one that already exists.
+ *
+ * The credentials are hashed by the token provider's own key function rather than held in a
+ * long-lived map key.
+ */
+function transportKey(config, deployment) {
+    return [
+        CamusTokenProvider.sharingKey(config.credentials, deployment),
+        String(config.batch.channelPoolSize),
+        String(config.batch.coalescingThreshold),
+        String(config.batch.coalescingDelayMs),
+    ].join('|');
+}
+function isLoginClient(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        typeof value.login === 'function' &&
+        typeof value.logout === 'function');
+}
+//# sourceMappingURL=runtime.js.map

package/dist/runtime.js.map

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

package/dist/shared-registry.d.ts

@@ -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.
+ */
+/**
+ * A bounded, process-wide registry of objects that several clients share.
+ *
+ * Four kinds of driver state outlive the client that created it: the endpoint rotation and the
+ * health it depends on, the bearer token, the transport that holds prepared-statement
+ * registrations, and the learned-route cache. Each is a property of a deployment, not of one
+ * client object, and an application that builds a client per request would otherwise start every
+ * one of them cold — a multi-endpoint deployment would send all its traffic to one node, and every
+ * request would perform its own login against a per-account rate limit.
+ *
+ * Past `maxEntries` a caller gets an unshared object rather than growing a map nothing empties.
+ * Sharing is an optimization, so the cap trades that optimization for a bound on a process that
+ * talks to unboundedly many deployments or identities.
+ */
+export declare class SharedRegistry<T> {
+    private readonly entries;
+    private readonly maxEntries;
+    constructor(maxEntries?: number);
+    /** The shared object for `key`, built on first use. */
+    get(key: string, factory: () => T): T;
+    /** Every shared object. Used to shut a process down cleanly. */
+    values(): IterableIterator<T>;
+    /** Drops every entry. Tests use it to isolate one case from the next. */
+    clear(): void;
+}
+//# sourceMappingURL=shared-registry.d.ts.map

package/dist/shared-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared-registry.d.ts","sourceRoot":"","sources":["../src/shared-registry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;;;;;GAaG;AACH,qBAAa,cAAc,CAAC,CAAC;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;IAEhD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;gBAExB,UAAU,SAAO;IAI7B,uDAAuD;IACvD,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,GAAG,CAAC;IAarC,gEAAgE;IAChE,MAAM,IAAI,gBAAgB,CAAC,CAAC,CAAC;IAI7B,yEAAyE;IACzE,KAAK,IAAI,IAAI;CAGd"}

package/dist/shared-registry.js

@@ -0,0 +1,48 @@
+/**
+ * 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.
+ */
+/**
+ * A bounded, process-wide registry of objects that several clients share.
+ *
+ * Four kinds of driver state outlive the client that created it: the endpoint rotation and the
+ * health it depends on, the bearer token, the transport that holds prepared-statement
+ * registrations, and the learned-route cache. Each is a property of a deployment, not of one
+ * client object, and an application that builds a client per request would otherwise start every
+ * one of them cold — a multi-endpoint deployment would send all its traffic to one node, and every
+ * request would perform its own login against a per-account rate limit.
+ *
+ * Past `maxEntries` a caller gets an unshared object rather than growing a map nothing empties.
+ * Sharing is an optimization, so the cap trades that optimization for a bound on a process that
+ * talks to unboundedly many deployments or identities.
+ */
+export class SharedRegistry {
+    entries = new Map();
+    maxEntries;
+    constructor(maxEntries = 1024) {
+        this.maxEntries = maxEntries;
+    }
+    /** The shared object for `key`, built on first use. */
+    get(key, factory) {
+        const existing = this.entries.get(key);
+        if (existing !== undefined)
+            return existing;
+        const created = factory();
+        if (this.entries.size >= this.maxEntries)
+            return created;
+        // A racing caller cannot exist: this runs on one thread and `factory` is synchronous.
+        this.entries.set(key, created);
+        return created;
+    }
+    /** Every shared object. Used to shut a process down cleanly. */
+    values() {
+        return this.entries.values();
+    }
+    /** Drops every entry. Tests use it to isolate one case from the next. */
+    clear() {
+        this.entries.clear();
+    }
+}
+//# sourceMappingURL=shared-registry.js.map

package/dist/shared-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared-registry.js","sourceRoot":"","sources":["../src/shared-registry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,cAAc;IACR,OAAO,GAAG,IAAI,GAAG,EAAa,CAAC;IAE/B,UAAU,CAAS;IAEpC,YAAY,UAAU,GAAG,IAAI;QAC3B,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;IAED,uDAAuD;IACvD,GAAG,CAAC,GAAW,EAAE,OAAgB;QAC/B,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACvC,IAAI,QAAQ,KAAK,SAAS;YAAE,OAAO,QAAQ,CAAC;QAE5C,MAAM,OAAO,GAAG,OAAO,EAAE,CAAC;QAE1B,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,IAAI,IAAI,CAAC,UAAU;YAAE,OAAO,OAAO,CAAC;QAEzD,sFAAsF;QACtF,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QAC/B,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,gEAAgE;IAChE,MAAM;QACJ,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;IAC/B,CAAC;IAED,yEAAyE;IACzE,KAAK;QACH,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;CACF"}

package/dist/sql-syntax.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 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.
+ */
+/**
+ * Quoting and validation for the few places this driver composes SQL text rather than binding a
+ * parameter: a database name in a `CREATE DATABASE`, and a cache family name in a hint.
+ *
+ * Everything else a caller runs goes to the server as written, with values bound separately.
+ */
+/**
+ * A single-quoted SQL string literal.
+ *
+ * @throws {TypeError} when the value holds a backslash the lexer would read together with the
+ * closing quote.
+ */
+export declare function sqlLiteral(value: string, target: string): string;
+/**
+ * Refuses a value that cannot be written as a literal.
+ *
+ * CamusDB's lexer reads a backslash and the character after it as one unit. A doubled quote
+ * therefore stops escaping the quote when a backslash precedes it, and a trailing backslash
+ * consumes the literal's closing quote. Neither case has a spelling, so both are refused here
+ * rather than sent as a statement that would parse as something else.
+ */
+export declare function validateSqlLiteral(value: string, target: string): void;
+/**
+ * A backtick-delimited identifier.
+ *
+ * An identifier that holds a backtick is refused rather than doubled. CamusDB trims the delimiters
+ * instead of decoding a doubled backtick, so doubling neutralizes nothing and the name would break
+ * out of its quoting.
+ */
+export declare function delimitIdentifier(identifier: string, parameterName: string): string;
+/** Refuses an identifier that cannot be delimited. */
+export declare function validateIdentifier(identifier: string, parameterName: string): void;
+/**
+ * Refuses a name that is emitted into SQL as bare text and therefore cannot be escaped at all.
+ * Letters, digits, and `_ - . :` are allowed.
+ */
+export declare function validateBareName(name: string, maxLength: number, parameterName: string): void;
+//# sourceMappingURL=sql-syntax.d.ts.map

package/dist/sql-syntax.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sql-syntax.d.ts","sourceRoot":"","sources":["../src/sql-syntax.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;GAKG;AAEH;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAGhE;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAoBtE;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,CAGnF;AAED,sDAAsD;AACtD,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI,CAUlF;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI,CAmB7F"}

package/dist/sql-syntax.js

@@ -0,0 +1,83 @@
+/**
+ * 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.
+ */
+/**
+ * Quoting and validation for the few places this driver composes SQL text rather than binding a
+ * parameter: a database name in a `CREATE DATABASE`, and a cache family name in a hint.
+ *
+ * Everything else a caller runs goes to the server as written, with values bound separately.
+ */
+/**
+ * A single-quoted SQL string literal.
+ *
+ * @throws {TypeError} when the value holds a backslash the lexer would read together with the
+ * closing quote.
+ */
+export function sqlLiteral(value, target) {
+    validateSqlLiteral(value, target);
+    return `'${value.replaceAll("'", "''")}'`;
+}
+/**
+ * Refuses a value that cannot be written as a literal.
+ *
+ * CamusDB's lexer reads a backslash and the character after it as one unit. A doubled quote
+ * therefore stops escaping the quote when a backslash precedes it, and a trailing backslash
+ * consumes the literal's closing quote. Neither case has a spelling, so both are refused here
+ * rather than sent as a statement that would parse as something else.
+ */
+export function validateSqlLiteral(value, target) {
+    let index = value.indexOf('\\');
+    while (index >= 0) {
+        if (index === value.length - 1) {
+            throw new TypeError(`The value for ${target} ends with a backslash. CamusDB's lexer reads a backslash and the ` +
+                "character after it as one unit, so a trailing backslash would consume the literal's closing quote.");
+        }
+        if (value[index + 1] === "'") {
+            throw new TypeError(`The value for ${target} has a backslash immediately before a quote at position ${String(index)}. ` +
+                'CamusDB’s lexer reads that pair as one unit, so the quote cannot be escaped.');
+        }
+        index = value.indexOf('\\', index + 2);
+    }
+}
+/**
+ * A backtick-delimited identifier.
+ *
+ * An identifier that holds a backtick is refused rather than doubled. CamusDB trims the delimiters
+ * instead of decoding a doubled backtick, so doubling neutralizes nothing and the name would break
+ * out of its quoting.
+ */
+export function delimitIdentifier(identifier, parameterName) {
+    validateIdentifier(identifier, parameterName);
+    return `\`${identifier}\``;
+}
+/** Refuses an identifier that cannot be delimited. */
+export function validateIdentifier(identifier, parameterName) {
+    if (identifier.trim().length === 0) {
+        throw new TypeError(`An identifier cannot be empty (${parameterName}).`);
+    }
+    if (identifier.includes('`')) {
+        throw new TypeError(`The identifier '${identifier}' holds a backtick, which CamusDB cannot quote (${parameterName}).`);
+    }
+}
+/**
+ * Refuses a name that is emitted into SQL as bare text and therefore cannot be escaped at all.
+ * Letters, digits, and `_ - . :` are allowed.
+ */
+export function validateBareName(name, maxLength, parameterName) {
+    if (name.trim().length === 0) {
+        throw new TypeError(`'${parameterName}' cannot be empty.`);
+    }
+    if (name.length > maxLength) {
+        throw new TypeError(`'${parameterName}' is ${String(name.length)} characters; at most ${String(maxLength)} are allowed.`);
+    }
+    for (const character of name) {
+        if (/[\p{L}\p{Nd}_\-.:]/u.test(character))
+            continue;
+        throw new TypeError(`'${parameterName}' holds the character '${character}', which is not allowed. Use letters, digits, ` +
+            'or one of _ - . : — the name is emitted into SQL as text and cannot be escaped.');
+    }
+}
+//# sourceMappingURL=sql-syntax.js.map

package/dist/sql-syntax.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sql-syntax.js","sourceRoot":"","sources":["../src/sql-syntax.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;GAKG;AAEH;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,KAAa,EAAE,MAAc;IACtD,kBAAkB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IAClC,OAAO,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC;AAC5C,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAa,EAAE,MAAc;IAC9D,IAAI,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAEhC,OAAO,KAAK,IAAI,CAAC,EAAE,CAAC;QAClB,IAAI,KAAK,KAAK,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC/B,MAAM,IAAI,SAAS,CACjB,iBAAiB,MAAM,oEAAoE;gBACzF,oGAAoG,CACvG,CAAC;QACJ,CAAC;QAED,IAAI,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,GAAG,EAAE,CAAC;YAC7B,MAAM,IAAI,SAAS,CACjB,iBAAiB,MAAM,2DAA2D,MAAM,CAAC,KAAK,CAAC,IAAI;gBACjG,8EAA8E,CACjF,CAAC;QACJ,CAAC;QAED,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;IACzC,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,UAAkB,EAAE,aAAqB;IACzE,kBAAkB,CAAC,UAAU,EAAE,aAAa,CAAC,CAAC;IAC9C,OAAO,KAAK,UAAU,IAAI,CAAC;AAC7B,CAAC;AAED,sDAAsD;AACtD,MAAM,UAAU,kBAAkB,CAAC,UAAkB,EAAE,aAAqB;IAC1E,IAAI,UAAU,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACnC,MAAM,IAAI,SAAS,CAAC,kCAAkC,aAAa,IAAI,CAAC,CAAC;IAC3E,CAAC;IAED,IAAI,UAAU,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,SAAS,CACjB,mBAAmB,UAAU,mDAAmD,aAAa,IAAI,CAClG,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY,EAAE,SAAiB,EAAE,aAAqB;IACrF,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,SAAS,CAAC,IAAI,aAAa,oBAAoB,CAAC,CAAC;IAC7D,CAAC;IAED,IAAI,IAAI,CAAC,MAAM,GAAG,SAAS,EAAE,CAAC;QAC5B,MAAM,IAAI,SAAS,CACjB,IAAI,aAAa,QAAQ,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,wBAAwB,MAAM,CAAC,SAAS,CAAC,eAAe,CACrG,CAAC;IACJ,CAAC;IAED,KAAK,MAAM,SAAS,IAAI,IAAI,EAAE,CAAC;QAC7B,IAAI,qBAAqB,CAAC,IAAI,CAAC,SAAS,CAAC;YAAE,SAAS;QAEpD,MAAM,IAAI,SAAS,CACjB,IAAI,aAAa,0BAA0B,SAAS,gDAAgD;YAClG,iFAAiF,CACpF,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/statements.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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.
+ */
+/** True when the statement goes to the DDL route. */
+export declare function isDdlStatement(sql: string): boolean;
+/** True when the statement writes rows and reports how many. */
+export declare function isDmlStatement(sql: string): boolean;
+/** True when the statement may be registered as a prepared statement. */
+export declare function isPreparableStatement(sql: string): boolean;
+/** True when the statement cannot run inside an explicit transaction. */
+export declare function runsInOwnTransaction(sql: string): boolean;
+//# sourceMappingURL=statements.d.ts.map

package/dist/statements.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"statements.d.ts","sourceRoot":"","sources":["../src/statements.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAgEH,qDAAqD;AACrD,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED,gEAAgE;AAChE,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED,yEAAyE;AACzE,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED,yEAAyE;AACzE,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEzD"}

package/dist/statements.js

@@ -0,0 +1,90 @@
+/**
+ * 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.
+ */
+/**
+ * Classifies a statement by its leading keywords.
+ *
+ * The server decides what a statement means; these lists only decide which route the driver sends
+ * it to and whether it is worth preparing. A statement this module classifies wrongly still runs
+ * correctly, because the data route forwards a schema statement to the same implementation — it
+ * simply takes an extra parse and dispatch on the way.
+ */
+/**
+ * The schema statements that go to the server's DDL route rather than its data route.
+ *
+ * An older server does not forward, and refuses such a statement on the data route as an unknown
+ * node, so this list is also what keeps the driver working against one.
+ *
+ * `REFRESH MATERIALIZED VIEW` is deliberately absent. It is a write, not schema: it replaces a
+ * relation's contents and reports how many rows it wrote, which the DDL route has no shape to
+ * return.
+ */
+const DDL_PREFIXES = [
+    'CREATE TABLE',
+    'DROP TABLE',
+    'ALTER TABLE',
+    // TRUNCATE is schema, not a write: the server retires the table's whole key space and commits a
+    // replicated schema entry instead of deleting rows. The TABLE keyword is optional, so the prefix
+    // stops at the verb and covers both spellings.
+    'TRUNCATE',
+    'CREATE UNIQUE INDEX',
+    'CREATE INDEX',
+    'DROP INDEX',
+    // Views. "CREATE VIEW" does not cover "CREATE OR REPLACE VIEW", because the test is a prefix
+    // test, so each spelling needs its own entry. The IF EXISTS and IF NOT EXISTS variants do fall
+    // under the base prefixes, because the condition follows the object keyword.
+    'CREATE VIEW',
+    'CREATE OR REPLACE VIEW',
+    'DROP VIEW',
+    'ALTER VIEW',
+    'CREATE MATERIALIZED VIEW',
+    'DROP MATERIALIZED VIEW',
+    'ALTER MATERIALIZED VIEW',
+];
+const DML_PREFIXES = ['INSERT', 'UPDATE', 'DELETE'];
+/**
+ * The statements the server accepts a registration for: the repeatable data statements, whose
+ * whole point is running many times with different values. Schema and administration statements
+ * are one-shot and are excluded on the server too, so this list mirrors that rather than guessing.
+ */
+const PREPARABLE_PREFIXES = ['SELECT', 'INSERT', 'UPDATE', 'DELETE', 'SHOW'];
+/**
+ * The statements that own their internal transaction, which the server refuses inside an explicit
+ * one.
+ *
+ * `TRUNCATE` is the only member today. It commits a replicated schema entry, and a later rollback
+ * of the caller's transaction cannot undo that entry — so the server refuses the statement rather
+ * than promise a rollback it cannot deliver. The driver refuses it before the round trip, because
+ * the outcome is already known and a local message can name the fix.
+ */
+const OWN_TRANSACTION_PREFIXES = ['TRUNCATE'];
+/** True when the statement goes to the DDL route. */
+export function isDdlStatement(sql) {
+    return startsWithAny(sql, DDL_PREFIXES);
+}
+/** True when the statement writes rows and reports how many. */
+export function isDmlStatement(sql) {
+    return startsWithAny(sql, DML_PREFIXES);
+}
+/** True when the statement may be registered as a prepared statement. */
+export function isPreparableStatement(sql) {
+    return startsWithAny(sql, PREPARABLE_PREFIXES);
+}
+/** True when the statement cannot run inside an explicit transaction. */
+export function runsInOwnTransaction(sql) {
+    return startsWithAny(sql, OWN_TRANSACTION_PREFIXES);
+}
+function startsWithAny(sql, prefixes) {
+    const trimmed = sql.trimStart();
+    for (const prefix of prefixes) {
+        if (trimmed.length < prefix.length)
+            continue;
+        if (trimmed.slice(0, prefix.length).toUpperCase() === prefix)
+            return true;
+    }
+    return false;
+}
+//# sourceMappingURL=statements.js.map

package/dist/statements.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"statements.js","sourceRoot":"","sources":["../src/statements.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;GAOG;AAEH;;;;;;;;;GASG;AACH,MAAM,YAAY,GAAG;IACnB,cAAc;IACd,YAAY;IACZ,aAAa;IACb,gGAAgG;IAChG,iGAAiG;IACjG,+CAA+C;IAC/C,UAAU;IACV,qBAAqB;IACrB,cAAc;IACd,YAAY;IACZ,6FAA6F;IAC7F,+FAA+F;IAC/F,6EAA6E;IAC7E,aAAa;IACb,wBAAwB;IACxB,WAAW;IACX,YAAY;IACZ,0BAA0B;IAC1B,wBAAwB;IACxB,yBAAyB;CAC1B,CAAC;AAEF,MAAM,YAAY,GAAG,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;AAEpD;;;;GAIG;AACH,MAAM,mBAAmB,GAAG,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;AAE7E;;;;;;;;GAQG;AACH,MAAM,wBAAwB,GAAG,CAAC,UAAU,CAAC,CAAC;AAE9C,qDAAqD;AACrD,MAAM,UAAU,cAAc,CAAC,GAAW;IACxC,OAAO,aAAa,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC;AAC1C,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,cAAc,CAAC,GAAW;IACxC,OAAO,aAAa,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC;AAC1C,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,qBAAqB,CAAC,GAAW;IAC/C,OAAO,aAAa,CAAC,GAAG,EAAE,mBAAmB,CAAC,CAAC;AACjD,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,oBAAoB,CAAC,GAAW;IAC9C,OAAO,aAAa,CAAC,GAAG,EAAE,wBAAwB,CAAC,CAAC;AACtD,CAAC;AAED,SAAS,aAAa,CAAC,GAAW,EAAE,QAA2B;IAC7D,MAAM,OAAO,GAAG,GAAG,CAAC,SAAS,EAAE,CAAC;IAEhC,KAAK,MAAM,MAAM,IAAI,QAAQ,EAAE,CAAC;QAC9B,IAAI,OAAO,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM;YAAE,SAAS;QAE7C,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,WAAW,EAAE,KAAK,MAAM;YAAE,OAAO,IAAI,CAAC;IAC5E,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}