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

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

@@ -1,404 +0,0 @@
-import { describe, expect, test } from "vitest";
-import {
-	simulationTest,
-	type SimulationTestDef,
-	normalSimulation,
-} from "./simulation-test.js";
-import { commit } from "../../state/vtable/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_by_version")
-				.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 },
-						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 { rows: tableRows } = lix.engine!.executeSync({
-				sql: `SELECT name FROM sqlite_master 
-				WHERE type IN ('table', 'view') 
-				AND name NOT LIKE 'sqlite_%'
-				ORDER BY name`,
-				parameters: [],
-			});
-			const tablesAndViews = tableRows.map((row: Record<string, unknown>) =>
-				String(row.name)
-			);
-
-			// Query each table/view and check determinism
-			for (const tableName of tablesAndViews) {
-				const { rows } = lix.engine!.executeSync({
-					sql: `SELECT * FROM "${tableName}"`,
-					parameters: [],
-				});
-
-				try {
-					expectDeterministic(rows).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({ engine: lix.engine! });
-
-			const logLevels = await lix.db
-				.selectFrom("key_value")
-				.where("key", "=", "test_key_1")
-				.selectAll()
-				.execute();
-
-			expect(logLevels).toMatchObject([
-				{
-					key: "test_key_1",
-					value: ["*"],
-				},
-			]);
-		},
-		{ simulations: [normalSimulation] }
-	);
-});
-
-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

@@ -1,194 +0,0 @@
-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";
-import { engineBoundarySimulation } from "./engine-boundary-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, engine-boundary).
-	 */
-	simulations?: SimulationTestDef[];
-	/**
-	 * Optional timeout passed to each generated Vitest test case.
-	 */
-	timeout?: number;
-};
-
-// Default simulations available
-export const defaultSimulations: SimulationTestDef[] = [
-	normalSimulation,
-	// disabledQueryPreprocessorSimulation,
-	cacheMissSimulation,
-	engineBoundarySimulation,
-];
-
-// Export individual simulations for custom use
-export {
-	engineBoundarySimulation,
-	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) => {
-			vi.restoreAllMocks();
-
-			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.restoreAllMocks(); // Restore original implementations, not just reset
-		},
-		options?.timeout
-	);
-}

package/src/types/fs.d.ts

@@ -1,11 +0,0 @@
-declare module "fs" {
-	export const promises: {
-		writeFile(path: string, data: string, encoding?: string): Promise<void>;
-		mkdir(
-			path: string,
-			options?: {
-				recursive?: boolean;
-			}
-		): Promise<void>;
-	};
-}