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

package/src/schema-definition/definition.ts

@@ -0,0 +1,502 @@
+import type { FromSchema, JSONSchema } from "json-schema-to-ts";
+
+/**
+ * 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 string[] | string[];
+
+	/**
+	 * 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 string[] | string[];
+		/**
+		 * Optional version of the referenced schema
+		 */
+		schemaVersion?: string;
+	};
+
+	// Future features - not implemented yet
+	// onDelete?: "cascade" | "restrict" | "set null";
+	// onUpdate?: "cascade" | "restrict";
+};
+
+export const LixSchemaDefinition = {
+	$schema: "http://json-schema.org/draft-07/schema#",
+	title: "Lix Change Schema",
+	description:
+		"A JSON schema document that also includes custom x-key and x-version properties for identification and versioning.",
+	allOf: [
+		{
+			$ref: "http://json-schema.org/draft-07/schema#",
+		},
+		{
+			type: "object",
+			properties: {
+				"x-lix-unique": {
+					type: "array",
+					items: {
+						type: "array",
+						items: {
+							type: "string",
+						},
+					},
+				},
+				"x-primary-key": {
+					type: "array",
+					items: {
+						type: "string",
+					},
+				},
+				"x-lix-foreign-keys": {
+					type: "array",
+					items: {
+						type: "object",
+						required: ["properties", "references"],
+						properties: {
+							properties: {
+								type: "array",
+								minItems: 1,
+								items: { type: "string" },
+								description:
+									"Local JSON-schema property names that participate in the FK",
+							},
+							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" },
+										description:
+											"Remote property names (same length as local properties)",
+									},
+									schemaVersion: {
+										type: "string",
+										pattern: "^\\d+\\.\\d+$",
+										description: "Optional version of the referenced schema",
+									},
+								},
+							},
+							// 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)"
+							// },
+						},
+					},
+				},
+				"x-lix-key": {
+					type: "string",
+					description:
+						"The key of the schema. The key is used to identify the schema. You must use a unique key for each schema.",
+					examples: ["csv_plugin_cell"],
+				},
+				"x-lix-version": {
+					type: "string",
+					description:
+						"The version of the schema. Use the major version to signal breaking changes. Use the minor version to signal non-breaking changes.",
+					pattern: "^\\d+\\.\\d+$",
+					examples: ["1.0"],
+				},
+				properties: {
+					type: "object",
+					additionalProperties: {
+						allOf: [
+							{ $ref: "http://json-schema.org/draft-07/schema#" },
+							{
+								type: "object",
+								properties: {
+									"x-lix-generated": {
+										type: "boolean",
+										description:
+											"Whether this property is auto-generated by the database",
+									},
+								},
+							},
+						],
+					},
+				},
+			},
+			required: ["x-lix-key", "x-lix-version"],
+		},
+	],
+} as const;
+
+/**
+ * Extended property schema that includes Lix-specific extensions
+ */
+type LixPropertySchema = JSONSchema & {
+	"x-lix-generated"?: boolean;
+};
+
+/**
+ * LixSchema
+ *
+ * A superset of JSON Schema (draft-07) that includes Lix-specific metadata
+ * and supports custom extensions.
+ *
+ * Custom extensions may be added with any x-* prefix.
+ */
+export type LixSchemaDefinition = JSONSchema & {
+	/**
+	 * The key of the schema.
+	 *
+	 * The key is used to identify the schema. You must use a
+	 * unique key for each schema.
+	 *
+	 * @example
+	 *   "csv_plugin_cell"
+	 */
+	"x-lix-key": string;
+	/**
+	 * The version of the schema.
+	 *
+	 * Use the major version to signal breaking changes.
+	 * Use the minor version to signal non-breaking changes.
+	 *
+	 * @example
+	 *   "1.0"
+	 */
+	"x-lix-version": string;
+	"x-lix-primary-key"?: string[] | readonly string[];
+	/**
+	 * Properties that must be unique per version.
+	 *
+	 * Not to be confused by `x-version` which is used for versioning the schema.
+	 *
+	 *
+	 * @example
+	 *   {
+	 *     "x-lix-unique": [
+	 *       // the id must be unique
+	 *       ["id"],
+	 *       // the name and age must be unique as well
+	 *       ["name", "age"],
+	 *     ],
+	 *     properties: {
+	 *       id: { type: "string" },
+	 *       name: { type: "string" },
+	 *       age: { type: "number" },
+	 *     },
+	 *   }
+	 */
+	"x-lix-unique"?: string[][] | readonly (readonly string[])[];
+	/**
+	 * Foreign key constraints referencing other schemas.
+	 *
+	 * @example
+	 *   [
+	 *     {
+	 *       "properties": ["author_id"],
+	 *       "references": {
+	 *         "schemaKey": "user_profile",
+	 *         "properties": ["id"]
+	 *       }
+	 *     },
+	 *     {
+	 *       "properties": ["entity_id", "schema_key", "file_id"],
+	 *       "references": {
+	 *         "schemaKey": "state",
+	 *         "properties": ["entity_id", "schema_key", "file_id"]
+	 *       }
+	 *     }
+	 *   ]
+	 */
+	"x-lix-foreign-keys"?: LixForeignKey[] | readonly LixForeignKey[];
+	type: "object";
+	properties?: {
+		[key: string]: LixPropertySchema;
+	};
+};
+
+/**
+ * Marker type for database columns that are auto-generated.
+ *
+ * This type brands values as "generated" to enable special handling in insert/update
+ * operations. Generated fields become optional in inserts since the database
+ * provides default values.
+ *
+ * The type accepts T values directly for developer convenience while preserving
+ * the generated marker for type transformations.
+ *
+ * @example
+ * ```typescript
+ * type Account = {
+ *   id: LixGenerated<string>;  // Auto-generated UUID
+ *   name: string;              // User-provided
+ *   created_at: LixGenerated<string>;  // Auto-generated timestamp
+ * };
+ *
+ * // In inserts, generated fields are optional
+ * const newAccount: LixInsertable<Account> = {
+ *   name: "John"  // id and created_at are optional
+ * };
+ * ```
+ */
+export type LixGenerated<T> = T & {
+	readonly __lixGenerated?: true;
+};
+
+/**
+ * Check if a type has the LixGenerated brand
+ */
+type IsLixGenerated<T> = T extends { readonly __lixGenerated?: true }
+	? true
+	: false;
+
+/**
+ * Extract the base type from LixGenerated<T>
+ * Since LixGenerated<T> = T & { brand }, we need to extract T
+ */
+type ExtractFromGenerated<T> = T extends LixGenerated<infer U> ? U : T;
+
+/**
+ * Extract the select type from LixGenerated or return the type as-is
+ */
+type SelectType<T> = ExtractFromGenerated<T>;
+
+/**
+ * Extract the insert type from LixGenerated or return the type as-is
+ */
+type InsertType<T> =
+	IsLixGenerated<T> extends true ? ExtractFromGenerated<T> | undefined : T;
+
+/**
+ * Extract the update type from LixGenerated or return the type as-is
+ */
+type UpdateType<T> = ExtractFromGenerated<T>;
+
+/**
+ * Evaluates to K if T can be null or undefined
+ */
+type IfNullable<T, K> = undefined extends T ? K : null extends T ? K : never;
+
+/**
+ * Evaluates to K if T can't be null or undefined
+ */
+type IfNotNullable<T, K> = undefined extends T
+	? never
+	: null extends T
+		? never
+		: T extends never
+			? never
+			: K;
+
+/**
+ * Keys whose InsertType can be null or undefined (optional in inserts)
+ */
+type NullableInsertKeys<T> = {
+	[K in keyof T]: IfNullable<InsertType<T[K]>, K>;
+}[keyof T];
+
+/**
+ * Keys whose InsertType can't be null or undefined (required in inserts)
+ */
+type NonNullableInsertKeys<T> = {
+	[K in keyof T]: IfNotNullable<InsertType<T[K]>, K>;
+}[keyof T];
+
+/**
+ * Transform a type for insert operations.
+ *
+ * This type makes LixGenerated fields optional while keeping other required
+ * fields mandatory. Use this when defining types for creating new entities.
+ *
+ * The database will automatically populate generated fields (like IDs,
+ * timestamps) if not provided.
+ *
+ * @example
+ * ```typescript
+ * type Account = {
+ *   id: LixGenerated<string>;
+ *   name: string;
+ *   email: string;
+ *   created_at: LixGenerated<string>;
+ * };
+ *
+ * type NewAccount = LixInsertable<Account>;
+ * // Result: { name: string; email: string; id?: string; created_at?: string; }
+ *
+ * const account: NewAccount = {
+ *   name: "John",
+ *   email: "john@example.com"
+ *   // id and created_at are optional
+ * };
+ * ```
+ */
+export type LixInsertable<T> = {
+	[K in NonNullableInsertKeys<T>]: InsertType<T[K]>;
+} & {
+	[K in NullableInsertKeys<T>]?: InsertType<T[K]>;
+};
+
+/**
+ * Transform a type for update operations.
+ *
+ * This type makes all fields optional, allowing partial updates where you
+ * only specify the fields you want to change. LixGenerated markers are
+ * removed since you're providing explicit values.
+ *
+ * The database preserves existing values for any fields not included
+ * in the update.
+ *
+ * @example
+ * ```typescript
+ * type Account = {
+ *   id: LixGenerated<string>;
+ *   name: string;
+ *   email: string;
+ *   updated_at: LixGenerated<string>;
+ * };
+ *
+ * type AccountUpdate = LixUpdateable<Account>;
+ * // Result: { id?: string; name?: string; email?: string; updated_at?: string; }
+ *
+ * // Update only the email
+ * const updates: AccountUpdate = {
+ *   email: "newemail@example.com"
+ *   // Other fields remain unchanged
+ * };
+ * ```
+ */
+export type LixUpdateable<T> = {
+	[K in keyof T]?: UpdateType<T[K]>;
+};
+
+/**
+ * Transform a type for select/query operations.
+ *
+ * This type unwraps all LixGenerated markers, giving you the actual runtime
+ * types that will be returned from database queries. All fields are required
+ * and have their base types.
+ *
+ * Use this type when defining the shape of data returned from queries or
+ * when passing entity data to UI components.
+ *
+ * @example
+ * ```typescript
+ * type Account = {
+ *   id: LixGenerated<string>;
+ *   name: string;
+ *   email: string;
+ *   created_at: LixGenerated<string>;
+ * };
+ *
+ * type AccountData = LixSelectable<Account>;
+ * // Result: { id: string; name: string; email: string; created_at: string; }
+ *
+ * // Query results have this shape
+ * const accounts: AccountData[] = await db
+ *   .selectFrom("account")
+ *   .selectAll()
+ *   .execute();
+ *
+ * console.log(accounts[0].id);  // string (not LixGenerated<string>)
+ * ```
+ */
+export type LixSelectable<T> = {
+	[K in keyof T]: SelectType<T[K]>;
+};
+
+/**
+ * Transform object types with no properties from unknown to Record<string, any>
+ */
+type TransformEmptyObject<T> = T extends { [x: string]: unknown }
+	? Record<string, any>
+	: T;
+
+/**
+ * Check if a schema property is an empty object type (no properties defined)
+ */
+type IsEmptyObjectSchema<P> = P extends { type: "object" }
+	? P extends { properties: any }
+		? false
+		: true
+	: false;
+
+/**
+ * Get the nullable part of a type based on schema
+ */
+type GetNullablePart<P> = P extends { nullable: true } ? null : never;
+
+/**
+ * Internal type that applies LixGenerated markers to properties with x-lix-generated: true
+ */
+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 }
+					? LixGenerated<TransformEmptyObject<FromSchema<TSchema>[K]>>
+					: IsEmptyObjectSchema<Props[K]> extends true
+						? Record<string, any> | GetNullablePart<Props[K]>
+						: TransformEmptyObject<FromSchema<TSchema>[K]>
+				: TransformEmptyObject<FromSchema<TSchema>[K]>;
+		}
+	: never;
+
+/**
+ * Convert a LixSchemaDefinition to a TypeScript type.
+ *
+ * This type transformation:
+ * 1. Converts JSON Schema properties to TypeScript types
+ * 2. Wraps properties with `x-lix-generated: true` in LixGenerated markers
+ * 3. Transforms `type: "object"` without properties to `Record<string, any>`
+ *
+ * The resulting type can be used with LixInsertable, LixUpdateable, and
+ * LixSelectable for database operations.
+ *
+ * @example
+ * ```typescript
+ * const AccountSchema = {
+ *   "x-lix-key": "account",
+ *   "x-lix-version": "1.0",
+ *   "x-lix-primary-key": ["id"],
+ *   type: "object",
+ *   properties: {
+ *     id: { type: "string", "x-lix-generated": true },
+ *     name: { type: "string" },
+ *     email: { type: "string" },
+ *     metadata: { type: "object" },  // Becomes Record<string, any>
+ *     created_at: { type: "string", "x-lix-generated": true }
+ *   },
+ *   required: ["id", "name", "email"],
+ *   additionalProperties: false
+ * } as const satisfies LixSchemaDefinition;
+ *
+ * type Account = FromLixSchemaDefinition<typeof AccountSchema>;
+ * // Result: {
+ * //   id: LixGenerated<string>;
+ * //   name: string;
+ * //   email: string;
+ * //   metadata: Record<string, any> | undefined;
+ * //   created_at: LixGenerated<string> | undefined;
+ * // }
+ * ```
+ */
+export type FromLixSchemaDefinition<T extends LixSchemaDefinition> =
+	ApplyLixGenerated<T>;

package/src/schema-definition/index.ts

@@ -0,0 +1,13 @@
+export {
+	LixSchemaDefinition,
+	type FromLixSchemaDefinition,
+	type LixGenerated,
+	type LixInsertable,
+	type LixUpdateable,
+	type LixSelectable,
+} from "./definition.js";
+export { JSONTypeSchema, type JSONType } from "./json-type.js";
+export {
+	validateLixSchema,
+	validateLixSchemaDefinition,
+} from "./validate-lix-schema.js";

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

@@ -0,0 +1,30 @@
+import { expect, it } from "vitest";
+import { isJsonType } from "./json-type.js";
+
+it("detects type: 'object'", () => {
+	expect(isJsonType({ type: "object" })).toBe(true);
+	expect(isJsonType({ type: ["object", "null"] })).toBe(true);
+});
+
+it("detects type: 'array'", () => {
+	expect(isJsonType({ type: "array" })).toBe(true);
+	expect(isJsonType({ type: ["array", "null"] })).toBe(true);
+});
+
+it("detects anyOf with object or array", () => {
+	expect(isJsonType({ anyOf: [{ type: "object" }, { type: "string" }] })).toBe(
+		true
+	);
+	expect(isJsonType({ anyOf: [{ type: "array" }, { type: "number" }] })).toBe(
+		true
+	);
+	expect(isJsonType({ anyOf: [{ type: "boolean" }, { type: "null" }] })).toBe(
+		false
+	);
+});
+
+it("returns false for non-json types", () => {
+	expect(isJsonType({ type: "string" })).toBe(false);
+	expect(isJsonType({ type: ["number", "null"] })).toBe(false);
+	expect(isJsonType({})).toBe(false);
+});

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

@@ -0,0 +1,53 @@
+export type JSONType =
+	| string
+	| number
+	| boolean
+	| null
+	| JSONType[]
+	| { [key: string]: JSONType };
+
+/**
+ * JSON schema definition for JSON values (object, array, string, number, boolean, null).
+ *
+ * @example
+ *   const MySchema = {
+ *     type: "object",
+ *     properties: {
+ *       myJsonField: JSONTypeSchema,
+ *     },
+ *   }
+ */
+export const JSONTypeSchema: Record<string, any> = {
+	anyOf: [
+		{ type: "object" },
+		{ type: "array" },
+		{ type: "string" },
+		{ type: "number" },
+		{ type: "boolean" },
+		{ type: "null" },
+	],
+};
+
+/**
+ * Determines if a JSON schema property definition allows JSON values (object or array).
+ *
+ * Returns true if the definition's `type` is "object" or "array" (including arrays of types),
+ * or if any `anyOf` subschemas specify `type: "object"` or `type: "array"`.
+ * Used to identify columns that should be treated as JSON in the database layer.
+ */
+export function isJsonType(def: any): boolean {
+	// Handles type: "object" or "array", or anyOf: [{type:...}]
+	if (def.type) {
+		const types = Array.isArray(def.type) ? def.type : [def.type];
+		if (types.includes("object") || types.includes("array")) return true;
+	}
+	if (Array.isArray(def.anyOf)) {
+		if (
+			def.anyOf.some(
+				(sub: any) => sub.type === "object" || sub.type === "array"
+			)
+		)
+			return true;
+	}
+	return false;
+}

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

@@ -0,0 +1,94 @@
+import { test, expect } from "vitest";
+import {
+	validateLixSchema,
+	validateLixSchemaDefinition,
+} from "./validate-lix-schema.js";
+
+test("validateLixSchemaDefinition passes for valid Lix schema", () => {
+	const validSchema = {
+		"x-lix-key": "test_entity",
+		"x-lix-version": "1.0",
+		type: "object",
+		properties: {
+			id: { type: "string" },
+		},
+	};
+
+	expect(() => validateLixSchemaDefinition(validSchema)).not.toThrow();
+	expect(validateLixSchemaDefinition(validSchema)).toBe(true);
+});
+
+test("validateLixSchemaDefinition throws for invalid schema", () => {
+	const invalidSchema = {
+		"x-lix-version": "1.0",
+		type: "object",
+		properties: {
+			id: { type: "string" },
+		},
+		// Missing required x-lix-key
+	};
+
+	expect(() => validateLixSchemaDefinition(invalidSchema)).toThrow(
+		"Invalid Lix schema definition"
+	);
+});
+
+test("validateLixSchema validates both schema and data successfully", () => {
+	const schema = {
+		"x-lix-key": "user",
+		"x-lix-version": "1.0",
+		type: "object",
+		properties: {
+			id: { type: "string" },
+			name: { type: "string" },
+		},
+		required: ["id", "name"],
+	};
+
+	const validData = {
+		id: "123",
+		name: "John Doe",
+	};
+
+	expect(() => validateLixSchema(schema, validData)).not.toThrow();
+	expect(validateLixSchema(schema, validData)).toBe(true);
+});
+
+test("validateLixSchema throws when schema is invalid", () => {
+	const invalidSchema = {
+		// Missing x-lix-key
+		"x-lix-version": "1.0",
+		type: "object",
+		properties: {
+			id: { type: "string" },
+		},
+	};
+
+	const data = { id: "123" };
+
+	expect(() => validateLixSchema(invalidSchema, data)).toThrow(
+		"Invalid Lix schema definition"
+	);
+});
+
+test("validateLixSchema throws when data doesn't match schema", () => {
+	const schema = {
+		"x-lix-key": "user",
+		"x-lix-version": "1.0",
+		type: "object",
+		properties: {
+			id: { type: "string" },
+			name: { type: "string" },
+		},
+		required: ["id", "name"],
+	};
+
+	const invalidData = {
+		id: "123",
+		// Missing required 'name' field
+	};
+
+	expect(() => validateLixSchema(schema, invalidData)).toThrow(
+		"Data validation failed"
+	);
+});