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

package/src/file/store-detected-change-schema.ts

@@ -0,0 +1,52 @@
+import { executeSync } from "../database/execute-sync.js";
+import type { Lix } from "../lix/open-lix.js";
+import type { LixSchemaDefinition } from "../schema-definition/definition.js";
+
+export function storeDetectedChangeSchema(args: {
+	lix: Pick<Lix, "sqlite" | "db">;
+	schema: LixSchemaDefinition;
+	untracked?: boolean;
+}): void {
+	const schemaKey = args.schema["x-lix-key"];
+	const schemaVersion = args.schema["x-lix-version"];
+
+	// Check if schema already exists
+	const existingSchema = executeSync({
+		lix: args.lix,
+		query: args.lix.db
+			.selectFrom("stored_schema")
+			.where("key", "=", schemaKey)
+			.where("version", "=", schemaVersion)
+			.select(["key", "version", "value"])
+			.limit(1),
+	})[0];
+
+	if (existingSchema) {
+		// Compare schemas using JSON.stringify for strict determinism
+		// Handle case where stored value might already be stringified
+		const existingSchemaJson =
+			typeof existingSchema.value === "string"
+				? existingSchema.value
+				: JSON.stringify(existingSchema.value);
+		const newSchemaJson = JSON.stringify(args.schema);
+
+		if (existingSchemaJson !== newSchemaJson) {
+			throw new Error(
+				`Schema differs from stored version for key '${schemaKey}' version '${schemaVersion}'. ` +
+					`Please bump the schema version (x-lix-version) to use a different schema.`
+			);
+		}
+		// Schemas match, continue
+	} else {
+		// Store new schema
+		executeSync({
+			lix: args.lix,
+			query: args.lix.db.insertInto("stored_schema").values({
+				key: schemaKey,
+				version: schemaVersion,
+				value: args.schema as any,
+				lixcol_untracked: args.untracked || false,
+			}),
+		});
+	}
+}

package/src/file/unknown-file-fallback-plugin.test.ts

@@ -0,0 +1,368 @@
+import { describe, it, expect } from "vitest";
+import {
+	lixUnknownFileFallbackPlugin,
+	LixUnknownFileSchema,
+} from "./unknown-file-fallback-plugin.js";
+
+// From https://developer.mozilla.org/en-US/docs/Glossary/Base64#the_unicode_problem.
+function bytesToBase64(bytes: Uint8Array): string {
+	const binString = String.fromCodePoint(...bytes);
+	return btoa(binString);
+}
+
+const createTestFile = (id: string, data: string) => ({
+	id,
+	path: `/test/${id}.unknown`,
+	data: new TextEncoder().encode(data),
+	version_id: "test-version",
+	metadata: null,
+});
+
+describe("detectChanges", () => {
+	it("should detect changes when file data is different", () => {
+		const before = createTestFile("file1", "original content");
+		const after = createTestFile("file1", "updated content");
+
+		const changes = lixUnknownFileFallbackPlugin.detectChanges!({
+			before,
+			after,
+		});
+
+		expect(changes).toHaveLength(1);
+		expect(changes[0]).toMatchObject({
+			schema: LixUnknownFileSchema,
+			entity_id: "file1",
+			snapshot_content: {
+				value: bytesToBase64(new TextEncoder().encode("updated content")),
+			},
+		});
+	});
+
+	it("should not detect changes when file data is identical", () => {
+		const before = createTestFile("file1", "same content");
+		const after = createTestFile("file1", "same content");
+
+		const changes = lixUnknownFileFallbackPlugin.detectChanges!({
+			before,
+			after,
+		});
+
+		expect(changes).toHaveLength(0);
+	});
+
+	it("should detect changes when before file is undefined (new file)", () => {
+		const after = createTestFile("file1", "new file content");
+
+		const changes = lixUnknownFileFallbackPlugin.detectChanges!({
+			after,
+		});
+
+		expect(changes).toHaveLength(1);
+		expect(changes[0]).toMatchObject({
+			schema: LixUnknownFileSchema,
+			entity_id: "file1",
+			snapshot_content: {
+				value: bytesToBase64(new TextEncoder().encode("new file content")),
+			},
+		});
+	});
+
+	it("should detect changes when before file has no data", () => {
+		const before = { ...createTestFile("file1", ""), data: undefined as any };
+		const after = createTestFile("file1", "new content");
+
+		const changes = lixUnknownFileFallbackPlugin.detectChanges!({
+			before,
+			after,
+		});
+
+		expect(changes).toHaveLength(1);
+		expect(changes[0]).toMatchObject({
+			entity_id: "file1",
+			snapshot_content: {
+				value: bytesToBase64(new TextEncoder().encode("new content")),
+			},
+		});
+	});
+
+	it("should handle binary data correctly", () => {
+		const binaryData1 = new Uint8Array([0, 1, 2, 3, 255]);
+		const binaryData2 = new Uint8Array([0, 1, 2, 4, 255]);
+
+		const before = { ...createTestFile("file1", ""), data: binaryData1 };
+		const after = { ...createTestFile("file1", ""), data: binaryData2 };
+
+		const changes = lixUnknownFileFallbackPlugin.detectChanges!({
+			before,
+			after,
+		});
+
+		expect(changes).toHaveLength(1);
+		expect(changes[0]?.snapshot_content.value).toEqual(
+			bytesToBase64(binaryData2)
+		);
+	});
+
+	it("should handle empty files", () => {
+		const before = createTestFile("file1", "some content");
+		const after = createTestFile("file1", "");
+
+		const changes = lixUnknownFileFallbackPlugin.detectChanges!({
+			before,
+			after,
+		});
+
+		expect(changes).toHaveLength(1);
+		expect(changes[0]?.snapshot_content.value).toEqual(
+			bytesToBase64(new Uint8Array([]))
+		);
+	});
+
+	it("should handle Unicode content correctly", () => {
+		// Sample string from web.dev article with various Unicode code points
+		const unicodeContent = "hello⛳❤️🧀";
+		const before = createTestFile("file1", "simple ascii");
+		const after = createTestFile("file1", unicodeContent);
+
+		const changes = lixUnknownFileFallbackPlugin.detectChanges!({
+			before,
+			after,
+		});
+
+		expect(changes).toHaveLength(1);
+		expect(changes[0]).toMatchObject({
+			schema: LixUnknownFileSchema,
+			entity_id: "file1",
+			snapshot_content: {
+				value: bytesToBase64(new TextEncoder().encode(unicodeContent)),
+			},
+		});
+
+		// Verify the content can be round-tripped correctly
+		const testChanges = [
+			{
+				id: "test-id",
+				entity_id: "test-file",
+				schema_key: "lix_unknown_file",
+				file_id: "test-file",
+				plugin_key: "lix_unknown_file_fallback_plugin",
+				created_at: "2023-01-01T00:00:00Z",
+				snapshot_content: changes[0]?.snapshot_content,
+				version_id: "test-version",
+			},
+		] as any;
+
+		const result = lixUnknownFileFallbackPlugin.applyChanges!({
+			file: createTestFile("test-file", ""),
+			changes: testChanges,
+		});
+
+		// Decode the result back to string to verify Unicode preservation
+		const decodedContent = new TextDecoder().decode(result.fileData);
+		expect(decodedContent).toBe(unicodeContent);
+	});
+});
+
+describe("applyChanges", () => {
+	it("should restore file data from blob change", () => {
+		const originalData = "test file content";
+		const changes = [
+			{
+				id: "test-id",
+				entity_id: "test-file",
+				schema_key: "lix_unknown_file",
+				file_id: "test-file",
+				plugin_key: "lix_unknown_file_fallback_plugin",
+				created_at: "2023-01-01T00:00:00Z",
+				snapshot_content: {
+					value: bytesToBase64(new TextEncoder().encode(originalData)),
+				},
+				version_id: "test-version",
+			},
+		] as any;
+
+		const result = lixUnknownFileFallbackPlugin.applyChanges!({
+			file: createTestFile("test-file", ""),
+			changes,
+		});
+
+		expect(result.fileData).toEqual(new TextEncoder().encode(originalData));
+	});
+
+	it("should handle binary data restoration", () => {
+		const binaryData = new Uint8Array([0, 1, 2, 3, 255, 128, 64]);
+		const changes = [
+			{
+				id: "test-id",
+				entity_id: "binary-file",
+				schema_key: "lix_unknown_file",
+				file_id: "binary-file",
+				plugin_key: "lix_unknown_file_fallback_plugin",
+				created_at: "2023-01-01T00:00:00Z",
+				snapshot_content: { value: bytesToBase64(binaryData) },
+				version_id: "test-version",
+			},
+		] as any;
+
+		const result = lixUnknownFileFallbackPlugin.applyChanges!({
+			file: createTestFile("binary-file", ""),
+			changes,
+		});
+
+		expect(result.fileData).toEqual(binaryData);
+	});
+
+	// The plugin should throw when no changes are provided because we snapshot
+	// the entire file, so there must always be exactly one change per file
+	it("should throw when no changes are provided", () => {
+		expect(() => {
+			lixUnknownFileFallbackPlugin.applyChanges!({
+				file: createTestFile("test-file", ""),
+				changes: [],
+			});
+		}).toThrow(
+			"Expected exactly one change for file test-file, but received no changes"
+		);
+	});
+
+	// The plugin should throw when the change doesn't match the file ID because
+	// entity_id should always equal the file ID for this plugin
+	it("should throw when change entity_id doesn't match file ID", () => {
+		const changes = [
+			{
+				id: "test-id",
+				entity_id: "different-file-id",
+				schema_key: "lix_unknown_file",
+				file_id: "test-file",
+				plugin_key: "lix_unknown_file_fallback_plugin",
+				created_at: "2023-01-01T00:00:00Z",
+				snapshot_content: {
+					value: "some content",
+				},
+				version_id: "test-version",
+			},
+		] as any;
+
+		expect(() => {
+			lixUnknownFileFallbackPlugin.applyChanges!({
+				file: createTestFile("test-file", ""),
+				changes,
+			});
+		}).toThrow(
+			"Expected change for file test-file, but received change for entity different-file-id"
+		);
+	});
+
+	it("should handle valid base64 content", () => {
+		// Since we now always expect base64 strings, any valid base64 string should work
+		const changes = [
+			{
+				id: "test-id",
+				entity_id: "test-file",
+				schema_key: "lix_unknown_file",
+				file_id: "test-file",
+				plugin_key: "lix_unknown_file_fallback_plugin",
+				created_at: "2023-01-01T00:00:00Z",
+				snapshot_content: {
+					value: "",
+				},
+				version_id: "test-version",
+			},
+		] as any;
+
+		const result = lixUnknownFileFallbackPlugin.applyChanges!({
+			file: createTestFile("test-file", ""),
+			changes,
+		});
+
+		expect(result.fileData).toEqual(new Uint8Array());
+	});
+
+	// The plugin should throw when receiving more than one change because
+	// we snapshot the entire file as a single blob, not multiple pieces
+	it("should throw when receiving more than one change", () => {
+		const changes = [
+			{
+				id: "test-id-1",
+				entity_id: "test-file",
+				schema_key: "lix_unknown_file",
+				file_id: "test-file",
+				plugin_key: "lix_unknown_file_fallback_plugin",
+				snapshot_id: "test-snapshot-1",
+				created_at: "2023-01-01T00:00:00Z",
+				snapshot_content: {
+					value: bytesToBase64(new TextEncoder().encode("content1")),
+				},
+				version_id: "test-version",
+			},
+			{
+				id: "test-id-2",
+				entity_id: "test-file",
+				schema_key: "lix_unknown_file",
+				file_id: "test-file",
+				plugin_key: "lix_unknown_file_fallback_plugin",
+				snapshot_id: "test-snapshot-2",
+				created_at: "2023-01-01T00:00:00Z",
+				snapshot_content: {
+					value: bytesToBase64(new TextEncoder().encode("content2")),
+				},
+				version_id: "test-version",
+			},
+		] as any;
+
+		expect(() => {
+			lixUnknownFileFallbackPlugin.applyChanges!({
+				file: createTestFile("test-file", ""),
+				changes,
+			});
+		}).toThrow(
+			"Expected exactly one change for file test-file, but received 2 changes"
+		);
+	});
+
+	// The plugin should throw when snapshot_content is not a string because
+	// we always store file data as base64-encoded strings
+	it("should throw when snapshot_content is not a string", () => {
+		const changes = [
+			{
+				id: "test-id",
+				entity_id: "test-file",
+				schema_key: "lix_unknown_file",
+				file_id: "test-file",
+				plugin_key: "lix_unknown_file_fallback_plugin",
+				created_at: "2023-01-01T00:00:00Z",
+				snapshot_content: { value: { not: "a string" } },
+				version_id: "test-version",
+			},
+		] as any;
+
+		expect(() => {
+			lixUnknownFileFallbackPlugin.applyChanges!({
+				file: createTestFile("test-file", ""),
+				changes,
+			});
+		}).toThrow(
+			"Expected base64 string content for file test-file, but received object"
+		);
+	});
+});
+
+describe("plugin configuration", () => {
+	it("should have correct key", () => {
+		expect(lixUnknownFileFallbackPlugin.key).toBe(
+			"lix_unknown_file_fallback_plugin"
+		);
+	});
+
+	it("should have glob pattern that matches all files", () => {
+		expect(lixUnknownFileFallbackPlugin.detectChangesGlob).toBe("*");
+	});
+
+	it("should have detectChanges function", () => {
+		expect(typeof lixUnknownFileFallbackPlugin.detectChanges).toBe("function");
+	});
+
+	it("should have applyChanges function", () => {
+		expect(typeof lixUnknownFileFallbackPlugin.applyChanges).toBe("function");
+	});
+});

package/src/file/unknown-file-fallback-plugin.ts

@@ -0,0 +1,95 @@
+import type { LixSchemaDefinition } from "../schema-definition/definition.js";
+import type { DetectedChange, LixPlugin } from "../plugin/lix-plugin.js";
+
+export const LixUnknownFileSchema = {
+	type: "object",
+	properties: {
+		value: {
+			type: "string",
+			contentEncoding: "base64",
+			description: "Base64-encoded binary file data",
+		},
+	},
+	"x-lix-key": "lix_unknown_file",
+	"x-lix-version": "1.0",
+} as const;
+LixUnknownFileSchema satisfies LixSchemaDefinition;
+
+// From https://developer.mozilla.org/en-US/docs/Glossary/Base64#the_unicode_problem.
+function base64ToBytes(base64: string): Uint8Array {
+	const binString = atob(base64);
+	return Uint8Array.from(binString, (m) => m.codePointAt(0)!);
+}
+
+// From https://developer.mozilla.org/en-US/docs/Glossary/Base64#the_unicode_problem.
+function bytesToBase64(bytes: Uint8Array): string {
+	const binString = String.fromCodePoint(...bytes);
+	return btoa(binString);
+}
+
+/**
+ * Internal fallback plugin that handles unknown file types by storing the entire blob.
+ * This serves as a fallback for materialization when no specific plugin matches a file.
+ *
+ * This plugin always matches any file path and stores the complete file data
+ * as a single entity, allowing retrieval of the original file content.
+ */
+export const lixUnknownFileFallbackPlugin: LixPlugin = {
+	key: "lix_unknown_file_fallback_plugin",
+	detectChangesGlob: "*", // Matches all files
+	detectChanges: ({ before, after }) => {
+		const detectedChanges: DetectedChange<any>[] = [];
+
+		// Compare the raw file data using Unicode-safe base64 encoding
+		const beforeData = before?.data;
+		const afterData = after.data;
+
+		const beforeBase64 = beforeData ? bytesToBase64(beforeData) : "";
+		const afterBase64 = afterData ? bytesToBase64(afterData) : "";
+
+		if (beforeBase64 !== afterBase64) {
+			detectedChanges.push({
+				schema: LixUnknownFileSchema,
+				entity_id: after.id,
+				snapshot_content: { value: afterBase64 }, // Store as Unicode-safe base64 string
+			});
+		}
+
+		return detectedChanges;
+	},
+	applyChanges: ({ file, changes }) => {
+		// This plugin snapshots the entire file, so there should only be one change
+		if (changes.length > 1) {
+			throw new Error(
+				`[lix_unknown_file_fallback_plugin] Expected exactly one change for file ${file.id}, but received ${changes.length} changes`
+			);
+		}
+
+		// There must be exactly one change for this file
+		if (changes.length === 0) {
+			throw new Error(
+				`[lix_unknown_file_fallback_plugin] Expected exactly one change for file ${file.id}, but received no changes`
+			);
+		}
+
+		const fileChange = changes[0]!; // Safe since we validated length > 0
+
+		// The change must match this file's ID
+		if (fileChange.entity_id !== file.id) {
+			throw new Error(
+				`[lix_unknown_file_fallback_plugin] Expected change for file ${file.id}, but received change for entity ${fileChange.entity_id}`
+			);
+		}
+
+		if (typeof fileChange.snapshot_content?.value === "string") {
+			// Restore the blob from Unicode-safe base64 string
+			return {
+				fileData: base64ToBytes(fileChange.snapshot_content.value),
+			};
+		}
+
+		throw new Error(
+			`[lix_unknown_file_fallback_plugin] Expected base64 string content for file ${file.id}, but received ${typeof fileChange.snapshot_content}`
+		);
+	},
+};

package/src/hooks/create-hooks.test.ts

@@ -0,0 +1,125 @@
+import { expect, test, vi } from "vitest";
+import { createHooks } from "./create-hooks.js";
+
+test("should create hooks with onStateCommit method", () => {
+	const hooks = createHooks();
+
+	expect(hooks.onStateCommit).toBeDefined();
+	expect(typeof hooks.onStateCommit).toBe("function");
+	expect(hooks._emit).toBeDefined();
+	expect(typeof hooks._emit).toBe("function");
+});
+
+test("should call handler when state_commit event is emitted", () => {
+	const hooks = createHooks();
+	const handler = vi.fn();
+
+	hooks.onStateCommit(handler);
+	hooks._emit("state_commit");
+
+	expect(handler).toHaveBeenCalledTimes(1);
+});
+
+test("should call multiple handlers when state_commit event is emitted", () => {
+	const hooks = createHooks();
+	const handler1 = vi.fn();
+	const handler2 = vi.fn();
+
+	hooks.onStateCommit(handler1);
+	hooks.onStateCommit(handler2);
+	hooks._emit("state_commit");
+
+	expect(handler1).toHaveBeenCalledTimes(1);
+	expect(handler2).toHaveBeenCalledTimes(1);
+});
+
+test("should return unsubscribe function that removes the handler", () => {
+	const hooks = createHooks();
+	const handler = vi.fn();
+
+	const unsubscribe = hooks.onStateCommit(handler);
+
+	// Emit event - handler should be called
+	hooks._emit("state_commit");
+	expect(handler).toHaveBeenCalledTimes(1);
+
+	// Unsubscribe and emit again - handler should not be called
+	unsubscribe();
+	hooks._emit("state_commit");
+	expect(handler).toHaveBeenCalledTimes(1);
+});
+
+test("should handle multiple subscriptions and unsubscriptions correctly", () => {
+	const hooks = createHooks();
+	const handler1 = vi.fn();
+	const handler2 = vi.fn();
+	const handler3 = vi.fn();
+
+	const unsubscribe1 = hooks.onStateCommit(handler1);
+	const unsubscribe2 = hooks.onStateCommit(handler2);
+	const unsubscribe3 = hooks.onStateCommit(handler3);
+
+	// All handlers should be called
+	hooks._emit("state_commit");
+	expect(handler1).toHaveBeenCalledTimes(1);
+	expect(handler2).toHaveBeenCalledTimes(1);
+	expect(handler3).toHaveBeenCalledTimes(1);
+
+	// Remove handler2
+	unsubscribe2();
+	hooks._emit("state_commit");
+	expect(handler1).toHaveBeenCalledTimes(2);
+	expect(handler2).toHaveBeenCalledTimes(1); // Still 1
+	expect(handler3).toHaveBeenCalledTimes(2);
+
+	// Remove handler1 and handler3
+	unsubscribe1();
+	unsubscribe3();
+	hooks._emit("state_commit");
+	expect(handler1).toHaveBeenCalledTimes(2); // Still 2
+	expect(handler2).toHaveBeenCalledTimes(1); // Still 1
+	expect(handler3).toHaveBeenCalledTimes(2); // Still 2
+});
+
+test("should not call handlers for different event types", () => {
+	const hooks = createHooks();
+	const handler = vi.fn();
+
+	hooks.onStateCommit(handler);
+	hooks._emit("other_event");
+
+	expect(handler).not.toHaveBeenCalled();
+});
+
+test("should handle async handlers without issues", async () => {
+	const hooks = createHooks();
+	const handler = vi.fn().mockResolvedValue(undefined);
+
+	hooks.onStateCommit(handler);
+	hooks._emit("state_commit");
+
+	// Wait a bit to ensure async handler has time to run
+	await new Promise((resolve) => setTimeout(resolve, 0));
+
+	expect(handler).toHaveBeenCalledTimes(1);
+});
+
+test("should create independent hook instances", () => {
+	const hooks1 = createHooks();
+	const hooks2 = createHooks();
+	const handler1 = vi.fn();
+	const handler2 = vi.fn();
+
+	hooks1.onStateCommit(handler1);
+	hooks2.onStateCommit(handler2);
+
+	// Emit on hooks1 - only handler1 should be called
+	hooks1._emit("state_commit");
+	expect(handler1).toHaveBeenCalledTimes(1);
+	expect(handler2).not.toHaveBeenCalled();
+
+	// Emit on hooks2 - only handler2 should be called
+	hooks2._emit("state_commit");
+	expect(handler1).toHaveBeenCalledTimes(1);
+	expect(handler2).toHaveBeenCalledTimes(1);
+});

package/src/hooks/create-hooks.ts

@@ -0,0 +1,68 @@
+import type { Change } from "../change/index.js";
+
+/**
+ * Lix hooks system for listening to database lifecycle events.
+ *
+ * Hooks allow you to register callbacks that fire at specific points
+ * in Lix's execution, such as when state changes are committed.
+ */
+export type LixHooks = {
+	/**
+	 * Listen to state commit events.
+	 *
+	 * Fires after any state mutation is committed to the database.
+	 * Useful for auto-saving, cache invalidation, sync operations, etc.
+	 *
+	 * @param handler - Function to call when state is committed
+	 * @returns Unsubscribe function to remove the listener
+	 *
+	 * @example
+	 * ```typescript
+	 * const unsubscribe = lix.hooks.onStateCommit(() => {
+	 *   console.log('State was committed!');
+	 *   storage.save();
+	 * });
+	 *
+	 * // Later, remove the listener
+	 * unsubscribe();
+	 * ```
+	 */
+	onStateCommit: (handler: (data: { changes: Change[] }) => void) => () => void;
+
+	/**
+	 * Internal method for emitting events.
+	 *
+	 * @internal
+	 * This method is for internal use only and should not be called directly.
+	 * Use this to emit events from state mutation functions.
+	 */
+	_emit: (eventType: string, data?: any) => void;
+};
+
+/**
+ * Creates a new hooks system for a Lix instance.
+ *
+ * Uses the native EventTarget API under the hood for efficient
+ * event handling and automatic memory management.
+ *
+ * @returns LixHooks instance with event subscription methods
+ */
+export function createHooks(): LixHooks {
+	const eventTarget = new EventTarget();
+
+	return {
+		onStateCommit(handler: (data: { changes: Change[] }) => void): () => void {
+			const wrappedHandler = (event: Event) => {
+				const customEvent = event as CustomEvent;
+				handler(customEvent.detail);
+			};
+			eventTarget.addEventListener("state_commit", wrappedHandler);
+			return () =>
+				eventTarget.removeEventListener("state_commit", wrappedHandler);
+		},
+
+		_emit(eventType: string, data?: any): void {
+			eventTarget.dispatchEvent(new CustomEvent(eventType, { detail: data }));
+		},
+	};
+}