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

package/src/entity-views/entity-view-builder.test.ts

@@ -0,0 +1,293 @@
+import { test, expect, describe } from "vitest";
+import { openLix } from "../lix/open-lix.js";
+import { createEntityViewsIfNotExists } from "./entity-view-builder.js";
+import type { LixSchemaDefinition } from "../schema-definition/definition.js";
+
+describe("createEntityViewsIfNotExists (Integration)", () => {
+	const testSchema: LixSchemaDefinition = {
+		"x-lix-key": "test_entity",
+		"x-lix-version": "1.0",
+		"x-lix-primary-key": ["id"],
+		type: "object",
+		properties: {
+			id: { type: "string" },
+			name: { type: "string" },
+			value: { type: "number" },
+		},
+		required: ["id", "name"],
+	} as const;
+
+	test("should create all three views: active, _all, and _history", async () => {
+		const lix = await openLix({});
+
+		// Add stored schema
+		const mockSchema: LixSchemaDefinition = {
+			"x-lix-key": "test_entity",
+			"x-lix-version": "1.0",
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				name: { type: "string" },
+				value: { type: "number" },
+			},
+		};
+
+		await lix.db
+			.insertInto("stored_schema")
+			.values({ value: mockSchema })
+			.execute();
+
+		createEntityViewsIfNotExists({
+			lix,
+			schema: testSchema,
+			overrideName: "triple_test",
+			pluginKey: "test_plugin",
+			hardcodedFileId: "test_file",
+		});
+
+		// Insert data through primary view
+		await lix.db
+			.insertInto("triple_test" as any)
+			.values({ id: "test_id", name: "test_name", value: 42 })
+			.execute();
+
+		// All three views should be queryable
+		const activeResult = await lix.db
+			.selectFrom("triple_test" as any)
+			.selectAll()
+			.execute();
+
+		const allResult = await lix.db
+			.selectFrom("triple_test_all" as any)
+			.selectAll()
+			.execute();
+
+		// Get the active version's change set to query history
+		const activeVersion = await lix.db
+			.selectFrom("active_version")
+			.innerJoin("version", "active_version.version_id", "version.id")
+			.select("version.change_set_id")
+			.executeTakeFirstOrThrow();
+
+		const historyResult = await lix.db
+			.selectFrom("triple_test_history" as any)
+			.where("lixcol_change_set_id", "=", activeVersion.change_set_id)
+			.selectAll()
+			.execute();
+
+		// All views should return data
+		expect(activeResult).toHaveLength(1);
+		expect(allResult).toHaveLength(1);
+		expect(historyResult).toHaveLength(1);
+
+		// Verify business data consistency across all views
+		expect(activeResult[0]).toMatchObject({
+			id: "test_id",
+			name: "test_name",
+			value: 42,
+		});
+		expect(allResult[0]).toMatchObject({
+			id: "test_id",
+			name: "test_name",
+			value: 42,
+		});
+		expect(historyResult[0]).toMatchObject({
+			id: "test_id",
+			name: "test_name",
+			value: 42,
+		});
+
+		// Verify column differences between views
+		expect(activeResult[0]).not.toHaveProperty("lixcol_version_id"); // Primary view hides version_id
+		expect(allResult[0]).toHaveProperty("lixcol_version_id"); // _all view exposes version_id
+		expect(historyResult[0]).toHaveProperty("lixcol_change_set_id"); // _history view has history columns
+		expect(historyResult[0]).toHaveProperty("lixcol_depth", 0); // Current state is at depth 0
+	});
+
+	test("should handle cross-view operations", async () => {
+		const lix = await openLix({});
+
+		// Add stored schema
+		const mockSchema: LixSchemaDefinition = {
+			"x-lix-key": "test_entity",
+			"x-lix-version": "1.0",
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				name: { type: "string" },
+				value: { type: "number" },
+			},
+		};
+
+		await lix.db
+			.insertInto("stored_schema")
+			.values({ value: mockSchema })
+			.execute();
+
+		createEntityViewsIfNotExists({
+			lix,
+			schema: testSchema,
+			overrideName: "cross_test",
+			pluginKey: "test_plugin",
+			hardcodedFileId: "test_file",
+		});
+
+		// Insert through _all view
+		await lix.db
+			.insertInto("cross_test_all" as any)
+			.values({
+				id: "test_id",
+				name: "test_name",
+				value: 42,
+				lixcol_version_id: lix.db
+					.selectFrom("active_version")
+					.select("version_id"),
+			})
+			.execute();
+
+		// Update through primary view
+		await lix.db
+			.updateTable("cross_test" as any)
+			.where("id", "=", "test_id")
+			.set({ name: "updated_name", value: 100 })
+			.execute();
+
+		// Update again to create history
+		await lix.db
+			.updateTable("cross_test" as any)
+			.where("id", "=", "test_id")
+			.set({ name: "final_name", value: 200 })
+			.execute();
+
+		// Verify update in both CRUD views
+		const primaryResult = await lix.db
+			.selectFrom("cross_test" as any)
+			.selectAll()
+			.execute();
+
+		const allResult = await lix.db
+			.selectFrom("cross_test_all" as any)
+			.selectAll()
+			.execute();
+
+		expect(primaryResult[0]).toMatchObject({ name: "final_name", value: 200 });
+		expect(allResult[0]).toMatchObject({ name: "final_name", value: 200 });
+
+		// Verify history view shows current state and can access historical data
+		const activeVersion = await lix.db
+			.selectFrom("active_version")
+			.innerJoin("version", "active_version.version_id", "version.id")
+			.select("version.change_set_id")
+			.executeTakeFirstOrThrow();
+
+		const historyResult = await lix.db
+			.selectFrom("cross_test_history" as any)
+			.where("entity_id", "=", "test_id")
+			.where("lixcol_change_set_id", "=", activeVersion.change_set_id)
+			.orderBy("lixcol_depth", "asc")
+			.selectAll()
+			.execute();
+
+		expect(historyResult.length).toBeGreaterThan(0);
+
+		// Current state should be at depth 0
+		const currentState = historyResult.find((h: any) => h.lixcol_depth === 0);
+		expect(currentState).toBeDefined();
+		expect(currentState).toMatchObject({
+			name: "final_name",
+			value: 200,
+		});
+
+		// Delete through primary view
+		await lix.db
+			.deleteFrom("cross_test" as any)
+			.where("id", "=", "test_id")
+			.execute();
+
+		// Verify deletion in both CRUD views
+		const afterDeletePrimary = await lix.db
+			.selectFrom("cross_test" as any)
+			.selectAll()
+			.execute();
+
+		const afterDeleteAll = await lix.db
+			.selectFrom("cross_test_all" as any)
+			.selectAll()
+			.execute();
+
+		expect(afterDeletePrimary).toHaveLength(0);
+		expect(afterDeleteAll).toHaveLength(0);
+	});
+
+	test("should use consistent naming conventions", async () => {
+		const lix = await openLix({});
+
+		createEntityViewsIfNotExists({
+			lix,
+			schema: testSchema,
+			// No overrideName - should use schema["x-lix-key"] as base
+			pluginKey: "test_plugin",
+			hardcodedFileId: "test_file",
+		});
+
+		// Should create views with default names based on schema key
+		// Primary view: test_entity
+		// All view: test_entity_all
+		// History view: test_entity_history
+
+		// Test primary view
+		await lix.db
+			.insertInto("test_entity" as any)
+			.values({ id: "test_id", name: "test_name", value: 42 })
+			.execute();
+
+		const primaryResult = await lix.db
+			.selectFrom("test_entity" as any)
+			.selectAll()
+			.execute();
+
+		expect(primaryResult).toHaveLength(1);
+
+		// Test _all view
+		const allResult = await lix.db
+			.selectFrom("test_entity_all" as any)
+			.selectAll()
+			.execute();
+
+		expect(allResult).toHaveLength(1);
+
+		// Test _history view
+		const historyViews = await lix.db
+			.selectFrom("test_entity_history" as any)
+			.selectAll()
+			.limit(1)
+			.execute();
+
+		// History view should exist (even if no results match current query)
+		expect(historyViews).toBeDefined();
+	});
+
+	test("should handle validation and error cases", async () => {
+		const lix = await openLix({});
+
+		const invalidSchema: LixSchemaDefinition = {
+			"x-lix-key": "invalid_schema",
+			"x-lix-version": "1.0",
+			type: "object",
+			properties: {
+				name: { type: "string" },
+			},
+		} as const;
+
+		// Should throw error for all view types when schema is invalid
+		expect(() => {
+			createEntityViewsIfNotExists({
+				lix,
+				schema: invalidSchema,
+				pluginKey: "test_plugin",
+			});
+		}).toThrow(
+			"Schema must define 'x-lix-primary-key' for entity view generation"
+		);
+	});
+});

package/src/entity-views/entity-view-builder.ts

@@ -0,0 +1,148 @@
+import type { Lix } from "../lix/open-lix.js";
+import type {
+	FromLixSchemaDefinition,
+	LixSchemaDefinition,
+} from "../schema-definition/definition.js";
+import {
+	createEntityStateView,
+	type StateEntityView,
+	type ValidationRule,
+	type ValidationCallbacks,
+} from "./entity-state.js";
+import {
+	createEntityStateAllView,
+	type StateEntityAllView,
+} from "./entity-state-all.js";
+import {
+	createEntityStateHistoryView,
+	type StateEntityHistoryView,
+} from "./entity-state-history.js";
+import type {
+	EntityStateView,
+	EntityStateAllView,
+	EntityStateHistoryView,
+	ToKysely,
+} from "./types.js";
+
+// Re-export types for backward compatibility
+export type { StateEntityView, StateEntityAllView, StateEntityHistoryView };
+export type { ValidationRule, ValidationCallbacks };
+
+/**
+ * Utility type that generates database schema view entries for an entity schema.
+ * Creates three views: normal (active version), all versions, and history.
+ *
+ * TSchema should be a LixSchemaDefinition (typeof SomeSchema).
+ * TOverride allows you to provide partial type overrides for specific properties.
+ *
+ * @example
+ * ```typescript
+ * // Basic usage with schema definition
+ * type LogViews = EntityViews<typeof LixLogSchema, "log">;
+ *
+ * // With partial property override
+ * type ThreadCommentViews = EntityViews<
+ *   typeof LixThreadCommentSchema,
+ *   "thread_comment",
+ *   { body: ZettelDoc }
+ * >;
+ * ```
+ */
+export type EntityViews<
+	TSchema extends LixSchemaDefinition,
+	TViewName extends string,
+	TOverride = object,
+> = {
+	[K in TViewName]: ToKysely<
+		EntityStateView<FromLixSchemaDefinition<TSchema> & TOverride>
+	>;
+} & {
+	[K in `${TViewName}_all`]: ToKysely<
+		EntityStateAllView<FromLixSchemaDefinition<TSchema> & TOverride>
+	>;
+} & {
+	[K in `${TViewName}_history`]: ToKysely<
+		EntityStateHistoryView<FromLixSchemaDefinition<TSchema> & TOverride>
+	>;
+};
+
+/**
+ * Creates SQL views and CRUD triggers for an entity based on its schema definition.
+ *
+ * This function automatically generates three views:
+ * - Primary view (e.g., "key_value") - uses state (active version only)
+ * - All view (e.g., "key_value_all") - uses state (all versions)
+ * - History view (e.g., "key_value_history") - uses state_history (historical states)
+ *
+ * Each view includes:
+ * - A view that extracts JSON properties from the respective table
+ * - CRUD triggers for entity and entity_all views (history view is read-only)
+ *
+ * @throws Error if schema type is not "object" or x-lix-primary-key is not defined
+ *
+ * @example
+ * ```typescript
+ * // Basic usage for key-value entities
+ * createEntityViewsIfNotExists({
+ *   lix,
+ *   schema: LixKeyValueSchema,
+ *   overrideName: "key_value",
+ *   pluginKey: "lix_key_value",
+ *   hardcodedFileId: "lix"
+ * });
+ * // Creates: key_value, key_value_all, and key_value_history
+ *
+ * // With default values for account entities
+ * createEntityViewsIfNotExists({
+ *   lix,
+ *   schema: LixAccountSchema,
+ *   overrideName: "account",
+ *   pluginKey: "lix_own_entity",
+ *   hardcodedFileId: "lix",
+ *   defaultValues: {
+ *     id: (row) => nanoid()
+ *   }
+ * });
+ * // Creates: account, account_all, and account_history
+ * ```
+ */
+export function createEntityViewsIfNotExists(args: {
+	lix: Pick<Lix, "sqlite">;
+	schema: LixSchemaDefinition;
+	/** Overrides the view name which defaults to schema["x-lix-key"] */
+	overrideName?: string;
+	/** Plugin identifier for the entity */
+	pluginKey: string;
+	/** Optional hardcoded file_id (if not provided, uses lixcol_file_id from mutations) */
+	hardcodedFileId?: string;
+	/** Optional hardcoded version_id (if not provided, uses lixcol_version_id from mutations or active version) */
+	hardcodedVersionId?: string;
+	/** Object mapping property names to functions that generate default values */
+	defaultValues?: Record<
+		string,
+		(() => any) | ((row: Record<string, any>) => any)
+	>;
+	/** Custom validation logic for entity operations */
+	validation?: ValidationCallbacks;
+}): void {
+	const view_name = args.overrideName ?? args.schema["x-lix-key"];
+
+	// Create the primary view (active only)
+	createEntityStateView({
+		...args,
+		overrideName: view_name,
+	});
+
+	// Create the _all view (all versions)
+	createEntityStateAllView({
+		...args,
+		overrideName: view_name + "_all",
+	});
+
+	// Create the _history view (historical states)
+	createEntityStateHistoryView({
+		lix: args.lix,
+		schema: args.schema,
+		overrideName: view_name + "_history",
+	});
+}

package/src/entity-views/index.ts

@@ -0,0 +1 @@
+export * from "./types.js";

package/src/entity-views/types.test.ts

@@ -0,0 +1,99 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+import { test } from "vitest";
+import type { ToKysely, NewState } from "./types.js";
+import type {
+	LixSchemaDefinition,
+	FromLixSchemaDefinition,
+	LixGenerated,
+	LixInsertable,
+	LixSelectable,
+	LixUpdateable,
+} from "../schema-definition/definition.js";
+import type { Generated as KyselyGenerated } from "kysely";
+
+test("ToKysely converts LixGenerated to Kysely Generated", () => {
+	type MockType = {
+		id: LixGenerated<string>;
+		name: string;
+		count: LixGenerated<number>;
+		metadata: { foo: string };
+		optional?: string | null;
+	};
+
+	// The conversion should map LixGenerated to KyselyGenerated
+	type KyselyVersion = ToKysely<MockType>;
+
+	// Verify the conversion is correct by creating a type-compatible object
+	const kyselyTable: KyselyVersion = {
+		id: {} as KyselyGenerated<string>,
+		name: "test",
+		count: {} as KyselyGenerated<number>,
+		metadata: { foo: "bar" },
+		optional: null,
+	};
+
+	// Type checks - verify specific field types
+	type IdType = KyselyVersion["id"]; // Should be KyselyGenerated<string>
+	type NameType = KyselyVersion["name"]; // Should be string
+	type CountType = KyselyVersion["count"]; // Should be KyselyGenerated<number>
+	type MetadataType = KyselyVersion["metadata"]; // Should be { foo: string }
+	type OptionalType = KyselyVersion["optional"]; // Should be string | null | undefined
+
+	// These should work
+	const id: IdType = {} as KyselyGenerated<string>;
+	const name: NameType = "test";
+	const count: CountType = {} as KyselyGenerated<number>;
+	const metadata: MetadataType = { foo: "test" };
+	const optional1: OptionalType = "value";
+	const optional2: OptionalType = null;
+	const optional3: OptionalType = undefined;
+});
+
+test("LixGenerated markers work with NewState", () => {
+	// Define a mock schema with x-lix-generated
+	const MockEntitySchema = {
+		"x-lix-key": "mock_entity",
+		"x-lix-version": "1.0",
+		"x-lix-primary-key": ["id"],
+		type: "object",
+		properties: {
+			id: { type: "string", "x-lix-generated": true },
+			name: { type: "string" },
+			count: { type: "number", "x-lix-generated": true },
+			optional_field: { type: "string", nullable: true },
+		},
+		required: ["id", "name", "count"],
+		additionalProperties: false,
+	} as const satisfies LixSchemaDefinition;
+
+	// Business logic type with LixGenerated markers
+	type MockEntity = FromLixSchemaDefinition<typeof MockEntitySchema>;
+
+	// Test that NewState makes generated fields optional
+	const newMockEntity: NewState<MockEntity> = {
+		name: "test-name",
+		// id should be optional because it's LixGenerated
+		// count should be optional because it's LixGenerated
+		// optional_field should be optional because it's nullable
+	};
+
+	// Test that NewState also accepts generated fields when provided
+	const newMockEntityWithGenerated: NewState<MockEntity> = {
+		id: "custom-id",
+		name: "test-name",
+		count: 42,
+		optional_field: "optional",
+	};
+
+	// Test that required non-generated fields are still required
+	// @ts-expect-error - name is required
+	const invalidNewMockEntity: NewState<MockEntity> = {
+		count: 42,
+		// Missing required field 'name'
+	};
+
+	// Verify the types work as expected
+	void newMockEntity;
+	void newMockEntityWithGenerated;
+	void invalidNewMockEntity;
+});