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

package/src/deterministic/is-deterministic-mode.test.ts

@@ -0,0 +1,133 @@
+import { test, expect } from "vitest";
+import { isDeterministicMode } from "./is-deterministic-mode.js";
+import { openLix } from "../lix/open-lix.js";
+import { newLixFile } from "../lix/new-lix.js";
+
+test("isDeterministicMode returns false when lix_deterministic_mode is not set", async () => {
+	const lix = await openLix({ blob: await newLixFile() });
+
+	const result = isDeterministicMode({ lix });
+
+	expect(result).toBe(false);
+});
+
+test("isDeterministicMode returns false when lix_deterministic_mode is explicitly false", async () => {
+	const lix = await openLix({
+		blob: await newLixFile(),
+		keyValues: [{ key: "lix_deterministic_mode", value: { enabled: false } }],
+	});
+
+	const result = isDeterministicMode({ lix });
+
+	expect(result).toBe(false);
+});
+
+test("isDeterministicMode returns true when lix_deterministic_mode is true", async () => {
+	const lix = await openLix({
+		blob: await newLixFile(),
+		keyValues: [{ key: "lix_deterministic_mode", value: { enabled: true } }],
+	});
+
+	const result = isDeterministicMode({ lix });
+
+	expect(result).toBe(true);
+});
+
+test("isDeterministicMode returns true for enabled values loosely equal to true", async () => {
+	const testCases = [
+		{ enabled: 1, expected: true },
+		{ enabled: "1", expected: true },
+		{ enabled: true, expected: true },
+	];
+
+	for (const { enabled, expected } of testCases) {
+		const lix = await openLix({
+			blob: await newLixFile(),
+			keyValues: [{ key: "lix_deterministic_mode", value: { enabled } }],
+		});
+
+		const result = isDeterministicMode({ lix });
+
+		expect(result).toBe(expected);
+	}
+});
+
+test("isDeterministicMode returns false for enabled values not loosely equal to true", async () => {
+	const testCases = [
+		{ enabled: "yes", expected: false },
+		{ enabled: "true", expected: false },
+		{ enabled: 2, expected: false },
+		{ enabled: {}, expected: false },
+		{ enabled: [], expected: false },
+	];
+
+	for (const { enabled, expected } of testCases) {
+		const lix = await openLix({
+			blob: await newLixFile(),
+			keyValues: [{ key: "lix_deterministic_mode", value: { enabled } }],
+		});
+
+		const result = isDeterministicMode({ lix });
+
+		expect(result).toBe(expected);
+	}
+});
+
+test("isDeterministicMode returns false for falsy enabled values", async () => {
+	const testCases = [
+		{ enabled: null, expected: false },
+		{ enabled: 0, expected: false },
+		{ enabled: "", expected: false },
+		{ enabled: undefined, expected: false },
+		{ enabled: false, expected: false },
+	];
+
+	for (const { enabled, expected } of testCases) {
+		const lix = await openLix({
+			blob: await newLixFile(),
+			keyValues: [{ key: "lix_deterministic_mode", value: { enabled } }],
+		});
+
+		const result = isDeterministicMode({ lix });
+
+		expect(result).toBe(expected);
+	}
+});
+
+test("isDeterministicMode works with only required properties from Lix", async () => {
+	const lix = await openLix({ blob: await newLixFile() });
+
+	// Create a minimal object with only required properties
+	const minimalLix = {
+		sqlite: lix.sqlite,
+		db: lix.db,
+	};
+
+	const result = isDeterministicMode({ lix: minimalLix });
+
+	expect(result).toBe(false);
+});
+
+test("isDeterministicMode can be changed at runtime", async () => {
+	const lix = await openLix({ blob: await newLixFile() });
+
+	// Initially false
+	expect(isDeterministicMode({ lix })).toBe(false);
+
+	// Set to true
+	await lix.db
+		.insertInto("key_value")
+		.values({ key: "lix_deterministic_mode", value: { enabled: true } })
+		.execute();
+
+	expect(isDeterministicMode({ lix })).toBe(true);
+
+	// Update to false
+	await lix.db
+		.updateTable("key_value")
+		.where("key", "=", "lix_deterministic_mode")
+		.set({ value: { enabled: false } })
+		.execute();
+
+	expect(isDeterministicMode({ lix })).toBe(false);
+});

package/src/deterministic/is-deterministic-mode.ts

@@ -0,0 +1,32 @@
+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";
+
+/**
+ * Checks if deterministic mode is enabled by querying the key_value table.
+ *
+ * Returns true if the enabled property in the JSON object is true.
+ * Returns false for any other value or if the key doesn't exist.
+ *
+ * @param args - Object containing the lix instance with sqlite connection
+ * @returns true if deterministic mode is enabled, false otherwise
+ */
+export function isDeterministicMode(args: {
+	lix: Pick<Lix, "sqlite" | "db">;
+}): boolean {
+	// TODO account for active version
+	// Need to query from underlying state to avoid recursion
+	const [row] = 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.enabled')`.as("enabled")
+			),
+	});
+
+	return row?.enabled == true;
+}

package/src/deterministic/nano-id.test.ts

@@ -0,0 +1,200 @@
+import { expect, test, vi } from "vitest";
+import { _nanoIdAlphabet, nanoId } from "./nano-id.js";
+import { openLix } from "../lix/open-lix.js";
+
+test("nanoId returns deterministic values when deterministic mode is enabled", async () => {
+	const lix = await openLix({
+		keyValues: [{ key: "lix_deterministic_mode", value: { enabled: true } }],
+	});
+
+	const id1 = nanoId({ lix });
+	const id2 = nanoId({ lix });
+	const id3 = nanoId({ lix });
+
+	// Should have test_ prefix and 10 digits
+	expect(id1).toMatch(/^test_\d{10}$/);
+	expect(id2).toMatch(/^test_\d{10}$/);
+	expect(id3).toMatch(/^test_\d{10}$/);
+
+	// Extract counters
+	const counter1 = parseInt(id1.slice(5), 10);
+	const counter2 = parseInt(id2.slice(5), 10);
+	const counter3 = parseInt(id3.slice(5), 10);
+
+	// Should be sequential
+	expect(counter2).toBe(counter1 + 1);
+	expect(counter3).toBe(counter2 + 1);
+});
+
+test("nanoId returns random values when deterministic mode is disabled", async () => {
+	const lix = await openLix({
+		keyValues: [{ key: "lix_deterministic_mode", value: { enabled: false } }],
+	});
+
+	const id1 = nanoId({ lix });
+	const id2 = nanoId({ lix });
+	const id3 = nanoId({ lix });
+
+	// Should NOT have test_ prefix
+	expect(id1).not.toMatch(/^test_/);
+	expect(id2).not.toMatch(/^test_/);
+	expect(id3).not.toMatch(/^test_/);
+
+	// Should be 21 characters (default nanoid length)
+	expect(id1.length).toBe(21);
+	expect(id2.length).toBe(21);
+	expect(id3.length).toBe(21);
+
+	// Should all be different
+	expect(id1).not.toBe(id2);
+	expect(id2).not.toBe(id3);
+	expect(id1).not.toBe(id3);
+});
+
+test("nanoId toggles between deterministic and random", async () => {
+	const lix = await openLix({
+		keyValues: [{ key: "lix_deterministic_mode", value: { enabled: true } }],
+	});
+
+	// Start with deterministic
+	const deterministicId = nanoId({ lix });
+	expect(deterministicId).toMatch(/^test_\d{10}$/);
+
+	// Switch to random
+	await lix.db
+		.updateTable("key_value")
+		.set({ value: { enabled: false } })
+		.where("key", "=", "lix_deterministic_mode")
+		.execute();
+
+	const randomId = nanoId({ lix });
+	expect(randomId).not.toMatch(/^test_/);
+	expect(randomId.length).toBe(21);
+
+	// Switch back to deterministic
+	await lix.db
+		.updateTable("key_value")
+		.set({ value: { enabled: true } })
+		.where("key", "=", "lix_deterministic_mode")
+		.execute();
+
+	const deterministicId2 = nanoId({ lix });
+	expect(deterministicId2).toMatch(/^test_\d{10}$/);
+});
+
+test("nanoId 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 = nanoId({ lix: lix1 });
+	const id2 = nanoId({ lix: lix1 });
+	const id3 = nanoId({ 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 = nanoId({ lix: lix2 });
+
+	// Extract counters
+	const counters = [id1, id2, id3, id4].map((id) => parseInt(id.slice(5), 10));
+
+	// 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("nanoId advances correctly with many operations", async () => {
+	const lix = await openLix({
+		keyValues: [{ key: "lix_deterministic_mode", value: { enabled: true } }],
+	});
+
+	// Generate 100 nanoIds
+	const ids: string[] = [];
+	for (let i = 0; i < 100; i++) {
+		ids.push(nanoId({ lix }));
+	}
+
+	// All should have test_ prefix
+	for (const id of ids) {
+		expect(id).toMatch(/^test_\d{10}$/);
+	}
+
+	// Extract counters
+	const counters = ids.map((id) => parseInt(id.slice(5), 10));
+
+	// 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);
+});
+
+test("nanoId format is consistent across different counter values", async () => {
+	const lix = await openLix({
+		keyValues: [{ key: "lix_deterministic_mode", value: { enabled: true } }],
+	});
+
+	// Generate an ID with initial counter
+	const id1 = nanoId({ lix });
+	expect(id1).toMatch(/^test_\d{10}$/);
+	expect(id1.length).toBe(15); // "test_" (5) + 10 digits
+
+	// Generate many IDs to get different counter magnitudes
+	for (let i = 0; i < 1000; i++) {
+		nanoId({ lix });
+	}
+
+	const idAfter1000 = nanoId({ lix });
+	expect(idAfter1000).toMatch(/^test_\d{10}$/);
+	expect(idAfter1000.length).toBe(15); // Should still be padded to same length
+});
+
+test("length is obeyed", async () => {
+	const lix = await openLix({});
+	const id = nanoId({ lix, length: 10 });
+	expect(id.length).toBe(10);
+});
+
+test("the alphabet does not contain underscores `_` because they are not URL safe", () => {
+	expect(_nanoIdAlphabet).not.toContain("_");
+});
+
+test("the alphabet does not contain dashes `-` because they break selecting the ID from the URL in the browser", () => {
+	expect(_nanoIdAlphabet).not.toContain("-");
+});
+
+/**
+ * Test the crypto polyfill that was added to fix environments without crypto support
+ * like older versions of Node in Stackblitz.
+ *
+ * See: https://github.com/opral/lix-sdk/issues/258
+ */
+test("polyfill works when crypto is not available", async () => {
+	const lix = await openLix({});
+
+	// Store original crypto
+	const originalCrypto = global.crypto;
+
+	// Mock crypto as undefined to test the polyfill
+	vi.stubGlobal("crypto", undefined);
+
+	try {
+		const id = nanoId({ lix, length: 10 });
+		expect(id.length).toBe(10);
+		expect(typeof id).toBe("string");
+		// Check that it only contains characters from our alphabet
+		for (let i = 0; i < id.length; i++) {
+			expect(_nanoIdAlphabet).toContain(id[i]);
+		}
+	} finally {
+		// Restore original crypto
+		vi.stubGlobal("crypto", originalCrypto);
+	}
+});

package/src/deterministic/nano-id.ts

@@ -0,0 +1,188 @@
+import type { Lix } from "../lix/open-lix.js";
+import { nextDeterministicSequenceNumber } from "./index.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 a nano ID that is deterministic in deterministic mode.
+ *
+ * In normal mode, returns a random 21-character nano ID using the [nanoid](https://github.com/ai/nanoid) algorithm.
+ * In deterministic mode, returns sequential IDs with "test_" prefix for easy identification.
+ *
+ * Use nano IDs when IDs will appear in URLs - their shorter length makes links easier to share.
+ * For better database performance with time-ordered queries, consider {@link uuidV7} instead.
+ *
+ * - Normal mode: URL-safe random ID using custom alphabet (no `-` or `_`)
+ * - Deterministic mode: "test_" + 10-digit zero-padded counter
+ * - Counter state shared with {@link nextDeterministicSequenceNumber}
+ * - The "test_" prefix makes deterministic IDs easily identifiable
+ * - Choose nano IDs for URL-friendly short IDs, {@link uuidV7} for time-sortable database keys
+ * - Use the [Nano ID collision calculator](https://zelark.github.io/nano-id-cc/) to find the optimal length for your shareability vs uniqueness needs
+ *
+ * @example Normal mode - returns random nanoid
+ * ```ts
+ * const lix = await openLix();
+ * nanoId({ lix }); // "V1StGXR8_Z5jdHi6B-myT"
+ * ```
+ *
+ * @example Deterministic mode - returns sequential IDs
+ * ```ts
+ * const lix = await openLix({
+ *   keyValues: [{ key: "lix_deterministic_mode", value: { enabled: true }, lixcol_version_id: "global" }]
+ * });
+ * nanoId({ lix }); // "test_0000000000"
+ * nanoId({ lix }); // "test_0000000001"
+ * nanoId({ lix }); // "test_0000000002"
+ * ```
+ *
+ * @example Database operations
+ * ```ts
+ * await lix.db
+ *   .insertInto("label")
+ *   .values({
+ *     id: nanoId({ lix }),
+ *     name: "bug",
+ *     color: "#ff0000"
+ *   })
+ *   .execute();
+ * ```
+ *
+ * @param args.lix - The Lix instance with sqlite and db connections
+ * @param args.length - Custom length for non-deterministic mode (default: 21)
+ * @returns Nano ID string
+ */
+export function nanoId(args: {
+	lix: Pick<Lix, "sqlite" | "db">;
+	length?: number;
+}): string {
+	// Check if deterministic mode is enabled
+	if (isDeterministicMode({ lix: args.lix })) {
+		// Check if nano_id 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.nano_id')`.as("nano_id")
+				),
+		});
+
+		// If nano_id is explicitly set to false, use non-deterministic
+		if (config?.nano_id == false) {
+			return randomNanoId(args.length);
+		}
+
+		// Otherwise use deterministic nano ID
+		// Get the next deterministic counter value
+		const counter = nextDeterministicSequenceNumber({ lix: args.lix });
+		// Return counter with test_ prefix and padded to 10 digits
+		return `test_${counter.toString().padStart(10, "0")}`;
+	}
+
+	// Return regular nanoid
+	return randomNanoId(args.length);
+}
+
+/**
+ * Code taken from the [nanoid](https://github.com/ai/nanoid/blob/main/index.browser.js)
+ * browser implementation. The code is licensed under the MIT license.
+ *
+ */
+
+/**
+ * Polyfill for crypto.getRandomValues in environments that don't have it,
+ * such as older versions of Node in Stackblitz.
+ *
+ * This implementation is not cryptographically secure, but is sufficient for ID generation
+ * in these environments. In environments with proper crypto support, we'll use the native implementation.
+ *
+ * See: https://github.com/opral/lix-sdk/issues/258
+ */
+const insecureRandom = (array: Uint8Array) => {
+	for (let i = 0; i < array.length; i++) {
+		array[i] = Math.floor(Math.random() * 256);
+	}
+	return array;
+};
+
+// Use crypto.getRandomValues if available, otherwise use our polyfill
+const random = (bytes: any) => {
+	const array = new Uint8Array(bytes);
+	if (typeof crypto !== "undefined" && crypto.getRandomValues) {
+		return crypto.getRandomValues(array);
+	}
+
+	// Fallback to insecure random number generator if crypto is not available
+	return insecureRandom(array);
+};
+
+const customRandom = (
+	alphabet: string,
+	defaultSize: number,
+	getRandom: any
+) => {
+	// First, a bitmask is necessary to generate the ID. The bitmask makes bytes
+	// values closer to the alphabet size. The bitmask calculates the closest
+	// `2^31 - 1` number, which exceeds the alphabet size.
+	// For example, the bitmask for the alphabet size 30 is 31 (00011111).
+	// `Math.clz32` is not used, because it is not available in browsers.
+	const mask = (2 << Math.log2(alphabet.length - 1)) - 1;
+	// Though, the bitmask solution is not perfect since the bytes exceeding
+	// the alphabet size are refused. Therefore, to reliably generate the ID,
+	// the random bytes redundancy has to be satisfied.
+
+	// Note: every hardware random generator call is performance expensive,
+	// because the system call for entropy collection takes a lot of time.
+	// So, to avoid additional system calls, extra bytes are requested in advance.
+
+	// Next, a step determines how many random bytes to generate.
+	// The number of random bytes gets decided upon the ID size, mask,
+	// alphabet size, and magic number 1.6 (using 1.6 peaks at performance
+	// according to benchmarks).
+
+	// `-~f => Math.ceil(f)` if f is a float
+	// `-~i => i + 1` if i is an integer
+	const step = -~((1.6 * mask * defaultSize) / alphabet.length);
+
+	return (size = defaultSize) => {
+		let id = "";
+		while (true) {
+			const bytes = getRandom(step);
+			// A compact alternative for `for (var i = 0; i < step; i++)`.
+			let j = step | 0;
+			while (j--) {
+				// Adding `|| ''` refuses a random byte that exceeds the alphabet size.
+				id += alphabet[bytes[j] & mask] || "";
+				if (id.length >= size) return id;
+			}
+		}
+	};
+};
+
+const customAlphabet = (alphabet: string, size = 21) =>
+	customRandom(alphabet, size | 0, random);
+
+/**
+ * Uses every character from nano id except for the `-` and `_` character.
+ *
+ * - Underscore `_` is not URL safe https://github.com/ai/nanoid/issues/347.
+ * - Dash `-` breaks selecting the ID from the URL in the browser.
+ */
+export const _nanoIdAlphabet =
+	"0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+
+/**
+ * Generate secure URL-friendly unique ID.
+ *
+ * NOTE: This is the non-deterministic version. For deterministic IDs in tests,
+ * use `nanoid({ lix })` from './functions.js' instead.
+ *
+ * Use https://zelark.github.io/nano-id-cc/ to calculate the length
+ * of the ID for the use case with the alphabet provided in the
+ * implementation.
+ */
+const randomNanoId: (size?: number) => string = customAlphabet(_nanoIdAlphabet);