camusdb 0.1.0

package/dist/endpoint-pool.js

@@ -0,0 +1,120 @@
+/**
+ * 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 { SharedRegistry } from './shared-registry.js';
+/**
+ * The endpoints one deployment's clients rotate through, and which of them are set aside after
+ * failing to answer at all.
+ *
+ * A pool is shared per endpoint list rather than owned by one client. The rotation and the health
+ * it depends on are properties of the deployment; a per-client pool would restart its rotation at
+ * the first endpoint on every request.
+ *
+ * Quarantine expires. A pool that outlives the request that marked an endpoint cannot mark it
+ * forever: with a single endpoint configured — the common case — the first refused connection
+ * would otherwise end the process's ability to reach the database at all, long after the node came
+ * back. An endpoint is set aside for `QUARANTINE_PERIOD_MS` and then drawn again; a node that is
+ * still down is simply marked again by the request that draws it, at a cost of one failed request
+ * per period.
+ */
+export class CamusEndpointPool {
+    /** How long an endpoint that failed at the transport level is passed over. */
+    static QUARANTINE_PERIOD_MS = 30_000;
+    static shared = new SharedRegistry();
+    /**
+     * The process-wide pool for an endpoint list, built on first use. Keyed by the list alone, so
+     * clients that differ only in database, credentials, or timeout share one rotation and one view
+     * of which nodes are answering.
+     */
+    static forEndpoints(endpointList) {
+        return CamusEndpointPool.shared.get(endpointList, () => new CamusEndpointPool(endpointList));
+    }
+    /** @internal Test hook: drops every shared pool. */
+    static resetShared() {
+        CamusEndpointPool.shared.clear();
+    }
+    endpoints;
+    /**
+     * Monotonic-clock deadlines, indexed alongside `endpoints`. Zero — the initial value — is in the
+     * past, so an endpoint that has never failed needs no special case.
+     */
+    quarantinedUntil;
+    nextIndex = 0;
+    /** @internal Test hook: the monotonic clock this pool reads. */
+    clock = () => performance.now();
+    constructor(endpointList) {
+        this.endpoints = endpointList
+            .split(',')
+            .map((endpoint) => endpoint.trim())
+            .filter((endpoint) => endpoint.length > 0);
+        if (this.endpoints.length === 0) {
+            throw new CamusError(CamusErrorCode.Generic, 'Endpoint is required.');
+        }
+        this.quarantinedUntil = new Array(this.endpoints.length).fill(0);
+    }
+    /** Every configured endpoint, in the order it was written. */
+    get members() {
+        return this.endpoints;
+    }
+    /**
+     * The next endpoint to send to, skipping those in quarantine.
+     *
+     * When every endpoint is quarantined the one closest to leaving is returned rather than an
+     * error. The deployment is evidently down, and letting the request go and fail against the real
+     * node reports why, where a synthetic "no endpoints" would replace the server's diagnosis with
+     * the driver's bookkeeping.
+     */
+    next() {
+        const now = this.clock();
+        let fallback = -1;
+        for (let i = 0; i < this.endpoints.length; i++) {
+            const index = this.nextIndex;
+            this.nextIndex = (this.nextIndex + 1) % this.endpoints.length;
+            if (this.quarantinedUntil[index] <= now)
+                return this.endpoints[index];
+            if (fallback < 0 || this.quarantinedUntil[index] < this.quarantinedUntil[fallback]) {
+                fallback = index;
+            }
+        }
+        return this.endpoints[fallback === -1 ? 0 : fallback];
+    }
+    /**
+     * Whether an endpoint is currently set aside. Learned routing reads it before preferring an
+     * endpoint, so a route pointing at a node that stopped answering falls back to rotation. An
+     * address the pool does not know reports as not quarantined.
+     */
+    isQuarantined(endpoint) {
+        const index = this.indexOf(endpoint);
+        if (index < 0)
+            return false;
+        return this.quarantinedUntil[index] > this.clock();
+    }
+    /**
+     * Whether an address is one of the configured endpoints. The routing trust map uses it to refuse
+     * mapping a node identity to any address the operator did not list.
+     */
+    contains(endpoint) {
+        return this.indexOf(endpoint) >= 0;
+    }
+    /** Sets an endpoint aside, so the endpoints that are answering carry the traffic meanwhile. */
+    markUnreachable(endpoint) {
+        const index = this.indexOf(endpoint);
+        if (index < 0)
+            return;
+        this.quarantinedUntil[index] = this.clock() + CamusEndpointPool.QUARANTINE_PERIOD_MS;
+    }
+    indexOf(endpoint) {
+        const wanted = endpoint.toLowerCase();
+        for (let i = 0; i < this.endpoints.length; i++) {
+            if (this.endpoints[i].toLowerCase() === wanted)
+                return i;
+        }
+        return -1;
+    }
+}
+//# sourceMappingURL=endpoint-pool.js.map

package/dist/endpoint-pool.js.map

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

package/dist/error-codes.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.
+ */
+/**
+ * The server error codes this driver reacts to. Every other `CADBxxxx` code reaches the caller
+ * unchanged on `CamusError.code`.
+ */
+export declare const CamusErrorCode: {
+    /** The driver's own generic code, used when the far end supplied none. */
+    readonly Generic: "CADB0000";
+    /** A parameter cannot be mapped to a wire value. Raised locally, before any request. */
+    readonly InvalidParameter: "CADB0400";
+    /** A byte payload read as a vector has a length that is not a multiple of four. */
+    readonly InvalidVector: "CADB0410";
+    /** The database already exists. Also raised when `IF NOT EXISTS` loses a registration race. */
+    readonly DatabaseAlreadyExists: "CADB0012";
+    /**
+     * The commit or rollback outcome is not resolved yet. The transaction is not dead: the same
+     * finalize must be re-issued on the same handle, never replayed from `BEGIN`.
+     */
+    readonly FinalizeUnresolved: "CADB0509";
+    /**
+     * No token, an invalid or expired token, an unknown user, or a wrong password (HTTP 401). Every
+     * authentication failure returns this one code so replies cannot be used to enumerate accounts.
+     */
+    readonly AuthenticationFailed: "CADB0516";
+    /** Authenticated, but without the privilege the statement needs (HTTP 403). Never retried. */
+    readonly InsufficientPrivilege: "CADB0517";
+    /** The login rate limit was exceeded, or the key derivation function is saturated (HTTP 429). */
+    readonly TooManyAuthAttempts: "CADB0518";
+    /** A request that carries a credential arrived over a plaintext connection (HTTP 400). */
+    readonly InsecureTransport: "CADB0519";
+    /** The named prepared statement is gone: it expired, or the node that held it restarted. */
+    readonly UnknownPreparedStatement: "CADB0520";
+    /** The per-principal prepared-statement cap is full. */
+    readonly PreparedStatementLimitExceeded: "CADB0521";
+    /** The statement runs in its own internal transaction and is refused inside an explicit one. */
+    readonly StatementNotAllowedInTransaction: "CADB0538";
+};
+export type CamusErrorCode = (typeof CamusErrorCode)[keyof typeof CamusErrorCode];
+//# sourceMappingURL=error-codes.d.ts.map

package/dist/error-codes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-codes.d.ts","sourceRoot":"","sources":["../src/error-codes.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;GAGG;AACH,eAAO,MAAM,cAAc;IACzB,0EAA0E;;IAG1E,wFAAwF;;IAGxF,mFAAmF;;IAGnF,+FAA+F;;IAG/F;;;OAGG;;IAGH;;;OAGG;;IAGH,8FAA8F;;IAG9F,iGAAiG;;IAGjG,0FAA0F;;IAG1F,4FAA4F;;IAG5F,wDAAwD;;IAGxD,gGAAgG;;CAExF,CAAC;AAEX,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,OAAO,cAAc,CAAC,CAAC"}

package/dist/error-codes.js

@@ -0,0 +1,43 @@
+/**
+ * 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.
+ */
+/**
+ * The server error codes this driver reacts to. Every other `CADBxxxx` code reaches the caller
+ * unchanged on `CamusError.code`.
+ */
+export const CamusErrorCode = {
+    /** The driver's own generic code, used when the far end supplied none. */
+    Generic: 'CADB0000',
+    /** A parameter cannot be mapped to a wire value. Raised locally, before any request. */
+    InvalidParameter: 'CADB0400',
+    /** A byte payload read as a vector has a length that is not a multiple of four. */
+    InvalidVector: 'CADB0410',
+    /** The database already exists. Also raised when `IF NOT EXISTS` loses a registration race. */
+    DatabaseAlreadyExists: 'CADB0012',
+    /**
+     * The commit or rollback outcome is not resolved yet. The transaction is not dead: the same
+     * finalize must be re-issued on the same handle, never replayed from `BEGIN`.
+     */
+    FinalizeUnresolved: 'CADB0509',
+    /**
+     * No token, an invalid or expired token, an unknown user, or a wrong password (HTTP 401). Every
+     * authentication failure returns this one code so replies cannot be used to enumerate accounts.
+     */
+    AuthenticationFailed: 'CADB0516',
+    /** Authenticated, but without the privilege the statement needs (HTTP 403). Never retried. */
+    InsufficientPrivilege: 'CADB0517',
+    /** The login rate limit was exceeded, or the key derivation function is saturated (HTTP 429). */
+    TooManyAuthAttempts: 'CADB0518',
+    /** A request that carries a credential arrived over a plaintext connection (HTTP 400). */
+    InsecureTransport: 'CADB0519',
+    /** The named prepared statement is gone: it expired, or the node that held it restarted. */
+    UnknownPreparedStatement: 'CADB0520',
+    /** The per-principal prepared-statement cap is full. */
+    PreparedStatementLimitExceeded: 'CADB0521',
+    /** The statement runs in its own internal transaction and is refused inside an explicit one. */
+    StatementNotAllowedInTransaction: 'CADB0538',
+};
+//# sourceMappingURL=error-codes.js.map

package/dist/error-codes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-codes.js","sourceRoot":"","sources":["../src/error-codes.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,0EAA0E;IAC1E,OAAO,EAAE,UAAU;IAEnB,wFAAwF;IACxF,gBAAgB,EAAE,UAAU;IAE5B,mFAAmF;IACnF,aAAa,EAAE,UAAU;IAEzB,+FAA+F;IAC/F,qBAAqB,EAAE,UAAU;IAEjC;;;OAGG;IACH,kBAAkB,EAAE,UAAU;IAE9B;;;OAGG;IACH,oBAAoB,EAAE,UAAU;IAEhC,8FAA8F;IAC9F,qBAAqB,EAAE,UAAU;IAEjC,iGAAiG;IACjG,mBAAmB,EAAE,UAAU;IAE/B,0FAA0F;IAC1F,iBAAiB,EAAE,UAAU;IAE7B,4FAA4F;IAC5F,wBAAwB,EAAE,UAAU;IAEpC,wDAAwD;IACxD,8BAA8B,EAAE,UAAU;IAE1C,gGAAgG;IAChG,gCAAgC,EAAE,UAAU;CACpC,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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.
+ */
+/**
+ * Every failure this driver raises for a database-level problem.
+ *
+ * `code` is the server's `CADBxxxx` code, taken from the HTTP body's `code` field or from the
+ * `camus-error-code` gRPC trailer. It is the value to switch on; the message is human text and is
+ * not a stable contract. `CADB0000` is the generic code the driver uses when the far end supplied
+ * none.
+ */
+export declare class CamusError extends Error {
+    readonly name = "CamusError";
+    readonly code: string;
+    constructor(code: string, message: string, options?: {
+        cause?: unknown;
+    });
+    /** True when `value` is a `CamusError`, including one raised by another copy of this package. */
+    static is(value: unknown): value is CamusError;
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;GAOG;AACH,qBAAa,UAAW,SAAQ,KAAK;IACnC,SAAkB,IAAI,gBAAgB;IAEtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;IAQxE,iGAAiG;IACjG,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU;CAS/C"}

package/dist/errors.js

@@ -0,0 +1,33 @@
+/**
+ * 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.
+ */
+/**
+ * Every failure this driver raises for a database-level problem.
+ *
+ * `code` is the server's `CADBxxxx` code, taken from the HTTP body's `code` field or from the
+ * `camus-error-code` gRPC trailer. It is the value to switch on; the message is human text and is
+ * not a stable contract. `CADB0000` is the generic code the driver uses when the far end supplied
+ * none.
+ */
+export class CamusError extends Error {
+    name = 'CamusError';
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+        // Keeps `instanceof` working when the package is compiled down to ES5 by a consumer's bundler.
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+    /** True when `value` is a `CamusError`, including one raised by another copy of this package. */
+    static is(value) {
+        return (value instanceof CamusError ||
+            (typeof value === 'object' &&
+                value !== null &&
+                value.name === 'CamusError' &&
+                typeof value.code === 'string'));
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;GAOG;AACH,MAAM,OAAO,UAAW,SAAQ,KAAK;IACjB,IAAI,GAAG,YAAY,CAAC;IAE7B,IAAI,CAAS;IAEtB,YAAY,IAAY,EAAE,OAAe,EAAE,OAA6B;QACtE,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QAEjB,+FAA+F;QAC/F,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;IAED,iGAAiG;IACjG,MAAM,CAAC,EAAE,CAAC,KAAc;QACtB,OAAO,CACL,KAAK,YAAY,UAAU;YAC3B,CAAC,OAAO,KAAK,KAAK,QAAQ;gBACxB,KAAK,KAAK,IAAI;gBACb,KAA4B,CAAC,IAAI,KAAK,YAAY;gBACnD,OAAQ,KAA4B,CAAC,IAAI,KAAK,QAAQ,CAAC,CAC1D,CAAC;IACJ,CAAC;CACF"}

package/dist/hlc.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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.
+ */
+/**
+ * One instant on the cluster's hybrid logical clock, as a response envelope reports it.
+ *
+ * `l` is the physical component in milliseconds and `c` is the logical counter that orders events
+ * inside one millisecond. The node dimension is not part of a cache report, so it is absent here.
+ */
+export interface CamusHlcTimestamp {
+    readonly l: bigint;
+    readonly c: number;
+}
+/** `l:c`, the form the server writes an instant in. */
+export declare function formatHlc(timestamp: CamusHlcTimestamp): string;
+//# sourceMappingURL=hlc.d.ts.map

package/dist/hlc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hlc.d.ts","sourceRoot":"","sources":["../src/hlc.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,uDAAuD;AACvD,wBAAgB,SAAS,CAAC,SAAS,EAAE,iBAAiB,GAAG,MAAM,CAE9D"}

package/dist/hlc.js

@@ -0,0 +1,11 @@
+/**
+ * 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.
+ */
+/** `l:c`, the form the server writes an instant in. */
+export function formatHlc(timestamp) {
+    return `${timestamp.l.toString()}:${timestamp.c.toString()}`;
+}
+//# sourceMappingURL=hlc.js.map

package/dist/hlc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hlc.js","sourceRoot":"","sources":["../src/hlc.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAaH,uDAAuD;AACvD,MAAM,UAAU,SAAS,CAAC,SAA4B;IACpD,OAAO,GAAG,SAAS,CAAC,CAAC,CAAC,QAAQ,EAAE,IAAI,SAAS,CAAC,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC;AAC/D,CAAC"}

package/dist/index.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.
+ */
+/**
+ * The CamusDB connector for Node.js.
+ *
+ * ```ts
+ * import { CamusClient } from 'camusdb';
+ *
+ * const client = new CamusClient({ endpoint: 'http://localhost:8082', database: 'test' });
+ *
+ * const { rows } = await client.query<Robot>('SELECT * FROM robots WHERE year = @year', { year: 1974 });
+ * ```
+ */
+export { CamusClient } from './client.js';
+export type { AutocommitStatementOptions, ExecuteResult, QueryResult, StatementOptions, TransactionRunOptions, } from './client.js';
+export { CamusTransaction } from './transaction.js';
+export { CamusQueryStream } from './query-stream.js';
+export { CamusBackupClient } from './backup.js';
+export type { CamusBackupGcDeletion, CamusBackupGcOrphan, CamusBackupGcResult, CamusBackupInfo, } from './backup.js';
+export { CamusProtocol, CamusRoutingMode, DEFAULT_BATCH_OPTIONS } from './config.js';
+export type { CamusClientOptions, GrpcBatchOptions, ResolvedConfig } from './config.js';
+export { parseConnectionString, redactConnectionString } from './connection-string.js';
+export { CamusIsolationLevel, CamusLocking, CamusTransactionMode, DEFAULT_TRANSACTION_OPTIONS, OPTIMISTIC_TRANSACTION_OPTIONS, SNAPSHOT_TRANSACTION_OPTIONS, } from './options.js';
+export type { CamusTransactionOptions } from './options.js';
+export { CamusError } from './errors.js';
+export { CamusErrorCode } from './error-codes.js';
+export { computeDelayMs, isRetryable, withRetry } from './retry.js';
+export type { RetryOptions } from './retry.js';
+export { ColumnType, columnTypeName, isColumnType } from './column-type.js';
+export type { ColumnValue } from './column-value.js';
+export { camus } from './values/typed.js';
+export type { TypedParameter } from './values/typed.js';
+export type { Parameters, ParameterValue } from './values/encode.js';
+export type { DecodeOptions, Int64Mode } from './values/decode.js';
+export { decodeValue } from './values/decode.js';
+export { CamusObjectId } from './object-id.js';
+export { CamusVector } from './vector.js';
+export { TICKS_PER_DAY, TICKS_PER_MILLISECOND, UNIX_EPOCH_TICKS, dateToDayTicks, dateToTicks, ticksToDate, } from './values/ticks.js';
+export { bytesToUuid, isUuid, uuidToBytes } from './values/uuid.js';
+export { CamusResultSet } from './result-set.js';
+export type { CamusColumn } from './result-set.js';
+export type { CamusBranchRow } from './transport/transport.js';
+export { CamusCacheStatus, cacheHint, evictAllCacheStatement, evictCacheStatement } from './cache.js';
+export type { CamusCacheMetadata } from './cache.js';
+export { CamusRoutingDisposition, ROUTING_ACCEPT_VERSION } from './routing/advice.js';
+export type { CamusRoutingAdvice } from './routing/advice.js';
+export { formatHlc } from './hlc.js';
+export type { CamusHlcTimestamp } from './hlc.js';
+export { CamusTransportPool } from './transport/transport-pool.js';
+export { delimitIdentifier, sqlLiteral, validateBareName, validateIdentifier, validateSqlLiteral, } from './sql-syntax.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -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.
+ */
+/**
+ * The CamusDB connector for Node.js.
+ *
+ * ```ts
+ * import { CamusClient } from 'camusdb';
+ *
+ * const client = new CamusClient({ endpoint: 'http://localhost:8082', database: 'test' });
+ *
+ * const { rows } = await client.query<Robot>('SELECT * FROM robots WHERE year = @year', { year: 1974 });
+ * ```
+ */
+// ─── The client ─────────────────────────────────────────────────────────────
+export { CamusClient } from './client.js';
+export { CamusTransaction } from './transaction.js';
+export { CamusQueryStream } from './query-stream.js';
+export { CamusBackupClient } from './backup.js';
+// ─── Configuration ──────────────────────────────────────────────────────────
+export { CamusProtocol, CamusRoutingMode, DEFAULT_BATCH_OPTIONS } from './config.js';
+export { parseConnectionString, redactConnectionString } from './connection-string.js';
+export { CamusIsolationLevel, CamusLocking, CamusTransactionMode, DEFAULT_TRANSACTION_OPTIONS, OPTIMISTIC_TRANSACTION_OPTIONS, SNAPSHOT_TRANSACTION_OPTIONS, } from './options.js';
+// ─── Errors and retries ─────────────────────────────────────────────────────
+export { CamusError } from './errors.js';
+export { CamusErrorCode } from './error-codes.js';
+export { computeDelayMs, isRetryable, withRetry } from './retry.js';
+// ─── Values ─────────────────────────────────────────────────────────────────
+export { ColumnType, columnTypeName, isColumnType } from './column-type.js';
+export { camus } from './values/typed.js';
+export { decodeValue } from './values/decode.js';
+export { CamusObjectId } from './object-id.js';
+export { CamusVector } from './vector.js';
+export { TICKS_PER_DAY, TICKS_PER_MILLISECOND, UNIX_EPOCH_TICKS, dateToDayTicks, dateToTicks, ticksToDate, } from './values/ticks.js';
+export { bytesToUuid, isUuid, uuidToBytes } from './values/uuid.js';
+// ─── Results ────────────────────────────────────────────────────────────────
+export { CamusResultSet } from './result-set.js';
+// ─── The query result cache ─────────────────────────────────────────────────
+export { CamusCacheStatus, cacheHint, evictAllCacheStatement, evictCacheStatement } from './cache.js';
+// ─── Learned routing ────────────────────────────────────────────────────────
+export { CamusRoutingDisposition, ROUTING_ACCEPT_VERSION } from './routing/advice.js';
+// ─── Clocks ─────────────────────────────────────────────────────────────────
+export { formatHlc } from './hlc.js';
+// ─── Process lifetime ───────────────────────────────────────────────────────
+export { CamusTransportPool } from './transport/transport-pool.js';
+// ─── SQL text helpers ───────────────────────────────────────────────────────
+export { delimitIdentifier, sqlLiteral, validateBareName, validateIdentifier, validateSqlLiteral, } from './sql-syntax.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;;GAUG;AAEH,+EAA+E;AAE/E,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAS1C,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAQhD,+EAA+E;AAE/E,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAGrF,OAAO,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAEvF,OAAO,EACL,mBAAmB,EACnB,YAAY,EACZ,oBAAoB,EACpB,2BAA2B,EAC3B,8BAA8B,EAC9B,4BAA4B,GAC7B,MAAM,cAAc,CAAC;AAGtB,+EAA+E;AAE/E,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAGpE,+EAA+E;AAE/E,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAE5E,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAI1C,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEjD,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,OAAO,EACL,aAAa,EACb,qBAAqB,EACrB,gBAAgB,EAChB,cAAc,EACd,WAAW,EACX,WAAW,GACZ,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpE,+EAA+E;AAE/E,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAIjD,+EAA+E;AAE/E,OAAO,EAAE,gBAAgB,EAAE,SAAS,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAGtG,+EAA+E;AAE/E,OAAO,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAGtF,+EAA+E;AAE/E,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAGrC,+EAA+E;AAE/E,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAEnE,+EAA+E;AAE/E,OAAO,EACL,iBAAiB,EACjB,UAAU,EACV,gBAAgB,EAChB,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,iBAAiB,CAAC"}

package/dist/json.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 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 JSON reader and writer that keeps 64-bit integers exact.
+ *
+ * CamusDB is a 64-bit database. An `int64` column, a transaction's physical-time component, and a
+ * date's tick count all reach the wire as JSON numbers whose value can exceed 2^53, which is where
+ * a JavaScript number stops being able to name every integer. `JSON.parse` would round such a
+ * value silently, and `JSON.stringify` refuses a `bigint` outright. Both are unacceptable in a
+ * driver: a row must come back holding what was written.
+ *
+ * So this module reads an integer that does not fit a `number` as a `bigint`, and writes a
+ * `bigint` as the bare digits a JSON number is. Everything else behaves exactly as the built-in
+ * functions do.
+ */
+/**
+ * Parses JSON text, reading an integer outside the safe range as a `bigint`.
+ *
+ * The common reply holds no such integer, and the built-in parser is far faster than any parser
+ * written in JavaScript. So the text is first tested for a run of 16 or more digits — the shortest
+ * run that can leave the safe range. Without one the built-in parser is exact and is used. A run
+ * inside a string literal costs nothing but a slower parse of that one reply.
+ */
+export declare function parseLossless(text: string): unknown;
+/**
+ * Serializes a value as JSON, writing a `bigint` as a JSON number.
+ *
+ * `undefined`, a function, and a symbol are omitted from an object and become `null` in an array,
+ * which is what `JSON.stringify` does. A value with a `toJSON` method is replaced by its result,
+ * also as `JSON.stringify` does.
+ */
+export declare function stringifyLossless(value: unknown): string;
+/** Reads a value that may have arrived as a number, a bigint, or a numeric string. */
+export declare function asBigInt(value: unknown, fallback?: bigint): bigint;
+/** Reads a value that may have arrived as a number or a bigint, as a `number`. */
+export declare function asNumber(value: unknown, fallback?: number): number;
+//# sourceMappingURL=json.d.ts.map

package/dist/json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.d.ts","sourceRoot":"","sources":["../src/json.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;;;;GAYG;AAEH;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEnD;AAID;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAIxD;AAwVD,sFAAsF;AACtF,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,SAAK,GAAG,MAAM,CAe9D;AAED,kFAAkF;AAClF,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,SAAI,GAAG,MAAM,CAa7D"}