camusdb 0.1.0

package/dist/values/encode.js

@@ -0,0 +1,271 @@
+/**
+ * This file is part of CamusDB
+ *
+ * For the full copyright and license information, please view the LICENSE.txt
+ * file that was distributed with this source code.
+ */
+import { ColumnType, columnTypeName } from '../column-type.js';
+import { CamusError } from '../errors.js';
+import { CamusErrorCode } from '../error-codes.js';
+import { CamusObjectId } from '../object-id.js';
+import { dateToDayTicks, dateToTicks } from './ticks.js';
+import { isUuid, uuidToHalves } from './uuid.js';
+import { isTypedParameter, registerArrayEncoder } from './typed.js';
+/**
+ * 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 function encodeParameter(value) {
+    if (isTypedParameter(value))
+        return value.value;
+    return encodeInferred(value);
+}
+/**
+ * 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 function encodeParameters(parameters) {
+    if (parameters === undefined)
+        return undefined;
+    const names = Object.keys(parameters);
+    if (names.length === 0)
+        return undefined;
+    const encoded = new Map();
+    for (const name of names) {
+        if (name.length === 0) {
+            throw new CamusError(CamusErrorCode.InvalidParameter, 'A parameter name cannot be empty.');
+        }
+        const wireName = name.startsWith('@') ? name : `@${name}`;
+        if (encoded.has(wireName)) {
+            throw new CamusError(CamusErrorCode.InvalidParameter, `The parameter '${wireName}' is bound twice. A name with and without its leading '@' is the same parameter.`);
+        }
+        encoded.set(wireName, encodeParameter(parameters[name]));
+    }
+    return encoded;
+}
+/** Encodes one value against a declared column type. Used for array elements. */
+export function encodeAs(value, declared) {
+    if (value === null || value === undefined)
+        return { type: ColumnType.Null };
+    if (isTypedParameter(value))
+        return value.value;
+    switch (declared) {
+        case ColumnType.Null:
+            return { type: ColumnType.Null };
+        case ColumnType.Id:
+            return { type: ColumnType.Id, strValue: asIdString(value) };
+        case ColumnType.String:
+            return { type: ColumnType.String, strValue: asString(value) };
+        case ColumnType.Uuid:
+            return encodeUuid(asString(value));
+        case ColumnType.Integer64:
+            return { type: ColumnType.Integer64, longValue: asBigInt(value) };
+        case ColumnType.Float64:
+        case ColumnType.Float32:
+            return { type: declared, floatValue: asNumber(value) };
+        case ColumnType.Bool:
+            return { type: ColumnType.Bool, boolValue: asBoolean(value) };
+        case ColumnType.Bytes:
+            return { type: ColumnType.Bytes, bytesValue: asBytes(value) };
+        case ColumnType.Date:
+            return { type: ColumnType.Date, longValue: dateToDayTicks(asDate(value)) };
+        case ColumnType.DateTime:
+            return { type: ColumnType.DateTime, longValue: dateToTicks(asDate(value)) };
+        case ColumnType.Array:
+            return encodeArray(value, ColumnType.Null);
+        default:
+            return invalid(`Cannot encode a value as ${columnTypeName(declared)}.`);
+    }
+}
+registerArrayEncoder(encodeAs);
+function encodeInferred(value) {
+    if (value === null || value === undefined)
+        return { type: ColumnType.Null };
+    switch (typeof value) {
+        case 'boolean':
+            return { type: ColumnType.Bool, boolValue: value };
+        case 'bigint':
+            return { type: ColumnType.Integer64, longValue: value };
+        case 'string':
+            return { type: ColumnType.String, strValue: value };
+        case 'number':
+            return Number.isInteger(value)
+                ? { type: ColumnType.Integer64, longValue: BigInt(value) }
+                : { type: ColumnType.Float64, floatValue: value };
+        case 'object':
+            break;
+        default:
+            return invalid(`Cannot bind a value of type ${typeof value}.`);
+    }
+    if (value instanceof Date) {
+        return { type: ColumnType.DateTime, longValue: dateToTicks(value) };
+    }
+    if (value instanceof CamusObjectId) {
+        return { type: ColumnType.Id, strValue: value.toString() };
+    }
+    if (value instanceof Float32Array) {
+        return { type: ColumnType.Bytes, bytesValue: packVector(value) };
+    }
+    if (value instanceof Uint8Array) {
+        return { type: ColumnType.Bytes, bytesValue: value };
+    }
+    if (value instanceof ArrayBuffer) {
+        return { type: ColumnType.Bytes, bytesValue: new Uint8Array(value) };
+    }
+    if (ArrayBuffer.isView(value)) {
+        return {
+            type: ColumnType.Bytes,
+            bytesValue: new Uint8Array(value.buffer, value.byteOffset, value.byteLength),
+        };
+    }
+    if (Array.isArray(value)) {
+        return encodeArray(value, ColumnType.Null);
+    }
+    return invalid(`Cannot bind a value of type ${describe(value)}.`);
+}
+function encodeArray(value, declaredElementType) {
+    if (!Array.isArray(value)) {
+        return invalid(`An array parameter needs an array; got ${describe(value)}.`);
+    }
+    let elementType = declaredElementType;
+    if (elementType === ColumnType.Null) {
+        for (const item of value) {
+            if (item === null || item === undefined)
+                continue;
+            elementType = inferElementType(item);
+            break;
+        }
+        if (elementType === ColumnType.Null && value.length > 0) {
+            return invalid('Cannot infer the element type of an array parameter whose elements are all null. ' +
+                'State it with camus.array(items, ColumnType.…).');
+        }
+    }
+    const items = new Array(value.length);
+    for (let i = 0; i < value.length; i++) {
+        const item = value[i];
+        items[i] = item === null || item === undefined ? { type: ColumnType.Null } : encodeAs(item, elementType);
+    }
+    return { type: ColumnType.Array, arrayElementType: elementType, arrayValues: items };
+}
+function inferElementType(item) {
+    if (isTypedParameter(item))
+        return item.value.type;
+    return encodeInferred(item).type;
+}
+function encodeUuid(value) {
+    if (!isUuid(value)) {
+        return invalid(`'${value}' is not a canonical UUID string.`);
+    }
+    const { high, low } = uuidToHalves(value);
+    return { type: ColumnType.Uuid, strValue: value, uuidHigh: high, longValue: low };
+}
+function packVector(vector) {
+    const bytes = new Uint8Array(vector.length * 4);
+    const view = new DataView(bytes.buffer);
+    for (let i = 0; i < vector.length; i++) {
+        view.setFloat32(i * 4, vector[i], true);
+    }
+    return bytes;
+}
+function asString(value) {
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number' || typeof value === 'bigint' || typeof value === 'boolean') {
+        return String(value);
+    }
+    return invalid(`Cannot use ${describe(value)} as a string value.`);
+}
+function asIdString(value) {
+    if (value instanceof CamusObjectId)
+        return value.toString();
+    return asString(value);
+}
+function asBigInt(value) {
+    if (typeof value === 'bigint')
+        return value;
+    if (typeof value === 'number') {
+        if (!Number.isInteger(value)) {
+            return invalid(`An int64 parameter needs an integer; got ${String(value)}.`);
+        }
+        return BigInt(value);
+    }
+    if (typeof value === 'boolean')
+        return value ? 1n : 0n;
+    return invalid(`Cannot use ${describe(value)} as an int64 value.`);
+}
+function asNumber(value) {
+    if (typeof value === 'number')
+        return value;
+    if (typeof value === 'bigint')
+        return Number(value);
+    if (typeof value === 'boolean')
+        return value ? 1 : 0;
+    return invalid(`Cannot use ${describe(value)} as a float value.`);
+}
+function asBoolean(value) {
+    if (typeof value === 'boolean')
+        return value;
+    if (typeof value === 'number')
+        return value !== 0;
+    if (typeof value === 'bigint')
+        return value !== 0n;
+    return invalid(`Cannot use ${describe(value)} as a bool value.`);
+}
+function asBytes(value) {
+    if (value instanceof Float32Array)
+        return packVector(value);
+    if (value instanceof Uint8Array)
+        return value;
+    if (value instanceof ArrayBuffer)
+        return new Uint8Array(value);
+    if (ArrayBuffer.isView(value)) {
+        return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+    }
+    if (Array.isArray(value))
+        return Uint8Array.from(value);
+    return invalid(`Cannot use ${describe(value)} as a bytes value.`);
+}
+function asDate(value) {
+    if (value instanceof Date)
+        return value;
+    if (typeof value === 'number')
+        return new Date(value);
+    if (typeof value === 'string') {
+        const parsed = new Date(value);
+        if (Number.isNaN(parsed.getTime())) {
+            return invalid(`'${value}' is not a date this driver can read.`);
+        }
+        return parsed;
+    }
+    return invalid(`Cannot use ${describe(value)} as a date value.`);
+}
+function describe(value) {
+    if (value === null)
+        return 'null';
+    if (value === undefined)
+        return 'undefined';
+    if (typeof value !== 'object')
+        return typeof value;
+    return value.constructor?.name ?? 'object';
+}
+function invalid(message) {
+    throw new CamusError(CamusErrorCode.InvalidParameter, message);
+}
+//# sourceMappingURL=encode.js.map

package/dist/values/encode.js.map

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

package/dist/values/ticks.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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.
+ */
+/**
+ * Converts between a JavaScript `Date` and the .NET tick count CamusDB stores for a `Date` or a
+ * `DateTime` column.
+ *
+ * A tick is 100 nanoseconds. Tick zero is 0001-01-01T00:00:00 UTC. A `Date` holds whole
+ * milliseconds since 1970-01-01T00:00:00 UTC, so the two differ by a fixed offset and by
+ * resolution: 10,000 ticks make one millisecond.
+ *
+ * The conversion to a `Date` therefore discards sub-millisecond precision. That loss is one-way
+ * and unavoidable in JavaScript. Read `ColumnValue.longValue` from the raw row when you need the
+ * exact stored instant.
+ */
+/** Ticks in one millisecond. */
+export declare const TICKS_PER_MILLISECOND = 10000n;
+/** Ticks in one day. */
+export declare const TICKS_PER_DAY = 864000000000n;
+/** Ticks between 0001-01-01 and the Unix epoch. */
+export declare const UNIX_EPOCH_TICKS = 621355968000000000n;
+/** The UTC `Date` a tick count names. Sub-millisecond precision is truncated toward the past. */
+export declare function ticksToDate(ticks: bigint): Date;
+/** The tick count for an instant. */
+export declare function dateToTicks(date: Date): bigint;
+/** The tick count for an instant, truncated to UTC midnight — what a `Date` column stores. */
+export declare function dateToDayTicks(date: Date): bigint;
+//# sourceMappingURL=ticks.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ticks.d.ts","sourceRoot":"","sources":["../../src/values/ticks.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;;;GAWG;AAEH,gCAAgC;AAChC,eAAO,MAAM,qBAAqB,SAAU,CAAC;AAE7C,wBAAwB;AACxB,eAAO,MAAM,aAAa,gBAAmB,CAAC;AAE9C,mDAAmD;AACnD,eAAO,MAAM,gBAAgB,sBAA2B,CAAC;AAEzD,iGAAiG;AACjG,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAG/C;AAED,qCAAqC;AACrC,wBAAgB,WAAW,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAQ9C;AAED,8FAA8F;AAC9F,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAGjD"}

package/dist/values/ticks.js

@@ -0,0 +1,52 @@
+/**
+ * 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.
+ */
+/**
+ * Converts between a JavaScript `Date` and the .NET tick count CamusDB stores for a `Date` or a
+ * `DateTime` column.
+ *
+ * A tick is 100 nanoseconds. Tick zero is 0001-01-01T00:00:00 UTC. A `Date` holds whole
+ * milliseconds since 1970-01-01T00:00:00 UTC, so the two differ by a fixed offset and by
+ * resolution: 10,000 ticks make one millisecond.
+ *
+ * The conversion to a `Date` therefore discards sub-millisecond precision. That loss is one-way
+ * and unavoidable in JavaScript. Read `ColumnValue.longValue` from the raw row when you need the
+ * exact stored instant.
+ */
+/** Ticks in one millisecond. */
+export const TICKS_PER_MILLISECOND = 10000n;
+/** Ticks in one day. */
+export const TICKS_PER_DAY = 864000000000n;
+/** Ticks between 0001-01-01 and the Unix epoch. */
+export const UNIX_EPOCH_TICKS = 621355968000000000n;
+/** The UTC `Date` a tick count names. Sub-millisecond precision is truncated toward the past. */
+export function ticksToDate(ticks) {
+    const millis = floorDiv(ticks - UNIX_EPOCH_TICKS, TICKS_PER_MILLISECOND);
+    return new Date(Number(millis));
+}
+/** The tick count for an instant. */
+export function dateToTicks(date) {
+    const millis = date.getTime();
+    if (!Number.isFinite(millis)) {
+        throw new RangeError('An invalid Date has no tick value.');
+    }
+    return BigInt(millis) * TICKS_PER_MILLISECOND + UNIX_EPOCH_TICKS;
+}
+/** The tick count for an instant, truncated to UTC midnight — what a `Date` column stores. */
+export function dateToDayTicks(date) {
+    const ticks = dateToTicks(date);
+    return ticks - floorMod(ticks, TICKS_PER_DAY);
+}
+// BigInt division truncates toward zero, so a pre-epoch instant would round the wrong way.
+function floorDiv(a, b) {
+    const quotient = a / b;
+    return a % b !== 0n && a < 0n !== b < 0n ? quotient - 1n : quotient;
+}
+function floorMod(a, b) {
+    const remainder = a % b;
+    return remainder !== 0n && remainder < 0n !== b < 0n ? remainder + b : remainder;
+}
+//# sourceMappingURL=ticks.js.map

package/dist/values/ticks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ticks.js","sourceRoot":"","sources":["../../src/values/ticks.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;;;GAWG;AAEH,gCAAgC;AAChC,MAAM,CAAC,MAAM,qBAAqB,GAAG,MAAO,CAAC;AAE7C,wBAAwB;AACxB,MAAM,CAAC,MAAM,aAAa,GAAG,aAAgB,CAAC;AAE9C,mDAAmD;AACnD,MAAM,CAAC,MAAM,gBAAgB,GAAG,mBAAwB,CAAC;AAEzD,iGAAiG;AACjG,MAAM,UAAU,WAAW,CAAC,KAAa;IACvC,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,GAAG,gBAAgB,EAAE,qBAAqB,CAAC,CAAC;IACzE,OAAO,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;AAClC,CAAC;AAED,qCAAqC;AACrC,MAAM,UAAU,WAAW,CAAC,IAAU;IACpC,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;IAE9B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,UAAU,CAAC,oCAAoC,CAAC,CAAC;IAC7D,CAAC;IAED,OAAO,MAAM,CAAC,MAAM,CAAC,GAAG,qBAAqB,GAAG,gBAAgB,CAAC;AACnE,CAAC;AAED,8FAA8F;AAC9F,MAAM,UAAU,cAAc,CAAC,IAAU;IACvC,MAAM,KAAK,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;IAChC,OAAO,KAAK,GAAG,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC;AAChD,CAAC;AAED,2FAA2F;AAC3F,SAAS,QAAQ,CAAC,CAAS,EAAE,CAAS;IACpC,MAAM,QAAQ,GAAG,CAAC,GAAG,CAAC,CAAC;IACvB,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,QAAQ,GAAG,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC;AACtE,CAAC;AAED,SAAS,QAAQ,CAAC,CAAS,EAAE,CAAS;IACpC,MAAM,SAAS,GAAG,CAAC,GAAG,CAAC,CAAC;IACxB,OAAO,SAAS,KAAK,EAAE,IAAI,SAAS,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AACnF,CAAC"}

package/dist/values/typed.d.ts

@@ -0,0 +1,67 @@
+/**
+ * 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';
+declare const TYPED: unique symbol;
+/**
+ * A parameter whose column type the caller stated, rather than one the driver inferred from the
+ * JavaScript value. Build one with a helper from `camus` below and pass it as a parameter value.
+ */
+export interface TypedParameter {
+    readonly [TYPED]: true;
+    readonly value: ColumnValue;
+}
+/** True when `value` came from one of the `camus.*` helpers. */
+export declare function isTypedParameter(value: unknown): value is TypedParameter;
+/**
+ * Explicit column types for parameters.
+ *
+ * The driver infers a column type from the JavaScript value, which is right for most parameters. A
+ * helper here states the type instead, for the cases inference cannot reach: a `uuid` column (a
+ * UUID is an ordinary string in JavaScript), an `id` column, a `float32` column, a date-only
+ * column, and an empty array, whose element type nothing can be read from.
+ */
+export declare const camus: {
+    /** An `id` column value: an ObjectId as its 24-character string. */
+    readonly id: (value: string) => TypedParameter;
+    /** A `uuid` column value, from the canonical hyphenated string. */
+    readonly uuid: (value: string) => TypedParameter;
+    /** An `int64` column value. */
+    readonly int64: (value: number | bigint) => TypedParameter;
+    /** A `float64` column value. */
+    readonly float64: (value: number) => TypedParameter;
+    /** A `float32` column value. The server narrows it to single precision. */
+    readonly float32: (value: number) => TypedParameter;
+    /** A `bool` column value. */
+    readonly bool: (value: boolean) => TypedParameter;
+    /** A `string` column value. */
+    readonly string: (value: string) => TypedParameter;
+    /** A `bytes` column value. */
+    readonly bytes: (value: Uint8Array | ArrayBuffer) => TypedParameter;
+    /**
+     * A `bytes` column value holding an embedding: tightly packed little-endian float32 elements.
+     * The same layout `CamusVector` reads back.
+     */
+    readonly vector: (value: ArrayLike<number>) => TypedParameter;
+    /** A `date` column value. The instant is truncated to UTC midnight, as the column stores it. */
+    readonly date: (value: Date) => TypedParameter;
+    /** A `datetime` column value. */
+    readonly dateTime: (value: Date) => TypedParameter;
+    /**
+     * An array column value with a stated element type. Use it for an empty array, whose element
+     * type cannot be inferred, and whenever the element type is not the one inference would pick.
+     */
+    readonly array: (items: readonly unknown[], elementType: ColumnType) => TypedParameter;
+    /** A typed `NULL`. */
+    readonly null: () => TypedParameter;
+    /** A value built by hand, sent as written. The escape hatch when nothing above fits. */
+    readonly raw: (value: ColumnValue) => TypedParameter;
+};
+/** @internal */
+export declare function registerArrayEncoder(encode: (value: unknown, declared: ColumnType) => ColumnValue): void;
+export {};
+//# sourceMappingURL=typed.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"typed.d.ts","sourceRoot":"","sources":["../../src/values/typed.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAMtD,QAAA,MAAM,KAAK,eAAuC,CAAC;AAEnD;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;CAC7B;AAED,gEAAgE;AAChE,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAExE;AAUD;;;;;;;GAOG;AACH,eAAO,MAAM,KAAK;IAChB,oEAAoE;yBAC1D,MAAM,KAAG,cAAc;IAIjC,mEAAmE;2BACvD,MAAM,KAAG,cAAc;IASnC,+BAA+B;4BAClB,MAAM,GAAG,MAAM,KAAG,cAAc;IAI7C,gCAAgC;8BACjB,MAAM,KAAG,cAAc;IAItC,2EAA2E;8BAC5D,MAAM,KAAG,cAAc;IAItC,6BAA6B;2BACjB,OAAO,KAAG,cAAc;IAIpC,+BAA+B;6BACjB,MAAM,KAAG,cAAc;IAIrC,8BAA8B;4BACjB,UAAU,GAAG,WAAW,KAAG,cAAc;IAItD;;;OAGG;6BACW,SAAS,CAAC,MAAM,CAAC,KAAG,cAAc;IAWhD,gGAAgG;2BACpF,IAAI,KAAG,cAAc;IAIjC,iCAAiC;+BACjB,IAAI,KAAG,cAAc;IAIrC;;;OAGG;4BACU,SAAS,OAAO,EAAE,eAAe,UAAU,KAAG,cAAc;IAiBzE,sBAAsB;yBACd,cAAc;IAItB,wFAAwF;0BAC7E,WAAW,KAAG,cAAc;CAG/B,CAAC;AASX,gBAAgB;AAChB,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,KAAK,WAAW,GAAG,IAAI,CAExG"}

package/dist/values/typed.js

@@ -0,0 +1,134 @@
+/**
+ * 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 { CamusError } from '../errors.js';
+import { CamusErrorCode } from '../error-codes.js';
+import { dateToDayTicks, dateToTicks } from './ticks.js';
+import { isUuid, uuidToHalves } from './uuid.js';
+const TYPED = Symbol.for('camusdb.typedParameter');
+/** True when `value` came from one of the `camus.*` helpers. */
+export function isTypedParameter(value) {
+    return typeof value === 'object' && value !== null && value[TYPED] === true;
+}
+function typed(value) {
+    return { [TYPED]: true, value };
+}
+function invalid(message) {
+    throw new CamusError(CamusErrorCode.InvalidParameter, message);
+}
+/**
+ * Explicit column types for parameters.
+ *
+ * The driver infers a column type from the JavaScript value, which is right for most parameters. A
+ * helper here states the type instead, for the cases inference cannot reach: a `uuid` column (a
+ * UUID is an ordinary string in JavaScript), an `id` column, a `float32` column, a date-only
+ * column, and an empty array, whose element type nothing can be read from.
+ */
+export const camus = {
+    /** An `id` column value: an ObjectId as its 24-character string. */
+    id(value) {
+        return typed({ type: ColumnType.Id, strValue: value });
+    },
+    /** A `uuid` column value, from the canonical hyphenated string. */
+    uuid(value) {
+        if (!isUuid(value)) {
+            invalid(`'${value}' is not a canonical UUID string.`);
+        }
+        const { high, low } = uuidToHalves(value);
+        return typed({ type: ColumnType.Uuid, strValue: value, uuidHigh: high, longValue: low });
+    },
+    /** An `int64` column value. */
+    int64(value) {
+        return typed({ type: ColumnType.Integer64, longValue: toBigInt(value) });
+    },
+    /** A `float64` column value. */
+    float64(value) {
+        return typed({ type: ColumnType.Float64, floatValue: value });
+    },
+    /** A `float32` column value. The server narrows it to single precision. */
+    float32(value) {
+        return typed({ type: ColumnType.Float32, floatValue: value });
+    },
+    /** A `bool` column value. */
+    bool(value) {
+        return typed({ type: ColumnType.Bool, boolValue: value });
+    },
+    /** A `string` column value. */
+    string(value) {
+        return typed({ type: ColumnType.String, strValue: value });
+    },
+    /** A `bytes` column value. */
+    bytes(value) {
+        return typed({ type: ColumnType.Bytes, bytesValue: toBytes(value) });
+    },
+    /**
+     * A `bytes` column value holding an embedding: tightly packed little-endian float32 elements.
+     * The same layout `CamusVector` reads back.
+     */
+    vector(value) {
+        const bytes = new Uint8Array(value.length * 4);
+        const view = new DataView(bytes.buffer);
+        for (let i = 0; i < value.length; i++) {
+            view.setFloat32(i * 4, value[i], true);
+        }
+        return typed({ type: ColumnType.Bytes, bytesValue: bytes });
+    },
+    /** A `date` column value. The instant is truncated to UTC midnight, as the column stores it. */
+    date(value) {
+        return typed({ type: ColumnType.Date, longValue: dateToDayTicks(value) });
+    },
+    /** A `datetime` column value. */
+    dateTime(value) {
+        return typed({ type: ColumnType.DateTime, longValue: dateToTicks(value) });
+    },
+    /**
+     * An array column value with a stated element type. Use it for an empty array, whose element
+     * type cannot be inferred, and whenever the element type is not the one inference would pick.
+     */
+    array(items, elementType) {
+        // Imported lazily to break the cycle with the encoder, which imports this module.
+        const encode = arrayEncoder;
+        if (encode === undefined) {
+            throw new Error('The value encoder is not registered yet.');
+        }
+        return typed({
+            type: ColumnType.Array,
+            arrayElementType: elementType,
+            arrayValues: items.map((item) => item === null || item === undefined ? { type: ColumnType.Null } : encode(item, elementType)),
+        });
+    },
+    /** A typed `NULL`. */
+    null() {
+        return typed({ type: ColumnType.Null });
+    },
+    /** A value built by hand, sent as written. The escape hatch when nothing above fits. */
+    raw(value) {
+        return typed(value);
+    },
+};
+/**
+ * The element encoder `camus.array` uses, registered by the encoder module at load time. The two
+ * modules genuinely need each other — an array holds values, and a value can be an array — and a
+ * one-way registration is clearer than a cycle the bundler has to resolve.
+ */
+let arrayEncoder;
+/** @internal */
+export function registerArrayEncoder(encode) {
+    arrayEncoder = encode;
+}
+function toBigInt(value) {
+    if (typeof value === 'bigint')
+        return value;
+    if (!Number.isInteger(value)) {
+        invalid(`An int64 parameter needs an integer; got ${String(value)}.`);
+    }
+    return BigInt(value);
+}
+function toBytes(value) {
+    return value instanceof Uint8Array ? value : new Uint8Array(value);
+}
+//# sourceMappingURL=typed.js.map

package/dist/values/typed.js.map

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

package/dist/values/uuid.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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 `value` is a canonical hyphenated UUID string. Matching ignores case. */
+export declare function isUuid(value: string): boolean;
+/** The 16 big-endian bytes of a canonical UUID string. */
+export declare function uuidToBytes(uuid: string): Uint8Array;
+/** The canonical string for 16 big-endian bytes. */
+export declare function bytesToUuid(bytes: Uint8Array): string;
+/** The two big-endian 64-bit halves of a canonical UUID string. */
+export declare function uuidToHalves(uuid: string): {
+    high: bigint;
+    low: bigint;
+};
+/** The two big-endian 64-bit halves of 16 bytes. */
+export declare function bytesToHalves(bytes: Uint8Array): {
+    high: bigint;
+    low: bigint;
+};
+/** The 16 big-endian bytes of two 64-bit halves. */
+export declare function halvesToBytes(high: bigint, low: bigint): Uint8Array;
+/** The canonical string for two 64-bit halves. */
+export declare function halvesToUuid(high: bigint, low: bigint): string;
+//# sourceMappingURL=uuid.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"uuid.d.ts","sourceRoot":"","sources":["../../src/values/uuid.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAgBH,sFAAsF;AACtF,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE7C;AAED,0DAA0D;AAC1D,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAoBpD;AAED,oDAAoD;AACpD,wBAAgB,WAAW,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAcrD;AAED,mEAAmE;AACnE,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAExE;AAED,oDAAoD;AACpD,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAM9E;AAED,oDAAoD;AACpD,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,UAAU,CAMnE;AAED,kDAAkD;AAClD,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAE9D"}