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

package/src/deterministic/timestamp.ts

@@ -0,0 +1,83 @@
+import type { Lix } from "../lix/open-lix.js";
+import { nextDeterministicSequenceNumber } from "./sequence.js";
+import { isDeterministicMode } from "./is-deterministic-mode.js";
+import { executeSync } from "../database/execute-sync.js";
+import { sql, type Kysely } from "kysely";
+import type { LixInternalDatabaseSchema } from "../database/schema.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 function timestamp(args: { lix: Pick<Lix, "sqlite" | "db"> }): string {
+	// 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 as unknown as Kysely<LixInternalDatabaseSchema>)
+				.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();
+}

package/src/deterministic/uuid-v7.test.ts

@@ -0,0 +1,144 @@
+import { expect, test } from "vitest";
+import { uuidV7 } from "./uuid-v7.js";
+import { openLix } from "../lix/open-lix.js";
+
+test("uuidV7 returns deterministic values when deterministic mode is enabled", async () => {
+	const lix = await openLix({
+		keyValues: [{ key: "lix_deterministic_mode", value: { enabled: true } }],
+	});
+
+	const id1 = uuidV7({ lix });
+	const id2 = uuidV7({ lix });
+	const id3 = uuidV7({ lix });
+
+	// Should be valid UUID v7 format
+	const uuidRegex =
+		/^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+	expect(id1).toMatch(uuidRegex);
+	expect(id2).toMatch(uuidRegex);
+	expect(id3).toMatch(uuidRegex);
+
+	// Should have deterministic pattern
+	expect(id1).toMatch(/^01920000-0000-7000-8000-/);
+	expect(id2).toMatch(/^01920000-0000-7000-8000-/);
+	expect(id3).toMatch(/^01920000-0000-7000-8000-/);
+
+	// Should be sequential
+	const counter1 = parseInt(id1.slice(-8), 16);
+	const counter2 = parseInt(id2.slice(-8), 16);
+	const counter3 = parseInt(id3.slice(-8), 16);
+
+	expect(counter2).toBe(counter1 + 1);
+	expect(counter3).toBe(counter2 + 1);
+});
+
+test("uuidV7 returns random values when deterministic mode is disabled", async () => {
+	const lix = await openLix({
+		keyValues: [{ key: "lix_deterministic_mode", value: { enabled: false } }],
+	});
+
+	const id1 = uuidV7({ lix });
+	const id2 = uuidV7({ lix });
+	const id3 = uuidV7({ lix });
+
+	// Should be valid UUID v7 format
+	const uuidRegex =
+		/^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+	expect(id1).toMatch(uuidRegex);
+	expect(id2).toMatch(uuidRegex);
+	expect(id3).toMatch(uuidRegex);
+
+	// Should NOT have deterministic pattern
+	expect(id1).not.toMatch(/^01920000-0000-7000-8000-/);
+	expect(id2).not.toMatch(/^01920000-0000-7000-8000-/);
+	expect(id3).not.toMatch(/^01920000-0000-7000-8000-/);
+
+	// Should all be different
+	expect(id1).not.toBe(id2);
+	expect(id2).not.toBe(id3);
+	expect(id1).not.toBe(id3);
+});
+
+test("uuidV7 toggles between deterministic and random", async () => {
+	const lix = await openLix({
+		keyValues: [{ key: "lix_deterministic_mode", value: { enabled: true } }],
+	});
+
+	// Start with deterministic
+	const deterministicId = uuidV7({ lix });
+	expect(deterministicId).toMatch(/^01920000-0000-7000-8000-/);
+
+	// Switch to random
+	await lix.db
+		.updateTable("key_value")
+		.set({ value: { enabled: false } })
+		.where("key", "=", "lix_deterministic_mode")
+		.execute();
+
+	const randomId = uuidV7({ lix });
+	expect(randomId).not.toMatch(/^01920000-0000-7000-8000-/);
+
+	// Switch back to deterministic
+	await lix.db
+		.updateTable("key_value")
+		.set({ value: { enabled: true } })
+		.where("key", "=", "lix_deterministic_mode")
+		.execute();
+
+	const deterministicId2 = uuidV7({ lix });
+	expect(deterministicId2).toMatch(/^01920000-0000-7000-8000-/);
+});
+
+test("uuidV7 is persisted across lix instances", async () => {
+	const lix1 = await openLix({
+		keyValues: [{ key: "lix_deterministic_mode", value: { enabled: true } }],
+	});
+
+	// Generate some IDs to advance the counter
+	const id1 = uuidV7({ lix: lix1 });
+	const id2 = uuidV7({ lix: lix1 });
+	const id3 = uuidV7({ lix: lix1 });
+
+	// Create a new instance from the blob
+	const blob = await lix1.toBlob();
+	const lix2 = await openLix({ blob });
+
+	// Next ID should continue from where we left off
+	const id4 = uuidV7({ lix: lix2 });
+
+	// Extract counters
+	const counters = [id1, id2, id3, id4].map((id) => parseInt(id.slice(-8), 16));
+
+	// Verify they continue sequentially
+	expect(counters[1]).toBe(counters[0]! + 1);
+	expect(counters[2]).toBe(counters[1]! + 1);
+	expect(counters[3]).toBe(counters[2]! + 1);
+});
+
+test("uuidV7 advances correctly with many operations", async () => {
+	const lix = await openLix({
+		keyValues: [{ key: "lix_deterministic_mode", value: { enabled: true } }],
+	});
+
+	// Generate 100 UUIDs
+	const uuids: string[] = [];
+	for (let i = 0; i < 100; i++) {
+		uuids.push(uuidV7({ lix }));
+	}
+
+	// All should match deterministic pattern
+	for (const uuid of uuids) {
+		expect(uuid).toMatch(/^01920000-0000-7000-8000-/);
+	}
+
+	// Extract counters
+	const counters = uuids.map((id) => parseInt(id.slice(-8), 16));
+
+	// All should be strictly increasing
+	for (let i = 1; i < counters.length; i++) {
+		expect(counters[i]).toBe(counters[i - 1]! + 1);
+	}
+
+	// Verify the sequence span
+	expect(counters[99]! - counters[0]!).toBe(99);
+});

package/src/deterministic/uuid-v7.ts

@@ -0,0 +1,82 @@
+import { v7 } from "uuid";
+import { nextDeterministicSequenceNumber } from "./sequence.js";
+import { isDeterministicMode } from "./is-deterministic-mode.js";
+import type { Lix } from "../lix/open-lix.js";
+import { executeSync } from "../database/execute-sync.js";
+import { sql, type Kysely } from "kysely";
+import type { LixInternalDatabaseSchema } from "../database/schema.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 function uuidV7(args: { lix: Pick<Lix, "sqlite" | "db"> }): string {
+	// 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 as unknown as Kysely<LixInternalDatabaseSchema>)
+				.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();
+}