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

package/src/deterministic/random.ts

@@ -0,0 +1,261 @@
+import type { SqliteWasmDatabase } from "sqlite-wasm-kysely";
+import { sql, type Kysely } from "kysely";
+import { executeSync } from "../database/execute-sync.js";
+import { LixKeyValueSchema, type LixKeyValue } from "../key-value/schema.js";
+import type { Lix } from "../lix/open-lix.js";
+import type { LixInternalDatabaseSchema } from "../database/schema.js";
+import { isDeterministicMode } from "./is-deterministic-mode.js";
+import { timestamp } from "./timestamp.js";
+import { updateUntrackedState } from "../state/untracked/update-untracked-state.js";
+
+/** State kept per SQLite connection - 16 bytes for xorshift128+ */
+type RngState = {
+	hi: bigint;
+	lo: bigint;
+	dirty: boolean;
+};
+
+const rngCache = new WeakMap<SqliteWasmDatabase, RngState>();
+
+/**
+ * Non-deterministic random number generator using crypto.getRandomValues().
+ * Returns a 53-bit precision float in [0, 1).
+ */
+function randomUnstable(): number {
+	const buf = new Uint32Array(2);
+	if (typeof crypto !== "undefined" && crypto.getRandomValues) {
+		crypto.getRandomValues(buf);
+	} else {
+		// Fallback for environments without crypto API
+		// This is not cryptographically secure but better than failing
+		buf[0] = Math.floor(Math.random() * 0xffffffff);
+		buf[1] = Math.floor(Math.random() * 0xffffffff);
+	}
+	// 53-bit float in [0,1) - standard technique for full precision
+	const high = buf[0]! >>> 5; // 27 bits
+	const low = buf[1]! >>> 6; // 26 bits
+	// Combine to get 53 bits total, then divide by 2^53
+	return (high * 0x4000000 + low) / Math.pow(2, 53);
+}
+
+/**
+ * Returns a random float between 0 (inclusive) and 1 (exclusive).
+ *
+ * In deterministic mode, generates reproducible values using xorshift128+ PRNG
+ * (the same algorithm used by V8/Chrome for Math.random()).
+ * In normal mode, uses crypto.getRandomValues() for cryptographically secure randomness.
+ *
+ * - Normal mode: Uses crypto.getRandomValues() for cryptographic quality
+ * - Deterministic mode: Uses xorshift128+ PRNG (same as V8/Chrome's Math.random())
+ * - Default seed: Uses `lix_id` value unless `lix_deterministic_rng_seed` is set
+ * - State persisted via `lix_deterministic_rng_state` key value
+ * - Both modes return 53-bit precision floats for consistency
+ * - For ID generation, consider {@link uuidV7} or {@link nanoId} instead
+ *
+ * @example Normal mode - cryptographically secure randomness
+ * ```ts
+ * const lix = await openLix();
+ * const r1 = random({ lix }); // 0.823... (unpredictable)
+ * const r2 = random({ lix }); // 0.156... (unpredictable)
+ * ```
+ *
+ * @example Deterministic mode - reproducible randomness
+ * ```ts
+ * const lix = await openLix({
+ *   keyValues: [{ key: "lix_deterministic_mode", value: { enabled: true } }]
+ * });
+ * const r1 = random({ lix }); // 0.318... (always same sequence)
+ * const r2 = random({ lix }); // 0.937... (for same seed)
+ * const r3 = random({ lix }); // 0.543...
+ * ```
+ *
+ * @example Sampling and shuffling
+ * ```ts
+ * // Random selection
+ * const items = ["a", "b", "c", "d"];
+ * const idx = Math.floor(random({ lix }) * items.length);
+ * const selected = items[idx];
+ *
+ * // Fisher-Yates shuffle
+ * function shuffle<T>(array: T[], lix: Lix): T[] {
+ *   const result = [...array];
+ *   for (let i = result.length - 1; i > 0; i--) {
+ *     const j = Math.floor(random({ lix }) * (i + 1));
+ *     [result[i], result[j]] = [result[j], result[i]];
+ *   }
+ *   return result;
+ * }
+ * ```
+ *
+ * @param args.lix - The Lix instance with sqlite and db connections
+ * @returns Random float between 0 (inclusive) and 1 (exclusive) with 53-bit precision
+ */
+export function random(args: { lix: Pick<Lix, "sqlite" | "db"> }): number {
+	// Non-deterministic mode: use crypto.getRandomValues()
+	if (!isDeterministicMode({ lix: args.lix })) {
+		return randomUnstable();
+	}
+
+	// Deterministic mode: use xorshift128+
+	let state = rngCache.get(args.lix.sqlite);
+
+	/* First use on this connection → initialize from seed */
+	if (!state) {
+		// Check if we have persisted RNG state
+		const [stateRow] = executeSync({
+			lix: { sqlite: args.lix.sqlite },
+			query: args.lix.db
+				.selectFrom("key_value_all")
+				.where("key", "=", "lix_deterministic_rng_state")
+				.where("lixcol_version_id", "=", "global")
+				.select("value"),
+		});
+
+		if (stateRow && stateRow.value) {
+			// Restore persisted state
+			// The value is stored as a JSON string in key_value_all view
+			const stateData =
+				typeof stateRow.value === "string"
+					? JSON.parse(stateRow.value)
+					: stateRow.value;
+
+			// Handle both string and direct values
+			state = {
+				hi: BigInt(stateData.hi),
+				lo: BigInt(stateData.lo),
+				dirty: false,
+			};
+		} else {
+			// Initialize from seed
+			const seed = getRngSeed(args);
+			state = seedXorshift128Plus(seed);
+		}
+
+		rngCache.set(args.lix.sqlite, state);
+	}
+
+	// Generate next random value using xorshift128+
+	const result = nextXorshift128Plus(state);
+	state.dirty = true;
+	return result;
+}
+
+/**
+ * Get the RNG seed - either from deterministic mode config or derive from lix_id
+ */
+function getRngSeed(args: { lix: Pick<Lix, "sqlite" | "db"> }): string {
+	// Check for seed in the deterministic mode config
+	const [configRow] = executeSync({
+		lix: { sqlite: args.lix.sqlite },
+		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.random_seed')`.as(
+					"random_seed"
+				)
+			),
+	});
+
+	if (configRow && configRow.random_seed) {
+		return configRow.random_seed as string;
+	}
+
+	// Derive default seed from lix_id
+	const [idRow] = executeSync({
+		lix: { sqlite: args.lix.sqlite },
+		query: args.lix.db
+			.selectFrom("key_value")
+			.where("key", "=", "lix_id")
+			.select("value"),
+	});
+
+	if (!idRow || !idRow.value) {
+		throw new Error("Could not find lix_id for RNG seed");
+	}
+
+	// Use lix_id as the seed - no need to insert it
+	return idRow.value as string;
+}
+
+/**
+ * Initialize state from a 64-bit hash of the seed string (SplitMix64-style)
+ */
+function seedXorshift128Plus(seed: string): RngState {
+	// FNV-1a hash to get initial value
+	let z = 0xcbf29ce484222325n;
+	for (const ch of seed) {
+		z = ((z ^ BigInt(ch.charCodeAt(0))) * 0x100000001b3n) & 0xffffffffffffffffn;
+	}
+
+	// SplitMix64 to expand into two non-zero words
+	const next = (): bigint => {
+		z = (z + 0x9e3779b97f4a7c15n) & 0xffffffffffffffffn;
+		let t = z;
+		t = ((t ^ (t >> 30n)) * 0xbf58476d1ce4e5b9n) & 0xffffffffffffffffn;
+		t = ((t ^ (t >> 27n)) * 0x94d049bb133111ebn) & 0xffffffffffffffffn;
+		return t ^ (t >> 31n);
+	};
+
+	return {
+		hi: next() || 1n,
+		lo: next() || 2n,
+		dirty: true, // New seed always needs to be persisted
+	};
+}
+
+/**
+ * One xorshift128+ step → returns 53-bit float in [0,1)
+ * This is the same algorithm used by V8/Chrome for Math.random()
+ */
+function nextXorshift128Plus(state: RngState): number {
+	let s1 = state.lo;
+	const s0 = state.hi;
+	state.lo = s0;
+	s1 ^= (s1 << 23n) & 0xffffffffffffffffn;
+	state.hi = (s1 ^ s0 ^ (s1 >> 17n) ^ (s0 >> 26n)) & 0xffffffffffffffffn;
+	const sum = (state.hi + state.lo) & 0xffffffffffffffffn;
+	// 53 high bits → IEEE-754 double in [0,1)
+	return Number(sum >> 11n) / Math.pow(2, 53);
+}
+
+/**
+ * @internal
+ * Flush the in-memory RNG state 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 commitDeterministicRngState(args: {
+	lix: Pick<Lix, "sqlite" | "db">;
+	timestamp?: string;
+}): void {
+	const state = rngCache.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_rng_state",
+		value: {
+			hi: state.hi.toString(),
+			lo: state.lo.toString(),
+		},
+	} satisfies LixKeyValue);
+
+	const now = args.timestamp ?? timestamp({ lix: args.lix });
+	updateUntrackedState({
+		lix: args.lix,
+		change: {
+			entity_id: "lix_deterministic_rng_state",
+			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",
+	});
+}

package/src/deterministic/sequence.test.ts

@@ -0,0 +1,93 @@
+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);
+});

package/src/deterministic/sequence.ts

@@ -0,0 +1,132 @@
+import type { SqliteWasmDatabase } from "sqlite-wasm-kysely";
+import { executeSync } from "../database/execute-sync.js";
+import { LixKeyValueSchema, type LixKeyValue } from "../key-value/schema.js";
+import type { Lix } from "../lix/open-lix.js";
+import { isDeterministicMode } from "./is-deterministic-mode.js";
+import { timestamp } from "./timestamp.js";
+import { updateUntrackedState } from "../state/untracked/update-untracked-state.js";
+
+/** State kept per SQLite connection */
+type CounterState = {
+	next: number; // number that will be handed out _next_
+	highestSeen: number; // highest value actually handed out
+	dirty: boolean; // true ⇢ we have to persist on commit
+};
+
+const counterCache = new WeakMap<SqliteWasmDatabase, CounterState>();
+
+/**
+ * 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: {
+	lix: Pick<Lix, "sqlite" | "db">;
+}): number {
+	// 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: {
+	lix: Pick<Lix, "sqlite" | "db">;
+	timestamp?: string;
+}): void {
+	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,
+	} satisfies LixKeyValue);
+
+	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",
+	});
+}

package/src/deterministic/timestamp.test.ts

@@ -0,0 +1,170 @@
+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: string[] = [];
+	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
+});