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

package/dist/deterministic/sequence.js

@@ -0,0 +1,107 @@
+import { executeSync } from "../database/execute-sync.js";
+import { LixKeyValueSchema } from "../key-value/schema.js";
+import { isDeterministicMode } from "./is-deterministic-mode.js";
+import { timestamp } from "./timestamp.js";
+import { updateUntrackedState } from "../state/untracked/update-untracked-state.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 timestamp}, {@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 nextDeterministicSequenceNumber(args) {
+    // Check if deterministic mode is enabled
+    if (!isDeterministicMode({ lix: args.lix })) {
+        throw new Error("nextDeterministicSequenceNumber() is available only when lix_deterministic_mode = true");
+    }
+    let state = counterCache.get(args.lix.sqlite);
+    /* First use on this connection → pull initial value from DB */
+    if (!state) {
+        const [row] = executeSync({
+            lix: { sqlite: args.lix.sqlite },
+            // querying from key_value_all is fine here because its a view
+            // that hits the internal_state_all_untracked table
+            query: args.lix.db
+                .selectFrom("key_value_all")
+                .where("key", "=", "lix_deterministic_sequence_number")
+                .where("lixcol_version_id", "=", "global")
+                .select("value"),
+        });
+        // 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(args.lix.sqlite, state);
+    }
+    /* Hand out current, then bump for the next call */
+    const count = state.next++;
+    state.highestSeen = count;
+    state.dirty = true;
+    return count;
+}
+/**
+ * @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 commitDeterministicSequenceNumber(args) {
+    const state = counterCache.get(args.lix.sqlite);
+    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 ?? timestamp({ lix: args.lix });
+    updateUntrackedState({
+        lix: args.lix,
+        change: {
+            entity_id: "lix_deterministic_sequence_number",
+            schema_key: LixKeyValueSchema["x-lix-key"],
+            file_id: "lix",
+            plugin_key: "lix_own_entity",
+            snapshot_content: newValue,
+            schema_version: LixKeyValueSchema["x-lix-version"],
+            created_at: now,
+        },
+        version_id: "global",
+    });
+}
+//# sourceMappingURL=sequence.js.map

package/dist/deterministic/sequence.js.map

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

package/dist/deterministic/sequence.test.d.ts

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

package/dist/deterministic/sequence.test.d.ts.map

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

package/dist/deterministic/sequence.test.js

@@ -0,0 +1,71 @@
+import { expect, test } from "vitest";
+import { openLix } from "../lix/open-lix.js";
+import { nextDeterministicSequenceNumber } from "./sequence.js";
+test("nextDeterministicSequenceNumber throws error when deterministic mode is false", async () => {
+    const lix = await openLix({
+        keyValues: [{ key: "lix_deterministic_mode", value: { enabled: false } }],
+    });
+    expect(() => nextDeterministicSequenceNumber({ lix })).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({});
+    expect(() => nextDeterministicSequenceNumber({ lix })).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 = nextDeterministicSequenceNumber({ lix });
+    const n2 = nextDeterministicSequenceNumber({ lix });
+    const n3 = nextDeterministicSequenceNumber({ 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 = nextDeterministicSequenceNumber({ lix: lix1 });
+    const n2 = nextDeterministicSequenceNumber({ lix: lix1 });
+    const n3 = nextDeterministicSequenceNumber({ 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 = nextDeterministicSequenceNumber({ lix: lix2 });
+    const n5 = nextDeterministicSequenceNumber({ 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 = nextDeterministicSequenceNumber({ lix: lix1 });
+    const lix2_n1 = nextDeterministicSequenceNumber({ lix: lix2 });
+    expect(lix1_n1).toBe(lix2_n1);
+    // Both increment independently but maintain the same sequence
+    const lix1_n2 = nextDeterministicSequenceNumber({ lix: lix1 });
+    const lix2_n2 = nextDeterministicSequenceNumber({ 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/deterministic/sequence.test.js.map

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

package/dist/deterministic/timestamp.d.ts

@@ -0,0 +1,47 @@
+import type { Lix } from "../lix/open-lix.js";
+/**
+ * Returns 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 across reopens via `lix_deterministic_sequence_number`
+ * - Common uses: `createdAt` fields, TTL calculations, time-ordered queries
+ *
+ * @example Normal mode - returns current time
+ * ```ts
+ * const lix = await openLix();
+ * 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 } }]
+ * });
+ * timestamp({ lix }); // "1970-01-01T00:00:00.000Z"
+ * timestamp({ lix }); // "1970-01-01T00:00:00.001Z" (+1ms)
+ * timestamp({ lix }); // "1970-01-01T00:00:00.002Z" (+1ms)
+ * ```
+ *
+ * @example Database operations - createdAt, TTL, time-ordered queries
+ * ```ts
+ * await lix.db
+ *   .insertInto("log")
+ *   .values({
+ *     id: "log1",
+ *     created_at: timestamp({ lix }),
+ *     message: "User logged in"
+ *   })
+ *   .execute();
+ * ```
+ *
+ * @param args.lix - The Lix instance with sqlite and db connections
+ * @returns ISO 8601 timestamp string
+ */
+export declare function timestamp(args: {
+    lix: Pick<Lix, "sqlite" | "db">;
+}): string;
+//# sourceMappingURL=timestamp.d.ts.map

package/dist/deterministic/timestamp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timestamp.d.ts","sourceRoot":"","sources":["../../src/deterministic/timestamp.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAC;AAO9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE;IAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,QAAQ,GAAG,IAAI,CAAC,CAAA;CAAE,GAAG,MAAM,CAiC3E"}

package/dist/deterministic/timestamp.js

@@ -0,0 +1,74 @@
+import { nextDeterministicSequenceNumber } from "./sequence.js";
+import { isDeterministicMode } from "./is-deterministic-mode.js";
+import { executeSync } from "../database/execute-sync.js";
+import { sql } from "kysely";
+/**
+ * Returns 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 across reopens via `lix_deterministic_sequence_number`
+ * - Common uses: `createdAt` fields, TTL calculations, time-ordered queries
+ *
+ * @example Normal mode - returns current time
+ * ```ts
+ * const lix = await openLix();
+ * 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 } }]
+ * });
+ * timestamp({ lix }); // "1970-01-01T00:00:00.000Z"
+ * timestamp({ lix }); // "1970-01-01T00:00:00.001Z" (+1ms)
+ * timestamp({ lix }); // "1970-01-01T00:00:00.002Z" (+1ms)
+ * ```
+ *
+ * @example Database operations - createdAt, TTL, time-ordered queries
+ * ```ts
+ * await lix.db
+ *   .insertInto("log")
+ *   .values({
+ *     id: "log1",
+ *     created_at: timestamp({ lix }),
+ *     message: "User logged in"
+ *   })
+ *   .execute();
+ * ```
+ *
+ * @param args.lix - The Lix instance with sqlite and db connections
+ * @returns ISO 8601 timestamp string
+ */
+export function timestamp(args) {
+    // Check if deterministic mode is enabled
+    if (isDeterministicMode({ lix: args.lix })) {
+        // Check if timestamps are disabled in the config
+        const [config] = executeSync({
+            lix: args.lix,
+            query: args.lix.db
+                .selectFrom("internal_resolved_state_all")
+                .where("entity_id", "=", "lix_deterministic_mode")
+                .where("schema_key", "=", "lix_key_value")
+                .select(sql `json_extract(snapshot_content, '$.value.timestamp')`.as("timestamp")),
+        });
+        // 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 = nextDeterministicSequenceNumber({
+            lix: args.lix,
+        });
+        // Use counter as milliseconds since epoch
+        return new Date(counter).toISOString();
+    }
+    // Return current timestamp in ISO format
+    return new Date().toISOString();
+}
+//# sourceMappingURL=timestamp.js.map

package/dist/deterministic/timestamp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timestamp.js","sourceRoot":"","sources":["../../src/deterministic/timestamp.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,+BAA+B,EAAE,MAAM,eAAe,CAAC;AAChE,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC1D,OAAO,EAAE,GAAG,EAAe,MAAM,QAAQ,CAAC;AAG1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,MAAM,UAAU,SAAS,CAAC,IAAyC;IAClE,yCAAyC;IACzC,IAAI,mBAAmB,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC;QAC5C,iDAAiD;QACjD,MAAM,CAAC,MAAM,CAAC,GAAG,WAAW,CAAC;YAC5B,GAAG,EAAE,IAAI,CAAC,GAAG;YACb,KAAK,EAAG,IAAI,CAAC,GAAG,CAAC,EAAmD;iBAClE,UAAU,CAAC,6BAA6B,CAAC;iBACzC,KAAK,CAAC,WAAW,EAAE,GAAG,EAAE,wBAAwB,CAAC;iBACjD,KAAK,CAAC,YAAY,EAAE,GAAG,EAAE,eAAe,CAAC;iBACzC,MAAM,CACN,GAAG,CAAA,qDAAqD,CAAC,EAAE,CAC1D,WAAW,CACX,CACD;SACF,CAAC,CAAC;QAEH,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,+BAA+B,CAAC;YAC/C,GAAG,EAAE,IAAI,CAAC,GAAG;SACb,CAAC,CAAC;QACH,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"}

package/dist/deterministic/timestamp.test.d.ts

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

package/dist/deterministic/timestamp.test.d.ts.map

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

package/dist/deterministic/timestamp.test.js

@@ -0,0 +1,145 @@
+import { expect, test } from "vitest";
+import { timestamp } 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 = timestamp({ lix });
+    const t2 = timestamp({ lix });
+    const t3 = timestamp({ 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 = timestamp({ 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 = timestamp({ lix });
+    expect(t1).toMatch(/^1970-/);
+    // Switch to real time by deleting the key (cleaner approach)
+    await lix.db
+        .deleteFrom("key_value")
+        .where("key", "=", "lix_deterministic_mode")
+        .execute();
+    const t2 = timestamp({ lix });
+    expect(t2).not.toMatch(/^1970-/);
+    // Switch back to deterministic
+    await lix.db
+        .insertInto("key_value")
+        .values({
+        key: "lix_deterministic_mode",
+        value: { enabled: true },
+    })
+        .execute();
+    const t3 = timestamp({ 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 = timestamp({ lix: lix1 });
+    const t2 = timestamp({ lix: lix1 });
+    const t3 = timestamp({ 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 = timestamp({ 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(timestamp({ 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/deterministic/timestamp.test.js.map

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

package/dist/deterministic/uuid-v7.d.ts

@@ -0,0 +1,49 @@
+import type { Lix } from "../lix/open-lix.js";
+/**
+ * Returns a UUID v7 that is deterministic in deterministic mode.
+ *
+ * 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 nextDeterministicSequenceNumber}
+ * - Choose UUID v7 for time-sortable database keys, {@link nanoId} for URL-friendly short IDs
+ *
+ * @example Normal mode - returns random UUID v7
+ * ```ts
+ * const lix = await openLix();
+ * uuidV7({ lix }); // "01920000-5432-7654-8abc-def012345678"
+ * ```
+ *
+ * @example Deterministic mode - returns sequential UUIDs
+ * ```ts
+ * const lix = await openLix({
+ *   keyValues: [{ key: "lix_deterministic_mode", value: { enabled: true }, lixcol_version_id: "global" }]
+ * });
+ * uuidV7({ lix }); // "01920000-0000-7000-8000-000000000000"
+ * uuidV7({ lix }); // "01920000-0000-7000-8000-000000000001"
+ * uuidV7({ lix }); // "01920000-0000-7000-8000-000000000002"
+ * ```
+ *
+ * @example Database operations
+ * ```ts
+ * await lix.db
+ *   .insertInto("change")
+ *   .values({
+ *     id: uuidV7({ lix }),
+ *     content: "Updated user profile"
+ *   })
+ *   .execute();
+ * ```
+ *
+ * @param args.lix - The Lix instance with sqlite and db connections
+ * @returns UUID v7 string
+ */
+export declare function uuidV7(args: {
+    lix: Pick<Lix, "sqlite" | "db">;
+}): string;
+//# sourceMappingURL=uuid-v7.d.ts.map

package/dist/deterministic/uuid-v7.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uuid-v7.d.ts","sourceRoot":"","sources":["../../src/deterministic/uuid-v7.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAC;AAK9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE;IAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,QAAQ,GAAG,IAAI,CAAC,CAAA;CAAE,GAAG,MAAM,CA6BxE"}

package/dist/deterministic/uuid-v7.js

@@ -0,0 +1,75 @@
+import { v7 } from "uuid";
+import { nextDeterministicSequenceNumber } from "./sequence.js";
+import { isDeterministicMode } from "./is-deterministic-mode.js";
+import { executeSync } from "../database/execute-sync.js";
+import { sql } from "kysely";
+/**
+ * Returns a UUID v7 that is deterministic in deterministic mode.
+ *
+ * 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 nextDeterministicSequenceNumber}
+ * - Choose UUID v7 for time-sortable database keys, {@link nanoId} for URL-friendly short IDs
+ *
+ * @example Normal mode - returns random UUID v7
+ * ```ts
+ * const lix = await openLix();
+ * uuidV7({ lix }); // "01920000-5432-7654-8abc-def012345678"
+ * ```
+ *
+ * @example Deterministic mode - returns sequential UUIDs
+ * ```ts
+ * const lix = await openLix({
+ *   keyValues: [{ key: "lix_deterministic_mode", value: { enabled: true }, lixcol_version_id: "global" }]
+ * });
+ * uuidV7({ lix }); // "01920000-0000-7000-8000-000000000000"
+ * uuidV7({ lix }); // "01920000-0000-7000-8000-000000000001"
+ * uuidV7({ lix }); // "01920000-0000-7000-8000-000000000002"
+ * ```
+ *
+ * @example Database operations
+ * ```ts
+ * await lix.db
+ *   .insertInto("change")
+ *   .values({
+ *     id: uuidV7({ lix }),
+ *     content: "Updated user profile"
+ *   })
+ *   .execute();
+ * ```
+ *
+ * @param args.lix - The Lix instance with sqlite and db connections
+ * @returns UUID v7 string
+ */
+export function uuidV7(args) {
+    // Check if deterministic mode is enabled
+    if (isDeterministicMode({ lix: args.lix })) {
+        // Check if uuid_v7 is disabled in the config
+        const [config] = executeSync({
+            lix: args.lix,
+            query: args.lix.db
+                .selectFrom("internal_resolved_state_all")
+                .where("entity_id", "=", "lix_deterministic_mode")
+                .where("schema_key", "=", "lix_key_value")
+                .select(sql `json_extract(snapshot_content, '$.value.uuid_v7')`.as("uuid_v7")),
+        });
+        // If uuid_v7 is explicitly set to false, use non-deterministic
+        if (config?.uuid_v7 == false) {
+            return v7();
+        }
+        // Otherwise use deterministic UUID
+        // Get the next deterministic counter value
+        const counter = nextDeterministicSequenceNumber({ lix: args.lix });
+        const hex = counter.toString(16).padStart(8, "0");
+        return `01920000-0000-7000-8000-0000${hex}`;
+    }
+    // Return regular UUID v7
+    return v7();
+}
+//# sourceMappingURL=uuid-v7.js.map

package/dist/deterministic/uuid-v7.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"uuid-v7.js","sourceRoot":"","sources":["../../src/deterministic/uuid-v7.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,MAAM,MAAM,CAAC;AAC1B,OAAO,EAAE,+BAA+B,EAAE,MAAM,eAAe,CAAC;AAChE,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAEjE,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC1D,OAAO,EAAE,GAAG,EAAe,MAAM,QAAQ,CAAC;AAG1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,MAAM,UAAU,MAAM,CAAC,IAAyC;IAC/D,yCAAyC;IACzC,IAAI,mBAAmB,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC;QAC5C,6CAA6C;QAC7C,MAAM,CAAC,MAAM,CAAC,GAAG,WAAW,CAAC;YAC5B,GAAG,EAAE,IAAI,CAAC,GAAG;YACb,KAAK,EAAG,IAAI,CAAC,GAAG,CAAC,EAAmD;iBAClE,UAAU,CAAC,6BAA6B,CAAC;iBACzC,KAAK,CAAC,WAAW,EAAE,GAAG,EAAE,wBAAwB,CAAC;iBACjD,KAAK,CAAC,YAAY,EAAE,GAAG,EAAE,eAAe,CAAC;iBACzC,MAAM,CACN,GAAG,CAAA,mDAAmD,CAAC,EAAE,CAAC,SAAS,CAAC,CACpE;SACF,CAAC,CAAC;QAEH,+DAA+D;QAC/D,IAAI,MAAM,EAAE,OAAO,IAAI,KAAK,EAAE,CAAC;YAC9B,OAAO,EAAE,EAAE,CAAC;QACb,CAAC;QAED,mCAAmC;QACnC,2CAA2C;QAC3C,MAAM,OAAO,GAAG,+BAA+B,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;QACnE,MAAM,GAAG,GAAG,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;QAClD,OAAO,+BAA+B,GAAG,EAAE,CAAC;IAC7C,CAAC;IAED,yBAAyB;IACzB,OAAO,EAAE,EAAE,CAAC;AACb,CAAC"}

package/dist/deterministic/uuid-v7.test.d.ts

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

package/dist/deterministic/uuid-v7.test.d.ts.map

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