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

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

@@ -1,200 +0,0 @@
-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

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

package/src/deterministic/options.test.ts

@@ -1,157 +0,0 @@
-import { test, expect } from "vitest";
-import {
-	LixDeterministicModeOptionsSchema,
-	type DeterministicModeOptions,
-} from "./options.js";
-import {
-	validateLixSchema,
-	validateLixSchemaDefinition,
-} from "../schema-definition/validate-lix-schema.js";
-
-test("deterministic mode options schema is a valid LixSchemaDefinition", () => {
-	expect(() =>
-		validateLixSchemaDefinition(LixDeterministicModeOptionsSchema)
-	).not.toThrow();
-});
-
-test("validates correct deterministic mode options", () => {
-	const validOptions: DeterministicModeOptions = {
-		enabled: true,
-		randomLixId: false,
-		timestamp: true,
-		random_seed: "test-seed",
-		nano_id: true,
-		uuid_v7: true,
-	};
-
-	expect(() =>
-		validateLixSchema(LixDeterministicModeOptionsSchema, validOptions)
-	).not.toThrow();
-});
-
-test("validates minimal deterministic mode options with only required fields", () => {
-	const minimalOptions: DeterministicModeOptions = {
-		enabled: true,
-	};
-
-	expect(() =>
-		validateLixSchema(LixDeterministicModeOptionsSchema, minimalOptions)
-	).not.toThrow();
-});
-
-test("fails validation when enabled is missing", () => {
-	// @ts-expect-error - Testing missing required field
-	const invalidOptions: DeterministicModeOptions = {
-		randomLixId: false,
-		timestamp: true,
-	};
-
-	expect(() =>
-		validateLixSchema(LixDeterministicModeOptionsSchema, invalidOptions)
-	).toThrow(/Data validation failed/);
-});
-
-test("fails validation when enabled is not a boolean", () => {
-	const invalidOptions: DeterministicModeOptions = {
-		// @ts-expect-error - Testing invalid type for enabled field
-		enabled: "true", // string instead of boolean
-		randomLixId: false,
-	};
-
-	expect(() =>
-		validateLixSchema(LixDeterministicModeOptionsSchema, invalidOptions)
-	).toThrow(/Data validation failed/);
-});
-
-test("fails validation with additional properties", () => {
-	const invalidOptions: DeterministicModeOptions = {
-		enabled: true,
-		// @ts-expect-error - Testing additional properties
-		unknown_property: "value",
-	};
-
-	expect(() =>
-		validateLixSchema(LixDeterministicModeOptionsSchema, invalidOptions)
-	).toThrow(/Data validation failed/);
-});
-
-test("validates all boolean fields correctly", () => {
-	const options: DeterministicModeOptions = {
-		enabled: false,
-		randomLixId: true,
-		timestamp: false,
-		random_seed: "custom-seed",
-		nano_id: false,
-		uuid_v7: true,
-	};
-
-	expect(() =>
-		validateLixSchema(LixDeterministicModeOptionsSchema, options)
-	).not.toThrow();
-});
-
-test("fails validation when boolean fields have wrong types", () => {
-	const testCases: DeterministicModeOptions[] = [
-		{
-			enabled: true,
-			// @ts-expect-error - Testing invalid type for randomLixId
-			randomLixId: "true",
-		},
-		{
-			enabled: true,
-			// @ts-expect-error - Testing invalid type for timestamp
-			timestamp: 1,
-		},
-		{
-			enabled: true,
-			// @ts-expect-error - Testing invalid type for nano_id
-			nano_id: null,
-		},
-		{
-			enabled: true,
-			// @ts-expect-error - Testing invalid type for uuid_v7
-			uuid_v7: {},
-		},
-	];
-
-	for (const testCase of testCases) {
-		expect(() =>
-			validateLixSchema(LixDeterministicModeOptionsSchema, testCase)
-		).toThrow(/Data validation failed/);
-	}
-});
-
-test("fails validation when random_seed is not a string", () => {
-	const invalidOptions: DeterministicModeOptions = {
-		enabled: true,
-		// @ts-expect-error - Testing invalid type for random_seed
-		random_seed: 12345, // number instead of string
-	};
-
-	expect(() =>
-		validateLixSchema(LixDeterministicModeOptionsSchema, invalidOptions)
-	).toThrow(/Data validation failed/);
-});
-
-test("schema has correct metadata", () => {
-	expect(LixDeterministicModeOptionsSchema["x-lix-key"]).toBe(
-		"lix_deterministic_mode"
-	);
-	expect(LixDeterministicModeOptionsSchema["x-lix-version"]).toBe("1.0");
-	expect(LixDeterministicModeOptionsSchema.type).toBe("object");
-	expect(LixDeterministicModeOptionsSchema.required).toEqual(["enabled"]);
-	expect(LixDeterministicModeOptionsSchema.additionalProperties).toBe(false);
-});
-
-test("schema has correct default values", () => {
-	const properties = LixDeterministicModeOptionsSchema.properties;
-
-	expect(properties.randomLixId.default).toBe(false);
-	expect(properties.timestamp.default).toBe(true);
-	expect(properties.random_seed.default).toBe("lix-deterministic-seed");
-	expect(properties.nano_id.default).toBe(true);
-	expect(properties.uuid_v7.default).toBe(true);
-
-	// enabled should not have a default
-	expect(properties.enabled).not.toHaveProperty("default");
-});

package/src/deterministic/options.ts

@@ -1,62 +0,0 @@
-import type {
-	FromLixSchemaDefinition,
-	LixInsertable,
-	LixSchemaDefinition,
-} from "../schema-definition/index.js";
-
-/**
- * Schema definition for deterministic mode options.
- *
- * @example
- * const options = {
- *   enabled: true,
- *   randomLixId: false,
- *   timestamp: true,
- *   random_seed: "default-seed",
- *   nano_id: true,
- *   uuid_v7: true
- * };
- */
-export const LixDeterministicModeOptionsSchema = {
-	"x-lix-key": "lix_deterministic_mode",
-	"x-lix-version": "1.0",
-	type: "object",
-	properties: {
-		enabled: {
-			type: "boolean",
-		},
-		randomLixId: {
-			type: "boolean",
-			default: false,
-			"x-lix-generated": true,
-		},
-		timestamp: {
-			type: "boolean",
-			default: true,
-			"x-lix-generated": true,
-		},
-		random_seed: {
-			type: "string",
-			default: "lix-deterministic-seed",
-			"x-lix-generated": true,
-		},
-		nano_id: {
-			type: "boolean",
-			default: true,
-			"x-lix-generated": true,
-		},
-		uuid_v7: {
-			type: "boolean",
-			default: true,
-			"x-lix-generated": true,
-		},
-	},
-	required: ["enabled"],
-	additionalProperties: false,
-} as const;
-
-export type DeterministicModeOptions = LixInsertable<
-	FromLixSchemaDefinition<typeof LixDeterministicModeOptionsSchema>
->;
-
-LixDeterministicModeOptionsSchema satisfies LixSchemaDefinition;