@lix-js/sdk 0.5.1 → 0.6.0-preview.1

package/src/engine/functions/nano-id.ts

@@ -1,205 +0,0 @@
-import type { Lix } from "../../lix/open-lix.js";
-import type { LixEngine } from "../boot.js";
-import { isDeterministicModeSync } from "../deterministic-mode/is-deterministic-mode.js";
-import { sql } from "kysely";
-import { nextSequenceNumberSync } from "./sequence.js";
-import { internalQueryBuilder } from "../internal-query-builder.js";
-import { withRuntimeCache } from "../with-runtime-cache.js";
-
-/**
- * Sync variant of {@link nanoId}. See {@link nanoId} 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 nanoId}.
- *
- * @see nanoId
- */
-export function nanoIdSync(args: {
-	engine: Pick<LixEngine, "executeSync" | "hooks" | "runtimeCacheRef">;
-	length?: number;
-}): string {
-	const engine = args.engine;
-	// Check if deterministic mode is enabled
-	if (isDeterministicModeSync({ engine: engine })) {
-		// Check if nano_id is 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.nano_id')`.as("nano_id")
-				)
-				.limit(1)
-				.compile()
-		).rows;
-
-		// 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 = nextSequenceNumberSync({ engine: engine });
-		// Return counter with test_ prefix and padded to 10 digits
-		return `test_${counter.toString().padStart(10, "0")}`;
-	}
-
-	// Return regular nanoid
-	return randomNanoId(args.length);
-}
-
-/**
- * Generate a nano ID.
- *
- * Deterministic in deterministic mode; otherwise returns a random 21-character nano ID using the nanoid algorithm.
- *
- * 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 nextDetermininisticSequenceNumber | 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 to choose optimal length.
- *
- * @example Normal mode – random nanoid
- * ```ts
- * const lix = await openLix();
- * const id = await nanoId({ lix }) // "V1StGXR8_Z5jdHi6B-myT"
- * ```
- *
- * @example Deterministic mode – sequential IDs
- * ```ts
- * const lix = await openLix({
- *   keyValues: [{ key: "lix_deterministic_mode", value: { enabled: true }, lixcol_version_id: "global" }]
- * });
- * await nanoId({ lix }) // "test_0000000000"
- * await nanoId({ lix }) // "test_0000000001"
- * await nanoId({ lix }) // "test_0000000002"
- * ```
- *
- * @example Database operations
- * ```ts
- * await lix.db
- *   .insertInto("label")
- *   .values({ id: await nanoId({ lix }), name: "bug", color: "#ff0000" })
- *   .execute();
- * ```
- *
- * @param args.lix Lix instance used to call into the engine.
- * @param args.length Optional length for non-deterministic mode (default: 21)
- */
-export async function nanoId(args: {
-	// Allow additional properties to avoid excess property errors at call sites
-	lix: Pick<Lix, "call"> & Record<string, unknown>;
-	length?: number;
-}): Promise<string> {
-	const res = await args.lix.call("lix_nano_id", { length: args.length });
-	return String(res);
-}
-
-/**
- * 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);

package/src/engine/functions/random.test.ts

@@ -1,293 +0,0 @@
-import { expect, test } from "vitest";
-import { openLix } from "../../lix/open-lix.js";
-import { random } from "./random.js";
-
-test("random works in non-deterministic mode", async () => {
-	const lix = await openLix({
-		keyValues: [{ key: "lix_deterministic_mode", value: { enabled: false } }],
-	});
-
-	const values = new Set<number>();
-	for (let i = 0; i < 1000; i++) {
-		const r = await random({ lix });
-		expect(r).toBeGreaterThanOrEqual(0);
-		expect(r).toBeLessThan(1);
-		values.add(r);
-	}
-
-	// With a good RNG generating 1000 floats, the probability of getting
-	// more than 50 duplicates is astronomically small (birthday paradox).
-	// This threshold prevents flaky tests while still catching bad RNGs.
-	expect(values.size).toBeGreaterThan(950);
-});
-
-test("random works in deterministic mode", async () => {
-	const lix = await openLix({
-		keyValues: [{ key: "lix_deterministic_mode", value: { enabled: true } }],
-	});
-
-	const sequence1 = [];
-	for (let i = 0; i < 10; i++) {
-		const r = await random({ lix });
-		expect(r).toBeGreaterThanOrEqual(0);
-		expect(r).toBeLessThan(1);
-		sequence1.push(r);
-	}
-
-	// All 10 values should be unique - deterministic doesn't mean constant
-	const uniqueValues = new Set(sequence1);
-	expect(uniqueValues.size).toBe(10);
-
-	const blob = await lix.toBlob();
-	const lix2 = await openLix({ blob });
-
-	const sequence2 = [];
-	for (let i = 0; i < 10; i++) {
-		sequence2.push(await random({ lix: lix2 }));
-	}
-
-	// After blob restore, sequence should continue from where it left off,
-	// not restart from the beginning
-	expect(sequence2).not.toEqual(sequence1);
-	expect(sequence2[0]).not.toBe(sequence1[0]);
-});
-
-test("deterministic mode produces same sequence with same seed", async () => {
-	const lix1 = await openLix({
-		keyValues: [
-			{
-				key: "lix_deterministic_mode",
-				value: {
-					enabled: true,
-					random_seed: "test-seed",
-				},
-			},
-		],
-	});
-
-	const sequence1 = [];
-	for (let i = 0; i < 5; i++) {
-		sequence1.push(await random({ lix: lix1 }));
-	}
-
-	// Test state persistence - continue generating after blob save/restore
-	const blob = await lix1.toBlob();
-	const lix1b = await openLix({ blob });
-
-	for (let i = 0; i < 5; i++) {
-		sequence1.push(await random({ lix: lix1b }));
-	}
-
-	const lix2 = await openLix({
-		keyValues: [
-			{
-				key: "lix_deterministic_mode",
-				value: {
-					enabled: true,
-					random_seed: "test-seed",
-				},
-			},
-		],
-	});
-
-	const sequence2 = [];
-	for (let i = 0; i < 10; i++) {
-		sequence2.push(await random({ lix: lix2 }));
-	}
-
-	// Same seed should produce identical 10-number sequence,
-	// including numbers generated after blob persistence
-	expect(sequence1).toEqual(sequence2);
-});
-
-test("deterministic mode produces different sequences with different seeds", async () => {
-	const lix1 = await openLix({
-		keyValues: [
-			{
-				key: "lix_deterministic_mode",
-				value: {
-					enabled: true,
-					random_seed: "seed-1",
-				},
-			},
-		],
-	});
-
-	const sequence1 = [];
-	for (let i = 0; i < 100; i++) {
-		sequence1.push(await random({ lix: lix1 }));
-	}
-
-	const lix2 = await openLix({
-		keyValues: [
-			{
-				key: "lix_deterministic_mode",
-				value: {
-					enabled: true,
-					random_seed: "seed-2",
-				},
-			},
-		],
-	});
-
-	const sequence2: any[] = [];
-	for (let i = 0; i < 100; i++) {
-		sequence2.push(await random({ lix: lix2 }));
-	}
-
-	// Different seeds should produce completely different sequences.
-	// With 100 samples each, any overlap would indicate poor seeding.
-	const overlap = sequence1.some((x) => sequence2.includes(x));
-	expect(overlap).toBe(false);
-});
-
-test("random state persists across blob operations", async () => {
-	const lix1 = await openLix({
-		keyValues: [{ key: "lix_deterministic_mode", value: { enabled: true } }],
-	});
-
-	const fullSequence = [];
-	for (let i = 0; i < 6; i++) {
-		fullSequence.push(await random({ lix: lix1 }));
-	}
-
-	const lix2 = await openLix({
-		keyValues: [{ key: "lix_deterministic_mode", value: { enabled: true } }],
-	});
-
-	const beforeBlob = [];
-	for (let i = 0; i < 3; i++) {
-		beforeBlob.push(await random({ lix: lix2 }));
-	}
-
-	const blob = await lix2.toBlob();
-	const lix3 = await openLix({ blob });
-
-	const afterBlob = [];
-	for (let i = 0; i < 3; i++) {
-		afterBlob.push(await random({ lix: lix3 }));
-	}
-
-	// The state should persist through blob serialization.
-	// The two instances should produce the exact same sequence
-	// as if it was one continuous instance.
-	expect(beforeBlob).toEqual(fullSequence.slice(0, 3));
-	expect(afterBlob).toEqual(fullSequence.slice(3, 6));
-});
-
-test("random uses lix_id as default seed when no seed specified", async () => {
-	// Create two instances with randomLixId: true to get different lix_ids
-	const lix1 = await openLix({
-		keyValues: [
-			{
-				key: "lix_deterministic_mode",
-				value: { enabled: true, randomLixId: true },
-			},
-		],
-	});
-
-	const lix2 = await openLix({
-		keyValues: [
-			{
-				key: "lix_deterministic_mode",
-				value: { enabled: true, randomLixId: true },
-			},
-		],
-	});
-
-	const sequence1 = [];
-	const sequence2 = [];
-
-	// Generate values from each instance
-	for (let i = 0; i < 10; i++) {
-		sequence1.push(await random({ lix: lix1 }));
-		sequence2.push(await random({ lix: lix2 }));
-	}
-
-	// With randomLixId: true, each instance gets a different lix_id,
-	// so they will produce different sequences when using lix_id as default seed
-	expect(sequence1).not.toEqual(sequence2);
-
-	// But each sequence should be deterministic (verified by other tests)
-});
-
-test("random produces same sequence with deterministic mode", async () => {
-	// Create two instances with deterministic mode enabled
-	const lix1 = await openLix({
-		keyValues: [{ key: "lix_deterministic_mode", value: { enabled: true } }],
-	});
-
-	const lix2 = await openLix({
-		keyValues: [{ key: "lix_deterministic_mode", value: { enabled: true } }],
-	});
-
-	const sequence1 = [];
-	const sequence2 = [];
-
-	// Generate values from each instance
-	for (let i = 0; i < 10; i++) {
-		sequence1.push(await random({ lix: lix1 }));
-		sequence2.push(await random({ lix: lix2 }));
-	}
-
-	// With deterministic mode, both instances get the same lix_id (deterministic-lix-id),
-	// so they will produce the same sequence when using lix_id as default seed
-	expect(sequence1).toEqual(sequence2);
-});
-
-test("random works after enabling deterministic mode", async () => {
-	const lix = await openLix({});
-
-	// Use random in non-deterministic mode first
-	const nonDeterministicValue = await random({ lix });
-	expect(nonDeterministicValue).toBeGreaterThanOrEqual(0);
-	expect(nonDeterministicValue).toBeLessThan(1);
-
-	// Enable deterministic mode
-	await lix.db
-		.insertInto("key_value")
-		.values({ key: "lix_deterministic_mode", value: { enabled: true } })
-		.execute();
-
-	// Generate deterministic values
-	const sequence1 = [];
-	for (let i = 0; i < 5; i++) {
-		sequence1.push(await random({ lix }));
-	}
-
-	// Save state and reload
-	const blob = await lix.toBlob();
-	const lix2 = await openLix({ blob });
-
-	// Continue generating values
-	const sequence2 = [];
-	for (let i = 0; i < 5; i++) {
-		sequence2.push(await random({ lix: lix2 }));
-	}
-
-	// Values should continue from where they left off (deterministic state persisted)
-	expect(sequence2[0]).not.toBe(sequence1[0]);
-
-	// All values should be valid random numbers
-	const allValues = [...sequence1, ...sequence2];
-	for (const val of allValues) {
-		expect(val).toBeGreaterThanOrEqual(0);
-		expect(val).toBeLessThan(1);
-	}
-});
-
-test("non-deterministic mode without key specified", async () => {
-	const lix = await openLix({});
-
-	const values = new Set<number>();
-	for (let i = 0; i < 100; i++) {
-		const r = await random({ lix });
-		expect(r).toBeGreaterThanOrEqual(0);
-		expect(r).toBeLessThan(1);
-		values.add(r);
-	}
-
-	// Even with only 100 samples, we expect high uniqueness
-	// This also verifies that omitting the key defaults to non-deterministic
-	expect(values.size).toBeGreaterThan(80);
-});