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

package/src/test-utilities/simulation-test/out-of-order-sequence-simulation.ts

@@ -0,0 +1,69 @@
+import { vi } from "vitest";
+import * as sequenceModule from "../../deterministic/sequence.js";
+import type { SimulationTestDef } from "./simulation-test.js";
+
+/**
+ * Out-of-order sequence simulation - Returns shuffled sequence numbers
+ * to ensure queries don't rely on ordered IDs or timestamps.
+ *
+ * This simulation shuffles sequence numbers to catch any code that incorrectly
+ * assumes monotonic ordering of IDs, timestamps, or other sequence-based values.
+ */
+export const outOfOrderSequenceSimulation: SimulationTestDef = {
+	name: "out-of-order-sequence",
+	setup: async (lix) => {
+		// Simple deterministic shuffle function using fixed seed
+		const createShuffledMapping = (
+			maxSequences: number
+		): Map<number, number> => {
+			const normalSequence = Array.from({ length: maxSequences }, (_, i) => i);
+			const shuffledSequence = [...normalSequence];
+
+			// Deterministic shuffle with fixed seed
+			let seed = 12345;
+			const random = () => {
+				seed = (seed * 9301 + 49297) % 233280;
+				return seed / 233280;
+			};
+
+			for (let i = shuffledSequence.length - 1; i > 0; i--) {
+				const j = Math.floor(random() * (i + 1));
+				const temp = shuffledSequence[i]!;
+				shuffledSequence[i] = shuffledSequence[j]!;
+				shuffledSequence[j] = temp;
+			}
+
+			// Create mapping from normal to shuffled
+			const mapping = new Map<number, number>();
+			for (let i = 0; i < normalSequence.length; i++) {
+				mapping.set(normalSequence[i]!, shuffledSequence[i]!);
+			}
+
+			return mapping;
+		};
+
+		// Pre-generate mapping for first 1000 sequence numbers
+		const shuffleMapping = createShuffledMapping(1000);
+
+		// Internal counter to track what the "normal" sequence would be
+		// This avoids calling the real sequence function which would change database state
+		let internalCounter = 0;
+
+		// Mock the nextDeterministicSequenceNumber function
+		vi.spyOn(
+			sequenceModule,
+			"nextDeterministicSequenceNumber"
+		).mockImplementation(() => {
+			// Use our internal counter instead of calling the real function
+			const normalSequence = internalCounter++;
+
+			// Look up the shuffled version, or use original if not in map
+			const shuffledSequence =
+				shuffleMapping.get(normalSequence) ?? normalSequence;
+
+			return shuffledSequence;
+		});
+
+		return lix;
+	},
+};

package/src/test-utilities/simulation-test/simulation-test.test.ts

@@ -0,0 +1,400 @@
+import { describe, expect, test } from "vitest";
+import {
+	simulationTest,
+	type SimulationTestDef,
+	normalSimulation,
+} from "./simulation-test.js";
+import { commit } from "../../state/commit.js";
+
+test("simulation test discovery", () => {});
+
+describe("expectDeterministic validates values across simulations", () => {
+	const customSimulation: SimulationTestDef = {
+		name: "custom",
+		setup: async (lix) => lix,
+	};
+
+	simulationTest(
+		"",
+		async ({ expectDeterministic }) => {
+			// These should be consistent across all simulations
+
+			expect(() => {
+				expectDeterministic("same-string").toBe("same-string");
+				expectDeterministic(42).toBe(42);
+				expectDeterministic({ foo: "bar" }).toEqual({ foo: "bar" });
+				expectDeterministic([1, 2, 3]).toEqual([1, 2, 3]);
+			}).not.toThrow();
+		},
+		{
+			simulations: [normalSimulation, customSimulation],
+		}
+	);
+});
+
+describe("expectDeterministic catches simulation differences", () => {
+	const customSimulation: SimulationTestDef = {
+		name: "custom",
+		setup: async (lix) => lix,
+	};
+
+	simulationTest(
+		"",
+		async ({ simulation, expectDeterministic }) => {
+			// This will store different values in different simulations
+			const simulationSpecificValue =
+				simulation.name === "normal" ? "normal-value" : "other-value";
+
+			if (simulation.name === "normal") {
+				// This will fail in the second simulation
+				expect(() =>
+					expectDeterministic(simulationSpecificValue).toBe("normal-value")
+				).not.toThrow();
+			} else {
+				expect(() =>
+					expectDeterministic(simulationSpecificValue).toBe("normal-value")
+				).toThrow(/SIMULATION DETERMINISM VIOLATION/);
+			}
+		},
+		{
+			simulations: [normalSimulation, customSimulation],
+		}
+	);
+});
+
+describe("deterministic state validation", () => {
+	// Testing this with materialized state and the changes the lix has
+	// Both need to be exactly the same for all simulations
+
+	let previousState: any | null = null;
+	let previousChanges: any | null = null;
+
+	const mockSimulation: SimulationTestDef = {
+		name: "mock-simulation",
+		setup: async (lix) => lix,
+	};
+
+	simulationTest(
+		"",
+		async ({ openSimulatedLix }) => {
+			const lix = await openSimulatedLix({
+				keyValues: [
+					{
+						key: "lix_deterministic_mode",
+						value: { enabled: true, bootstrap: true },
+						lixcol_version_id: "global",
+					},
+				],
+			});
+
+			const allState = await lix.db
+				.selectFrom("state_all")
+				.selectAll()
+				.execute();
+
+			const changes = await lix.db.selectFrom("change").selectAll().execute();
+
+			if (previousState === null) {
+				previousState = allState;
+				previousChanges = changes;
+			} else {
+				expect(previousState).toEqual(allState);
+				expect(previousChanges).toEqual(changes);
+			}
+
+			expect(allState).toBeDefined();
+		},
+		{
+			simulations: [normalSimulation, mockSimulation],
+		}
+	);
+});
+
+describe("database operations are deterministic", async () => {
+	const mockSimulation: SimulationTestDef = {
+		name: "mock-simulation",
+		setup: async (lix) => lix,
+	};
+
+	simulationTest(
+		"",
+		async ({ expectDeterministic, openSimulatedLix }) => {
+			const lix = await openSimulatedLix({
+				keyValues: [
+					{
+						key: "lix_deterministic_mode",
+						value: { enabled: true, bootstrap: true },
+						lixcol_version_id: "global",
+					},
+				],
+			});
+
+			// Testing two types of entity views that exist:
+			// 1. Regular entity view (on key_value table)
+			// 2. File entity view (whish is a special case because it aggregates multiple entities into one)
+
+			// regular entity view
+			await lix.db
+				.insertInto("key_value")
+				.values({
+					key: "test_key",
+					value: "test_value",
+				})
+				.execute();
+
+			// special entity view
+			await lix.db
+				.insertInto("file")
+				.values({
+					path: "/test.txt",
+					data: new TextEncoder().encode("test content"),
+				})
+				.execute();
+
+			// Get all tables and views from the database
+			const tablesAndViews = lix.sqlite
+				.exec({
+					sql: `SELECT name FROM sqlite_master 
+				WHERE type IN ('table', 'view') 
+				AND name NOT LIKE 'sqlite_%'
+				ORDER BY name`,
+					returnValue: "resultRows",
+				})
+				.map((row) => row[0] as string);
+
+			// Query each table/view and check determinism
+			for (const tableName of tablesAndViews) {
+				const data = lix.sqlite.exec({
+					sql: `SELECT * FROM "${tableName}"`,
+					returnValue: "resultRows",
+					columnNames: [],
+				});
+
+				try {
+					expectDeterministic(data).toBeDefined();
+				} catch (error) {
+					throw new Error(
+						`Determinism check failed for table/view "${tableName}": ${error}`
+					);
+				}
+			}
+		},
+		{
+			simulations: [normalSimulation, mockSimulation],
+		}
+	);
+});
+
+describe("providing key values", async () => {
+	simulationTest("", async ({ openSimulatedLix }) => {
+		const lix = await openSimulatedLix({
+			keyValues: [
+				{
+					key: "lix_deterministic_mode",
+					value: { enabled: true, bootstrap: true },
+					lixcol_version_id: "global",
+				},
+				{ key: "test_key_1", value: ["*"], lixcol_version_id: "global" },
+			],
+		});
+
+		commit({ lix });
+
+		const logLevels = await lix.db
+			.selectFrom("key_value")
+			.where("key", "=", "test_key_1")
+			.selectAll()
+			.execute();
+
+		expect(logLevels).toMatchObject([
+			{
+				key: "test_key_1",
+				value: ["*"],
+			},
+		]);
+	});
+});
+
+describe("expectDeterministic diff callback receives correct values", () => {
+	// Use a global store that persists across test runs
+	const globalStore = globalThis as any;
+	if (!globalStore.__testCallback1) {
+		globalStore.__testCallback1 = {};
+	}
+
+	// Reset before this test suite
+	globalStore.__testCallback1 = {
+		invoked: false,
+		actual: undefined,
+		expected: undefined,
+	};
+
+	const testSimulation: SimulationTestDef = {
+		name: "test-diff-callback",
+		setup: async (lix) => lix,
+	};
+
+	simulationTest(
+		"",
+		async ({ expectDeterministic, simulation }) => {
+			const store = globalStore.__testCallback1;
+
+			if (simulation.name === "normal") {
+				// First simulation - set the expected value
+				const testValue = { foo: "bar", count: 42 };
+				expectDeterministic(testValue).toBeDefined();
+			} else {
+				// Second simulation - use different value to trigger callback and error
+				const differentValue = { foo: "baz", count: 100 };
+				try {
+					expectDeterministic(differentValue, ({ actual, expected }) => {
+						store.invoked = true;
+						store.actual = actual;
+						store.expected = expected;
+					}).toBeDefined();
+				} catch {
+					// Expected to throw after callback
+				}
+			}
+		},
+		{
+			simulations: [normalSimulation, testSimulation],
+		}
+	);
+
+	test("callback was invoked with correct values", () => {
+		const { invoked, actual, expected } = globalStore.__testCallback1;
+
+		// Verify callback was invoked before the error
+		expect(invoked).toBe(true);
+
+		// Verify actual value matches what was passed in second simulation
+		expect(actual).toEqual({ foo: "baz", count: 100 });
+
+		// Verify expected value matches what was passed in first simulation
+		expect(expected).toEqual({ foo: "bar", count: 42 });
+	});
+});
+
+describe("expectDeterministic diff callback is not invoked when values match", () => {
+	// Use a global store that persists across test runs
+	const globalStore = globalThis as any;
+	if (!globalStore.__testCallback2) {
+		globalStore.__testCallback2 = {};
+	}
+
+	// Reset before this test suite
+	globalStore.__testCallback2 = { invoked: false };
+
+	const testSimulation: SimulationTestDef = {
+		name: "test-no-diff",
+		setup: async (lix) => lix,
+	};
+
+	simulationTest(
+		"",
+		async ({ expectDeterministic }) => {
+			const store = globalStore.__testCallback2;
+			const sameValue = { consistent: true, data: [1, 2, 3] };
+
+			expectDeterministic(sameValue, () => {
+				store.invoked = true;
+			}).toBeDefined();
+		},
+		{
+			simulations: [normalSimulation, testSimulation],
+		}
+	);
+
+	test("callback should not be invoked", () => {
+		expect(globalStore.__testCallback2.invoked).toBe(false);
+	});
+});
+
+describe("skip option filters out specified simulations", () => {
+	const globalStore = globalThis as any;
+	if (!globalStore.__skipTest) {
+		globalStore.__skipTest = {};
+	}
+
+	// Reset before this test suite
+	globalStore.__skipTest = {
+		normalRan: false,
+		cacheMissRan: false,
+		customRan: false,
+	};
+
+	const customSimulation: SimulationTestDef = {
+		name: "custom-for-skip-test",
+		setup: async (lix) => lix,
+	};
+
+	simulationTest(
+		"",
+		async ({ simulation }) => {
+			const store = globalStore.__skipTest;
+
+			// Track which simulations actually ran
+			if (simulation.name === "normal") {
+				store.normalRan = true;
+			} else if (simulation.name === "cache-miss") {
+				store.cacheMissRan = true;
+			} else if (simulation.name === "custom-for-skip-test") {
+				store.customRan = true;
+			}
+		},
+		{
+			simulations: [normalSimulation, customSimulation], // Skip cache-miss by not including it
+		}
+	);
+
+	test("should run normal simulation", () => {
+		expect(globalStore.__skipTest.normalRan).toBe(true);
+	});
+
+	test("should skip cache-miss simulation", () => {
+		expect(globalStore.__skipTest.cacheMissRan).toBe(false);
+	});
+
+	test("should run custom simulation (not affected by skip)", () => {
+		expect(globalStore.__skipTest.customRan).toBe(true);
+	});
+});
+
+describe("skip option combined with onlyRun", () => {
+	const globalStore = globalThis as any;
+	if (!globalStore.__skipOnlyRunTest) {
+		globalStore.__skipOnlyRunTest = {};
+	}
+
+	// Reset before this test suite
+	globalStore.__skipOnlyRunTest = {
+		normalRan: false,
+		cacheMissRan: false,
+	};
+
+	simulationTest(
+		"",
+		async ({ simulation }) => {
+			const store = globalStore.__skipOnlyRunTest;
+
+			// Track which simulations actually ran
+			if (simulation.name === "normal") {
+				store.normalRan = true;
+			} else if (simulation.name === "cache-miss") {
+				store.cacheMissRan = true;
+			}
+		},
+		{
+			simulations: [normalSimulation], // Only run normal (equivalent to including both but skipping cache-miss)
+		}
+	);
+
+	test("should run normal simulation (included and not skipped)", () => {
+		expect(globalStore.__skipOnlyRunTest.normalRan).toBe(true);
+	});
+
+	test("should skip cache-miss simulation (included but then skipped)", () => {
+		expect(globalStore.__skipOnlyRunTest.cacheMissRan).toBe(false);
+	});
+});

package/src/test-utilities/simulation-test/simulation-test.ts

@@ -0,0 +1,176 @@
+import { test, expect, type Assertion, vi } from "vitest";
+import { type Lix, openLix } from "../../lix/open-lix.js";
+import { cacheMissSimulation } from "./cache-miss-simulation.js";
+import { outOfOrderSequenceSimulation } from "./out-of-order-sequence-simulation.js";
+
+export type SimulationTestDef = {
+	name: string;
+	setup: (lix: Lix, baseline?: Lix) => Promise<Lix>;
+};
+
+/**
+ * Normal simulation - Standard test execution without any modifications.
+ */
+const normalSimulation: SimulationTestDef = {
+	name: "normal",
+	setup: async (lix) => lix,
+};
+
+/**
+ * Options for configuring simulation tests
+ */
+type SimulationTestOptions = {
+	/**
+	 * Array of simulations to run. If not specified, runs default simulations (normal, cache-miss).
+	 */
+	simulations?: SimulationTestDef[];
+};
+
+// Default simulations available
+export const defaultSimulations: SimulationTestDef[] = [
+	normalSimulation,
+	cacheMissSimulation,
+];
+
+// Export individual simulations for custom use
+export { normalSimulation, cacheMissSimulation, outOfOrderSequenceSimulation };
+
+/**
+ * Test utility that runs the same test in different simulations.
+ *
+ * @param name - Test name
+ * @param fn - Test function that receives simulation context
+ * @param options - Optional configuration:
+ *   - simulations: Array of simulations to run (defaults to normal + cache-miss)
+ *
+ * @example
+ * // Run default simulations (normal, cache-miss)
+ * simulationTest("my test", async ({ openSimulatedLix, expectDeterministic }) => {
+ *   const lix = await openSimulatedLix({});
+ *   // test code - expectDeterministic ensures values match across simulations
+ * });
+ *
+ * @example
+ * // Run only normal simulation
+ * simulationTest("my test", async ({ openSimulatedLix, expectDeterministic }) => {
+ *   const lix = await openSimulatedLix({});
+ *   // test code
+ * }, { simulations: [normalSimulation] });
+ *
+ * @example
+ * // Run custom simulations including out-of-order
+ * simulationTest("my test", async ({ openSimulatedLix, expectDeterministic }) => {
+ *   const lix = await openSimulatedLix({});
+ *   // test code - but be careful with expectDeterministic if using out-of-order!
+ * }, { simulations: [cacheMissSimulation, outOfOrderSequenceSimulation] });
+ */
+/**
+ * Enhanced expect function for simulation tests that verifies values are identical across simulations.
+ *
+ * @param actual - The value to test
+ * @param diffCallback - Optional callback that receives both actual and expected values when they differ.
+ *                       This is useful for debugging simulation differences by allowing you to inspect
+ *                       and log detailed differences between simulation results before the test fails.
+ *                       The callback is only invoked when values actually differ between simulations,
+ *                       allowing you to leave debugging code in place without cluttering output when
+ *                       tests are passing.
+ * @returns Standard expect assertion object
+ *
+ * @example
+ * expectDeterministic(cacheContents, ({ actual, expected }) => {
+ *   console.log(`Cache has ${actual.length} vs ${expected.length} entries`);
+ *   // Custom diff logic to help debug why simulations differ
+ * });
+ */
+interface ExpectDeterministic {
+	<T>(
+		actual: T,
+		diffCallback?: (args: { actual: T; expected: T }) => void
+	): Assertion<T>;
+}
+
+export function simulationTest(
+	name: string,
+	fn: (args: {
+		simulation: SimulationTestDef;
+		openSimulatedLix: typeof openLix;
+		expectDeterministic: ExpectDeterministic;
+	}) => Promise<void>,
+	options?: SimulationTestOptions
+): void {
+	// Use provided simulations or default ones
+	const simulationsToRun = options?.simulations || defaultSimulations;
+
+	const expectedValues = new Map<string, any>();
+
+	test.each(simulationsToRun)(`${name} > $name`, async (simulation) => {
+		let callIndex = 0;
+		const isFirstSimulation = simulation === simulationsToRun[0];
+
+		const deterministicExpect = (
+			actual: any,
+			diffCallback?: (args: { actual: any; expected: any }) => void
+		) => {
+			const key = `expect-${callIndex++}`;
+
+			if (isFirstSimulation) {
+				// Store expected values in first simulation
+				expectedValues.set(key, actual);
+			} else {
+				// Verify values match first simulation in subsequent simulations
+				const expected = expectedValues.get(key);
+				if (expected !== undefined) {
+					// Check if values differ before invoking callback
+					let valuesMatch = false;
+					try {
+						expect(actual).toEqual(expected);
+						valuesMatch = true;
+					} catch {
+						// Values don't match
+					}
+
+					// Only call diff callback if values actually differ
+					if (!valuesMatch && diffCallback) {
+						diffCallback({
+							actual,
+							expected,
+						});
+					}
+
+					// Always perform the assertion (will throw if values differ)
+					const errorMessage = `
+SIMULATION DETERMINISM VIOLATION
+
+expectDeterministic() failed: Values differ between simulations
+
+Location: Call #${callIndex - 1}
+Simulation: ${simulation.name} vs ${simulationsToRun[0]?.name || "normal"}
+
+Use expectDeterministic() for values that must be identical across simulations.
+Use regular expect() for simulation-specific assertions.
+
+`;
+					expect(actual, errorMessage).toEqual(expected);
+				}
+			}
+
+			return expect(actual);
+		};
+
+		// Create openSimulatedLix function
+		const openSimulatedLix = async (args: Parameters<typeof openLix>[0]) => {
+			// Open lix with the provided arguments
+			const lix = await openLix(args);
+
+			// Apply simulation setup
+			return await simulation.setup(lix);
+		};
+
+		await fn({
+			simulation: simulation,
+			openSimulatedLix,
+			expectDeterministic: deterministicExpect as ExpectDeterministic,
+		});
+		vi.resetAllMocks();
+	});
+}