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

package/src/schema-definition/definition.test-d.ts

@@ -0,0 +1,253 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+import type {
+	LixSchemaDefinition,
+	FromLixSchemaDefinition,
+	LixGenerated,
+	LixInsertable,
+	LixSelectable,
+	LixUpdateable,
+} from "./definition.js";
+import { test, assertType } from "vitest";
+
+test("a json change schema should be infer the properties", () => {
+	const jsonChangeSchema = {
+		"x-lix-version": "1.0",
+		"x-lix-key": "mock",
+		type: "object",
+		properties: {
+			name: { type: "string" },
+			age: { type: "number" },
+			location: { type: "object" },
+		},
+		required: ["name", "age", "location"],
+		additionalProperties: false,
+	} as const satisfies LixSchemaDefinition;
+
+	const snapshot: FromLixSchemaDefinition<typeof jsonChangeSchema> = {
+		name: "John",
+		age: 5,
+		location: {
+			city: "New York",
+			country: "USA",
+		},
+	};
+
+	assertType<{
+		name: string;
+		age: number;
+		location: {
+			[x: string]: unknown;
+		};
+	}>(snapshot);
+});
+
+test("LixInsertable combined with LixGenerated makes columns optional", () => {
+	type MockType = {
+		id: LixGenerated<string>;
+		name: string;
+	};
+
+	// pass (all properties are provided)
+	const z: LixInsertable<MockType> = {
+		id: "123",
+		name: "Test",
+	} satisfies LixInsertable<MockType>;
+
+	// pass (LixGenerated makes id optional)
+	const a: LixInsertable<MockType> = {
+		name: "Test",
+	};
+
+	// @ts-expect-error - Name is required in MockType
+	const x: LixInsertable<MockType> = {};
+
+	// @ts-expect-error - Name is required in MockType
+	const y: LixInsertable<MockType> = {
+		id: "123",
+	};
+});
+
+test("LixSelectable unwraps LixGenerated fields to their base types", () => {
+	type MockType = {
+		id: LixGenerated<string>;
+		name: string;
+		count: LixGenerated<number>;
+		metadata: { foo: string };
+	};
+
+	// All fields should be present and LixGenerated should be unwrapped
+	const selected: LixSelectable<MockType> = {
+		id: "123",
+		name: "Test",
+		count: 42,
+		metadata: { foo: "bar" },
+	} satisfies LixSelectable<MockType>;
+
+	// Type checking - all fields are required
+	// @ts-expect-error - All fields are required in selectable
+	const missing1: LixSelectable<MockType> = {
+		id: "123",
+		name: "Test",
+		count: 42,
+		// missing metadata
+	};
+
+	// @ts-expect-error - All fields are required in selectable
+	const missing2: LixSelectable<MockType> = {
+		// missing id
+		name: "Test",
+		count: 42,
+		metadata: { foo: "bar" },
+	};
+
+	// @ts-expect-error - All fields are required in selectable
+	const missing3: LixSelectable<MockType> = {
+		id: "123",
+		// missing name
+		count: 42,
+		metadata: { foo: "bar" },
+	};
+
+	// Verify types are correctly unwrapped
+	type IdType = LixSelectable<MockType>["id"]; // Should be string, not LixGenerated<string>
+	type CountType = LixSelectable<MockType>["count"]; // Should be number, not LixGenerated<number>
+
+	const idValue: IdType = "test";
+	const countValue: CountType = 123;
+});
+
+test("LixUpdateable makes all fields optional and unwraps LixGenerated", () => {
+	type MockType = {
+		id: LixGenerated<string>;
+		name: string;
+		count: LixGenerated<number>;
+		metadata: { foo: string };
+		optional?: string;
+	};
+
+	// All fields should be optional in updates
+	const update1: LixUpdateable<MockType> = {}; // Empty object is valid
+
+	const update2: LixUpdateable<MockType> = {
+		id: "new-id",
+	};
+
+	const update3: LixUpdateable<MockType> = {
+		name: "Updated Name",
+	};
+
+	const update4: LixUpdateable<MockType> = {
+		count: 100,
+	};
+
+	const update5: LixUpdateable<MockType> = {
+		metadata: { foo: "updated" },
+	};
+
+	const update6: LixUpdateable<MockType> = {
+		optional: "now set",
+	};
+
+	// Can update multiple fields at once
+	const update7: LixUpdateable<MockType> = {
+		id: "new-id",
+		name: "New Name",
+		count: 99,
+		metadata: { foo: "baz" },
+		optional: "value",
+	};
+
+	// Verify that LixGenerated fields are unwrapped
+	type UpdateIdType = LixUpdateable<MockType>["id"]; // Should be string | undefined
+	type UpdateCountType = LixUpdateable<MockType>["count"]; // Should be number | undefined
+	type UpdateNameType = LixUpdateable<MockType>["name"]; // Should be string | undefined
+
+	// These should all work since fields are optional
+	const idUpdate: UpdateIdType = undefined;
+	const countUpdate: UpdateCountType = undefined;
+	const nameUpdate: UpdateNameType = undefined;
+
+	// But when provided, must be correct type
+	const wrongType1: LixUpdateable<MockType> = {
+		// @ts-expect-error - id must be string when provided
+		id: 123,
+	};
+
+	const wrongType2: LixUpdateable<MockType> = {
+		// @ts-expect-error - count must be number when provided
+		count: "not a number",
+	};
+
+	const wrongType3: LixUpdateable<MockType> = {
+		// @ts-expect-error - metadata must match structure when provided
+		metadata: { bar: "wrong key" },
+	};
+});
+
+test("FromLixSchemaDefinition transforms schema with x-lix-generated to LixGenerated types", () => {
+	// Define a test schema with x-lix-generated properties
+	const TestSchema = {
+		"x-lix-key": "test_entity",
+		"x-lix-version": "1.0",
+		"x-lix-primary-key": ["id"],
+		type: "object",
+		properties: {
+			id: {
+				type: "string",
+				"x-lix-generated": true,
+			},
+			name: {
+				type: "string",
+			},
+		},
+		required: ["id", "name"],
+		additionalProperties: false,
+	} as const satisfies LixSchemaDefinition;
+
+	type TestEntity = FromLixSchemaDefinition<typeof TestSchema>;
+
+	// Test with LixInsertable - generated fields should be optional
+	const insertable: LixInsertable<TestEntity> = {
+		// id is optional
+		name: "test",
+	};
+
+	// Can also provide generated fields
+	const insertableWithGenerated: LixInsertable<TestEntity> = {
+		id: "custom-id",
+		name: "test",
+	};
+});
+
+test("FromLixSchemaDefinition transforms empty object types to Record<string, any>", () => {
+	const TestSchema = {
+		"x-lix-key": "test_entity",
+		"x-lix-version": "1.0",
+		"x-lix-primary-key": ["id"],
+		type: "object",
+		properties: {
+			id: { type: "string" },
+			metadata: { type: "object" },
+			config: { type: "object", nullable: true },
+		},
+		required: ["id", "metadata"],
+		additionalProperties: false,
+	} as const satisfies LixSchemaDefinition;
+
+	type TestEntity = FromLixSchemaDefinition<typeof TestSchema>;
+
+	// Test that metadata is Record<string, any>
+	const entity: TestEntity = {
+		id: "test",
+		metadata: {
+			author: "test-user",
+			created_at: new Date().toISOString(),
+			nested: { deep: { value: 123 } },
+		},
+		config: null,
+	};
+
+	// Verify types
+	assertType<Record<string, any>>(entity.metadata);
+	assertType<Record<string, any> | null | undefined>(entity.config);
+});

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

@@ -0,0 +1,377 @@
+import { test, expect } from "vitest";
+import { Ajv } from "ajv";
+import { LixSchemaDefinition } from "./definition.js";
+
+const ajv = new Ajv();
+
+test("valid schema", () => {
+	const schema = {
+		type: "object",
+		"x-lix-key": "mock",
+		"x-lix-version": "1.0",
+		properties: {
+			name: { type: "string" },
+		},
+		required: ["name"],
+		additionalProperties: false,
+	} as const satisfies LixSchemaDefinition;
+
+	const valid = ajv.validate(LixSchemaDefinition, schema);
+	const x2 = ajv.compile(LixSchemaDefinition);
+
+	const valid2 = x2(schema);
+
+	expect(valid).toBe(true);
+	expect(valid2).toBe(true);
+});
+
+test("x-key is required", () => {
+	const schema = {
+		type: "object",
+		// @ts-expect-error - invalid
+		"x-lix-key": undefined,
+		"x-lix-version": "1.0",
+		properties: {
+			name: { type: "string" },
+		},
+		required: ["name"],
+		additionalProperties: false,
+	} as const satisfies LixSchemaDefinition;
+
+	const valid = ajv.validate(LixSchemaDefinition, schema);
+
+	expect(valid).toBe(false);
+});
+
+test("x-lix-unique is optional", () => {
+	const schema = {
+		type: "object",
+		"x-lix-key": "mock",
+		"x-lix-version": "1.0",
+		properties: {
+			name: { type: "string" },
+		},
+		required: ["name"],
+		additionalProperties: false,
+	} as const satisfies LixSchemaDefinition;
+
+	const valid = ajv.validate(LixSchemaDefinition, schema);
+
+	expect(valid).toBe(true);
+});
+
+test("x-lix-unique must be array of arrays when present", () => {
+	const schema = {
+		type: "object",
+		"x-lix-key": "mock",
+		"x-lix-version": "1.0",
+		"x-lix-unique": [["id"], ["name", "age"]],
+		properties: {
+			id: { type: "string" },
+			name: { type: "string" },
+			age: { type: "number" },
+		},
+		required: ["id", "name", "age"],
+		additionalProperties: false,
+	} as const satisfies LixSchemaDefinition;
+
+	const valid = ajv.validate(LixSchemaDefinition, schema);
+
+	expect(valid).toBe(true);
+});
+
+test("x-lix-unique fails with invalid structure (not array of arrays)", () => {
+	const schema = {
+		type: "object",
+		"x-lix-key": "mock",
+		"x-lix-version": "1.0",
+		"x-lix-unique": ["id", "name"],
+		properties: {
+			id: { type: "string" },
+			name: { type: "string" },
+		},
+		required: ["id", "name"],
+		additionalProperties: false,
+	};
+
+	const valid = ajv.validate(LixSchemaDefinition, schema);
+
+	expect(valid).toBe(false);
+});
+
+test("x-lix-primary-key is optional", () => {
+	const schema = {
+		type: "object",
+		"x-lix-key": "mock",
+		"x-lix-version": "1.0",
+		properties: {
+			name: { type: "string" },
+		},
+		required: ["name"],
+		additionalProperties: false,
+	} as const satisfies LixSchemaDefinition;
+
+	const valid = ajv.validate(LixSchemaDefinition, schema);
+
+	expect(valid).toBe(true);
+});
+
+test("x-lix-primary-key must be array of strings when present", () => {
+	const schema = {
+		type: "object",
+		"x-lix-key": "mock",
+		"x-lix-version": "1.0",
+		"x-lix-primary-key": ["id", "version"],
+		properties: {
+			id: { type: "string" },
+			version: { type: "string" },
+			name: { type: "string" },
+		},
+		required: ["id", "version", "name"],
+		additionalProperties: false,
+	} as const satisfies LixSchemaDefinition;
+
+	const valid = ajv.validate(LixSchemaDefinition, schema);
+
+	expect(valid).toBe(true);
+});
+
+test("x-lix-foreign-keys is optional", () => {
+	const schema = {
+		type: "object",
+		"x-lix-key": "blog_post",
+		"x-lix-version": "1.0",
+		properties: {
+			id: { type: "string" },
+			author_id: { type: "string" },
+		},
+		required: ["id", "author_id"],
+		additionalProperties: false,
+	} as const satisfies LixSchemaDefinition;
+
+	const valid = ajv.validate(LixSchemaDefinition, schema);
+
+	expect(valid).toBe(true);
+});
+
+test("x-lix-foreign-keys with valid structure", () => {
+	const schema = {
+		type: "object",
+		"x-lix-key": "blog_post",
+		"x-lix-version": "1.0",
+		"x-lix-foreign-keys": {
+			author_id: {
+				schemaKey: "user_profile",
+				property: "id",
+			},
+			category_id: {
+				schemaKey: "post_category",
+				property: "id",
+			},
+		},
+		properties: {
+			id: { type: "string" },
+			author_id: { type: "string" },
+			category_id: { type: "string" },
+		},
+		required: ["id", "author_id", "category_id"],
+		additionalProperties: false,
+	} as const satisfies LixSchemaDefinition;
+
+	const valid = ajv.validate(LixSchemaDefinition, schema);
+
+	expect(valid).toBe(true);
+});
+
+test("x-lix-foreign-keys with schemaVersion", () => {
+	const schema = {
+		type: "object",
+		"x-lix-key": "comment",
+		"x-lix-version": "1.0",
+		"x-lix-foreign-keys": {
+			post_id: {
+				schemaKey: "blog_post",
+				property: "id",
+				schemaVersion: "1.0",
+			},
+		},
+		properties: {
+			id: { type: "string" },
+			post_id: { type: "string" },
+			content: { type: "string" },
+		},
+		required: ["id", "post_id", "content"],
+		additionalProperties: false,
+	} as const satisfies LixSchemaDefinition;
+
+	const valid = ajv.validate(LixSchemaDefinition, schema);
+
+	expect(valid).toBe(true);
+});
+
+test("x-lix-foreign-keys fails without required fields", () => {
+	const schema = {
+		type: "object",
+		"x-lix-key": "blog_post",
+		"x-lix-version": "1.0",
+		"x-lix-foreign-keys": {
+			author_id: {
+				schemaKey: "user_profile",
+				// Missing required "property" field
+			},
+		},
+		properties: {
+			id: { type: "string" },
+			author_id: { type: "string" },
+		},
+		required: ["id", "author_id"],
+		additionalProperties: false,
+	};
+
+	const valid = ajv.validate(LixSchemaDefinition, schema);
+
+	expect(valid).toBe(false);
+});
+
+test("x-lix-foreign-keys fails with invalid schemaVersion format", () => {
+	const schema = {
+		type: "object",
+		"x-lix-key": "comment",
+		"x-lix-version": "1.0",
+		"x-lix-foreign-keys": {
+			post_id: {
+				schemaKey: "blog_post",
+				property: "id",
+				schemaVersion: "v1.0.0", // Invalid format
+			},
+		},
+		properties: {
+			id: { type: "string" },
+			post_id: { type: "string" },
+		},
+		required: ["id", "post_id"],
+		additionalProperties: false,
+	};
+
+	const valid = ajv.validate(LixSchemaDefinition, schema);
+
+	expect(valid).toBe(false);
+});
+
+test("x-version is required", () => {
+	const schema = {
+		type: "object",
+		// @ts-expect-error - invalid
+		"x-lix-version": undefined,
+		"x-lix-key": "mock",
+		properties: {
+			name: { type: "string" },
+		},
+		required: ["name"],
+		additionalProperties: false,
+	} as const satisfies LixSchemaDefinition;
+
+	const valid = ajv.validate(LixSchemaDefinition, schema);
+
+	expect(valid).toBe(false);
+});
+
+test("x-lix-unique is optional", () => {
+	const schema = {
+		type: "object",
+		"x-lix-key": "mock",
+		"x-lix-version": "1.0",
+		properties: {
+			name: { type: "string" },
+		},
+		required: ["name"],
+		additionalProperties: false,
+	} as const satisfies LixSchemaDefinition;
+
+	const valid = ajv.validate(LixSchemaDefinition, schema);
+
+	expect(valid).toBe(true);
+});
+
+test("x-lix-unique must be array of arrays when present", () => {
+	const schema = {
+		type: "object",
+		"x-lix-key": "mock",
+		"x-lix-version": "1.0",
+		"x-lix-unique": [["id"], ["name", "age"]],
+		properties: {
+			id: { type: "string" },
+			name: { type: "string" },
+			age: { type: "number" },
+		},
+		required: ["id", "name", "age"],
+		additionalProperties: false,
+	} as const satisfies LixSchemaDefinition;
+
+	const valid = ajv.validate(LixSchemaDefinition, schema);
+
+	expect(valid).toBe(true);
+});
+
+test("x-lix-unique fails with invalid structure (not array of arrays)", () => {
+	const schema = {
+		type: "object",
+		"x-lix-key": "mock",
+		"x-lix-version": "1.0",
+		"x-lix-unique": ["id", "name"],
+		properties: {
+			id: { type: "string" },
+			name: { type: "string" },
+		},
+		required: ["id", "name"],
+		additionalProperties: false,
+	};
+
+	const valid = ajv.validate(LixSchemaDefinition, schema);
+
+	expect(valid).toBe(false);
+});
+
+test("x-lix-generated property is allowed in schema definition", () => {
+	// Test that schemas with x-lix-generated compile correctly
+	const TestSchemaWithGenerated = {
+		"x-lix-key": "test_entity",
+		"x-lix-version": "1.0",
+		"x-lix-primary-key": ["id"],
+		type: "object",
+		properties: {
+			id: {
+				type: "string",
+				description: "The unique identifier",
+				"x-lix-generated": true,
+			},
+		},
+		required: ["id"],
+		additionalProperties: false,
+	} as const;
+	TestSchemaWithGenerated satisfies LixSchemaDefinition;
+
+	// Validate with Ajv
+	const valid = ajv.validate(LixSchemaDefinition, TestSchemaWithGenerated);
+	expect(valid).toBe(true);
+
+	// Test that x-lix-generated can be false
+	const TestSchemaWithExplicitFalse = {
+		"x-lix-key": "test_entity2",
+		"x-lix-version": "1.0",
+		"x-lix-primary-key": ["id"],
+		type: "object",
+		properties: {
+			id: {
+				type: "string",
+				"x-lix-generated": false,
+			},
+		},
+		required: ["id"],
+		additionalProperties: false,
+	} as const;
+
+	TestSchemaWithExplicitFalse satisfies LixSchemaDefinition;
+	const valid2 = ajv.validate(LixSchemaDefinition, TestSchemaWithExplicitFalse);
+	expect(valid2).toBe(true);
+});