camusdb 0.1.0

package/dist/transport/transport.d.ts

@@ -0,0 +1,199 @@
+/**
+ * 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 { CamusCacheMetadata } from '../cache.js';
+import type { ColumnValue } from '../column-value.js';
+import type { CamusProtocol } from '../config.js';
+import type { CamusTransactionOptions } from '../options.js';
+import type { CamusResultSet } from '../result-set.js';
+import type { CamusRoutingAdvice } from '../routing/advice.js';
+import type { CamusRowSource } from '../row-source.js';
+/** One row of `SHOW BRANCHES` or `SHOW ANCESTORS`. */
+export interface CamusBranchRow {
+    readonly database?: string | undefined;
+    readonly id?: string | undefined;
+    readonly depth: number;
+    readonly parent?: string | undefined;
+    readonly forkTimestamp?: string | undefined;
+}
+/**
+ * A SQL request handed to a transport, in terms neither protocol owns.
+ *
+ * It carries everything a transport needs to run one statement: the resolved endpoint, the
+ * database, the SQL text, the bound parameters, and either the explicit transaction handle to join
+ * or the autocommit concurrency options the server should begin this statement's own short
+ * transaction with.
+ */
+export interface TransportSqlRequest {
+    readonly endpoint: string;
+    readonly database: string;
+    readonly sql: string;
+    readonly parameters?: ReadonlyMap<string, ColumnValue> | undefined;
+    /** The explicit transaction to resume. When set, `autocommitOptions` is ignored. */
+    readonly txnIdPT?: bigint | undefined;
+    readonly txnIdCounter?: number | undefined;
+    /**
+     * Concurrency options for the short transaction the server begins for this statement. They apply
+     * only when there is no explicit transaction, and are absent on the read-query path, which has
+     * no locking mode.
+     */
+    readonly autocommitOptions?: CamusTransactionOptions | undefined;
+    /**
+     * An opaque transport routing hint. For the gRPC batching transport it is the reserved
+     * `BatchExecute` stream slot a transaction's operations pin to, so the server orders them. The
+     * REST transport ignores it.
+     */
+    readonly streamSlot?: number | undefined;
+    readonly timeoutSeconds: number;
+    /**
+     * Run this statement as a prepared execution: the transport registers the SQL once, or reuses a
+     * registration it already holds, then sends only the handle and the values in the server's
+     * published binding order.
+     *
+     * It is a hint, not a demand. How a handle is scoped, invalidated, and replayed is the
+     * transport's business, and a transport that cannot prepare this statement runs it inline
+     * instead, with identical semantics.
+     */
+    readonly prepared: boolean;
+    /**
+     * The highest routing-metadata version the caller accepts on this statement's response. Zero,
+     * the default, asks for none and keeps the exact pre-routing wire shape.
+     */
+    readonly routingAcceptVersion: number;
+    readonly signal?: AbortSignal | undefined;
+}
+/**
+ * A row insert handed to a transport.
+ *
+ * The typed row-level insert names a table and a column-to-value map rather than SQL text, so it
+ * cannot ride `TransportSqlRequest`. It is otherwise an ordinary statement, and goes through the
+ * same transport, and therefore the same authorization, endpoint health, and error translation, as
+ * everything else.
+ */
+export interface TransportInsertRequest {
+    readonly endpoint: string;
+    readonly database: string;
+    readonly table: string;
+    readonly values?: ReadonlyMap<string, ColumnValue> | undefined;
+    readonly txnIdPT?: bigint | undefined;
+    readonly txnIdCounter?: number | undefined;
+    readonly streamSlot?: number | undefined;
+    readonly timeoutSeconds: number;
+    readonly signal?: AbortSignal | undefined;
+}
+/**
+ * The identity the server minted for a transaction, plus the opaque stream slot its later
+ * operations must pin to. The slot is absent for a transport that does not pin.
+ */
+export interface StartTransactionResult {
+    readonly txnIdPT: bigint;
+    readonly txnIdCounter: number;
+    readonly streamSlot?: number | undefined;
+}
+/** A decoded query result, plus whatever advisory metadata the response carried. */
+export interface QueryTransportResult {
+    readonly resultSet: CamusResultSet;
+    readonly cacheMetadata?: CamusCacheMetadata | undefined;
+    readonly routing?: CamusRoutingAdvice | undefined;
+}
+/** The affected-row count of a write statement, plus any routing advice its response carried. */
+export interface NonQueryTransportResult {
+    readonly affectedRows: number;
+    readonly routing?: CamusRoutingAdvice | undefined;
+}
+/** A statement the server registered: the placeholder names it declares, in binding order. */
+export interface PreparedStatementInfo {
+    readonly parameterNames: readonly string[];
+}
+/**
+ * The seam between the client surface and the wire protocol.
+ *
+ * One implementation speaks REST and JSON, another speaks gRPC. The client layer is
+ * protocol-agnostic and works entirely in CamusDB domain types whichever one is chosen.
+ *
+ * Every method performs exactly one round trip and turns a protocol-level failure into a
+ * `CamusError` carrying the server's `CADBxxxx` code. Retry policies that do not depend on the
+ * protocol — the `CADB0509` finalize loop, the transient create-database loop — stay in the client
+ * layer, so each transport call is a single attempt.
+ */
+export interface CamusTransport {
+    /** The protocol this transport implements. */
+    readonly protocol: CamusProtocol;
+    /** Begins an explicit transaction and reports the handle the server minted. */
+    startTransaction(endpoint: string, database: string, options: CamusTransactionOptions, timeoutSeconds: number, signal?: AbortSignal): Promise<StartTransactionResult>;
+    /**
+     * Commits or rolls back the transaction the handle names. It is a single attempt: the caller
+     * owns the `CADB0509` finalize-retry loop. `streamSlot` is the slot `startTransaction` reported;
+     * gRPC pins the finalize to the same stream as the transaction's statements, and REST ignores it.
+     */
+    finalizeTransaction(commit: boolean, endpoint: string, database: string, txnIdPT: bigint, txnIdCounter: number, streamSlot: number | undefined, timeoutSeconds: number, signal?: AbortSignal): Promise<void>;
+    /** Runs a `SELECT` and reports its decoded rows plus any cache and routing metadata. */
+    executeQuery(request: TransportSqlRequest): Promise<QueryTransportResult>;
+    /**
+     * Runs a `SELECT` and reports a source whose rows are pulled as the caller advances, so a large
+     * result never fully materializes on this side.
+     *
+     * REST streams the NDJSON body row by row. gRPC multiplexes its data plane over shared streams
+     * that decode a whole result before returning, so it buffers and replays through the same
+     * interface: correct, and uniform for the caller, but not incremental.
+     *
+     * The streaming path gives up the buffered path's transparent retry of a serializable conflict.
+     * Rows can reach the caller before the autocommit transaction commits, so a late conflict is
+     * reported while reading rather than retried.
+     */
+    executeQueryStream(request: TransportSqlRequest): Promise<CamusRowSource>;
+    /** Runs an `INSERT`, `UPDATE`, or `DELETE` and reports the affected-row count. */
+    executeNonQuery(request: TransportSqlRequest): Promise<NonQueryTransportResult>;
+    /**
+     * Inserts one row through the server's typed row-level surface — the same operation `INSERT INTO`
+     * performs, written as a table plus a column-to-value map instead of SQL text.
+     */
+    insert(request: TransportInsertRequest): Promise<number>;
+    /** Runs a DDL statement. */
+    executeDdl(request: TransportSqlRequest): Promise<boolean>;
+    /**
+     * Registers SQL as a prepared statement and reports the placeholder names in binding order, or
+     * reuses a registration this transport already holds for it.
+     *
+     * A caller receives no handle. A handle's lifetime is a property of the transport that minted it
+     * — a gRPC handle dies with its stream, a REST handle with an idle timeout or a node restart —
+     * so it stays inside, where it can be checked and renewed. What a caller gets is the statement's
+     * binding order, and the knowledge that later prepared executions will be cheap.
+     *
+     * It is idempotent per endpoint, database, and SQL; concurrent first calls share one
+     * registration.
+     */
+    prepare(endpoint: string, database: string, sql: string, timeoutSeconds: number, signal?: AbortSignal): Promise<PreparedStatementInfo>;
+    /**
+     * Releases this transport's registrations for a statement, both locally and on the server.
+     *
+     * It is best-effort by contract. A handle whose stream, node, or idle window is already gone was
+     * freed by the server anyway, so a failure here means the work was already done. Skipping it
+     * entirely is safe for the same reason: it exists so a long-lived client that cycles through
+     * many distinct statements stays under the server's caps instead of meeting them.
+     */
+    closePrepared(endpoint: string, database: string, sql: string, signal?: AbortSignal): Promise<void>;
+    /** A liveness check. Reports true when the server answers. */
+    ping(endpoint: string, timeoutSeconds: number, signal?: AbortSignal): Promise<boolean>;
+    /** Creates a database. It is a single attempt: the caller owns the transient-retry loop. */
+    createDatabase(endpoint: string, database: string, ifNotExists: boolean, timeoutSeconds: number, signal?: AbortSignal): Promise<void>;
+    /** Creates a copy-on-write branch database. A single attempt, like `createDatabase`. */
+    createBranchDatabase(endpoint: string, branchName: string, sourceDatabaseName: string, ifNotExists: boolean, timeoutSeconds: number, signal?: AbortSignal): Promise<void>;
+    /** Drops a database. */
+    dropDatabase(endpoint: string, database: string, timeoutSeconds: number, signal?: AbortSignal): Promise<void>;
+    /** Every transitive descendant of a database. */
+    showBranches(endpoint: string, database: string, timeoutSeconds: number, signal?: AbortSignal): Promise<CamusBranchRow[]>;
+    /** The full ancestry chain of a database. */
+    showAncestors(endpoint: string, database: string, timeoutSeconds: number, signal?: AbortSignal): Promise<CamusBranchRow[]>;
+    /** Releases every connection, stream, and channel this transport holds. */
+    close(): Promise<void>;
+}
+/** True when a transaction handle is present on a request. */
+export declare function hasTransaction(request: Pick<TransportSqlRequest, 'txnIdPT' | 'txnIdCounter'>): request is typeof request & {
+    txnIdPT: bigint;
+    txnIdCounter: number;
+};
+//# sourceMappingURL=transport.d.ts.map

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

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

package/dist/transport/transport.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.
+ */
+/** True when a transaction handle is present on a request. */
+export function hasTransaction(request) {
+    return request.txnIdPT !== undefined && request.txnIdCounter !== undefined;
+}
+//# sourceMappingURL=transport.js.map

package/dist/transport/transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.js","sourceRoot":"","sources":["../../src/transport/transport.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA8QH,8DAA8D;AAC9D,MAAM,UAAU,cAAc,CAC5B,OAA8D;IAE9D,OAAO,OAAO,CAAC,OAAO,KAAK,SAAS,IAAI,OAAO,CAAC,YAAY,KAAK,SAAS,CAAC;AAC7E,CAAC"}

package/dist/values/decode.d.ts

@@ -0,0 +1,39 @@
+/**
+ * This file is part of CamusDB
+ *
+ * For the full copyright and license information, please view the LICENSE.txt
+ * file that was distributed with this source code.
+ */
+import type { ColumnValue } from '../column-value.js';
+/**
+ * How an `int64` column reaches a caller.
+ *
+ * - `auto` (the default) — a `number` when the value is inside the safe integer range, a `bigint`
+ *   otherwise. Every value round-trips exactly, and ordinary counters and identifiers stay
+ *   numbers.
+ * - `number` — always a `number`. A value above 2^53 loses precision. Choose it only when the
+ *   schema cannot hold one.
+ * - `bigint` — always a `bigint`. Choose it when one uniform type matters more than convenience.
+ */
+export type Int64Mode = 'auto' | 'number' | 'bigint';
+/** How a cell is turned into a JavaScript value. */
+export interface DecodeOptions {
+    readonly int64: Int64Mode;
+}
+export declare const DEFAULT_DECODE_OPTIONS: DecodeOptions;
+/**
+ * The JavaScript value for one cell.
+ *
+ * - `Null` — `null`.
+ * - `Id` and `String` — `string`.
+ * - `Integer64` — `number` or `bigint`, per `options.int64`.
+ * - `Float64` and `Float32` — `number`.
+ * - `Bool` — `boolean`.
+ * - `Bytes` — `Uint8Array`.
+ * - `Date` and `DateTime` — `Date`, in UTC. Sub-millisecond precision is truncated; read
+ *   `longValue` from the raw row for the exact stored tick count.
+ * - `Uuid` — the canonical lowercase hyphenated `string`.
+ * - `Array` — an array of the values above.
+ */
+export declare function decodeValue(value: ColumnValue, options?: DecodeOptions): unknown;
+//# sourceMappingURL=decode.d.ts.map

package/dist/values/decode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decode.d.ts","sourceRoot":"","sources":["../../src/values/decode.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAItD;;;;;;;;;GASG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAErD,oDAAoD;AACpD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;CAC3B;AAED,eAAO,MAAM,sBAAsB,EAAE,aAAgD,CAAC;AAEtF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,GAAE,aAAsC,GAAG,OAAO,CAmCxG"}

package/dist/values/decode.js

@@ -0,0 +1,75 @@
+/**
+ * This file is part of CamusDB
+ *
+ * For the full copyright and license information, please view the LICENSE.txt
+ * file that was distributed with this source code.
+ */
+import { ColumnType } from '../column-type.js';
+import { ticksToDate } from './ticks.js';
+import { halvesToUuid } from './uuid.js';
+export const DEFAULT_DECODE_OPTIONS = Object.freeze({ int64: 'auto' });
+/**
+ * The JavaScript value for one cell.
+ *
+ * - `Null` — `null`.
+ * - `Id` and `String` — `string`.
+ * - `Integer64` — `number` or `bigint`, per `options.int64`.
+ * - `Float64` and `Float32` — `number`.
+ * - `Bool` — `boolean`.
+ * - `Bytes` — `Uint8Array`.
+ * - `Date` and `DateTime` — `Date`, in UTC. Sub-millisecond precision is truncated; read
+ *   `longValue` from the raw row for the exact stored tick count.
+ * - `Uuid` — the canonical lowercase hyphenated `string`.
+ * - `Array` — an array of the values above.
+ */
+export function decodeValue(value, options = DEFAULT_DECODE_OPTIONS) {
+    switch (value.type) {
+        case ColumnType.Null:
+            return null;
+        case ColumnType.Id:
+        case ColumnType.String:
+            return value.strValue ?? '';
+        case ColumnType.Integer64:
+            return decodeInt64(value.longValue ?? 0n, options.int64);
+        case ColumnType.Float64:
+        case ColumnType.Float32:
+            return value.floatValue ?? 0;
+        case ColumnType.Bool:
+            return value.boolValue ?? false;
+        case ColumnType.Bytes:
+            return value.bytesValue ?? new Uint8Array(0);
+        case ColumnType.Date:
+        case ColumnType.DateTime:
+            return ticksToDate(value.longValue ?? 0n);
+        case ColumnType.Uuid:
+            return decodeUuid(value);
+        case ColumnType.Array:
+            return (value.arrayValues ?? []).map((item) => decodeValue(item, options));
+        default:
+            return null;
+    }
+}
+function decodeInt64(value, mode) {
+    switch (mode) {
+        case 'bigint':
+            return value;
+        case 'number':
+            return Number(value);
+        default:
+            return value >= MIN_SAFE && value <= MAX_SAFE ? Number(value) : value;
+    }
+}
+const MIN_SAFE = BigInt(Number.MIN_SAFE_INTEGER);
+const MAX_SAFE = BigInt(Number.MAX_SAFE_INTEGER);
+function decodeUuid(value) {
+    const high = value.uuidHigh ?? 0n;
+    const low = value.longValue ?? 0n;
+    // The raw halves are authoritative. The canonical string is the fallback for a response that
+    // carried only it, and for the all-zeros UUID, whose halves are indistinguishable from absent.
+    if (high === 0n && low === 0n && value.uuidValue)
+        return value.uuidValue.toLowerCase();
+    if (high === 0n && low === 0n && value.strValue)
+        return value.strValue.toLowerCase();
+    return halvesToUuid(high, low);
+}
+//# sourceMappingURL=decode.js.map

package/dist/values/decode.js.map

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

package/dist/values/encode.d.ts

@@ -0,0 +1,45 @@
+/**
+ * This file is part of CamusDB
+ *
+ * For the full copyright and license information, please view the LICENSE.txt
+ * file that was distributed with this source code.
+ */
+import { ColumnType } from '../column-type.js';
+import type { ColumnValue } from '../column-value.js';
+/**
+ * A value a caller may bind to a parameter: a plain JavaScript value the driver infers a column
+ * type from, or a `camus.*` helper that states the type.
+ */
+export type ParameterValue = unknown;
+/** Bound parameters, keyed by placeholder name. A leading `@` is optional. */
+export type Parameters = Readonly<Record<string, ParameterValue>>;
+/**
+ * The wire form of one bound parameter.
+ *
+ * A `camus.*` helper carries its own column type. Anything else is inferred from the JavaScript
+ * value:
+ *
+ * - `null` and `undefined` — `Null`.
+ * - `boolean` — `Bool`.
+ * - `number` — `Integer64` when it is an integer, `Float64` otherwise.
+ * - `bigint` — `Integer64`.
+ * - `string` — `String`. A UUID string is **not** detected: state it with `camus.uuid`.
+ * - `Date` — `DateTime`. Use `camus.date` for a date-only column.
+ * - `Uint8Array`, `Buffer`, `ArrayBuffer` — `Bytes`.
+ * - `Float32Array` — `Bytes`, packed as a vector. It is the natural JavaScript form of an
+ *   embedding, and a packed float32 buffer has no other meaning in CamusDB.
+ * - `CamusObjectId` — `Id`.
+ * - an array — `Array`, with the element type inferred from the first element that is not null.
+ */
+export declare function encodeParameter(value: ParameterValue): ColumnValue;
+/**
+ * Builds the wire dictionary for a statement's parameters, or `undefined` when there are none.
+ *
+ * Placeholder names reach the server with a leading `@`, which is how the server publishes them
+ * for a prepared statement. A caller may write the name either way: `{ year: 1974 }` and
+ * `{ '@year': 1974 }` produce the same request.
+ */
+export declare function encodeParameters(parameters: Parameters | undefined): Map<string, ColumnValue> | undefined;
+/** Encodes one value against a declared column type. Used for array elements. */
+export declare function encodeAs(value: unknown, declared: ColumnType): ColumnValue;
+//# sourceMappingURL=encode.d.ts.map

package/dist/values/encode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encode.d.ts","sourceRoot":"","sources":["../../src/values/encode.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,UAAU,EAAkB,MAAM,mBAAmB,CAAC;AAC/D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAQtD;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,CAAC;AAErC,8EAA8E;AAC9E,MAAM,MAAM,UAAU,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC;AAElE;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,cAAc,GAAG,WAAW,CAIlE;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,UAAU,GAAG,SAAS,GAAG,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,SAAS,CA0BzG;AAED,iFAAiF;AACjF,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,GAAG,WAAW,CA0C1E"}