@lix-js/sdk 0.5.0-preview.0 → 0.5.0

package/dist/engine/functions/sequence.d.ts

@@ -0,0 +1,77 @@
+import type { LixEngine } from "../boot.js";
+import type { Lix } from "../../lix/open-lix.js";
+/**
+ * Returns the next monotonic sequence number, starting at 0.
+ *
+ * Only available in deterministic mode. Provides a simple counter for cases where
+ * you need sequential integers rather than timestamps or random values.
+ *
+ * - Requires `lix_deterministic_mode = true`
+ * - Increments by exactly 1 per call (no gaps or duplicates)
+ * - State persisted via `lix_deterministic_sequence_number` key value
+ * - Clones continue from where the sequence left off
+ * - Consider using {@link getTimestampSync}, {@link uuidV7}, or {@link nanoId} for most ID generation needs
+ *
+ * @example Basic usage (deterministic mode required)
+ * ```ts
+ * const lix = await openLix({
+ *   keyValues: [{ key: "lix_deterministic_mode", value: { enabled: true } }]
+ * });
+ * const n1 = nextDeterministicSequenceNumber({ lix }); // 0
+ * const n2 = nextDeterministicSequenceNumber({ lix }); // 1
+ * const n3 = nextDeterministicSequenceNumber({ lix }); // 2
+ * ```
+ *
+ * @example Collision-free IDs
+ * ```ts
+ * const n = nextDeterministicSequenceNumber({ lix }); // e.g. 7
+ * const id = `ENTITY_${n}`;              // "ENTITY_7"
+ * ```
+ *
+ * @example Pagination cursors
+ * ```ts
+ * const cursor = nextDeterministicSequenceNumber({ lix });
+ * await lix.db.insertInto("page_view")
+ *   .values({ cursor, page_id: "home" })
+ *   .execute();
+ * ```
+ *
+ * @param args.lix - The Lix instance with sqlite and db connections
+ * @returns The next number in the sequence (starting from 0)
+ * @throws {Error} If `lix_deterministic_mode` is not enabled
+ */
+export declare function nextSequenceNumberSync(args: {
+    engine: Pick<LixEngine, "executeSync" | "hooks" | "runtimeCacheRef">;
+}): number;
+/**
+ * Returns the next monotonic sequence number, starting at 0.
+ *
+ * Async wrapper around {@link nextSequenceNumberSync} that runs the computation
+ * next to the database engine via the engine router.
+ *
+ * - Available only when `lix_deterministic_mode.enabled = true`.
+ * - Persists state across `toBlob()`/`openLix({ blob })`.
+ * - Consider {@link getTimestampSync}, {@link uuidV7}, or {@link nanoId} for typical IDs.
+ *
+ * @example
+ * const lix = await openLix({
+ *   keyValues: [{ key: "lix_deterministic_mode", value: { enabled: true } }]
+ * })
+ * const n1 = await nextSequenceNumber({ lix }) // 0
+ * const n2 = await nextSequenceNumber({ lix }) // 1
+ */
+export declare function nextSequenceNumber(args: {
+    lix: Lix;
+}): Promise<number>;
+/**
+ * @internal
+ * Flush the in-memory deterministic counter to persistent storage.
+ *
+ * Called automatically by Lix after each committing write and during
+ * `lix.toBlob()` / `lix.close()`.  **Not part of the public API.**
+ */
+export declare function commitSequenceNumberSync(args: {
+    engine: Pick<LixEngine, "executeSync" | "hooks" | "runtimeCacheRef">;
+    timestamp?: string;
+}): void;
+//# sourceMappingURL=sequence.d.ts.map

package/dist/engine/functions/sequence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sequence.d.ts","sourceRoot":"","sources":["../../../src/engine/functions/sequence.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,uBAAuB,CAAC;AAgBjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE;IAC5C,MAAM,EAAE,IAAI,CAAC,SAAS,EAAE,aAAa,GAAG,OAAO,GAAG,iBAAiB,CAAC,CAAC;CACrE,GAAG,MAAM,CAuCT;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE;IAAE,GAAG,EAAE,GAAG,CAAA;CAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAG5E;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE;IAC9C,MAAM,EAAE,IAAI,CAAC,SAAS,EAAE,aAAa,GAAG,OAAO,GAAG,iBAAiB,CAAC,CAAC;IACrE,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,IAAI,CA4BP"}

package/dist/engine/functions/sequence.js

@@ -0,0 +1,136 @@
+import { LixKeyValueSchema, } from "../../key-value/schema-definition.js";
+import { isDeterministicModeSync } from "../deterministic-mode/is-deterministic-mode.js";
+import { getTimestampSync } from "./timestamp.js";
+import { updateUntrackedState } from "../../state/untracked/update-untracked-state.js";
+import { sql } from "kysely";
+import { internalQueryBuilder } from "../internal-query-builder.js";
+const counterCache = new WeakMap();
+/**
+ * Returns the next monotonic sequence number, starting at 0.
+ *
+ * Only available in deterministic mode. Provides a simple counter for cases where
+ * you need sequential integers rather than timestamps or random values.
+ *
+ * - Requires `lix_deterministic_mode = true`
+ * - Increments by exactly 1 per call (no gaps or duplicates)
+ * - State persisted via `lix_deterministic_sequence_number` key value
+ * - Clones continue from where the sequence left off
+ * - Consider using {@link getTimestampSync}, {@link uuidV7}, or {@link nanoId} for most ID generation needs
+ *
+ * @example Basic usage (deterministic mode required)
+ * ```ts
+ * const lix = await openLix({
+ *   keyValues: [{ key: "lix_deterministic_mode", value: { enabled: true } }]
+ * });
+ * const n1 = nextDeterministicSequenceNumber({ lix }); // 0
+ * const n2 = nextDeterministicSequenceNumber({ lix }); // 1
+ * const n3 = nextDeterministicSequenceNumber({ lix }); // 2
+ * ```
+ *
+ * @example Collision-free IDs
+ * ```ts
+ * const n = nextDeterministicSequenceNumber({ lix }); // e.g. 7
+ * const id = `ENTITY_${n}`;              // "ENTITY_7"
+ * ```
+ *
+ * @example Pagination cursors
+ * ```ts
+ * const cursor = nextDeterministicSequenceNumber({ lix });
+ * await lix.db.insertInto("page_view")
+ *   .values({ cursor, page_id: "home" })
+ *   .execute();
+ * ```
+ *
+ * @param args.lix - The Lix instance with sqlite and db connections
+ * @returns The next number in the sequence (starting from 0)
+ * @throws {Error} If `lix_deterministic_mode` is not enabled
+ */
+export function nextSequenceNumberSync(args) {
+    const engine = args.engine;
+    // Check if deterministic mode is enabled
+    if (!isDeterministicModeSync({ engine: engine })) {
+        throw new Error("nextDeterministicSequenceNumber() is available only when lix_deterministic_mode = true");
+    }
+    let state = counterCache.get(engine.runtimeCacheRef);
+    /* First use on this connection → pull initial value from DB */
+    if (!state) {
+        const compiled = internalQueryBuilder
+            .selectFrom("lix_internal_state_vtable")
+            .where("entity_id", "=", "lix_deterministic_sequence_number")
+            .where("schema_key", "=", "lix_key_value")
+            .where("version_id", "=", "global")
+            .where("snapshot_content", "is not", null)
+            .select(sql `json_extract(snapshot_content, '$.value')`.as("value"))
+            .compile();
+        const { rows } = engine.executeSync({
+            sql: compiled.sql,
+            parameters: compiled.parameters,
+        });
+        const row = rows[0];
+        // The persisted value is the next counter to use
+        const start = row ? Number(row.value) + 1 : 0;
+        state = { next: start, highestSeen: start - 1, dirty: false };
+        counterCache.set(engine.runtimeCacheRef, state);
+    }
+    /* Hand out current, then bump for the next call */
+    const count = state.next++;
+    state.highestSeen = count;
+    state.dirty = true;
+    return count;
+}
+/**
+ * Returns the next monotonic sequence number, starting at 0.
+ *
+ * Async wrapper around {@link nextSequenceNumberSync} that runs the computation
+ * next to the database engine via the engine router.
+ *
+ * - Available only when `lix_deterministic_mode.enabled = true`.
+ * - Persists state across `toBlob()`/`openLix({ blob })`.
+ * - Consider {@link getTimestampSync}, {@link uuidV7}, or {@link nanoId} for typical IDs.
+ *
+ * @example
+ * const lix = await openLix({
+ *   keyValues: [{ key: "lix_deterministic_mode", value: { enabled: true } }]
+ * })
+ * const n1 = await nextSequenceNumber({ lix }) // 0
+ * const n2 = await nextSequenceNumber({ lix }) // 1
+ */
+export async function nextSequenceNumber(args) {
+    const res = await args.lix.call("lix_next_sequence_number");
+    return Number(res);
+}
+/**
+ * @internal
+ * Flush the in-memory deterministic counter to persistent storage.
+ *
+ * Called automatically by Lix after each committing write and during
+ * `lix.toBlob()` / `lix.close()`.  **Not part of the public API.**
+ */
+export function commitSequenceNumberSync(args) {
+    const engine = args.engine;
+    const state = counterCache.get(engine.runtimeCacheRef);
+    if (!state || !state.dirty)
+        return; // nothing to do
+    state.dirty = false; // mark clean _before_ we try to write
+    const newValue = JSON.stringify({
+        key: "lix_deterministic_sequence_number",
+        value: state.highestSeen,
+    });
+    const now = args.timestamp ?? getTimestampSync({ engine });
+    updateUntrackedState({
+        engine: engine,
+        changes: [
+            {
+                entity_id: "lix_deterministic_sequence_number",
+                schema_key: LixKeyValueSchema["x-lix-key"],
+                file_id: "lix",
+                plugin_key: "lix_sdk",
+                snapshot_content: newValue,
+                schema_version: LixKeyValueSchema["x-lix-version"],
+                created_at: now,
+                lixcol_version_id: "global",
+            },
+        ],
+    });
+}
+//# sourceMappingURL=sequence.js.map

package/dist/engine/functions/sequence.js.map

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

package/dist/engine/functions/sequence.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=sequence.test.d.ts.map

package/dist/engine/functions/sequence.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sequence.test.d.ts","sourceRoot":"","sources":["../../../src/engine/functions/sequence.test.ts"],"names":[],"mappings":""}

package/dist/engine/functions/sequence.test.js

@@ -0,0 +1,77 @@
+import { expect, test } from "vitest";
+import { openLix } from "../../lix/open-lix.js";
+import { nextSequenceNumber } from "./sequence.js";
+test("nextSequenceNumberSync throws error when deterministic mode is false", async () => {
+    const lix = await openLix({
+        keyValues: [{ key: "lix_deterministic_mode", value: { enabled: false } }],
+    });
+    await expect(async () => {
+        // call inside to check throw in async wrapper by awaiting the call
+        // but since nextSequenceNumber throws only in sync variant, we emulate by calling and catching
+        await nextSequenceNumber({ lix });
+    }).rejects.toThrow("nextDeterministicSequenceNumber() is available only when lix_deterministic_mode = true");
+});
+test("nextDeterministicSequenceNumber throws error when deterministic mode is not set", async () => {
+    const lix = await openLix({});
+    await expect(async () => {
+        await nextSequenceNumber({ lix });
+    }).rejects.toThrow("nextDeterministicSequenceNumber() is available only when lix_deterministic_mode = true");
+});
+test("nextDeterministicSequenceNumber works when deterministic mode is true", async () => {
+    const lix = await openLix({
+        keyValues: [{ key: "lix_deterministic_mode", value: { enabled: true } }],
+    });
+    const n1 = await nextSequenceNumber({ lix });
+    const n2 = await nextSequenceNumber({ lix });
+    const n3 = await nextSequenceNumber({ lix });
+    // Should be strictly incrementing by 1
+    expect(n2).toBe(n1 + 1);
+    expect(n3).toBe(n2 + 1);
+    // Should be non-negative integers
+    expect(n1).toBeGreaterThanOrEqual(0);
+    expect(Number.isInteger(n1)).toBe(true);
+});
+test("nextDeterministicSequenceNumber persists state across blob operations", async () => {
+    const lix1 = await openLix({
+        keyValues: [
+            {
+                key: "lix_deterministic_mode",
+                value: { enabled: true },
+            },
+        ],
+    });
+    // Generate some sequence numbers and record the last one
+    const n1 = await nextSequenceNumber({ lix: lix1 });
+    const n2 = await nextSequenceNumber({ lix: lix1 });
+    const n3 = await nextSequenceNumber({ lix: lix1 });
+    // Verify they increment properly
+    expect(n2).toBe(n1 + 1);
+    expect(n3).toBe(n2 + 1);
+    // Create a new instance from the blob
+    const blob = await lix1.toBlob();
+    const lix2 = await openLix({ blob });
+    // Should continue from where it left off
+    const n4 = await nextSequenceNumber({ lix: lix2 });
+    const n5 = await nextSequenceNumber({ lix: lix2 });
+    expect(n4).toBe(n3 + 1);
+    expect(n5).toBe(n4 + 1);
+});
+test("independent Lix instances have independent sequences", async () => {
+    const lix1 = await openLix({
+        keyValues: [{ key: "lix_deterministic_mode", value: { enabled: true } }],
+    });
+    const lix2 = await openLix({
+        keyValues: [{ key: "lix_deterministic_mode", value: { enabled: true } }],
+    });
+    // Get initial values - they should be the same for both since they started identically
+    const lix1_n1 = await nextSequenceNumber({ lix: lix1 });
+    const lix2_n1 = await nextSequenceNumber({ lix: lix2 });
+    expect(lix1_n1).toBe(lix2_n1);
+    // Both increment independently but maintain the same sequence
+    const lix1_n2 = await nextSequenceNumber({ lix: lix1 });
+    const lix2_n2 = await nextSequenceNumber({ lix: lix2 });
+    expect(lix1_n2).toBe(lix1_n1 + 1);
+    expect(lix2_n2).toBe(lix2_n1 + 1);
+    expect(lix1_n2).toBe(lix2_n2);
+});
+//# sourceMappingURL=sequence.test.js.map

package/dist/engine/functions/sequence.test.js.map

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

package/dist/engine/functions/timestamp.d.ts

@@ -0,0 +1,44 @@
+import type { LixEngine } from "../boot.js";
+/**
+ * Sync variant of {@link getTimestamp}. See {@link getTimestamp} for behavior and examples.
+ *
+ * @remarks
+ * - Accepts `{ engine }` (or `{ lix }` for backward‑compat) and runs next to SQLite.
+ * - Intended for engine/router and UDFs; app code should use {@link getTimestamp}.
+ *
+ * @see getTimestamp
+ */
+export declare function getTimestampSync(args: {
+    engine: Pick<LixEngine, "executeSync" | "hooks" | "runtimeCacheRef">;
+}): string;
+/**
+ * Get the current timestamp as an ISO 8601 string.
+ *
+ * In deterministic mode, returns logical timestamps starting from Unix epoch (1970-01-01T00:00:00.000Z),
+ * incrementing by 1ms per call. In normal mode, returns the current system time.
+ *
+ * - In deterministic mode: advances by exactly 1ms per call.
+ * - Monotonically increasing (never goes backwards).
+ * - State persisted via `lix_deterministic_sequence_number`.
+ * - Common uses: `createdAt` fields, TTL calculations, time-ordered queries.
+ *
+ * @example Normal mode – current time
+ * ```ts
+ * const lix = await openLix();
+ * const ts = await timestamp({ lix }) // "2024-03-15T10:30:45.123Z"
+ * ```
+ *
+ * @example Deterministic mode – logical clock from epoch
+ * ```ts
+ * const lix = await openLix({ keyValues: [{ key: "lix_deterministic_mode", value: { enabled: true } }] });
+ * await timestamp({ lix }) // "1970-01-01T00:00:00.000Z"
+ * await timestamp({ lix }) // "1970-01-01T00:00:00.001Z"
+ * await timestamp({ lix }) // "1970-01-01T00:00:00.002Z"
+ * ```
+ */
+export declare function getTimestamp(args: {
+    lix: {
+        call: (name: string, args?: unknown) => Promise<unknown>;
+    };
+}): Promise<string>;
+//# sourceMappingURL=timestamp.d.ts.map

package/dist/engine/functions/timestamp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timestamp.d.ts","sourceRoot":"","sources":["../../../src/engine/functions/timestamp.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAO5C;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE;IACtC,MAAM,EAAE,IAAI,CAAC,SAAS,EAAE,aAAa,GAAG,OAAO,GAAG,iBAAiB,CAAC,CAAC;CACrE,GAAG,MAAM,CAmCT;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE;IACxC,GAAG,EAAE;QAAE,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;KAAE,CAAC;CAClE,GAAG,OAAO,CAAC,MAAM,CAAC,CAGlB"}

package/dist/engine/functions/timestamp.js

@@ -0,0 +1,70 @@
+import { nextSequenceNumberSync } from "./sequence.js";
+import { isDeterministicModeSync } from "../deterministic-mode/is-deterministic-mode.js";
+import { sql } from "kysely";
+import { internalQueryBuilder } from "../internal-query-builder.js";
+import { withRuntimeCache } from "../with-runtime-cache.js";
+/**
+ * Sync variant of {@link getTimestamp}. See {@link getTimestamp} for behavior and examples.
+ *
+ * @remarks
+ * - Accepts `{ engine }` (or `{ lix }` for backward‑compat) and runs next to SQLite.
+ * - Intended for engine/router and UDFs; app code should use {@link getTimestamp}.
+ *
+ * @see getTimestamp
+ */
+export function getTimestampSync(args) {
+    const engine = args.engine;
+    // Check if deterministic mode is enabled
+    const deterministic = isDeterministicModeSync({ engine: engine });
+    if (deterministic) {
+        // Check if timestamps are disabled in the config
+        const [config] = withRuntimeCache(engine, internalQueryBuilder
+            .selectFrom("lix_internal_state_vtable")
+            .where("entity_id", "=", "lix_deterministic_mode")
+            .where("schema_key", "=", "lix_key_value")
+            .where("snapshot_content", "is not", null)
+            .select(sql `json_extract(snapshot_content, '$.value.timestamp')`.as("timestamp"))
+            .compile()).rows;
+        // If timestamp is explicitly set to false, use real time
+        if (config?.timestamp == false) {
+            return new Date().toISOString();
+        }
+        // Otherwise use deterministic timestamps
+        // Get the next deterministic counter value
+        const counter = nextSequenceNumberSync({ engine: engine });
+        // Use counter as milliseconds since epoch
+        return new Date(counter).toISOString();
+    }
+    // Return current timestamp in ISO format
+    return new Date().toISOString();
+}
+/**
+ * Get the current timestamp as an ISO 8601 string.
+ *
+ * In deterministic mode, returns logical timestamps starting from Unix epoch (1970-01-01T00:00:00.000Z),
+ * incrementing by 1ms per call. In normal mode, returns the current system time.
+ *
+ * - In deterministic mode: advances by exactly 1ms per call.
+ * - Monotonically increasing (never goes backwards).
+ * - State persisted via `lix_deterministic_sequence_number`.
+ * - Common uses: `createdAt` fields, TTL calculations, time-ordered queries.
+ *
+ * @example Normal mode – current time
+ * ```ts
+ * const lix = await openLix();
+ * const ts = await timestamp({ lix }) // "2024-03-15T10:30:45.123Z"
+ * ```
+ *
+ * @example Deterministic mode – logical clock from epoch
+ * ```ts
+ * const lix = await openLix({ keyValues: [{ key: "lix_deterministic_mode", value: { enabled: true } }] });
+ * await timestamp({ lix }) // "1970-01-01T00:00:00.000Z"
+ * await timestamp({ lix }) // "1970-01-01T00:00:00.001Z"
+ * await timestamp({ lix }) // "1970-01-01T00:00:00.002Z"
+ * ```
+ */
+export async function getTimestamp(args) {
+    const res = await args.lix.call("lix_timestamp");
+    return String(res);
+}
+//# sourceMappingURL=timestamp.js.map

package/dist/engine/functions/timestamp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timestamp.js","sourceRoot":"","sources":["../../../src/engine/functions/timestamp.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,EAAE,uBAAuB,EAAE,MAAM,gDAAgD,CAAC;AACzF,OAAO,EAAE,GAAG,EAAE,MAAM,QAAQ,CAAC;AAC7B,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AACpE,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAE5D;;;;;;;;GAQG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAEhC;IACA,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;IAC3B,yCAAyC;IACzC,MAAM,aAAa,GAAG,uBAAuB,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAClE,IAAI,aAAa,EAAE,CAAC;QACnB,iDAAiD;QACjD,MAAM,CAAC,MAAM,CAAC,GAAG,gBAAgB,CAChC,MAAM,EACN,oBAAoB;aAClB,UAAU,CAAC,2BAA2B,CAAC;aACvC,KAAK,CAAC,WAAW,EAAE,GAAG,EAAE,wBAAwB,CAAC;aACjD,KAAK,CAAC,YAAY,EAAE,GAAG,EAAE,eAAe,CAAC;aACzC,KAAK,CAAC,kBAAkB,EAAE,QAAQ,EAAE,IAAI,CAAC;aACzC,MAAM,CACN,GAAG,CAAA,qDAAqD,CAAC,EAAE,CAC1D,WAAW,CACX,CACD;aACA,OAAO,EAAE,CACX,CAAC,IAAI,CAAC;QAEP,yDAAyD;QACzD,IAAI,MAAM,EAAE,SAAS,IAAI,KAAK,EAAE,CAAC;YAChC,OAAO,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QACjC,CAAC;QAED,yCAAyC;QACzC,2CAA2C;QAC3C,MAAM,OAAO,GAAG,sBAAsB,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;QAC3D,0CAA0C;QAC1C,OAAO,IAAI,IAAI,CAAC,OAAO,CAAC,CAAC,WAAW,EAAE,CAAC;IACxC,CAAC;IAED,yCAAyC;IACzC,OAAO,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;AACjC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,IAElC;IACA,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;IACjD,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;AACpB,CAAC"}

package/dist/engine/functions/timestamp.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=timestamp.test.d.ts.map

package/dist/engine/functions/timestamp.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timestamp.test.d.ts","sourceRoot":"","sources":["../../../src/engine/functions/timestamp.test.ts"],"names":[],"mappings":""}

package/dist/engine/functions/timestamp.test.js

@@ -0,0 +1,147 @@
+import { expect, test } from "vitest";
+import { getTimestamp } from "./timestamp.js";
+import { openLix } from "../../lix/open-lix.js";
+test("timestamp returns deterministic values when deterministic mode is enabled", async () => {
+    const lix = await openLix({
+        keyValues: [
+            {
+                key: "lix_deterministic_mode",
+                value: {
+                    enabled: true,
+                    bootstrap: true,
+                },
+                lixcol_version_id: "global",
+            },
+        ],
+    });
+    const t1 = await getTimestamp({ lix });
+    const t2 = await getTimestamp({ lix });
+    const t3 = await getTimestamp({ lix });
+    // Verify they're sequential milliseconds from epoch
+    const t1ms = new Date(t1).getTime();
+    const t2ms = new Date(t2).getTime();
+    const t3ms = new Date(t3).getTime();
+    // Should be strictly increasing by 1ms each time
+    expect(t2ms).toBe(t1ms + 1);
+    expect(t3ms).toBe(t2ms + 1);
+    // Should be from 1970
+    expect(t1).toMatch(/^1970-01-01T00:00:00\.\d{3}Z$/);
+    expect(t2).toMatch(/^1970-01-01T00:00:00\.\d{3}Z$/);
+    expect(t3).toMatch(/^1970-01-01T00:00:00\.\d{3}Z$/);
+});
+test("timestamp returns real time when deterministic mode is disabled", async () => {
+    const lix = await openLix({
+        keyValues: [
+            {
+                key: "lix_deterministic_mode",
+                value: {
+                    enabled: false,
+                },
+                lixcol_version_id: "global",
+            },
+        ],
+    });
+    const before = Date.now();
+    const t1 = await getTimestamp({ lix });
+    const after = Date.now();
+    const t1Time = new Date(t1).getTime();
+    // Should be within the test execution window
+    expect(t1Time).toBeGreaterThanOrEqual(before);
+    expect(t1Time).toBeLessThanOrEqual(after);
+    // Should not be from 1970
+    expect(t1).not.toMatch(/^1970-/);
+});
+test("timestamp toggles between deterministic and real time", async () => {
+    const lix = await openLix({
+        keyValues: [
+            {
+                key: "lix_deterministic_mode",
+                value: {
+                    enabled: true,
+                },
+                lixcol_version_id: "global",
+            },
+        ],
+    });
+    // Start with deterministic
+    const t1 = await getTimestamp({ lix });
+    expect(t1).toMatch(/^1970-/);
+    // Switch to real time by deleting the key (cleaner approach)
+    await lix.db
+        .deleteFrom("key_value_by_version")
+        .where("key", "=", "lix_deterministic_mode")
+        .where("lixcol_version_id", "=", "global")
+        .execute();
+    const t2 = await getTimestamp({ lix });
+    expect(t2).not.toMatch(/^1970-/);
+    // Switch back to deterministic
+    await lix.db
+        .insertInto("key_value_by_version")
+        .values({
+        key: "lix_deterministic_mode",
+        value: { enabled: true },
+        lixcol_version_id: "global",
+    })
+        .execute();
+    const t3 = await getTimestamp({ lix });
+    expect(t3).toMatch(/^1970-/);
+});
+test("timestamp is persisted across lix instances", async () => {
+    const lix1 = await openLix({
+        keyValues: [
+            {
+                key: "lix_deterministic_mode",
+                value: {
+                    enabled: true,
+                },
+                lixcol_version_id: "global",
+            },
+        ],
+    });
+    // Generate some timestamps to advance the counter
+    const t1 = await getTimestamp({ lix: lix1 });
+    const t2 = await getTimestamp({ lix: lix1 });
+    const t3 = await getTimestamp({ lix: lix1 });
+    // Create a new instance from the blob
+    const blob = await lix1.toBlob();
+    const lix2 = await openLix({ blob });
+    // Next timestamp should continue from where we left off
+    const t4 = await getTimestamp({ lix: lix2 });
+    // Verify they continue sequentially
+    const t1ms = new Date(t1).getTime();
+    const t2ms = new Date(t2).getTime();
+    const t3ms = new Date(t3).getTime();
+    const t4ms = new Date(t4).getTime();
+    expect(t2ms).toBe(t1ms + 1);
+    expect(t3ms).toBe(t2ms + 1);
+    expect(t4ms).toBe(t3ms + 1);
+});
+test("timestamp advances correctly with many operations", async () => {
+    const lix = await openLix({
+        keyValues: [
+            {
+                key: "lix_deterministic_mode",
+                value: {
+                    enabled: true,
+                },
+                lixcol_version_id: "global",
+            },
+        ],
+    });
+    // Generate 100 timestamps
+    const timestamps = [];
+    for (let i = 0; i < 100; i++) {
+        timestamps.push(await getTimestamp({ lix }));
+    }
+    // All should be strictly increasing by 1ms
+    for (let i = 1; i < timestamps.length; i++) {
+        const prev = new Date(timestamps[i - 1]).getTime();
+        const curr = new Date(timestamps[i]).getTime();
+        expect(curr).toBe(prev + 1);
+    }
+    // Verify the sequence span
+    const firstMs = new Date(timestamps[0]).getTime();
+    const lastMs = new Date(timestamps[99]).getTime();
+    expect(lastMs - firstMs).toBe(99); // 99ms difference between first and last
+});
+//# sourceMappingURL=timestamp.test.js.map

package/dist/engine/functions/timestamp.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timestamp.test.js","sourceRoot":"","sources":["../../../src/engine/functions/timestamp.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAEhD,IAAI,CAAC,2EAA2E,EAAE,KAAK,IAAI,EAAE;IAC5F,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC;QACzB,SAAS,EAAE;YACV;gBACC,GAAG,EAAE,wBAAwB;gBAC7B,KAAK,EAAE;oBACN,OAAO,EAAE,IAAI;oBACb,SAAS,EAAE,IAAI;iBACf;gBACD,iBAAiB,EAAE,QAAQ;aAC3B;SACD;KACD,CAAC,CAAC;IAEH,MAAM,EAAE,GAAG,MAAM,YAAY,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC;IACvC,MAAM,EAAE,GAAG,MAAM,YAAY,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC;IACvC,MAAM,EAAE,GAAG,MAAM,YAAY,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC;IAEvC,oDAAoD;IACpD,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;IACpC,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;IACpC,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;IAEpC,iDAAiD;IACjD,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC;IAC5B,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC;IAE5B,sBAAsB;IACtB,MAAM,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,+BAA+B,CAAC,CAAC;IACpD,MAAM,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,+BAA+B,CAAC,CAAC;IACpD,MAAM,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,+BAA+B,CAAC,CAAC;AACrD,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,iEAAiE,EAAE,KAAK,IAAI,EAAE;IAClF,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC;QACzB,SAAS,EAAE;YACV;gBACC,GAAG,EAAE,wBAAwB;gBAC7B,KAAK,EAAE;oBACN,OAAO,EAAE,KAAK;iBACd;gBACD,iBAAiB,EAAE,QAAQ;aAC3B;SACD;KACD,CAAC,CAAC;IAEH,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC1B,MAAM,EAAE,GAAG,MAAM,YAAY,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC;IACvC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAEzB,MAAM,MAAM,GAAG,IAAI,IAAI,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;IAEtC,6CAA6C;IAC7C,MAAM,CAAC,MAAM,CAAC,CAAC,sBAAsB,CAAC,MAAM,CAAC,CAAC;IAC9C,MAAM,CAAC,MAAM,CAAC,CAAC,mBAAmB,CAAC,KAAK,CAAC,CAAC;IAE1C,0BAA0B;IAC1B,MAAM,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;AAClC,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,uDAAuD,EAAE,KAAK,IAAI,EAAE;IACxE,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC;QACzB,SAAS,EAAE;YACV;gBACC,GAAG,EAAE,wBAAwB;gBAC7B,KAAK,EAAE;oBACN,OAAO,EAAE,IAAI;iBACb;gBACD,iBAAiB,EAAE,QAAQ;aAC3B;SACD;KACD,CAAC,CAAC;IAEH,2BAA2B;IAC3B,MAAM,EAAE,GAAG,MAAM,YAAY,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC;IACvC,MAAM,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAE7B,6DAA6D;IAC7D,MAAM,GAAG,CAAC,EAAE;SACV,UAAU,CAAC,sBAAsB,CAAC;SAClC,KAAK,CAAC,KAAK,EAAE,GAAG,EAAE,wBAAwB,CAAC;SAC3C,KAAK,CAAC,mBAAmB,EAAE,GAAG,EAAE,QAAQ,CAAC;SACzC,OAAO,EAAE,CAAC;IAEZ,MAAM,EAAE,GAAG,MAAM,YAAY,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC;IACvC,MAAM,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAEjC,+BAA+B;IAC/B,MAAM,GAAG,CAAC,EAAE;SACV,UAAU,CAAC,sBAAsB,CAAC;SAClC,MAAM,CAAC;QACP,GAAG,EAAE,wBAAwB;QAC7B,KAAK,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE;QACxB,iBAAiB,EAAE,QAAQ;KAC3B,CAAC;SACD,OAAO,EAAE,CAAC;IAEZ,MAAM,EAAE,GAAG,MAAM,YAAY,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC;IACvC,MAAM,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;AAC9B,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,6CAA6C,EAAE,KAAK,IAAI,EAAE;IAC9D,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC;QAC1B,SAAS,EAAE;YACV;gBACC,GAAG,EAAE,wBAAwB;gBAC7B,KAAK,EAAE;oBACN,OAAO,EAAE,IAAI;iBACb;gBACD,iBAAiB,EAAE,QAAQ;aAC3B;SACD;KACD,CAAC,CAAC;IAEH,kDAAkD;IAClD,MAAM,EAAE,GAAG,MAAM,YAAY,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7C,MAAM,EAAE,GAAG,MAAM,YAAY,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7C,MAAM,EAAE,GAAG,MAAM,YAAY,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC;IAE7C,sCAAsC;IACtC,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,MAAM,EAAE,CAAC;IACjC,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;IAErC,wDAAwD;IACxD,MAAM,EAAE,GAAG,MAAM,YAAY,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC;IAE7C,oCAAoC;IACpC,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;IACpC,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;IACpC,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;IACpC,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;IAEpC,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC;IAC5B,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC;IAC5B,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC;AAC7B,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,mDAAmD,EAAE,KAAK,IAAI,EAAE;IACpE,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC;QACzB,SAAS,EAAE;YACV;gBACC,GAAG,EAAE,wBAAwB;gBAC7B,KAAK,EAAE;oBACN,OAAO,EAAE,IAAI;iBACb;gBACD,iBAAiB,EAAE,QAAQ;aAC3B;SACD;KACD,CAAC,CAAC;IAEH,0BAA0B;IAC1B,MAAM,UAAU,GAAa,EAAE,CAAC;IAChC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC;QAC9B,UAAU,CAAC,IAAI,CAAC,MAAM,YAAY,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC;IAC9C,CAAC;IAED,2CAA2C;IAC3C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,UAAU,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAC5C,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,CAAE,CAAC,CAAC,OAAO,EAAE,CAAC;QACpD,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,UAAU,CAAC,CAAC,CAAE,CAAC,CAAC,OAAO,EAAE,CAAC;QAChD,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC;IAC7B,CAAC;IAED,2BAA2B;IAC3B,MAAM,OAAO,GAAG,IAAI,IAAI,CAAC,UAAU,CAAC,CAAC,CAAE,CAAC,CAAC,OAAO,EAAE,CAAC;IACnD,MAAM,MAAM,GAAG,IAAI,IAAI,CAAC,UAAU,CAAC,EAAE,CAAE,CAAC,CAAC,OAAO,EAAE,CAAC;IACnD,MAAM,CAAC,MAAM,GAAG,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,yCAAyC;AAC7E,CAAC,CAAC,CAAC"}

package/dist/engine/functions/uuid-v7.d.ts

@@ -0,0 +1,50 @@
+import type { Call } from "./function-registry.js";
+import type { LixEngine } from "../boot.js";
+/**
+ * Sync variant of {@link uuidV7}. See {@link uuidV7} for behavior and examples.
+ *
+ * @remarks
+ * - Accepts `{ engine }` (or `{ lix }`) and runs next to SQLite.
+ * - Intended for engine/router and UDFs; app code should use {@link uuidV7}.
+ *
+ * @see uuidV7
+ */
+export declare function uuidV7Sync(args: {
+    engine: Pick<LixEngine, "executeSync" | "hooks" | "runtimeCacheRef">;
+}): string;
+/**
+ * Returns a UUID v7.
+ *
+ * In normal mode, returns a standard time-based UUID v7. In deterministic mode,
+ * returns UUIDs with a fixed timestamp prefix and sequential counter suffix.
+ *
+ * UUID v7 provides better database performance than {@link nanoId} due to time-based sorting,
+ * but produces longer IDs that are less suitable for URLs.
+ *
+ * - Normal mode: standard UUID v7 with current timestamp.
+ * - Deterministic mode: fixed prefix "01920000-0000-7000-8800-" + 12-digit hex counter.
+ * - Counter state shared with {@link nextSequenceNumberSync}.
+ * - Choose UUID v7 for time-sortable database keys; {@link nanoId} for URL-friendly short IDs.
+ *
+ * @example Normal mode – random UUID v7
+ * ```ts
+ * const lix = await openLix();
+ * const id = await uuidV7({ lix }) // "01920000-5432-7654-8abc-def012345678"
+ * ```
+ *
+ * @example Deterministic mode – sequential UUIDs
+ * ```ts
+ * const lix = await openLix({
+ *   keyValues: [{ key: "lix_deterministic_mode", value: { enabled: true }, lixcol_version_id: "global" }]
+ * });
+ * await uuidV7({ lix }) // "01920000-0000-7000-8000-000000000000"
+ * await uuidV7({ lix }) // "01920000-0000-7000-8000-000000000001"
+ * await uuidV7({ lix }) // "01920000-0000-7000-8000-000000000002"
+ * ```
+ */
+export declare function uuidV7(args: {
+    lix: {
+        call: Call;
+    };
+}): Promise<string>;
+//# sourceMappingURL=uuid-v7.d.ts.map