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

package/src/schema-definition/json-pointer.ts

@@ -0,0 +1,168 @@
+export type JsonPointer = `/${string}`;
+
+export function parseJsonPointer(pointer: string): string[] {
+	if (typeof pointer !== "string") {
+		throw new Error("JSON Pointer must be a string");
+	}
+	if (pointer.length === 0) {
+		throw new Error("JSON Pointer must not be empty");
+	}
+	if (!pointer.startsWith("/")) {
+		throw new Error(
+			`JSON Pointer "${pointer}" must start with '/' (examples: /id, /value/x-lix-key).`
+		);
+	}
+
+	const segments = pointer
+		.slice(1)
+		.split("/")
+		.map((segment) => decodePointerSegment(segment));
+
+	if (segments.some((segment) => segment.length === 0)) {
+		throw new Error(
+			`JSON Pointer "${pointer}" contains an empty segment. Consecutive slashes are not allowed.`
+		);
+	}
+
+	return segments;
+}
+
+export type JsonPointerPath = {
+	segments: readonly string[];
+	label: string;
+	jsonPath: string;
+};
+
+/**
+ * Decodes a single JSON Pointer segment by unescaping the encoded forward-slash
+ * and tilde sequences.
+ *
+ * @example
+ * decodePointerSegment("foo~1bar");
+ * // => "foo/bar"
+ */
+export function decodePointerSegment(segment: string): string {
+	return segment.replace(/~1/g, "/").replace(/~0/g, "~");
+}
+
+/**
+ * Normalizes a JSON pointer string (or plain property name) to its top-level
+ * property. Returns the first JSON pointer segment for pointer values or the
+ * original property when the input is not a pointer.
+ *
+ * @example
+ * normalizePointerProperty("/value/x-lix-key");
+ * // => "value"
+ */
+export function normalizePointerProperty(value: string): string {
+	if (typeof value !== "string") {
+		return "";
+	}
+	if (!value.startsWith("/")) {
+		return value;
+	}
+	const segments = value.slice(1).split("/").map(decodePointerSegment);
+	return segments[0] ?? "";
+}
+
+/**
+ * Applies {@link normalizePointerProperty} to an array of pointer strings or
+ * property names, filtering out invalid entries.
+ *
+ * @example
+ * normalizePointerProperties(["/value/x-lix-key", "id"]);
+ * // => ["value", "id"]
+ */
+export function normalizePointerProperties(
+	values?: readonly string[] | string[]
+): string[] {
+	if (!Array.isArray(values)) {
+		return [];
+	}
+	return values
+		.map((value) => normalizePointerProperty(value))
+		.filter((value): value is string => value.length > 0);
+}
+
+/**
+ * Parses an array of JSON pointer strings (or simple property names) into
+ * structured path descriptors that include both pointer segments and a JSON
+ * path suitable for SQLite's `json_extract`.
+ */
+export function parsePointerPaths(
+	values?: readonly string[] | string[]
+): JsonPointerPath[] {
+	if (!Array.isArray(values)) {
+		return [];
+	}
+	const paths: JsonPointerPath[] = [];
+	for (const entry of values) {
+		if (typeof entry !== "string" || entry.length === 0) {
+			continue;
+		}
+		let segments: string[];
+		if (entry.startsWith("/")) {
+			try {
+				segments = parseJsonPointer(entry);
+			} catch {
+				continue;
+			}
+		} else {
+			segments = [entry];
+		}
+		paths.push({
+			segments,
+			label: entry,
+			jsonPath: buildSqliteJsonPath(segments),
+		});
+	}
+	return paths;
+}
+
+/**
+ * Builds a JSON path string compatible with SQLite's json_extract from pointer
+ * segments.
+ */
+export function buildSqliteJsonPath(segments: readonly string[]): string {
+	let path = "$";
+	for (const segment of segments) {
+		const index = Number(segment);
+		if (Number.isInteger(index) && String(index) === segment) {
+			path += `[${segment}]`;
+			continue;
+		}
+		if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(segment)) {
+			path += `.${segment}`;
+			continue;
+		}
+		const escaped = segment.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+		path += `."${escaped}"`;
+	}
+	return path;
+}
+
+/**
+ * Extracts a nested value from a JSON-like object/array using pointer segments.
+ */
+export function extractValueAtPath(
+	source: unknown,
+	segments: readonly string[]
+): any {
+	let current: any = source;
+	for (const segment of segments) {
+		if (Array.isArray(current)) {
+			const index = Number(segment);
+			if (!Number.isInteger(index)) {
+				return undefined;
+			}
+			current = current[index];
+			continue;
+		}
+		if (current && typeof current === "object") {
+			current = (current as Record<string, unknown>)[segment];
+			continue;
+		}
+		return undefined;
+	}
+	return current;
+}

package/src/schema-definition/validate-lix-schema.test.ts

@@ -1,5 +1,8 @@
 import { test, expect } from "vitest";
-import { validateLixSchema, validateLixSchemaDefinition } from "./validate-lix-schema.js";
+import {
+	validateLixSchema,
+	validateLixSchemaDefinition,
+} from "./validate-lix-schema.js";
 
 test("validateLixSchemaDefinition passes for valid Lix schema", () => {
 	const validSchema = {
@@ -9,6 +12,7 @@ test("validateLixSchemaDefinition passes for valid Lix schema", () => {
 		properties: {
 			id: { type: "string" },
 		},
+		additionalProperties: false,
 	};
 
 	expect(() => validateLixSchemaDefinition(validSchema)).not.toThrow();
@@ -22,10 +26,13 @@ test("validateLixSchemaDefinition throws for invalid schema", () => {
 		properties: {
 			id: { type: "string" },
 		},
+		additionalProperties: false,
 		// Missing required x-lix-key
 	};
 
-	expect(() => validateLixSchemaDefinition(invalidSchema)).toThrow("Invalid Lix schema definition");
+	expect(() => validateLixSchemaDefinition(invalidSchema)).toThrow(
+		"Invalid Lix schema definition"
+	);
 });
 
 test("validateLixSchema validates both schema and data successfully", () => {
@@ -38,6 +45,7 @@ test("validateLixSchema validates both schema and data successfully", () => {
 			name: { type: "string" },
 		},
 		required: ["id", "name"],
+		additionalProperties: false,
 	};
 
 	const validData = {
@@ -57,11 +65,14 @@ test("validateLixSchema throws when schema is invalid", () => {
 		properties: {
 			id: { type: "string" },
 		},
+		additionalProperties: false,
 	};
 
 	const data = { id: "123" };
 
-	expect(() => validateLixSchema(invalidSchema, data)).toThrow("Invalid Lix schema definition");
+	expect(() => validateLixSchema(invalidSchema, data)).toThrow(
+		"Invalid Lix schema definition"
+	);
 });
 
 test("validateLixSchema throws when data doesn't match schema", () => {
@@ -74,6 +85,7 @@ test("validateLixSchema throws when data doesn't match schema", () => {
 			name: { type: "string" },
 		},
 		required: ["id", "name"],
+		additionalProperties: false,
 	};
 
 	const invalidData = {
@@ -81,5 +93,101 @@ test("validateLixSchema throws when data doesn't match schema", () => {
 		// Missing required 'name' field
 	};
 
-	expect(() => validateLixSchema(schema, invalidData)).toThrow("Data validation failed");
-});
+	expect(() => validateLixSchema(schema, invalidData)).toThrow(
+		"Data validation failed"
+	);
+});
+
+test("validateLixSchemaDefinition rejects when additionalProperties is missing", () => {
+	const schemaMissingAdditionalProps = {
+		"x-lix-key": "user",
+		"x-lix-version": "1.0",
+		type: "object",
+		properties: {
+			id: { type: "string" },
+		},
+		required: ["id"],
+	};
+
+	expect(() =>
+		validateLixSchemaDefinition(schemaMissingAdditionalProps)
+	).toThrow("Invalid Lix schema definition");
+});
+
+test("additional properties must be false", () => {
+	const schemaWithAdditionalProps = {
+		"x-lix-key": "user",
+		"x-lix-version": "1.0",
+		type: "object",
+		properties: {
+			id: { type: "string" },
+			name: { type: "string" },
+		},
+		required: ["id", "name"],
+		additionalProperties: true, // This should cause validation to fail
+	};
+
+	const data = {
+		id: "123",
+		name: "John Doe",
+		extraField: "not allowed", // Extra field not defined in schema
+	};
+
+	expect(() =>
+		validateLixSchemaDefinition(schemaWithAdditionalProps)
+	).toThrow();
+
+	const validSchema = {
+		"x-lix-key": "user",
+		"x-lix-version": "1.0",
+		type: "object",
+		properties: {
+			id: { type: "string" },
+			name: { type: "string" },
+		},
+		required: ["id", "name"],
+		additionalProperties: false, // Correctly set to false
+	};
+
+	expect(() => validateLixSchemaDefinition(validSchema)).not.toThrow();
+	expect(validateLixSchemaDefinition(validSchema)).toBe(true);
+
+	expect(() => validateLixSchema(validSchema, data)).toThrow(
+		"Data validation failed"
+	);
+});
+
+test("validateLixSchemaDefinition rejects missing primary key properties", () => {
+	const schema = {
+		"x-lix-key": "missing_pk",
+		"x-lix-version": "1.0",
+		type: "object",
+		properties: {
+			value: { type: "string" },
+		},
+		required: ["value"],
+		"x-lix-primary-key": ["/entity_id"],
+		additionalProperties: false,
+	};
+
+	expect(() => validateLixSchemaDefinition(schema)).toThrow(
+		"x-lix-primary-key references missing property"
+	);
+});
+
+test("validateLixSchemaDefinition rejects missing unique constraint properties", () => {
+	const schema = {
+		"x-lix-key": "missing_unique",
+		"x-lix-version": "1.0",
+		type: "object",
+		properties: {
+			value: { type: "string" },
+		},
+		"x-lix-unique": [["/entity_id", "/value"]],
+		additionalProperties: false,
+	};
+
+	expect(() => validateLixSchemaDefinition(schema)).toThrow(
+		"x-lix-unique references missing property"
+	);
+});

package/src/schema-definition/validate-lix-schema.ts

@@ -1,5 +1,7 @@
 import { Ajv } from "ajv";
+import { parse } from "@marcbachmann/cel-js";
 import { LixSchemaDefinition } from "./definition.js";
+import { parseJsonPointer } from "./json-pointer.js";
 
 const ajv = new Ajv({
 	strict: true,
@@ -7,18 +9,84 @@ const ajv = new Ajv({
 	// https://json-schema.org/blog/posts/stable-json-schema
 	strictSchema: false,
 });
+ajv.addFormat("json-pointer", {
+	type: "string",
+	validate: (value: string) => {
+		try {
+			parseJsonPointer(value);
+			return true;
+		} catch {
+			return false;
+		}
+	},
+});
+ajv.addFormat("cel", {
+	type: "string",
+	validate: (value: string) => {
+		try {
+			parse(value);
+			return true;
+		} catch {
+			return false;
+		}
+	},
+});
 
 const _validateLixSchemaDefinition = ajv.compile(LixSchemaDefinition);
 
+function assertPrimaryKeyPointers(schema: LixSchemaDefinition) {
+	const primaryKey = (schema as any)["x-lix-primary-key"];
+	if (!Array.isArray(primaryKey)) return;
+	for (const pointer of primaryKey) {
+		if (typeof pointer !== "string") continue;
+		const segments = parseJsonPointer(pointer);
+		if (!segments.length || !schemaHasProperty(schema, segments)) {
+			throw new Error(
+				`Invalid Lix schema definition: x-lix-primary-key references missing property "${pointer}".`
+			);
+		}
+	}
+}
+
+function assertUniquePointers(schema: LixSchemaDefinition) {
+	const uniqueGroups = (schema as any)["x-lix-unique"];
+	if (!Array.isArray(uniqueGroups)) return;
+	for (const group of uniqueGroups) {
+		if (!Array.isArray(group)) continue;
+		for (const pointer of group) {
+			if (typeof pointer !== "string") continue;
+			const segments = parseJsonPointer(pointer);
+			if (!segments.length || !schemaHasProperty(schema, segments)) {
+				throw new Error(
+					`Invalid Lix schema definition: x-lix-unique references missing property "${pointer}".`
+				);
+			}
+		}
+	}
+}
+
+function schemaHasProperty(current: any, segments: readonly string[]): boolean {
+	let node: any = current;
+	for (const segment of segments) {
+		if (!node || typeof node !== "object") return false;
+		const props = (node as any).properties;
+		if (!props || typeof props !== "object" || !(segment in props)) {
+			return false;
+		}
+		node = (props as any)[segment];
+	}
+	return true;
+}
+
 /**
  * Validates that a schema conforms to the LixSchemaDefinition format
  * and then validates data against that schema.
- * 
+ *
  * @param schema - The Lix schema definition to validate against
  * @param data - The data to validate
  * @returns true if both the schema and data are valid
  * @throws Error with validation details if either validation fails
- * 
+ *
  * @example
  * ```typescript
  * const userSchema = {
@@ -32,13 +100,13 @@ const _validateLixSchemaDefinition = ajv.compile(LixSchemaDefinition);
  *   },
  *   required: ["id", "name"]
  * } as const satisfies LixSchemaDefinition;
- * 
+ *
  * const userData = {
  *   id: "123",
  *   name: "John Doe",
  *   age: 30
  * };
- * 
+ *
  * try {
  *   validateLixSchema(userSchema, userData); // returns true
  * } catch (error) {
@@ -46,10 +114,7 @@ const _validateLixSchemaDefinition = ajv.compile(LixSchemaDefinition);
  * }
  * ```
  */
-export function validateLixSchema(
-	schema: unknown,
-	data: unknown
-): boolean {
+export function validateLixSchema(schema: unknown, data: unknown): boolean {
 	// First validate that the schema itself is valid
 	const schemaValid = _validateLixSchemaDefinition(schema);
 	if (!schemaValid) {
@@ -57,6 +122,8 @@ export function validateLixSchema(
 			`Invalid Lix schema definition: ${JSON.stringify(_validateLixSchemaDefinition.errors, null, 2)}`
 		);
 	}
+	assertPrimaryKeyPointers(schema as LixSchemaDefinition);
+	assertUniquePointers(schema as LixSchemaDefinition);
 
 	// Then validate the data against the schema
 	const dataValidator = ajv.compile(schema as LixSchemaDefinition);
@@ -73,22 +140,22 @@ export function validateLixSchema(
 /**
  * Validates only the Lix schema definition format.
  * Use this when you only need to check if a schema is valid.
- * 
+ *
  * @param schema - The schema to validate
  * @returns true if the schema is valid
  * @throws Error with validation details if validation fails
- * 
+ *
  * @example
  * ```typescript
  * const schema = {
- *   "x-lix-key": "product", 
+ *   "x-lix-key": "product",
  *   "x-lix-version": "1.0",
  *   type: "object",
  *   properties: {
  *     id: { type: "string" }
  *   }
  * };
- * 
+ *
  * try {
  *   validateLixSchemaDefinition(schema); // returns true
  * } catch (error) {
@@ -103,6 +170,7 @@ export function validateLixSchemaDefinition(schema: unknown): boolean {
 			`Invalid Lix schema definition: ${JSON.stringify(_validateLixSchemaDefinition.errors, null, 2)}`
 		);
 	}
+	assertPrimaryKeyPointers(schema as LixSchemaDefinition);
+	assertUniquePointers(schema as LixSchemaDefinition);
 	return valid;
 }
-

package/src/server-protocol-handler/environment/create-in-memory-environment.test.ts

@@ -14,7 +14,7 @@ test.skip("opening a lix works", async () => {
 		.executeTakeFirstOrThrow()) as { value: string };
 
 	// initialize the env with the lix file
-	environment.setLix({ id: lixId, blob: await mockLix.toBlob() });
+	await environment.setLix({ id: lixId, blob: await mockLix.toBlob() });
 
 	const open0 = await environment.openLix({ id: lixId });
 
@@ -61,7 +61,7 @@ test.todo("it handles concurrent connections", async () => {
 		.executeTakeFirstOrThrow()) as { value: string };
 
 	// initialize the env with the lix file
-	environment.setLix({ id: lixId, blob: await mockLix.toBlob() });
+	await environment.setLix({ id: lixId, blob: await mockLix.toBlob() });
 
 	const open0 = await environment.openLix({ id: lixId });
 	const open1 = await environment.openLix({ id: lixId });

package/src/server-protocol-handler/environment/create-in-memory-environment.ts

@@ -59,7 +59,7 @@ export const createLspInMemoryEnvironment = (): LspEnvironment => {
 					keyValues: [{ key: "lix_sync", value: "false" }],
 				});
 
-				lix.sqlite.exec("PRAGMA foreign_keys = OFF;");
+				lix.engine!.sqlite.exec("PRAGMA foreign_keys = OFF;");
 
 				openLixes.set(args.id, lix);
 			}

package/src/server-protocol-handler/routes/get-v1.ts

@@ -2,7 +2,7 @@ import {
 	contentFromDatabase,
 	createInMemoryDatabase,
 	importDatabase,
-} from "sqlite-wasm-kysely";
+} from "../../database/sqlite/index.js";
 import type { LixServerProtocolHandlerRoute } from "../create-server-protocol-handler.js";
 
 export const route: LixServerProtocolHandlerRoute = async (context) => {
@@ -51,7 +51,9 @@ export const route: LixServerProtocolHandlerRoute = async (context) => {
 		"UPDATE key_value SET value = json('true') WHERE key = 'lix_sync'"
 	);
 
-	const blob2 = new Blob([contentFromDatabase(sqlite)]);
+	const blob2 = new Blob([
+		contentFromDatabase(sqlite) as Uint8Array<ArrayBuffer>,
+	]);
 
 	return new Response(blob2, {
 		status: 200,

package/src/server-protocol-handler/routes/pull-v1.test.ts

@@ -1,5 +1,5 @@
 import { test, expect } from "vitest";
-import type * as LixServerProtocol from "../../../../lix/server-protocol-schema/dist/schema.js";
+import type * as LixServerProtocol from "../../../../server-protocol-schema/dist/schema.js";
 import { openLix } from "../../lix/open-lix.js";
 import { createServerProtocolHandler } from "../create-server-protocol-handler.js";
 import { createLspInMemoryEnvironment } from "../environment/create-in-memory-environment.js";

package/src/server-protocol-handler/routes/pull-v1.ts

@@ -1,4 +1,4 @@
-import type * as LixServerProtocol from "../../../../lix/server-protocol-schema/dist/schema.js";
+import type * as LixServerProtocol from "../../../../server-protocol-schema/dist/schema.js";
 import type { LixServerProtocolHandlerRoute } from "../create-server-protocol-handler.js";
 import { getDiffingRows } from "../../sync/get-diffing-rows.js";
 

package/src/server-protocol-handler/routes/push-v1.test.ts

@@ -2,7 +2,7 @@
 // @ts-nocheck
 
 import { test, expect, vi } from "vitest";
-import type * as LixServerProtocol from "../../../../lix/server-protocol-schema/dist/schema.js";
+import type * as LixServerProtocol from "../../../../server-protocol-schema/dist/schema.js";
 import { openLix } from "../../lix/open-lix.js";
 import { createServerProtocolHandler } from "../create-server-protocol-handler.js";
 import type { Change } from "../../database/schema.js";
@@ -130,7 +130,7 @@ test.skip("it should return 400 for a failed insert operation", async () => {
 
 	const environment = createLspInMemoryEnvironment();
 
-	environment.setLix({ id, blob: await lix.toBlob() });
+	await environment.setLix({ id, blob: await lix.toBlob() });
 
 	const lsa = await createServerProtocolHandler({ environment });
 
@@ -182,7 +182,7 @@ test.skip("it should detect conflicts", async () => {
 
 	const lsaHandler = await createServerProtocolHandler({ environment });
 
-	global.fetch = vi.fn((request) => lsaHandler(request));
+	vi.stubGlobal("fetch", vi.fn((request) => lsaHandler(request)) as any);
 
 	// server has/creates value0 for mock_key
 	await lixOnServer.db

package/src/server-protocol-handler/routes/push-v1.ts

@@ -1,7 +1,7 @@
 // eslint-disable-next-line @typescript-eslint/ban-ts-comment
 // @ts-nocheck
 
-import type * as LixServerProtocol from "../../../../lix/server-protocol-schema/dist/schema.js";
+import type * as LixServerProtocol from "../../../../server-protocol-schema/dist/schema.js";
 import type { LixServerProtocolHandlerRoute } from "../create-server-protocol-handler.js";
 import { mergeTheirState } from "../../sync/merge-state.js";
 import type { Change } from "../../database/schema.js";

package/src/services/env-variables/index.d.ts

@@ -4,7 +4,7 @@
  */
 
 /**
- * Env variables that are available at runtime.
+ * Env variables that are available at engine.
  */
 export declare const ENV_VARIABLES: {
 	LIX_SDK_POSTHOG_TOKEN?: string;

package/src/services/telemetry/capture.test.ts

@@ -2,7 +2,7 @@ import { expect, test, vi } from "vitest";
 import { capture } from "./capture.js";
 
 test("it should not capture if telemetry is off", async () => {
-	global.fetch = vi.fn(() => Promise.resolve(new Response()));
+	vi.stubGlobal("fetch", vi.fn(() => Promise.resolve(new Response())) as any);
 
 	vi.mock("../env-variables/index.js", async () => {
 		return {
@@ -19,11 +19,11 @@ test("it should not capture if telemetry is off", async () => {
 		properties: {},
 	});
 
-	expect(global.fetch).not.toHaveBeenCalled();
+	expect((globalThis as any).fetch).not.toHaveBeenCalled();
 });
 
 test("it should not capture if telemetry is NOT off", async () => {
-	global.fetch = vi.fn(() => Promise.resolve(new Response()));
+	vi.stubGlobal("fetch", vi.fn(() => Promise.resolve(new Response())) as any);
 
 	vi.mock("../env-variables/index.js", async () => {
 		return {
@@ -40,5 +40,5 @@ test("it should not capture if telemetry is NOT off", async () => {
 		properties: {},
 	});
 
-	expect(global.fetch).toHaveBeenCalled();
+	expect((globalThis as any).fetch).toHaveBeenCalled();
 });