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

package/dist/filesystem/file/store-detected-change-schema.test.js

@@ -0,0 +1,222 @@
+import { test, expect } from "vitest";
+import { openLix } from "../../lix/open-lix.js";
+import { storeDetectedChangeSchema } from "./store-detected-change-schema.js";
+import { sql } from "kysely";
+test("storeDetectedChangeSchema stores new schema on first use", async () => {
+    const lix = await openLix({});
+    const testSchema = {
+        "x-lix-key": "test_schema",
+        "x-lix-version": "1.0",
+        type: "object",
+        properties: {
+            value: { type: "string" },
+        },
+        additionalProperties: false,
+    };
+    // Store schema for the first time
+    storeDetectedChangeSchema({
+        engine: lix.engine,
+        schema: testSchema,
+    });
+    // Check that schema was stored
+    const storedSchema = await lix.db
+        .selectFrom("stored_schema")
+        .select("value")
+        .where(sql `json_extract("stored_schema"."value", '$."x-lix-key"')`, "=", "test_schema")
+        .where(sql `json_extract("stored_schema"."value", '$."x-lix-version"')`, "=", "1.0")
+        .execute();
+    expect(storedSchema).toHaveLength(1);
+    expect(storedSchema[0]?.value).toEqual(testSchema);
+});
+test("storeDetectedChangeSchema allows identical schema to be used again", async () => {
+    const lix = await openLix({});
+    const testSchema = {
+        "x-lix-key": "test_schema_2",
+        "x-lix-version": "1.0",
+        type: "object",
+        properties: {
+            value: { type: "string" },
+        },
+        additionalProperties: false,
+    };
+    // Store schema first time
+    storeDetectedChangeSchema({
+        engine: lix.engine,
+        schema: testSchema,
+    });
+    // Store same schema again - should not throw
+    expect(() => {
+        storeDetectedChangeSchema({
+            engine: lix.engine,
+            schema: testSchema,
+        });
+    }).not.toThrow();
+    // Should only have one schema stored
+    const storedSchemas = await lix.db
+        .selectFrom("stored_schema")
+        .select("value")
+        .where(sql `json_extract("stored_schema"."value", '$."x-lix-key"')`, "=", "test_schema_2")
+        .execute();
+    expect(storedSchemas).toHaveLength(1);
+});
+test("storeDetectedChangeSchema throws error when schema differs for same version", async () => {
+    const lix = await openLix({});
+    const originalSchema = {
+        "x-lix-key": "test_schema_3",
+        "x-lix-version": "1.0",
+        type: "object",
+        properties: {
+            value: { type: "string" },
+        },
+        additionalProperties: false,
+    };
+    const differentSchema = {
+        "x-lix-key": "test_schema_3",
+        "x-lix-version": "1.0", // Same version
+        type: "object",
+        properties: {
+            value: { type: "number" }, // Different property type!
+        },
+        additionalProperties: false,
+    };
+    // Store original schema
+    storeDetectedChangeSchema({
+        engine: lix.engine,
+        schema: originalSchema,
+    });
+    // Try to store different schema with same version - should throw
+    expect(() => {
+        storeDetectedChangeSchema({
+            engine: lix.engine,
+            schema: differentSchema,
+        });
+    }).toThrow("Schema differs from stored version for key 'test_schema_3' version '1.0'. Please bump the schema version (x-lix-version) to use a different schema.");
+});
+test("storeDetectedChangeSchema allows different schemas with different versions", async () => {
+    const lix = await openLix({});
+    const schemaV1 = {
+        "x-lix-key": "test_schema_4",
+        "x-lix-version": "1.0",
+        type: "object",
+        properties: {
+            value: { type: "string" },
+        },
+        additionalProperties: false,
+    };
+    const schemaV2 = {
+        "x-lix-key": "test_schema_4",
+        "x-lix-version": "2.0", // Different version
+        type: "object",
+        properties: {
+            value: { type: "number" }, // Different property type is OK with different version
+        },
+        additionalProperties: false,
+    };
+    // Store v1 schema
+    storeDetectedChangeSchema({
+        engine: lix.engine,
+        schema: schemaV1,
+    });
+    // Store v2 schema - should not throw
+    expect(() => {
+        storeDetectedChangeSchema({
+            engine: lix.engine,
+            schema: schemaV2,
+        });
+    }).not.toThrow();
+    // Should have both schemas stored
+    const storedSchemas = await lix.db
+        .selectFrom("stored_schema")
+        .select("value")
+        .where(sql `json_extract("stored_schema"."value", '$."x-lix-key"')`, "=", "test_schema_4")
+        .execute();
+    expect(storedSchemas).toHaveLength(2);
+    expect(storedSchemas.map((s) => s.value["x-lix-version"]).sort()).toEqual(["1.0", "2.0"]);
+});
+test("storeDetectedChangeSchema enforces strict JSON determinism", async () => {
+    const lix = await openLix({});
+    const originalSchema = {
+        "x-lix-key": "test_schema_5",
+        "x-lix-version": "1.0",
+        type: "object",
+        properties: {
+            a: { type: "string" },
+            b: { type: "number" },
+        },
+        additionalProperties: false,
+    };
+    // Same schema but different property order
+    const reorderedSchema = {
+        "x-lix-key": "test_schema_5",
+        "x-lix-version": "1.0",
+        type: "object",
+        properties: {
+            b: { type: "number" }, // Reordered properties
+            a: { type: "string" },
+        },
+        additionalProperties: false,
+    };
+    // Store original schema
+    storeDetectedChangeSchema({
+        engine: lix.engine,
+        schema: originalSchema,
+    });
+    // Try to store reordered schema - should throw because JSON.stringify will be different
+    expect(() => {
+        storeDetectedChangeSchema({
+            engine: lix.engine,
+            schema: reorderedSchema,
+        });
+    }).toThrow("Schema differs from stored version for key 'test_schema_5' version '1.0'. Please bump the schema version (x-lix-version) to use a different schema.");
+});
+test("integration with plugin detectChanges", async () => {
+    const mockPlugin = {
+        key: "test-plugin",
+        detectChangesGlob: "*.txt",
+        detectChanges: () => [
+            {
+                entity_id: "entity1",
+                schema: {
+                    "x-lix-key": "integration_test_schema",
+                    "x-lix-version": "1.0",
+                    type: "object",
+                    additionalProperties: false,
+                    properties: {
+                        value: { type: "string" },
+                    },
+                },
+                snapshot_content: { value: "test" },
+            },
+        ],
+    };
+    const lix = await openLix({
+        providePlugins: [mockPlugin],
+    });
+    // Insert a file - should automatically store the schema via file handlers
+    await lix.db
+        .insertInto("file")
+        .values({
+        id: "test-file",
+        data: new TextEncoder().encode("test content"),
+        path: "/test.txt",
+    })
+        .execute();
+    // Check that schema was automatically stored
+    const storedSchema = await lix.db
+        .selectFrom("stored_schema")
+        .select("value")
+        .where(sql `json_extract("stored_schema"."value", '$."x-lix-key"')`, "=", "integration_test_schema")
+        .where(sql `json_extract("stored_schema"."value", '$."x-lix-version"')`, "=", "1.0")
+        .execute();
+    expect(storedSchema).toHaveLength(1);
+    expect(storedSchema[0]?.value).toEqual({
+        "x-lix-key": "integration_test_schema",
+        "x-lix-version": "1.0",
+        additionalProperties: false,
+        type: "object",
+        properties: {
+            value: { type: "string" },
+        },
+    });
+});
+//# sourceMappingURL=store-detected-change-schema.test.js.map

package/dist/filesystem/file/store-detected-change-schema.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-detected-change-schema.test.js","sourceRoot":"","sources":["../../../src/filesystem/file/store-detected-change-schema.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAChD,OAAO,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAC;AAE9E,OAAO,EAAE,GAAG,EAAE,MAAM,QAAQ,CAAC;AAE7B,IAAI,CAAC,0DAA0D,EAAE,KAAK,IAAI,EAAE;IAC3E,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,EAAE,CAAC,CAAC;IAE9B,MAAM,UAAU,GAAG;QAClB,WAAW,EAAE,aAAa;QAC1B,eAAe,EAAE,KAAK;QACtB,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACX,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;SACzB;QACD,oBAAoB,EAAE,KAAK;KAClB,CAAC;IAEX,kCAAkC;IAClC,yBAAyB,CAAC;QACzB,MAAM,EAAE,GAAG,CAAC,MAAO;QACnB,MAAM,EAAE,UAAU;KAClB,CAAC,CAAC;IAEH,+BAA+B;IAC/B,MAAM,YAAY,GAAG,MAAM,GAAG,CAAC,EAAE;SAC/B,UAAU,CAAC,eAAe,CAAC;SAC3B,MAAM,CAAC,OAAO,CAAC;SACf,KAAK,CACL,GAAG,CAAA,wDAAwD,EAC3D,GAAG,EACH,aAAa,CACb;SACA,KAAK,CACL,GAAG,CAAA,4DAA4D,EAC/D,GAAG,EACH,KAAK,CACL;SACA,OAAO,EAAE,CAAC;IAEZ,MAAM,CAAC,YAAY,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IACrC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;AACpD,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,oEAAoE,EAAE,KAAK,IAAI,EAAE;IACrF,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,EAAE,CAAC,CAAC;IAE9B,MAAM,UAAU,GAAG;QAClB,WAAW,EAAE,eAAe;QAC5B,eAAe,EAAE,KAAK;QACtB,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACX,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;SACzB;QACD,oBAAoB,EAAE,KAAK;KAClB,CAAC;IAEX,0BAA0B;IAC1B,yBAAyB,CAAC;QACzB,MAAM,EAAE,GAAG,CAAC,MAAO;QACnB,MAAM,EAAE,UAAU;KAClB,CAAC,CAAC;IAEH,6CAA6C;IAC7C,MAAM,CAAC,GAAG,EAAE;QACX,yBAAyB,CAAC;YACzB,MAAM,EAAE,GAAG,CAAC,MAAO;YACnB,MAAM,EAAE,UAAU;SAClB,CAAC,CAAC;IACJ,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;IAEjB,qCAAqC;IACrC,MAAM,aAAa,GAAG,MAAM,GAAG,CAAC,EAAE;SAChC,UAAU,CAAC,eAAe,CAAC;SAC3B,MAAM,CAAC,OAAO,CAAC;SACf,KAAK,CACL,GAAG,CAAA,wDAAwD,EAC3D,GAAG,EACH,eAAe,CACf;SACA,OAAO,EAAE,CAAC;IAEZ,MAAM,CAAC,aAAa,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;AACvC,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,6EAA6E,EAAE,KAAK,IAAI,EAAE;IAC9F,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,EAAE,CAAC,CAAC;IAE9B,MAAM,cAAc,GAAG;QACtB,WAAW,EAAE,eAAe;QAC5B,eAAe,EAAE,KAAK;QACtB,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACX,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;SACzB;QACD,oBAAoB,EAAE,KAAK;KAClB,CAAC;IAEX,MAAM,eAAe,GAAG;QACvB,WAAW,EAAE,eAAe;QAC5B,eAAe,EAAE,KAAK,EAAE,eAAe;QACvC,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACX,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,2BAA2B;SACtD;QACD,oBAAoB,EAAE,KAAK;KAClB,CAAC;IAEX,wBAAwB;IACxB,yBAAyB,CAAC;QACzB,MAAM,EAAE,GAAG,CAAC,MAAO;QACnB,MAAM,EAAE,cAAc;KACtB,CAAC,CAAC;IAEH,iEAAiE;IACjE,MAAM,CAAC,GAAG,EAAE;QACX,yBAAyB,CAAC;YACzB,MAAM,EAAE,GAAG,CAAC,MAAO;YACnB,MAAM,EAAE,eAAe;SACvB,CAAC,CAAC;IACJ,CAAC,CAAC,CAAC,OAAO,CACT,qJAAqJ,CACrJ,CAAC;AACH,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,4EAA4E,EAAE,KAAK,IAAI,EAAE;IAC7F,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,EAAE,CAAC,CAAC;IAE9B,MAAM,QAAQ,GAAG;QAChB,WAAW,EAAE,eAAe;QAC5B,eAAe,EAAE,KAAK;QACtB,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACX,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;SACzB;QACD,oBAAoB,EAAE,KAAK;KAClB,CAAC;IAEX,MAAM,QAAQ,GAAG;QAChB,WAAW,EAAE,eAAe;QAC5B,eAAe,EAAE,KAAK,EAAE,oBAAoB;QAC5C,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACX,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,uDAAuD;SAClF;QACD,oBAAoB,EAAE,KAAK;KAClB,CAAC;IAEX,kBAAkB;IAClB,yBAAyB,CAAC;QACzB,MAAM,EAAE,GAAG,CAAC,MAAO;QACnB,MAAM,EAAE,QAAQ;KAChB,CAAC,CAAC;IAEH,qCAAqC;IACrC,MAAM,CAAC,GAAG,EAAE;QACX,yBAAyB,CAAC;YACzB,MAAM,EAAE,GAAG,CAAC,MAAO;YACnB,MAAM,EAAE,QAAQ;SAChB,CAAC,CAAC;IACJ,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;IAEjB,kCAAkC;IAClC,MAAM,aAAa,GAAG,MAAM,GAAG,CAAC,EAAE;SAChC,UAAU,CAAC,eAAe,CAAC;SAC3B,MAAM,CAAC,OAAO,CAAC;SACf,KAAK,CACL,GAAG,CAAA,wDAAwD,EAC3D,GAAG,EACH,eAAe,CACf;SACA,OAAO,EAAE,CAAC;IAEZ,MAAM,CAAC,aAAa,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IACtC,MAAM,CACL,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAE,CAAC,CAAC,KAAa,CAAC,eAAe,CAAC,CAAC,CAAC,IAAI,EAAE,CAClE,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC;AAC3B,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,4DAA4D,EAAE,KAAK,IAAI,EAAE;IAC7E,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,EAAE,CAAC,CAAC;IAE9B,MAAM,cAAc,GAAG;QACtB,WAAW,EAAE,eAAe;QAC5B,eAAe,EAAE,KAAK;QACtB,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACX,CAAC,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;YACrB,CAAC,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;SACrB;QACD,oBAAoB,EAAE,KAAK;KAClB,CAAC;IAEX,2CAA2C;IAC3C,MAAM,eAAe,GAAG;QACvB,WAAW,EAAE,eAAe;QAC5B,eAAe,EAAE,KAAK;QACtB,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACX,CAAC,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,uBAAuB;YAC9C,CAAC,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;SACrB;QACD,oBAAoB,EAAE,KAAK;KAClB,CAAC;IAEX,wBAAwB;IACxB,yBAAyB,CAAC;QACzB,MAAM,EAAE,GAAG,CAAC,MAAO;QACnB,MAAM,EAAE,cAAc;KACtB,CAAC,CAAC;IAEH,wFAAwF;IACxF,MAAM,CAAC,GAAG,EAAE;QACX,yBAAyB,CAAC;YACzB,MAAM,EAAE,GAAG,CAAC,MAAO;YACnB,MAAM,EAAE,eAAe;SACvB,CAAC,CAAC;IACJ,CAAC,CAAC,CAAC,OAAO,CACT,qJAAqJ,CACrJ,CAAC;AACH,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,uCAAuC,EAAE,KAAK,IAAI,EAAE;IACxD,MAAM,UAAU,GAAc;QAC7B,GAAG,EAAE,aAAa;QAClB,iBAAiB,EAAE,OAAO;QAC1B,aAAa,EAAE,GAAG,EAAE,CAAC;YACpB;gBACC,SAAS,EAAE,SAAS;gBACpB,MAAM,EAAE;oBACP,WAAW,EAAE,yBAAyB;oBACtC,eAAe,EAAE,KAAK;oBACtB,IAAI,EAAE,QAAQ;oBACd,oBAAoB,EAAE,KAAK;oBAC3B,UAAU,EAAE;wBACX,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;qBACzB;iBACD;gBACD,gBAAgB,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE;aACnC;SACD;KACD,CAAC;IAEF,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC;QACzB,cAAc,EAAE,CAAC,UAAU,CAAC;KAC5B,CAAC,CAAC;IAEH,0EAA0E;IAC1E,MAAM,GAAG,CAAC,EAAE;SACV,UAAU,CAAC,MAAM,CAAC;SAClB,MAAM,CAAC;QACP,EAAE,EAAE,WAAW;QACf,IAAI,EAAE,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,cAAc,CAAC;QAC9C,IAAI,EAAE,WAAW;KACjB,CAAC;SACD,OAAO,EAAE,CAAC;IAEZ,6CAA6C;IAC7C,MAAM,YAAY,GAAG,MAAM,GAAG,CAAC,EAAE;SAC/B,UAAU,CAAC,eAAe,CAAC;SAC3B,MAAM,CAAC,OAAO,CAAC;SACf,KAAK,CACL,GAAG,CAAA,wDAAwD,EAC3D,GAAG,EACH,yBAAyB,CACzB;SACA,KAAK,CACL,GAAG,CAAA,4DAA4D,EAC/D,GAAG,EACH,KAAK,CACL;SACA,OAAO,EAAE,CAAC;IAEZ,MAAM,CAAC,YAAY,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IACrC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,OAAO,CAAC;QACtC,WAAW,EAAE,yBAAyB;QACtC,eAAe,EAAE,KAAK;QACtB,oBAAoB,EAAE,KAAK;QAC3B,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACX,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;SACzB;KACD,CAAC,CAAC;AACJ,CAAC,CAAC,CAAC"}

package/dist/filesystem/file/unknown-file-fallback-plugin.d.ts

@@ -0,0 +1,23 @@
+import type { LixPlugin } from "../../plugin/lix-plugin.js";
+export declare const LixUnknownFileSchema: {
+    readonly type: "object";
+    readonly properties: {
+        readonly value: {
+            readonly type: "string";
+            readonly contentEncoding: "base64";
+            readonly description: "Base64-encoded binary file data";
+        };
+    };
+    readonly additionalProperties: false;
+    readonly "x-lix-key": "lix_unknown_file";
+    readonly "x-lix-version": "1.0";
+};
+/**
+ * Internal fallback plugin that handles unknown file types by storing the entire blob.
+ * This serves as a fallback for materialization when no specific plugin matches a file.
+ *
+ * This plugin always matches any file path and stores the complete file data
+ * as a single entity, allowing retrieval of the original file content.
+ */
+export declare const lixUnknownFileFallbackPlugin: LixPlugin;
+//# sourceMappingURL=unknown-file-fallback-plugin.d.ts.map

package/dist/filesystem/file/unknown-file-fallback-plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unknown-file-fallback-plugin.d.ts","sourceRoot":"","sources":["../../../src/filesystem/file/unknown-file-fallback-plugin.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAkB,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAE5E,eAAO,MAAM,oBAAoB;;;;;;;;;;;;CAYvB,CAAC;AAeX;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B,EAAE,SA0D1C,CAAC"}

package/dist/filesystem/file/unknown-file-fallback-plugin.js

@@ -0,0 +1,74 @@
+export const LixUnknownFileSchema = {
+    type: "object",
+    properties: {
+        value: {
+            type: "string",
+            contentEncoding: "base64",
+            description: "Base64-encoded binary file data",
+        },
+    },
+    additionalProperties: false,
+    "x-lix-key": "lix_unknown_file",
+    "x-lix-version": "1.0",
+};
+LixUnknownFileSchema;
+// From https://developer.mozilla.org/en-US/docs/Glossary/Base64#the_unicode_problem.
+function base64ToBytes(base64) {
+    const binString = atob(base64);
+    return Uint8Array.from(binString, (m) => m.codePointAt(0));
+}
+// From https://developer.mozilla.org/en-US/docs/Glossary/Base64#the_unicode_problem.
+function bytesToBase64(bytes) {
+    const binString = String.fromCodePoint(...bytes);
+    return btoa(binString);
+}
+/**
+ * Internal fallback plugin that handles unknown file types by storing the entire blob.
+ * This serves as a fallback for materialization when no specific plugin matches a file.
+ *
+ * This plugin always matches any file path and stores the complete file data
+ * as a single entity, allowing retrieval of the original file content.
+ */
+export const lixUnknownFileFallbackPlugin = {
+    key: "lix_unknown_file_fallback_plugin",
+    detectChangesGlob: "*", // Matches all files
+    detectChanges: ({ before, after }) => {
+        const detectedChanges = [];
+        // Compare the raw file data using Unicode-safe base64 encoding
+        const beforeData = before?.data;
+        const afterData = after.data;
+        const beforeBase64 = beforeData ? bytesToBase64(beforeData) : "";
+        const afterBase64 = afterData ? bytesToBase64(afterData) : "";
+        if (beforeBase64 !== afterBase64) {
+            detectedChanges.push({
+                schema: LixUnknownFileSchema,
+                entity_id: after.id,
+                snapshot_content: { value: afterBase64 }, // Store as Unicode-safe base64 string
+            });
+        }
+        return detectedChanges;
+    },
+    applyChanges: ({ file, changes }) => {
+        // This plugin snapshots the entire file, so there should only be one change
+        if (changes.length > 1) {
+            throw new Error(`[lix_unknown_file_fallback_plugin] Expected exactly one change for file ${file.id}, but received ${changes.length} changes`);
+        }
+        // There must be exactly one change for this file
+        if (changes.length === 0) {
+            throw new Error(`[lix_unknown_file_fallback_plugin] Expected exactly one change for file ${file.id}, but received no changes`);
+        }
+        const fileChange = changes[0]; // Safe since we validated length > 0
+        // The change must match this file's ID
+        if (fileChange.entity_id !== file.id) {
+            throw new Error(`[lix_unknown_file_fallback_plugin] Expected change for file ${file.id}, but received change for entity ${fileChange.entity_id}`);
+        }
+        if (typeof fileChange.snapshot_content?.value === "string") {
+            // Restore the blob from Unicode-safe base64 string
+            return {
+                fileData: base64ToBytes(fileChange.snapshot_content.value),
+            };
+        }
+        throw new Error(`[lix_unknown_file_fallback_plugin] Expected base64 string content for file ${file.id}, but received ${typeof fileChange.snapshot_content}`);
+    },
+};
+//# sourceMappingURL=unknown-file-fallback-plugin.js.map

package/dist/filesystem/file/unknown-file-fallback-plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unknown-file-fallback-plugin.js","sourceRoot":"","sources":["../../../src/filesystem/file/unknown-file-fallback-plugin.ts"],"names":[],"mappings":"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"}

package/dist/filesystem/file/unknown-file-fallback-plugin.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unknown-file-fallback-plugin.test.d.ts","sourceRoot":"","sources":["../../../src/filesystem/file/unknown-file-fallback-plugin.test.ts"],"names":[],"mappings":""}

package/dist/filesystem/file/unknown-file-fallback-plugin.test.js

@@ -0,0 +1,319 @@
+import { describe, it, expect } from "vitest";
+import { lixUnknownFileFallbackPlugin, LixUnknownFileSchema, } from "./unknown-file-fallback-plugin.js";
+// From https://developer.mozilla.org/en-US/docs/Glossary/Base64#the_unicode_problem.
+function bytesToBase64(bytes) {
+    const binString = String.fromCodePoint(...bytes);
+    return btoa(binString);
+}
+const createTestFile = (id, data) => ({
+    id,
+    path: `/test/${id}.unknown`,
+    data: new TextEncoder().encode(data),
+    directory_id: null,
+    name: id,
+    extension: "unknown",
+    metadata: null,
+    hidden: false,
+});
+// This plugin doesn't use database access; provide a dummy to satisfy types.
+const dummyQuerySync = (() => {
+    throw new Error("querySync not expected to be called in these tests");
+});
+describe("detectChanges", () => {
+    it("should detect changes when file data is different", () => {
+        const before = createTestFile("file1", "original content");
+        const after = createTestFile("file1", "updated content");
+        const changes = lixUnknownFileFallbackPlugin.detectChanges({
+            before,
+            after,
+            querySync: dummyQuerySync,
+        });
+        expect(changes).toHaveLength(1);
+        expect(changes[0]).toMatchObject({
+            schema: LixUnknownFileSchema,
+            entity_id: "file1",
+            snapshot_content: {
+                value: bytesToBase64(new TextEncoder().encode("updated content")),
+            },
+        });
+    });
+    it("should not detect changes when file data is identical", () => {
+        const before = createTestFile("file1", "same content");
+        const after = createTestFile("file1", "same content");
+        const changes = lixUnknownFileFallbackPlugin.detectChanges({
+            before,
+            after,
+            querySync: dummyQuerySync,
+        });
+        expect(changes).toHaveLength(0);
+    });
+    it("should detect changes when before file is undefined (new file)", () => {
+        const after = createTestFile("file1", "new file content");
+        const changes = lixUnknownFileFallbackPlugin.detectChanges({
+            after,
+            querySync: dummyQuerySync,
+        });
+        expect(changes).toHaveLength(1);
+        expect(changes[0]).toMatchObject({
+            schema: LixUnknownFileSchema,
+            entity_id: "file1",
+            snapshot_content: {
+                value: bytesToBase64(new TextEncoder().encode("new file content")),
+            },
+        });
+    });
+    it("should detect changes when before file has no data", () => {
+        const before = { ...createTestFile("file1", ""), data: undefined };
+        const after = createTestFile("file1", "new content");
+        const changes = lixUnknownFileFallbackPlugin.detectChanges({
+            before,
+            after,
+            querySync: dummyQuerySync,
+        });
+        expect(changes).toHaveLength(1);
+        expect(changes[0]).toMatchObject({
+            entity_id: "file1",
+            snapshot_content: {
+                value: bytesToBase64(new TextEncoder().encode("new content")),
+            },
+        });
+    });
+    it("should handle binary data correctly", () => {
+        const binaryData1 = new Uint8Array([0, 1, 2, 3, 255]);
+        const binaryData2 = new Uint8Array([0, 1, 2, 4, 255]);
+        const before = { ...createTestFile("file1", ""), data: binaryData1 };
+        const after = { ...createTestFile("file1", ""), data: binaryData2 };
+        const changes = lixUnknownFileFallbackPlugin.detectChanges({
+            before,
+            after,
+            querySync: dummyQuerySync,
+        });
+        expect(changes).toHaveLength(1);
+        expect(changes[0]?.snapshot_content.value).toEqual(bytesToBase64(binaryData2));
+    });
+    it("should handle empty files", () => {
+        const before = createTestFile("file1", "some content");
+        const after = createTestFile("file1", "");
+        const changes = lixUnknownFileFallbackPlugin.detectChanges({
+            before,
+            after,
+            querySync: dummyQuerySync,
+        });
+        expect(changes).toHaveLength(1);
+        expect(changes[0]?.snapshot_content.value).toEqual(bytesToBase64(new Uint8Array([])));
+    });
+    it("should handle Unicode content correctly", () => {
+        // Sample string from web.dev article with various Unicode code points
+        const unicodeContent = "hello⛳❤️🧀";
+        const before = createTestFile("file1", "simple ascii");
+        const after = createTestFile("file1", unicodeContent);
+        const changes = lixUnknownFileFallbackPlugin.detectChanges({
+            before,
+            after,
+            querySync: dummyQuerySync,
+        });
+        expect(changes).toHaveLength(1);
+        expect(changes[0]).toMatchObject({
+            schema: LixUnknownFileSchema,
+            entity_id: "file1",
+            snapshot_content: {
+                value: bytesToBase64(new TextEncoder().encode(unicodeContent)),
+            },
+        });
+        // Verify the content can be round-tripped correctly
+        const testChanges = [
+            {
+                id: "test-id",
+                entity_id: "test-file",
+                schema_key: "lix_unknown_file",
+                file_id: "test-file",
+                plugin_key: "lix_unknown_file_fallback_plugin",
+                created_at: "2023-01-01T00:00:00Z",
+                snapshot_content: changes[0]?.snapshot_content,
+                version_id: "test-version",
+            },
+        ];
+        const result = lixUnknownFileFallbackPlugin.applyChanges({
+            file: createTestFile("test-file", ""),
+            changes: testChanges,
+        });
+        // Decode the result back to string to verify Unicode preservation
+        const decodedContent = new TextDecoder().decode(result.fileData);
+        expect(decodedContent).toBe(unicodeContent);
+    });
+});
+describe("applyChanges", () => {
+    it("should restore file data from blob change", () => {
+        const originalData = "test file content";
+        const changes = [
+            {
+                id: "test-id",
+                entity_id: "test-file",
+                schema_key: "lix_unknown_file",
+                file_id: "test-file",
+                plugin_key: "lix_unknown_file_fallback_plugin",
+                created_at: "2023-01-01T00:00:00Z",
+                snapshot_content: {
+                    value: bytesToBase64(new TextEncoder().encode(originalData)),
+                },
+                version_id: "test-version",
+            },
+        ];
+        const result = lixUnknownFileFallbackPlugin.applyChanges({
+            file: createTestFile("test-file", ""),
+            changes,
+        });
+        expect(result.fileData).toEqual(new TextEncoder().encode(originalData));
+    });
+    it("should handle binary data restoration", () => {
+        const binaryData = new Uint8Array([0, 1, 2, 3, 255, 128, 64]);
+        const changes = [
+            {
+                id: "test-id",
+                entity_id: "binary-file",
+                schema_key: "lix_unknown_file",
+                file_id: "binary-file",
+                plugin_key: "lix_unknown_file_fallback_plugin",
+                created_at: "2023-01-01T00:00:00Z",
+                snapshot_content: { value: bytesToBase64(binaryData) },
+                version_id: "test-version",
+            },
+        ];
+        const result = lixUnknownFileFallbackPlugin.applyChanges({
+            file: createTestFile("binary-file", ""),
+            changes,
+        });
+        expect(result.fileData).toEqual(binaryData);
+    });
+    // The plugin should throw when no changes are provided because we snapshot
+    // the entire file, so there must always be exactly one change per file
+    it("should throw when no changes are provided", () => {
+        expect(() => {
+            lixUnknownFileFallbackPlugin.applyChanges({
+                file: createTestFile("test-file", ""),
+                changes: [],
+            });
+        }).toThrow("Expected exactly one change for file test-file, but received no changes");
+    });
+    // The plugin should throw when the change doesn't match the file ID because
+    // entity_id should always equal the file ID for this plugin
+    it("should throw when change entity_id doesn't match file ID", () => {
+        const changes = [
+            {
+                id: "test-id",
+                entity_id: "different-file-id",
+                schema_key: "lix_unknown_file",
+                file_id: "test-file",
+                plugin_key: "lix_unknown_file_fallback_plugin",
+                created_at: "2023-01-01T00:00:00Z",
+                snapshot_content: {
+                    value: "some content",
+                },
+                version_id: "test-version",
+            },
+        ];
+        expect(() => {
+            lixUnknownFileFallbackPlugin.applyChanges({
+                file: createTestFile("test-file", ""),
+                changes,
+            });
+        }).toThrow("Expected change for file test-file, but received change for entity different-file-id");
+    });
+    it("should handle valid base64 content", () => {
+        // Since we now always expect base64 strings, any valid base64 string should work
+        const changes = [
+            {
+                id: "test-id",
+                entity_id: "test-file",
+                schema_key: "lix_unknown_file",
+                file_id: "test-file",
+                plugin_key: "lix_unknown_file_fallback_plugin",
+                created_at: "2023-01-01T00:00:00Z",
+                snapshot_content: {
+                    value: "",
+                },
+                version_id: "test-version",
+            },
+        ];
+        const result = lixUnknownFileFallbackPlugin.applyChanges({
+            file: createTestFile("test-file", ""),
+            changes,
+        });
+        expect(result.fileData).toEqual(new Uint8Array());
+    });
+    // The plugin should throw when receiving more than one change because
+    // we snapshot the entire file as a single blob, not multiple pieces
+    it("should throw when receiving more than one change", () => {
+        const changes = [
+            {
+                id: "test-id-1",
+                entity_id: "test-file",
+                schema_key: "lix_unknown_file",
+                file_id: "test-file",
+                plugin_key: "lix_unknown_file_fallback_plugin",
+                snapshot_id: "test-snapshot-1",
+                created_at: "2023-01-01T00:00:00Z",
+                snapshot_content: {
+                    value: bytesToBase64(new TextEncoder().encode("content1")),
+                },
+                version_id: "test-version",
+            },
+            {
+                id: "test-id-2",
+                entity_id: "test-file",
+                schema_key: "lix_unknown_file",
+                file_id: "test-file",
+                plugin_key: "lix_unknown_file_fallback_plugin",
+                snapshot_id: "test-snapshot-2",
+                created_at: "2023-01-01T00:00:00Z",
+                snapshot_content: {
+                    value: bytesToBase64(new TextEncoder().encode("content2")),
+                },
+                version_id: "test-version",
+            },
+        ];
+        expect(() => {
+            lixUnknownFileFallbackPlugin.applyChanges({
+                file: createTestFile("test-file", ""),
+                changes,
+            });
+        }).toThrow("Expected exactly one change for file test-file, but received 2 changes");
+    });
+    // The plugin should throw when snapshot_content is not a string because
+    // we always store file data as base64-encoded strings
+    it("should throw when snapshot_content is not a string", () => {
+        const changes = [
+            {
+                id: "test-id",
+                entity_id: "test-file",
+                schema_key: "lix_unknown_file",
+                file_id: "test-file",
+                plugin_key: "lix_unknown_file_fallback_plugin",
+                created_at: "2023-01-01T00:00:00Z",
+                snapshot_content: { value: { not: "a string" } },
+                version_id: "test-version",
+            },
+        ];
+        expect(() => {
+            lixUnknownFileFallbackPlugin.applyChanges({
+                file: createTestFile("test-file", ""),
+                changes,
+            });
+        }).toThrow("Expected base64 string content for file test-file, but received object");
+    });
+});
+describe("plugin configuration", () => {
+    it("should have correct key", () => {
+        expect(lixUnknownFileFallbackPlugin.key).toBe("lix_unknown_file_fallback_plugin");
+    });
+    it("should have glob pattern that matches all files", () => {
+        expect(lixUnknownFileFallbackPlugin.detectChangesGlob).toBe("*");
+    });
+    it("should have detectChanges function", () => {
+        expect(typeof lixUnknownFileFallbackPlugin.detectChanges).toBe("function");
+    });
+    it("should have applyChanges function", () => {
+        expect(typeof lixUnknownFileFallbackPlugin.applyChanges).toBe("function");
+    });
+});
+//# sourceMappingURL=unknown-file-fallback-plugin.test.js.map