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

package/dist/entity-views/entity-state-history.test.js

@@ -0,0 +1,274 @@
+import { test, expect, describe } from "vitest";
+import { openLix } from "../lix/open-lix.js";
+import { createEntityStateHistoryView } from "./entity-state-history.js";
+describe("createEntityHistoryViewIfNotExists", () => {
+    const testSchema = {
+        "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"],
+        additionalProperties: false,
+    };
+    test("should throw error if schema has no primary key", async () => {
+        const lix = await openLix({});
+        const invalidSchema = {
+            "x-lix-key": "invalid_schema",
+            "x-lix-version": "1.0",
+            type: "object",
+            additionalProperties: false,
+            properties: {
+                name: { type: "string" },
+            },
+        };
+        expect(() => {
+            createEntityStateHistoryView({
+                lix,
+                schema: invalidSchema,
+            });
+        }).toThrow("Schema must define 'x-lix-primary-key' for entity history view generation");
+    });
+    test("should create history view with correct columns", async () => {
+        const lix = await openLix({});
+        createEntityStateHistoryView({
+            lix,
+            schema: testSchema,
+            overrideName: "test_entity_history",
+        });
+        // Insert some test data into state to create history
+        await lix.db
+            .insertInto("state_all")
+            .values({
+            entity_id: "test_id",
+            schema_key: "test_entity",
+            file_id: "test_file",
+            plugin_key: "test_plugin",
+            snapshot_content: {
+                id: "test_id",
+                name: "test_name",
+                value: 42,
+            },
+            schema_version: "1.0",
+            version_id: lix.db.selectFrom("active_version").select("version_id"),
+        })
+            .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();
+        // Query the history view
+        const historyResult = await lix.db
+            .selectFrom("test_entity_history")
+            .where("lixcol_change_set_id", "=", activeVersion.change_set_id)
+            .selectAll()
+            .execute();
+        expect(historyResult).toHaveLength(1);
+        const historyEntity = historyResult[0];
+        // Business logic columns
+        expect(historyEntity).toHaveProperty("id", "test_id");
+        expect(historyEntity).toHaveProperty("name", "test_name");
+        expect(historyEntity).toHaveProperty("value", 42);
+        // History-specific columns
+        expect(historyEntity).toHaveProperty("entity_id", "test_id");
+        expect(historyEntity).toHaveProperty("schema_key", "test_entity");
+        expect(historyEntity).toHaveProperty("lixcol_file_id", "test_file");
+        expect(historyEntity).toHaveProperty("lixcol_plugin_key", "test_plugin");
+        expect(historyEntity).toHaveProperty("lixcol_schema_version", "1.0");
+        expect(historyEntity).toHaveProperty("lixcol_change_id");
+        expect(historyEntity).toHaveProperty("lixcol_change_set_id", activeVersion.change_set_id);
+        expect(historyEntity).toHaveProperty("lixcol_depth", 0);
+    });
+    test("should use schema key + _history as default view name", async () => {
+        const lix = await openLix({});
+        createEntityStateHistoryView({
+            lix,
+            schema: testSchema,
+            // No overrideName - should use schema["x-lix-key"] + "_history"
+        });
+        // Insert test data
+        await lix.db
+            .insertInto("state_all")
+            .values({
+            entity_id: "test_id",
+            schema_key: "test_entity",
+            file_id: "test_file",
+            plugin_key: "test_plugin",
+            snapshot_content: {
+                id: "test_id",
+                name: "test_name",
+                value: 42,
+            },
+            schema_version: "1.0",
+            version_id: lix.db.selectFrom("active_version").select("version_id"),
+        })
+            .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();
+        // Test that we can query the view using the schema key + _history name
+        const result = await lix.db
+            .selectFrom("test_entity_history")
+            .where("lixcol_change_set_id", "=", activeVersion.change_set_id)
+            .selectAll()
+            .execute();
+        expect(result).toHaveLength(1);
+        expect(result[0]).toMatchObject({
+            id: "test_id",
+            name: "test_name",
+            value: 42,
+        });
+    });
+    test("should query historical states at different depths", async () => {
+        const lix = await openLix({});
+        // Add stored schema first
+        const mockSchema = {
+            "x-lix-key": "test_entity",
+            "x-lix-version": "1.0",
+            type: "object",
+            additionalProperties: false,
+            properties: {
+                id: { type: "string" },
+                name: { type: "string" },
+                value: { type: "number" },
+            },
+        };
+        await lix.db
+            .insertInto("stored_schema")
+            .values({ value: mockSchema })
+            .execute();
+        createEntityStateHistoryView({
+            lix,
+            schema: testSchema,
+            overrideName: "test_history",
+        });
+        // Insert initial state
+        await lix.db
+            .insertInto("state_all")
+            .values({
+            entity_id: "tracked_entity",
+            schema_key: "test_entity",
+            file_id: "test_file",
+            plugin_key: "test_plugin",
+            snapshot_content: { id: "tracked_entity", name: "initial", value: 1 },
+            schema_version: "1.0",
+            version_id: lix.db.selectFrom("active_version").select("version_id"),
+        })
+            .execute();
+        // Update to create history
+        await lix.db
+            .updateTable("state_all")
+            .set({
+            snapshot_content: { id: "tracked_entity", name: "updated", value: 2 },
+        })
+            .where("entity_id", "=", "tracked_entity")
+            .execute();
+        // Update again to create more history
+        await lix.db
+            .updateTable("state_all")
+            .set({
+            snapshot_content: { id: "tracked_entity", name: "final", value: 3 },
+        })
+            .where("entity_id", "=", "tracked_entity")
+            .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();
+        // Query all history for this entity
+        const historyResult = await lix.db
+            .selectFrom("test_history")
+            .where("entity_id", "=", "tracked_entity")
+            .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) => h.lixcol_depth === 0);
+        expect(currentState).toBeDefined();
+        expect(currentState).toMatchObject({
+            name: "final",
+            value: 3,
+        });
+        // Check that different depths exist if there's history
+        if (historyResult.length > 1) {
+            const depthValues = historyResult.map((h) => h.lixcol_depth);
+            expect(depthValues).toContain(0); // Current state
+            expect(Math.max(...depthValues)).toBeGreaterThan(0); // At least one historical state
+        }
+    });
+    test("should be read-only (no CRUD triggers)", async () => {
+        const lix = await openLix({});
+        createEntityStateHistoryView({
+            lix,
+            schema: testSchema,
+            overrideName: "readonly_history",
+        });
+        // History views should be read-only, so INSERT/UPDATE/DELETE should fail
+        // This test verifies that no CRUD triggers were created
+        // Attempt to insert should fail (no INSERT trigger)
+        await expect(lix.db
+            .insertInto("readonly_history")
+            .values({
+            id: "test_id",
+            name: "test_name",
+            value: 42,
+        })
+            .execute()).rejects.toThrow();
+        // Insert some data directly into state for testing UPDATE/DELETE
+        await lix.db
+            .insertInto("state_all")
+            .values({
+            entity_id: "test_id",
+            schema_key: "test_entity",
+            file_id: "test_file",
+            plugin_key: "test_plugin",
+            snapshot_content: {
+                id: "test_id",
+                name: "test_name",
+                value: 42,
+            },
+            schema_version: "1.0",
+            version_id: lix.db.selectFrom("active_version").select("version_id"),
+        })
+            .execute();
+        // Get the active version's change set
+        const activeVersion = await lix.db
+            .selectFrom("active_version")
+            .innerJoin("version", "active_version.version_id", "version.id")
+            .select("version.change_set_id")
+            .executeTakeFirstOrThrow();
+        // Verify we can read the data
+        const readResult = await lix.db
+            .selectFrom("readonly_history")
+            .where("entity_id", "=", "test_id")
+            .where("lixcol_change_set_id", "=", activeVersion.change_set_id)
+            .selectAll()
+            .execute();
+        expect(readResult).toHaveLength(1);
+        // Attempt to update should fail (no UPDATE trigger)
+        await expect(lix.db
+            .updateTable("readonly_history")
+            .where("entity_id", "=", "test_id")
+            .set({ name: "updated_name" })
+            .execute()).rejects.toThrow();
+        // Attempt to delete should fail (no DELETE trigger)
+        await expect(lix.db
+            .deleteFrom("readonly_history")
+            .where("entity_id", "=", "test_id")
+            .execute()).rejects.toThrow();
+    });
+});
+//# sourceMappingURL=entity-state-history.test.js.map

package/dist/entity-views/entity-state-history.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-state-history.test.js","sourceRoot":"","sources":["../../src/entity-views/entity-state-history.test.ts"],"names":[],"mappings":"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"}

package/dist/entity-views/entity-state.d.ts

@@ -0,0 +1,217 @@
+import type { Generated } from "kysely";
+import type { Lix } from "../lix/open-lix.js";
+import type { LixGenerated, LixSchemaDefinition } from "../schema-definition/definition.js";
+/**
+ * Base type for regular entity views (active version only) that include operational columns from the state table.
+ * These views do NOT expose lixcol_version_id to prevent accidental version-specific operations.
+ *
+ * @example
+ * ```typescript
+ * // Define an entity view type for active version operations
+ * export type AccountView = {
+ *   id: Generated<string>;
+ *   name: string;
+ * } & StateEntityView;
+ * ```
+ */
+export type StateEntityView = {
+    /**
+     * File identifier where this entity is stored.
+     *
+     * This references the file_id in the state table and links the entity
+     * to a specific file in the Lix file system.
+     */
+    lixcol_file_id: Generated<string>;
+    /**
+     * Version identifier this entity was inherited from during branching.
+     *
+     * - `null` if the entity was created in the current version
+     * - Contains the source version_id if the entity was inherited from another version
+     *
+     * This is useful for tracking entity lineage across version branches.
+     */
+    lixcol_inherited_from_version_id: Generated<string | null>;
+    /**
+     * Timestamp when this entity was created in the current version.
+     *
+     * **Important**: This timestamp is relative to the version, not global.
+     * - When an entity is first created, this is the actual creation time
+     * - When an entity is inherited from another version, this is the time it was inherited
+     *
+     * Format: ISO 8601 string (e.g., "2024-03-20T10:30:00.000Z")
+     */
+    lixcol_created_at: Generated<string>;
+    /**
+     * Timestamp when this entity was last updated in the current version.
+     *
+     * **Important**: This timestamp is relative to the version, not global.
+     * - Updates only when the entity is modified within the current version
+     * - When first inherited, this equals lixcol_created_at
+     *
+     * Format: ISO 8601 string (e.g., "2024-03-20T10:30:00.000Z")
+     */
+    lixcol_updated_at: Generated<string>;
+    /**
+     * Change identifier for the last modification to this entity.
+     *
+     * This references the change.id that last modified this entity, enabling
+     * blame and diff functionality. Useful for tracking who made changes
+     * and when they were made.
+     */
+    lixcol_change_id: Generated<string>;
+    /**
+     * Whether this entity is stored as untracked state.
+     *
+     * - `false` (default): Entity follows normal change control and versioning
+     * - `true`: Entity bypasses change control for UI state, temporary data, etc.
+     *
+     * Untracked entities don't create change records and have highest priority
+     * in the state resolution order: untracked > tracked > inherited.
+     */
+    lixcol_untracked: Generated<boolean>;
+};
+/**
+ * Base type for regular entity views (active version only) that include operational columns from the state table.
+ * These views do NOT expose lixcol_version_id to prevent accidental version-specific operations.
+ *
+ * This type uses LixGenerated markers instead of Kysely's Generated type, making it compatible
+ * with the Lix SDK's type transformation system.
+ *
+ * @example
+ * ```typescript
+ * // Define an entity view type for active version operations
+ * export type AccountView = {
+ *   id: LixGenerated<string>;
+ *   name: string;
+ * } & EntityStateColumns;
+ * ```
+ */
+export type EntityStateColumns = {
+    /**
+     * File identifier where this entity is stored.
+     *
+     * This references the file_id in the state table and links the entity
+     * to a specific file in the Lix file system.
+     */
+    lixcol_file_id: LixGenerated<string>;
+    /**
+     * Version identifier this entity was inherited from during branching.
+     *
+     * - `null` if the entity was created in the current version
+     * - Contains the source version_id if the entity was inherited from another version
+     *
+     * This is useful for tracking entity lineage across version branches.
+     */
+    lixcol_inherited_from_version_id: LixGenerated<string | null>;
+    /**
+     * Timestamp when this entity was created in the current version.
+     *
+     * **Important**: This timestamp is relative to the version, not global.
+     * - When an entity is first created, this is the actual creation time
+     * - When an entity is inherited from another version, this is the time it was inherited
+     *
+     * Format: ISO 8601 string (e.g., "2024-03-20T10:30:00.000Z")
+     */
+    lixcol_created_at: LixGenerated<string>;
+    /**
+     * Timestamp when this entity was last updated in the current version.
+     *
+     * **Important**: This timestamp is relative to the version, not global.
+     * - Updates only when the entity is modified within the current version
+     * - When first inherited, this equals lixcol_created_at
+     *
+     * Format: ISO 8601 string (e.g., "2024-03-20T10:30:00.000Z")
+     */
+    lixcol_updated_at: LixGenerated<string>;
+    /**
+     * Change identifier for the last modification to this entity.
+     *
+     * This references the change.id that last modified this entity, enabling
+     * blame and diff functionality. Useful for tracking who made changes
+     * and when they were made.
+     */
+    lixcol_change_id: LixGenerated<string>;
+    /**
+     * Whether this entity is stored as untracked state.
+     *
+     * - `false` (default): Entity follows normal change control and versioning
+     * - `true`: Entity bypasses change control for UI state, temporary data, etc.
+     *
+     * Untracked entities don't create change records and have highest priority
+     * in the state resolution order: untracked > tracked > inherited.
+     */
+    lixcol_untracked: LixGenerated<boolean>;
+};
+/**
+ * Validation rule for SQL trigger generation.
+ */
+export type ValidationRule = {
+    /** SQL condition that must be true, or error will be raised */
+    condition: string;
+    /** Error message to display when validation fails */
+    errorMessage: string;
+};
+/**
+ * Validation callbacks for entity operations.
+ * These are converted to SQL validation triggers.
+ */
+export type ValidationCallbacks = {
+    /** Validation logic for INSERT operations */
+    onInsert?: ValidationRule[];
+    /** Validation logic for UPDATE operations */
+    onUpdate?: ValidationRule[];
+    /** Validation logic for DELETE operations */
+    onDelete?: ValidationRule[];
+};
+/**
+ * Creates SQL view and CRUD triggers for an entity based on its schema definition (active version only).
+ *
+ * This function generates:
+ * - A view that extracts JSON properties from the state table
+ * - INSERT trigger that serializes entity data to JSON in the state table
+ * - UPDATE trigger that updates the corresponding state record
+ * - DELETE trigger that removes the state record
+ *
+ * @throws Error if schema type is not "object" or x-lix-primary-key is not defined
+ *
+ * @example
+ * ```typescript
+ * // Basic usage for key-value entities
+ * createEntityViewIfNotExists({
+ *   lix,
+ *   schema: LixKeyValueSchema,
+ *   overrideName: "key_value",
+ *   pluginKey: "lix_key_value",
+ *   hardcodedFileId: "lix"
+ * });
+ *
+ * // With default values for account entities
+ * createEntityViewIfNotExists({
+ *   lix,
+ *   schema: LixAccountSchema,
+ *   overrideName: "account",
+ *   pluginKey: "lix_own_entity",
+ *   hardcodedFileId: "lix",
+ *   defaultValues: {
+ *     id: (row) => nanoid()
+ *   }
+ * });
+ * ```
+ */
+export declare function createEntityStateView(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 active version) */
+    hardcodedVersionId?: string;
+    /** Object mapping property names to functions that generate default values */
+    defaultValues?: Record<string, (() => string) | ((row: Record<string, any>) => string)>;
+    /** Custom validation logic for entity operations */
+    validation?: ValidationCallbacks;
+}): void;
+//# sourceMappingURL=entity-state.d.ts.map

package/dist/entity-views/entity-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-state.d.ts","sourceRoot":"","sources":["../../src/entity-views/entity-state.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AACxC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,KAAK,EACX,YAAY,EACZ,mBAAmB,EACnB,MAAM,oCAAoC,CAAC;AAE5C;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,eAAe,GAAG;IAC7B;;;;;OAKG;IACH,cAAc,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC;IAElC;;;;;;;OAOG;IACH,gCAAgC,EAAE,SAAS,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAE3D;;;;;;;;OAQG;IACH,iBAAiB,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC;IAErC;;;;;;;;OAQG;IACH,iBAAiB,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC;IAErC;;;;;;OAMG;IACH,gBAAgB,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC;IAEpC;;;;;;;;OAQG;IACH,gBAAgB,EAAE,SAAS,CAAC,OAAO,CAAC,CAAC;CACrC,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAChC;;;;;OAKG;IACH,cAAc,EAAE,YAAY,CAAC,MAAM,CAAC,CAAC;IAErC;;;;;;;OAOG;IACH,gCAAgC,EAAE,YAAY,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAE9D;;;;;;;;OAQG;IACH,iBAAiB,EAAE,YAAY,CAAC,MAAM,CAAC,CAAC;IAExC;;;;;;;;OAQG;IACH,iBAAiB,EAAE,YAAY,CAAC,MAAM,CAAC,CAAC;IAExC;;;;;;OAMG;IACH,gBAAgB,EAAE,YAAY,CAAC,MAAM,CAAC,CAAC;IAEvC;;;;;;;;OAQG;IACH,gBAAgB,EAAE,YAAY,CAAC,OAAO,CAAC,CAAC;CACxC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG;IAC5B,+DAA+D;IAC/D,SAAS,EAAE,MAAM,CAAC;IAClB,qDAAqD;IACrD,YAAY,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG;IACjC,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,cAAc,EAAE,CAAC;IAC5B,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,cAAc,EAAE,CAAC;IAC5B,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,cAAc,EAAE,CAAC;CAC5B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE;IAC3C,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;IACzB,MAAM,EAAE,mBAAmB,CAAC;IAC5B,oEAAoE;IACpE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,uCAAuC;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,uFAAuF;IACvF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,2EAA2E;IAC3E,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,8EAA8E;IAC9E,aAAa,CAAC,EAAE,MAAM,CACrB,MAAM,EACN,CAAC,MAAM,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,MAAM,CAAC,CACvD,CAAC;IACF,oDAAoD;IACpD,UAAU,CAAC,EAAE,mBAAmB,CAAC;CACjC,GAAG,IAAI,CAQP"}