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

package/src/observe/create-observe.ts

@@ -0,0 +1,146 @@
+import type { SelectQueryBuilder } from "kysely";
+import type { Lix } from "../lix/open-lix.js";
+import { LixObservable } from "./lix-observable.js";
+
+/**
+ * Options for the observe method.
+ */
+export interface ObserveOptions {
+	mode?: "array" | "first" | "firstOrThrow";
+}
+
+/**
+ * Map to track active observables and their cleanup functions.
+ */
+interface ActiveObservable {
+	unsubscribeFromStateCommit: () => void;
+}
+
+/**
+ * Deep equality check for query results.
+ * Compares arrays element by element using JSON.stringify for simplicity.
+ */
+function areResultsEqual<T>(a: T[], b: T[]): boolean {
+	if (a.length !== b.length) return false;
+
+	// Simple deep equality using JSON.stringify
+	// This works well for database results which are typically JSON-serializable
+	return JSON.stringify(a) === JSON.stringify(b);
+}
+
+/**
+ * Creates the observe function for a Lix instance.
+ *
+ * @param lix - The Lix instance to add observables to
+ * @returns The observe function
+ */
+export function createObserve(lix: Pick<Lix, "hooks">) {
+	const activeObservables = new WeakMap<LixObservable<any>, ActiveObservable>();
+
+	/**
+	 * Converts a **Kysely read-query** into a **LixObservable** – an implementation of
+	 * the TC-39 Observable protocol that emits a fresh result-set every time the
+	 * underlying state mutates.
+	 *
+	 * @example **Full table stream**
+	 * ```ts
+	 * observe(
+	 *   lix.db.selectFrom('key_value').selectAll()
+	 * ).subscribe({
+	 *   next: rows => console.table(rows)
+	 * })
+	 * ```
+	 *
+	 * @example **Watch latest change-set (first row)**
+	 * ```ts
+	 * observe(
+	 *   lix.db.selectFrom('change_set_all')
+	 *         .selectAll()
+	 *         .orderBy('created_at desc')
+	 * ).subscribeTakeFirst({
+	 *   next: cs => console.log('head →', cs)
+	 * })
+	 * ```
+	 */
+	return function observe<T>(
+		query: SelectQueryBuilder<any, any, T>,
+		options: ObserveOptions = { mode: "array" }
+	): LixObservable<T> {
+		// Create the observable
+		const observable = new LixObservable<T>((observer) => {
+			let isActive = true;
+			let previousResult: T[] | undefined;
+
+			// Helper to execute the query
+			const executeQuery = async () => {
+				if (!isActive) return;
+
+				try {
+					// Optimize query for first/firstOrThrow modes
+					let optimizedQuery = query;
+					if (options.mode === "first" || options.mode === "firstOrThrow") {
+						// Add limit(1) if we only need the first row
+						optimizedQuery = query.limit(1) as any;
+					}
+
+					// Execute the query
+					const result = await optimizedQuery.execute();
+
+					if (!isActive) return;
+
+					// Check if results have changed
+					const hasChanged =
+						!previousResult || !areResultsEqual(previousResult, result as T[]);
+
+					if (hasChanged) {
+						previousResult = result as T[];
+
+						// Handle different modes
+						if (options.mode === "first") {
+							observer.next?.(result as T[]);
+						} else if (options.mode === "firstOrThrow") {
+							observer.next?.(result as T[]);
+						} else {
+							// Default: array mode
+							observer.next?.(result as T[]);
+						}
+					}
+				} catch (error) {
+					if (!isActive) return;
+					observer.error?.(error);
+				}
+			};
+
+			// Execute initial query
+			executeQuery();
+
+			// Subscribe to state commits for updates
+			const unsubscribeFromStateCommit = lix.hooks.onStateCommit(() => {
+				executeQuery();
+			});
+
+			// Store the cleanup function
+			activeObservables.set(observable, { unsubscribeFromStateCommit });
+
+			// Return cleanup function
+			return () => {
+				isActive = false;
+				unsubscribeFromStateCommit();
+				activeObservables.delete(observable);
+			};
+		});
+
+		// Handle mode-specific behavior by returning wrapped observables
+		if (options.mode === "first") {
+			// For compatibility, we still return the base observable
+			// The subscribeTakeFirst method handles the transformation
+			return observable;
+		} else if (options.mode === "firstOrThrow") {
+			// For compatibility, we still return the base observable
+			// The subscribeTakeFirstOrThrow method handles the transformation
+			return observable;
+		}
+
+		return observable;
+	};
+}

package/src/observe/index.ts

@@ -0,0 +1 @@
+export { LixObservable } from "./lix-observable.js";

package/src/observe/lix-observable.test.ts

@@ -0,0 +1,247 @@
+import { test, expect, vi } from "vitest";
+import { LixObservable } from "./lix-observable.js";
+
+test("should deliver values to observer", () => {
+	const values: number[][] = [];
+	const observable = new LixObservable<number>((observer) => {
+		observer.next?.([1, 2, 3]);
+		observer.next?.([4, 5, 6]);
+	});
+
+	observable.subscribe({
+		next: (value) => values.push(value),
+	});
+
+	expect(values).toEqual([
+		[1, 2, 3],
+		[4, 5, 6],
+	]);
+});
+
+test("should call error handler", () => {
+	const error = new Error("Test error");
+	const errorHandler = vi.fn();
+
+	const observable = new LixObservable<number>((observer) => {
+		observer.error?.(error);
+	});
+
+	observable.subscribe({
+		error: errorHandler,
+	});
+
+	expect(errorHandler).toHaveBeenCalledWith(error);
+});
+
+test("should call complete handler", () => {
+	const completeHandler = vi.fn();
+
+	const observable = new LixObservable<number>((observer) => {
+		observer.complete?.();
+	});
+
+	observable.subscribe({
+		complete: completeHandler,
+	});
+
+	expect(completeHandler).toHaveBeenCalled();
+});
+
+test("should stop delivering values after unsubscribe", () => {
+	const values: number[][] = [];
+	let observerRef: any;
+
+	const observable = new LixObservable<number>((observer) => {
+		observerRef = observer;
+		observer.next?.([1]);
+		return () => {
+			// cleanup
+		};
+	});
+
+	const subscription = observable.subscribe({
+		next: (value) => values.push(value),
+	});
+
+	expect(values).toEqual([[1]]);
+
+	subscription.unsubscribe();
+	observerRef.next?.([2]); // Should not be delivered
+
+	expect(values).toEqual([[1]]);
+});
+
+test("should not deliver values after error", () => {
+	const values: number[][] = [];
+	const errors: any[] = [];
+	let observerRef: any;
+
+	const observable = new LixObservable<number>((observer) => {
+		observerRef = observer;
+	});
+
+	observable.subscribe({
+		next: (value) => values.push(value),
+		error: (err) => errors.push(err),
+	});
+
+	observerRef.next?.([1]);
+	observerRef.error?.(new Error("Test"));
+	observerRef.next?.([2]); // Should not be delivered
+
+	expect(values).toEqual([[1]]);
+	expect(errors).toHaveLength(1);
+});
+
+test("should not deliver values after complete", () => {
+	const values: number[][] = [];
+	let observerRef: any;
+
+	const observable = new LixObservable<number>((observer) => {
+		observerRef = observer;
+	});
+
+	observable.subscribe({
+		next: (value) => values.push(value),
+	});
+
+	observerRef.next?.([1]);
+	observerRef.complete?.();
+	observerRef.next?.([2]); // Should not be delivered
+
+	expect(values).toEqual([[1]]);
+});
+
+test("should call cleanup function on unsubscribe", () => {
+	const cleanup = vi.fn();
+
+	const observable = new LixObservable<number>(() => {
+		return cleanup;
+	});
+
+	const subscription = observable.subscribe({});
+	expect(cleanup).not.toHaveBeenCalled();
+
+	subscription.unsubscribe();
+	expect(cleanup).toHaveBeenCalledOnce();
+});
+
+test("should not call cleanup multiple times", () => {
+	const cleanup = vi.fn();
+
+	const observable = new LixObservable<number>(() => {
+		return cleanup;
+	});
+
+	const subscription = observable.subscribe({});
+	subscription.unsubscribe();
+	subscription.unsubscribe(); // Second call
+
+	expect(cleanup).toHaveBeenCalledOnce();
+});
+
+test("should implement Symbol.observable", () => {
+	const observable = new LixObservable<number>(() => {});
+	expect(observable[Symbol.observable]()).toBe(observable);
+});
+
+test("subscribeTakeFirst should return first element", () => {
+	const values: (number | undefined)[] = [];
+
+	const observable = new LixObservable<number>((observer) => {
+		observer.next?.([1, 2, 3]);
+		observer.next?.([4, 5, 6]);
+	});
+
+	observable.subscribeTakeFirst({
+		next: (value) => values.push(value),
+	});
+
+	expect(values).toEqual([1, 4]);
+});
+
+test("subscribeTakeFirst should return undefined for empty array", () => {
+	const values: (number | undefined)[] = [];
+
+	const observable = new LixObservable<number>((observer) => {
+		observer.next?.([]);
+	});
+
+	observable.subscribeTakeFirst({
+		next: (value) => values.push(value),
+	});
+
+	expect(values).toEqual([undefined]);
+});
+
+test("subscribeTakeFirstOrThrow should return first element", () => {
+	const values: number[] = [];
+
+	const observable = new LixObservable<number>((observer) => {
+		observer.next?.([1, 2, 3]);
+	});
+
+	observable.subscribeTakeFirstOrThrow({
+		next: (value) => values.push(value),
+	});
+
+	expect(values).toEqual([1]);
+});
+
+test("subscribeTakeFirstOrThrow should error on empty array", () => {
+	const errors: any[] = [];
+
+	const observable = new LixObservable<number>((observer) => {
+		observer.next?.([]);
+	});
+
+	observable.subscribeTakeFirstOrThrow({
+		error: (err) => errors.push(err),
+	});
+
+	expect(errors).toHaveLength(1);
+	expect(errors[0]).toBeInstanceOf(Error);
+	expect(errors[0].message).toBe("Query returned no rows");
+});
+
+test("subscribeTakeFirstOrThrow should pass through original errors", () => {
+	const originalError = new Error("Original error");
+	const errors: any[] = [];
+
+	const observable = new LixObservable<number>((observer) => {
+		observer.error?.(originalError);
+	});
+
+	observable.subscribeTakeFirstOrThrow({
+		error: (err) => errors.push(err),
+	});
+
+	expect(errors).toEqual([originalError]);
+});
+
+test("should handle observer without handlers gracefully", () => {
+	const observable = new LixObservable<number>((observer) => {
+		observer.next?.([1]);
+		observer.error?.(new Error("Test"));
+		observer.complete?.();
+	});
+
+	// Should not throw
+	expect(() => {
+		observable.subscribe({});
+	}).not.toThrow();
+});
+
+test("should support RxJS interop pattern", () => {
+	const observable = new LixObservable<number>(() => {});
+
+	// Simulate RxJS from() behavior
+	const rxjsCompatible = observable[Symbol.observable]();
+	expect(rxjsCompatible).toBe(observable);
+
+	// Should be able to subscribe to the returned value
+	const values: number[][] = [];
+	rxjsCompatible.subscribe({
+		next: (value) => values.push(value),
+	});
+});

package/src/observe/lix-observable.ts

@@ -0,0 +1,92 @@
+/**
+ * Micro-observable implementation following TC-39 Observable protocol.
+ * ~25 lines of code for minimal footprint while maintaining spec compliance.
+ */
+
+// Polyfill Symbol.observable if not present
+declare global {
+	interface SymbolConstructor {
+		readonly observable: symbol;
+	}
+}
+
+if (typeof Symbol.observable === "undefined") {
+	(Symbol as any).observable = Symbol("observable");
+}
+
+interface Observer<T> {
+	next?: (value: T) => void;
+	error?: (error: any) => void;
+	complete?: () => void;
+}
+
+interface Subscription {
+	unsubscribe(): void;
+}
+
+interface Observable<T> {
+	subscribe(observer: Partial<Observer<T>>): Subscription;
+	[Symbol.observable](): Observable<T>;
+}
+
+export class LixObservable<T> implements Observable<T[]> {
+	constructor(
+		private subscriber: (observer: Observer<T[]>) => (() => void) | void
+	) {}
+
+	subscribe(observer: Partial<Observer<T[]>>): Subscription {
+		let closed = false;
+		const safeObserver: Observer<T[]> = {
+			next: (value) => !closed && observer.next?.(value),
+			error: (err) => {
+				if (!closed) {
+					closed = true;
+					observer.error?.(err);
+				}
+			},
+			complete: () => {
+				if (!closed) {
+					closed = true;
+					observer.complete?.();
+				}
+			},
+		};
+
+		const cleanup = this.subscriber(safeObserver);
+
+		return {
+			unsubscribe() {
+				if (!closed) {
+					closed = true;
+					cleanup?.();
+				}
+			},
+		};
+	}
+
+	[Symbol.observable](): LixObservable<T> {
+		return this;
+	}
+
+	subscribeTakeFirst(observer: Partial<Observer<T | undefined>>): Subscription {
+		return this.subscribe({
+			next: (rows) => observer.next?.(rows[0]),
+			error: observer.error,
+			complete: observer.complete,
+		});
+	}
+
+	subscribeTakeFirstOrThrow(observer: Partial<Observer<T>>): Subscription {
+		return this.subscribe({
+			next: (rows) => {
+				if (rows.length === 0) {
+					observer.error?.(new Error("Query returned no rows"));
+				} else {
+					observer.next?.(rows[0]!);
+				}
+			},
+			error: observer.error,
+			complete: observer.complete,
+		});
+	}
+}

package/src/plugin/index.ts

@@ -1,7 +1,7 @@
 export type {
 	LixPlugin,
 	DetectedChange,
-	DetectedConflict,
-	LixReadonly,
 	UiDiffComponentProps,
 } from "./lix-plugin.js";
+
+export { mockJsonPlugin } from "./mock-json-plugin.js";

package/src/plugin/lix-plugin.test-d.ts

@@ -1,27 +1,38 @@
 /* eslint-disable @typescript-eslint/no-unused-vars */
 import { assertType, test } from "vitest";
 import type { DetectedChange, LixPlugin } from "./lix-plugin.js";
-import type { ExperimentalChangeSchema } from "../change-schema/types.js";
+import type {
+	FromLixSchemaDefinition,
+	LixSchemaDefinition,
+} from "../schema-definition/definition.js";
 
 test("json schema type of a detected change", () => {
 	const MockChangeSchema = {
-		key: "mock",
-		type: "json",
-		schema: {
-			type: "object",
-			properties: {
-				name: { type: "string" },
-				age: { type: "number" },
-				location: { type: "object" },
+		"x-lix-key": "mock",
+		"x-lix-version": "1.0",
+		type: "object",
+		properties: {
+			name: { type: "string" },
+			age: { type: "number" },
+			location: {
+				type: "object",
+				properties: {
+					city: { type: "string" },
+					country: { type: "string" },
+				},
+				required: ["city", "country"],
 			},
-			required: ["name", "age", "location"],
 		},
-	} as const satisfies ExperimentalChangeSchema;
+		required: ["name", "age", "location"],
+		additionalProperties: false,
+	} as const satisfies LixSchemaDefinition;
 
-	const change: DetectedChange<typeof MockChangeSchema> = {
+	const change: DetectedChange<
+		FromLixSchemaDefinition<typeof MockChangeSchema>
+	> = {
 		entity_id: "123",
 		schema: MockChangeSchema,
-		snapshot: {
+		snapshot_content: {
 			name: "John",
 			age: 5,
 			location: {
@@ -37,8 +48,8 @@ test("json schema type of a detected change", () => {
 test("file.data is potentially undefined", () => {
 	const plugin: LixPlugin = {
 		key: "plugin1",
-		applyChanges: async ({ file }) => {
-			assertType<ArrayBuffer | undefined>(file.data);
+		applyChanges: ({ file }) => {
+			assertType<Uint8Array | undefined>(file.data);
 			return { fileData: new Uint8Array() };
 		},
 	};

package/src/plugin/lix-plugin.ts

@@ -1,9 +1,6 @@
-import type {
-	ExperimentalChangeSchema,
-	ExperimentalInferType,
-} from "../change-schema/types.js";
-import { type Change, type LixFile } from "../database/schema.js";
-import type { Lix } from "../lix/open-lix.js";
+import type { Change } from "../change/schema.js";
+import type { LixFile } from "../file/schema.js";
+import type { LixSchemaDefinition } from "../schema-definition/definition.js";
 
 // named lixplugin to avoid conflict with built-in plugin type
 export type LixPlugin = {
@@ -26,24 +23,17 @@ export type LixPlugin = {
 	 * deleted. If the file is deleted, lix own change control
 	 * will handle the deletion. Hence, `after` is always be defined.
 	 */
-	detectChanges?: (args: {
-		lix: LixReadonly;
-		before?: LixFile;
-		after: LixFile;
-	}) => Promise<Array<DetectedChange>>;
-	/**
-	 * UI components that are used to render the diff view.
-	 */
-	diffUiComponent?: CustomElementConstructor;
-	/**
-	 * Detects changes from the source lix that conflict with changes in the target lix.
-	 */
-	detectConflicts?: (args: {
-		lix: LixReadonly;
-		changes: Array<Change>;
-	}) => Promise<DetectedConflict[]>;
-	applyChanges?: (args: {
-		lix: LixReadonly;
+	detectChanges?: ({
+		before,
+		after,
+	}: {
+		before?: Omit<LixFile, "data"> & { data?: Uint8Array };
+		after: Omit<LixFile, "data"> & { data: Uint8Array };
+	}) => DetectedChange[];
+	applyChanges?: ({
+		file,
+		changes,
+	}: {
 		/**
 		 * The file to which the changes should be applied.
 		 *
@@ -53,11 +43,20 @@ export type LixPlugin = {
 		 * that did not exist in the target version. Or, a file
 		 * has been deleted and should be restored at a later point.
 		 */
-		file: Omit<LixFile, "data"> & { data?: LixFile["data"] };
+		file: Omit<LixFile, "data"> & { data?: Uint8Array };
 		changes: Array<Change>;
-	}) => Promise<{
-		fileData: LixFile["data"];
-	}>;
+	}) => { fileData: Uint8Array };
+	/**
+	 * UI components that are used to render the diff view.
+	 */
+	diffUiComponent?: CustomElementConstructor;
+	/**
+	 * Detects changes from the source lix that conflict with changes in the target lix.
+	 */
+	// detectConflicts?: (args: {
+	// 	lix: LixReadonly;
+	// 	changes: Array<Change>;
+	// }) => Promise<DetectedConflict[]>;
 	// // TODO multiple resolution strategies should be reported to the user
 	// // similar to fixable lint rules. We likely need to expose in
 	// // detect conflicts how conflicts could potentially be resolved.
@@ -94,33 +93,25 @@ export type LixPlugin = {
  *   ```
  */
 
-export type DetectedChange<Schema extends ExperimentalChangeSchema = any> = {
+export type DetectedChange<T = any> = {
 	entity_id: string;
-	schema: Omit<ExperimentalChangeSchema, "schema">;
-	/**
-	 * The change is considered a deletion if `snapshot` is `undefined`.
-	 */
-
-	snapshot?: ExperimentalInferType<Schema>;
-};
-
-export type DetectedConflict = {
-	/**
-	 * @see {ChangeConflict.key}
-	 */
-	key: string;
+	schema: LixSchemaDefinition;
 	/**
-	 * The changes that are conflicting.
+	 * The change is considered a deletion if `snapshot_content` is `null`.
 	 */
-	conflictingChangeIds: Set<Change["id"]>;
+	snapshot_content: T | null;
 };
 
-export type LixReadonly = Pick<Lix, "plugin"> & {
-	db: {
-		selectFrom: Lix["db"]["selectFrom"];
-		withRecursive: Lix["db"]["withRecursive"];
-	};
-};
+// export type DetectedConflict = {
+// 	/**
+// 	 * @see {ChangeConflict.key}
+// 	 */
+// 	key: string;
+// 	/**
+// 	 * The changes that are conflicting.
+// 	 */
+// 	conflictingChangeIds: Set<Change["id"]>;
+// };
 
 export type UiDiffComponentProps = {
 	diffs: Array<