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

package/src/schema-definition/definition.ts

@@ -1,4 +1,55 @@
 import type { FromSchema, JSONSchema } from "json-schema-to-ts";
+import type { JsonPointer } from "./json-pointer.js";
+
+export type LixForeignKeyScopeColumn = "version_id" | "file_id";
+
+/**
+ * Foreign key constraint definition
+ */
+export type LixForeignKey = {
+	/**
+	 * Local JSON-schema property names that participate in the FK.
+	 * Must have at least one property.
+	 */
+	properties: readonly JsonPointer[] | JsonPointer[];
+
+	/**
+	 * Where they point to.
+	 */
+	references: {
+		/**
+		 * The x-lix-key of the referenced schema
+		 */
+		schemaKey: string;
+		/**
+		 * Remote property names (must have same length as local properties)
+		 */
+		properties: readonly JsonPointer[] | JsonPointer[];
+		/**
+		 * Optional version of the referenced schema
+		 */
+		schemaVersion?: string;
+	};
+
+	/**
+	 * Validation mode for this foreign key.
+	 * - "immediate" (default): validate referenced existence on insert/update; restrict deletion when referenced.
+	 * - "materialized": skip insert/update existence checks (reference is derived/materialized later);
+	 *   still restrict deletion when referenced.
+	 */
+	mode?: "immediate" | "materialized";
+
+	/**
+	 * Implicit columns that scope the foreign key relationship.
+	 * When omitted, defaults to ["version_id", "file_id"] for state-backed schemas.
+	 * Provide an empty array to disable implicit scoping entirely.
+	 */
+	scope?: readonly LixForeignKeyScopeColumn[] | LixForeignKeyScopeColumn[];
+
+	// Future features - not implemented yet
+	// onDelete?: "cascade" | "restrict" | "set null";
+	// onUpdate?: "cascade" | "restrict";
+};
 
 export const LixSchemaDefinition = {
 	$schema: "http://json-schema.org/draft-07/schema#",
@@ -16,45 +67,137 @@ export const LixSchemaDefinition = {
 					type: "array",
 					items: {
 						type: "array",
+						minItems: 1,
+						uniqueItems: true,
 						items: {
 							type: "string",
+							format: "json-pointer",
+							description: "JSON Pointer referencing a property",
 						},
 					},
 				},
-				"x-primary-key": {
+				additionalProperties: {
+					type: "boolean",
+					const: false,
+					description:
+						"Objects describing Lix schemas must not allow arbitrary additional properties; set this explicitly to false.",
+				},
+				"x-lix-primary-key": {
 					type: "array",
+					minItems: 1,
+					uniqueItems: true,
 					items: {
 						type: "string",
+						format: "json-pointer",
+						description:
+							"JSON Pointer referencing a property that participates in the primary key.",
 					},
 				},
 				"x-lix-foreign-keys": {
-					type: "object",
-					additionalProperties: {
+					type: "array",
+					items: {
 						type: "object",
+						required: ["properties", "references"],
 						properties: {
-							schemaKey: {
-								type: "string",
-								description: "The x-lix-key of the referenced schema",
+							properties: {
+								type: "array",
+								minItems: 1,
+								items: {
+									type: "string",
+									format: "json-pointer",
+									description: "JSON Pointer referencing the local field.",
+								},
+								uniqueItems: true,
+								description:
+									"Local JSON-schema property names that participate in the FK",
 							},
-							property: {
-								type: "string",
-								description: "The property name in the referenced schema",
+							references: {
+								type: "object",
+								required: ["schemaKey", "properties"],
+								properties: {
+									schemaKey: {
+										type: "string",
+										description: "The x-lix-key of the referenced schema",
+									},
+									properties: {
+										type: "array",
+										minItems: 1,
+										items: {
+											type: "string",
+											format: "json-pointer",
+											description: "JSON Pointer referencing the remote field.",
+										},
+										uniqueItems: true,
+										description:
+											"Remote property names (same length as local properties)",
+									},
+									schemaVersion: {
+										type: "string",
+										pattern: "^\\d+\\.\\d+$",
+										description: "Optional version of the referenced schema",
+									},
+								},
 							},
-							schemaVersion: {
+							mode: {
 								type: "string",
-								pattern: "^\\d+\\.\\d+$",
-								description: "Optional version of the referenced schema",
+								enum: ["immediate", "materialized"],
+								description:
+									"Validation mode: immediate (default) or materialized (defer insert/update existence checks)",
 							},
+							scope: {
+								type: "array",
+								items: {
+									type: "string",
+									enum: ["version_id", "file_id"],
+								},
+								uniqueItems: true,
+								description:
+									"Implicit columns (version_id and/or file_id) used to scope the foreign key relationship",
+							},
+							// onDelete: {
+							//   type: "string",
+							//   enum: ["cascade", "restrict", "set null"],
+							//   description: "Action to take when referenced entity is deleted (future feature)"
+							// },
+							// onUpdate: {
+							//   type: "string",
+							//   enum: ["cascade", "restrict"],
+							//   description: "Action to take when referenced entity is updated (future feature)"
+							// },
 						},
-						required: ["schemaKey", "property"],
 					},
 				},
 				"x-lix-key": {
 					type: "string",
+					pattern: "^[a-z][a-z0-9_]*$",
 					description:
-						"The key of the schema. The key is used to identify the schema. You must use a unique key for each schema.",
+						"The schema identifier. Must be snake_case (lowercase, underscores) to safely embed in SQL identifiers.",
 					examples: ["csv_plugin_cell"],
 				},
+				"x-lix-immutable": {
+					type: "boolean",
+					description:
+						"When true, entities for this schema cannot be updated after creation.",
+				},
+				"x-lix-override-lixcols": {
+					type: "object",
+					description:
+						"Default metadata column values (such as lixcol_file_id). Does not affect JSON property defaults.",
+					additionalProperties: {
+						type: "string",
+						format: "cel",
+					},
+				},
+				"x-lix-entity-views": {
+					type: "array",
+					description:
+						"Restricts which SQL entity views (state/state_by_version/state_history) are generated. When omitted, all views are created.",
+					items: {
+						type: "string",
+						enum: ["state", "state_by_version", "state_history"],
+					},
+					uniqueItems: true,
+				},
 				"x-lix-version": {
 					type: "string",
 					description:
@@ -70,10 +213,11 @@ export const LixSchemaDefinition = {
 							{
 								type: "object",
 								properties: {
-									"x-lix-generated": {
-										type: "boolean",
+									"x-lix-default": {
+										type: "string",
+										format: "cel",
 										description:
-											"Whether this property is auto-generated by the database",
+											"CEL expression evaluated to produce the default value when the property is omitted.",
 									},
 								},
 							},
@@ -81,7 +225,7 @@ export const LixSchemaDefinition = {
 					},
 				},
 			},
-			required: ["x-lix-key", "x-lix-version"],
+			required: ["x-lix-key", "x-lix-version", "additionalProperties"],
 		},
 	],
 } as const;
@@ -90,7 +234,7 @@ export const LixSchemaDefinition = {
  * Extended property schema that includes Lix-specific extensions
  */
 type LixPropertySchema = JSONSchema & {
-	"x-lix-generated"?: boolean;
+	"x-lix-default"?: string;
 };
 
 /**
@@ -112,6 +256,10 @@ export type LixSchemaDefinition = JSONSchema & {
 	 *   "csv_plugin_cell"
 	 */
 	"x-lix-key": string;
+	/**
+	 * Marks the schema as immutable. Immutable entities may be inserted but cannot be updated.
+	 */
+	"x-lix-immutable"?: boolean;
 	/**
 	 * The version of the schema.
 	 *
@@ -122,7 +270,33 @@ export type LixSchemaDefinition = JSONSchema & {
 	 *   "1.0"
 	 */
 	"x-lix-version": string;
-	"x-lix-primary-key"?: string[] | readonly string[];
+	/**
+	 * Override metadata column values applied by entity-view rewrites (e.g. `lixcol_file_id`).
+	 * Does not provide defaults for JSON properties inside `properties`. Each entry is a CEL
+	 * expression evaluated in the same context as property defaults.
+	 *
+	 * @example
+	 *   {
+	 *     "x-lix-override-lixcols": {
+	 *       "lixcol_file_id": "\"lix\"",
+	 *       "lixcol_untracked": "0"
+	 *     }
+	 *   }
+	 */
+	"x-lix-override-lixcols"?: Record<string, string>;
+	/**
+	 * Restricts which entity views are generated. When omitted, all default
+	 * variants (state, state_by_version, state_history) are emitted.
+	 *
+	 * @example
+	 *   {
+	 *     "x-lix-entity-views": ["state"] // only generate the base view
+	 *   }
+	 */
+	"x-lix-entity-views"?:
+		| ("state" | "state_by_version" | "state_history")[]
+		| readonly ("state" | "state_by_version" | "state_history")[];
+	"x-lix-primary-key"?: JsonPointer[] | readonly JsonPointer[];
 	/**
 	 * Properties that must be unique per version.
 	 *
@@ -133,9 +307,9 @@ export type LixSchemaDefinition = JSONSchema & {
 	 *   {
 	 *     "x-lix-unique": [
 	 *       // the id must be unique
-	 *       ["id"],
+	 *       ["/id"],
 	 *       // the name and age must be unique as well
-	 *       ["name", "age"],
+	 *       ["/name", "/age"],
 	 *     ],
 	 *     properties: {
 	 *       id: { type: "string" },
@@ -144,32 +318,34 @@ export type LixSchemaDefinition = JSONSchema & {
 	 *     },
 	 *   }
 	 */
-	"x-lix-unique"?: string[][] | readonly (readonly string[])[];
+	"x-lix-unique"?: JsonPointer[][] | readonly (readonly JsonPointer[])[];
 	/**
 	 * Foreign key constraints referencing other schemas.
 	 *
 	 * @example
-	 *   {
-	 *     "x-lix-foreign-keys": {
-	 *       "author_id": {
+	 *   [
+	 *     {
+	 *       "properties": ["/author_id"],
+	 *       "references": {
 	 *         "schemaKey": "user_profile",
-	 *         "property": "id"
-	 *       },
-	 *       "category_id": {
-	 *         "schemaKey": "post_category",
-	 *         "property": "id"
+	 *         "properties": ["/id"]
+	 *       }
+	 *     },
+	 *     {
+	 *       "properties": ["/entity_id", "/schema_key", "/file_id"],
+	 *       "references": {
+	 *         "schemaKey": "state",
+	 *         "properties": ["/entity_id", "/schema_key", "/file_id"]
 	 *       }
 	 *     }
-	 *   }
+	 *   ]
 	 */
-	"x-lix-foreign-keys"?: {
-		[localProperty: string]: {
-			schemaKey: string;
-			property: string;
-			schemaVersion?: string;
-		};
-	};
+	"x-lix-foreign-keys"?: LixForeignKey[] | readonly LixForeignKey[];
 	type: "object";
+	/**
+	 * Has to be false to know the schema beforehand.
+	 */
+	additionalProperties: false;
 	properties?: {
 		[key: string]: LixPropertySchema;
 	};
@@ -332,7 +508,7 @@ export type LixUpdateable<T> = {
 /**
  * Transform a type for select/query operations.
  *
- * This type unwraps all LixGenerated markers, giving you the actual runtime
+ * This type unwraps all LixGenerated markers, giving you the actual engine
  * types that will be returned from database queries. All fields are required
  * and have their base types.
  *
@@ -364,12 +540,22 @@ export type LixSelectable<T> = {
 	[K in keyof T]: SelectType<T[K]>;
 };
 
+type IsNever<T> = [T] extends [never] ? true : false;
+type IsAny<T> = 0 extends 1 & T ? true : false;
+
 /**
  * Transform object types with no properties from unknown to Record<string, any>
  */
-type TransformEmptyObject<T> = T extends { [x: string]: unknown }
-	? Record<string, any>
-	: T;
+type TransformEmptyObject<T> =
+	IsAny<T> extends true
+		? any
+		: IsNever<T> extends true
+			? never
+			: T extends object
+				? keyof T extends never
+					? Record<string, any>
+					: T
+				: T;
 
 /**
  * Check if a schema property is an empty object type (no properties defined)
@@ -386,14 +572,20 @@ type IsEmptyObjectSchema<P> = P extends { type: "object" }
 type GetNullablePart<P> = P extends { nullable: true } ? null : never;
 
 /**
- * Internal type that applies LixGenerated markers to properties with x-lix-generated: true
+ * Internal type that applies LixGenerated markers to properties that provide defaults.
  */
+type PropertyHasDefault<P> = P extends { "x-lix-default": any }
+	? true
+	: P extends { default: any }
+		? true
+		: false;
+
 type ApplyLixGenerated<TSchema extends LixSchemaDefinition> = TSchema extends {
 	properties: infer Props;
 }
 	? {
 			[K in keyof FromSchema<TSchema>]: K extends keyof Props
-				? Props[K] extends { "x-lix-generated": true }
+				? PropertyHasDefault<Props[K]> extends true
 					? LixGenerated<TransformEmptyObject<FromSchema<TSchema>[K]>>
 					: IsEmptyObjectSchema<Props[K]> extends true
 						? Record<string, any> | GetNullablePart<Props[K]>
@@ -407,7 +599,7 @@ type ApplyLixGenerated<TSchema extends LixSchemaDefinition> = TSchema extends {
  *
  * This type transformation:
  * 1. Converts JSON Schema properties to TypeScript types
- * 2. Wraps properties with `x-lix-generated: true` in LixGenerated markers
+ * 2. Wraps properties that declare defaults (`default` or `x-lix-default`) in LixGenerated markers
  * 3. Transforms `type: "object"` without properties to `Record<string, any>`
  *
  * The resulting type can be used with LixInsertable, LixUpdateable, and
@@ -418,14 +610,14 @@ type ApplyLixGenerated<TSchema extends LixSchemaDefinition> = TSchema extends {
  * const AccountSchema = {
  *   "x-lix-key": "account",
  *   "x-lix-version": "1.0",
- *   "x-lix-primary-key": ["id"],
+ *   "x-lix-primary-key": ["/id"],
  *   type: "object",
  *   properties: {
- *     id: { type: "string", "x-lix-generated": true },
+ *     id: { type: "string", default: "auto-generated" },
  *     name: { type: "string" },
  *     email: { type: "string" },
  *     metadata: { type: "object" },  // Becomes Record<string, any>
- *     created_at: { type: "string", "x-lix-generated": true }
+ *     created_at: { type: "string", "x-lix-default": "lix_now()" }
  *   },
  *   required: ["id", "name", "email"],
  *   additionalProperties: false

package/src/schema-definition/index.ts

@@ -10,4 +10,4 @@ export { JSONTypeSchema, type JSONType } from "./json-type.js";
 export {
 	validateLixSchema,
 	validateLixSchemaDefinition,
-} from "./validate-lix-schema.js";
+} from "./validate-lix-schema.js";

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

@@ -0,0 +1,101 @@
+import { describe, expect, test } from "vitest";
+import {
+	buildSqliteJsonPath,
+	extractValueAtPath,
+	parseJsonPointer,
+	parsePointerPaths,
+} from "./json-pointer.js";
+
+describe("parseJsonPointer", () => {
+	test("parses simple pointer", () => {
+		expect(parseJsonPointer("/foo/bar")).toEqual(["foo", "bar"]);
+	});
+
+	test("handles escaped characters", () => {
+		expect(parseJsonPointer("/foo~0bar/~1baz")).toEqual(["foo~bar", "/baz"]);
+	});
+
+	test("throws on invalid pointer", () => {
+		expect(() => parseJsonPointer("foo")).toThrowError(
+			/JSON Pointer "foo" must start with/
+		);
+		expect(() => parseJsonPointer("")).toThrowError(
+			/JSON Pointer must not be empty/
+		);
+		expect(() => parseJsonPointer("/foo//bar")).toThrowError(
+			/contains an empty segment/
+		);
+	});
+});
+
+describe("parsePointerPaths", () => {
+	test("returns empty array for non arrays", () => {
+		expect(parsePointerPaths(undefined)).toEqual([]);
+		// @ts-expect-error intentionally passing invalid input
+		expect(parsePointerPaths("foo")).toEqual([]);
+	});
+
+	test("parses property names and pointers", () => {
+		const paths = parsePointerPaths(["name", "/value/x-lix-version"]);
+		expect(paths).toHaveLength(2);
+		expect(paths[0]).toEqual({
+			label: "name",
+			segments: ["name"],
+			jsonPath: "$.name",
+		});
+		expect(paths[1]).toEqual({
+			label: "/value/x-lix-version",
+			segments: ["value", "x-lix-version"],
+			jsonPath: '$.value."x-lix-version"',
+		});
+	});
+
+	test("skips invalid entries", () => {
+		const paths = parsePointerPaths(["", "/bad//path"]);
+		expect(paths).toEqual([]);
+	});
+
+	test("keeps array indices in json path", () => {
+		const [result] = parsePointerPaths(["/items/0/name"]);
+		expect(result?.jsonPath).toBe("$.items[0].name");
+	});
+});
+
+describe("buildSqliteJsonPath", () => {
+	test("quotes unsafe identifiers", () => {
+		expect(buildSqliteJsonPath(["value", "x-lix-version", 'needs"quote'])).toBe(
+			'$.value."x-lix-version"."needs\\"quote"'
+		);
+	});
+
+	test("handles numeric segments as array indices", () => {
+		expect(buildSqliteJsonPath(["a", "0", "b"])).toBe("$.a[0].b");
+	});
+});
+
+describe("extractValueAtPath", () => {
+	const source = {
+		name: "example",
+		value: {
+			items: [{ id: 1 }, { id: 2 }],
+			meta: { "x-lix-version": "1.0" },
+		},
+	};
+
+	test("returns nested object values", () => {
+		expect(extractValueAtPath(source, ["value", "meta", "x-lix-version"])).toBe(
+			"1.0"
+		);
+	});
+
+	test("supports array access", () => {
+		expect(extractValueAtPath(source, ["value", "items", "1", "id"])).toBe(2);
+	});
+
+	test("returns undefined when path does not exist", () => {
+		expect(extractValueAtPath(source, ["missing"])).toBeUndefined();
+		expect(
+			extractValueAtPath(source, ["value", "items", "foo"])
+		).toBeUndefined();
+	});
+});