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

package/src/label/schema.test.ts

@@ -0,0 +1,92 @@
+import { expect, test } from "vitest";
+import { openLix } from "../lix/open-lix.js";
+
+test("creates checkpoint label on boot up", async () => {
+	const lix = await openLix({});
+
+	const checkpointLabel = await lix.db
+		.selectFrom("label")
+		.where("name", "=", "checkpoint")
+		.selectAll()
+		.executeTakeFirst();
+
+	expect(checkpointLabel).toBeDefined();
+	expect(checkpointLabel?.name).toBe("checkpoint");
+	expect(checkpointLabel?.id).toBeDefined();
+});
+
+test("insert, update, delete on the label view", async () => {
+	const lix = await openLix({});
+
+	await lix.db
+		.insertInto("label")
+		.values({ id: "label1", name: "bug" })
+		.execute();
+
+	const viewAfterInsert = await lix.db
+		.selectFrom("label")
+		.where("id", "=", "label1")
+		.selectAll()
+		.execute();
+
+	expect(viewAfterInsert).toMatchObject([
+		{
+			id: "label1",
+			name: "bug",
+		},
+	]);
+
+	await lix.db
+		.updateTable("label")
+		.where("id", "=", "label1")
+		.set({ name: "feature" })
+		.execute();
+
+	const viewAfterUpdate = await lix.db
+		.selectFrom("label")
+		.where("id", "=", "label1")
+		.selectAll()
+		.execute();
+
+	expect(viewAfterUpdate).toMatchObject([
+		{
+			id: "label1",
+			name: "feature",
+		},
+	]);
+
+	await lix.db.deleteFrom("label").where("id", "=", "label1").execute();
+
+	const viewAfterDelete = await lix.db
+		.selectFrom("label")
+		.where("id", "=", "label1")
+		.selectAll()
+		.execute();
+
+	expect(viewAfterDelete).toEqual([]);
+
+	const changes = await lix.db
+		.selectFrom("change")
+
+		.where("schema_key", "=", "lix_label")
+		.where("entity_id", "=", "label1")
+		.orderBy("change.created_at", "asc")
+		.selectAll("change")
+
+		.execute();
+
+	expect(changes.map((change) => change.snapshot_content)).toMatchObject([
+		// insert
+		{
+			id: "label1",
+			name: "bug",
+		},
+		// update
+		{
+			id: "label1",
+			name: "feature",
+		},
+		// delete
+		null,
+	]);
+});

package/src/label/schema.ts

@@ -0,0 +1,37 @@
+import type {
+	LixSchemaDefinition,
+	FromLixSchemaDefinition,
+} from "../schema-definition/definition.js";
+import { createEntityViewsIfNotExists } from "../entity-views/entity-view-builder.js";
+import { nanoId } from "../deterministic/index.js";
+import type { Lix } from "../lix/open-lix.js";
+
+export function applyLabelDatabaseSchema(
+	lix: Pick<Lix, "sqlite" | "db">
+): void {
+	createEntityViewsIfNotExists({
+		lix,
+		schema: LixLabelSchema,
+		overrideName: "label",
+		pluginKey: "lix_own_entity",
+		hardcodedFileId: "lix",
+		defaultValues: { id: () => nanoId({ lix }) },
+	});
+}
+
+export const LixLabelSchema = {
+	"x-lix-key": "lix_label",
+	"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;
+LixLabelSchema satisfies LixSchemaDefinition;
+
+// Pure business logic type (inferred from schema)
+export type LixLabel = FromLixSchemaDefinition<typeof LixLabelSchema>;

package/src/lix/index.ts

@@ -1,8 +1,5 @@
 export { type Lix, openLix } from "./open-lix.js";
-export { openLixInMemory } from "./open-lix-in-memory.js";
 export { newLixFile } from "./new-lix.js";
-export { toBlob } from "./to-blob.js";
-export { closeLix } from "./close-lix.js";
-// not exporting merge for api stability milestone
-// will need an overhaul to be stable
-// export { merge } from "./merge.js";
+export { type LixStorageAdapter } from "./storage/lix-storage-adapter.js";
+export { InMemoryStorage } from "./storage/in-memory.js";
+export { OpfsStorage } from "./storage/opfs.js";

package/src/lix/new-lix.test.ts

@@ -1,23 +1,419 @@
 import { test, expect } from "vitest";
-import { openLixInMemory } from "./open-lix-in-memory.js";
 import { newLixFile } from "./new-lix.js";
+import { openLix } from "./open-lix.js";
+import { LixSchemaViewMap } from "../database/schema.js";
 
-test("inserting a change should auto fill the created_at column", async () => {
-	const lix = await openLixInMemory({ blob: await newLixFile() });
+test("newLixFile creates a valid lix that can be reopened", async () => {
+	// Create a new lix file
+	const blob = await newLixFile();
+	expect(blob.size).toBeGreaterThan(0);
 
-	await lix.db
-		.insertInto("change")
-		.values({
-			id: "test",
-			entity_id: "test",
-			schema_key: "file",
-			file_id: "mock",
-			plugin_key: "mock-plugin",
-			snapshot_id: "no-content",
-		})
+	// Open the created lix file
+	const lix = await openLix({ blob });
+
+	// Try to query the state table to ensure it works
+	const result = await lix.db.selectFrom("state_all").selectAll().execute();
+	expect(Array.isArray(result)).toBe(true);
+});
+
+test("newLixFile creates a global and main version", async () => {
+	const blob = await newLixFile();
+	const lix = await openLix({ blob });
+
+	// Check that both global and main versions exist
+	const versions = await lix.db.selectFrom("version").selectAll().execute();
+
+	expect(versions).toHaveLength(2);
+
+	// Check global version exists
+	const globalVersion = versions.find((v) => v.name === "global");
+	expect(globalVersion).toBeDefined();
+	expect(globalVersion?.inherits_from_version_id).toBeNull();
+
+	// Check main version exists
+	const mainVersion = versions.find((v) => v.name === "main");
+	expect(mainVersion).toBeDefined();
+	expect(mainVersion?.inherits_from_version_id).toBe("global");
+});
+
+test("newLixFile creates required bootstrap change sets", async () => {
+	const blob = await newLixFile();
+	const lix = await openLix({ blob });
+
+	// Check that change sets exist (should be 4: 2 for global, 2 for main)
+	const changeSets = await lix.db
+		.selectFrom("change_set")
+		.selectAll()
+		.execute();
+
+	expect(changeSets).toHaveLength(4);
+});
+
+test("newLixFile creates checkpoint label", async () => {
+	const blob = await newLixFile();
+	const lix = await openLix({ blob });
+
+	// Check that checkpoint label exists
+	const labels = await lix.db.selectFrom("label").selectAll().execute();
+
+	expect(labels).toHaveLength(1);
+	expect(labels[0]?.name).toBe("checkpoint");
+});
+
+test("newLixFile creates all schema definitions", async () => {
+	const blob = await newLixFile();
+	const lix = await openLix({ blob });
+
+	// Check that all schemas from LixSchemaViewMap are created
+	const storedSchemas = await lix.db
+		.selectFrom("stored_schema")
+		.selectAll()
+		.execute();
+
+	const expectedSchemaCount = Object.keys(LixSchemaViewMap).length;
+	expect(storedSchemas).toHaveLength(expectedSchemaCount);
+
+	// Check that each schema from LixSchemaViewMap exists
+	for (const schema of Object.values(LixSchemaViewMap)) {
+		const storedSchema = storedSchemas.find(
+			(s) => s.key === schema["x-lix-key"]
+		);
+		expect(storedSchema).toBeDefined();
+		expect(storedSchema?.version).toBe(schema["x-lix-version"]);
+		expect(storedSchema?.lixcol_inherited_from_version_id).toBe("global");
+
+		// Verify the stored value is valid JSON and matches the schema
+		expect(storedSchema?.value["x-lix-key"]).toBe(schema["x-lix-key"]);
+		expect(storedSchema?.value["x-lix-version"]).toBe(schema["x-lix-version"]);
+	}
+});
+
+test("newLixFile creates change set elements for all changes", async () => {
+	const blob = await newLixFile();
+	const lix = await openLix({ blob });
+
+	// Check that change set elements exist
+	const changeSetElements = await lix.db
+		.selectFrom("change_set_element")
+		.selectAll()
+		.execute();
+
+	// Should have change set elements for all bootstrap changes
+	expect(changeSetElements.length).toBeGreaterThan(0);
+});
+
+test("bootstrap changes include lix_id key-value in global version", async () => {
+	const blob = await newLixFile();
+	const lix = await openLix({ blob });
+
+	const kv = await lix.db
+		.selectFrom("key_value_all")
+		.where("key", "=", "lix_id")
+		.where("lixcol_version_id", "=", "global")
+		.selectAll()
 		.execute();
 
-	const changes = await lix.db.selectFrom("change").selectAll().execute();
-	expect(changes).lengthOf(1);
-	expect(changes[0]?.created_at).toBeDefined();
+	expect(kv).toHaveLength(1);
+	expect(kv[0]?.key).toBe("lix_id");
+	expect(kv[0]?.value).toBeDefined();
+});
+
+test("bootstrap changes include lix_name key-value in the global version", async () => {
+	const blob = await newLixFile();
+	const lix = await openLix({ blob });
+
+	const kv = await lix.db
+		.selectFrom("key_value_all")
+		.where("key", "=", "lix_name")
+		.where("lixcol_version_id", "=", "global")
+		.selectAll()
+		.execute();
+
+	expect(kv).toHaveLength(1);
+	expect(kv[0]?.key).toBe("lix_name");
+	expect(kv[0]?.value).toBeDefined();
+});
+
+test("newLixFile returns blob with ._lix.id property", async () => {
+	const blob = await newLixFile();
+
+	// Check that ._lix.id is accessible directly on the blob
+	expect(blob._lix).toBeDefined();
+	expect(blob._lix.id).toBeDefined();
+	expect(typeof blob._lix.id).toBe("string");
+	expect(blob._lix.id.length).toBeGreaterThan(0);
+
+	// Verify the ._lix.id matches the one stored in the database
+	const lix = await openLix({ blob });
+	const kv = await lix.db
+		.selectFrom("key_value_all")
+		.where("key", "=", "lix_id")
+		.where("lixcol_version_id", "=", "global")
+		.selectAll()
+		.execute();
+
+	expect(kv).toHaveLength(1);
+	expect(blob._lix.id).toBe(kv[0]?.value);
+});
+
+test("newLixFile returns blob with ._lix.name property", async () => {
+	const blob = await newLixFile({});
+
+	// Check that ._lix.name is accessible directly on the blob
+	expect(blob._lix).toBeDefined();
+	expect(blob._lix.name).toBeDefined();
+	expect(typeof blob._lix.name).toBe("string");
+	expect(blob._lix.name.length).toBeGreaterThan(0);
+
+	// Verify the ._lix.name matches the one stored in the database
+	const lix = await openLix({ blob });
+	const kv = await lix.db
+		.selectFrom("key_value_all")
+		.where("key", "=", "lix_name")
+		.where("lixcol_version_id", "=", "global")
+		.selectAll()
+		.execute();
+
+	expect(kv).toHaveLength(1);
+	expect(blob._lix.name).toBe(kv[0]?.value);
+});
+
+test("newLixFile can use provided key values", async () => {
+	const blob = await newLixFile({
+		keyValues: [
+			{ key: "lix_name", value: "Test Lix Name", lixcol_version_id: "global" },
+			{ key: "lix_id", value: "test-lix-id", lixcol_version_id: "global" },
+			{ key: "custom_key", value: "custom_value", lixcol_version_id: "global" },
+		],
+	});
+
+	// Check the `_lix` property on the blob
+	expect(blob._lix.name).toBe("Test Lix Name");
+	expect(blob._lix.id).toBe("test-lix-id");
+
+	// Check the values in the database
+	const lix = await openLix({ blob });
+	const nameKv = await lix.db
+		.selectFrom("key_value_all")
+		.where("key", "=", "lix_name")
+		.selectAll()
+		.executeTakeFirst();
+	expect(nameKv?.value).toBe("Test Lix Name");
+
+	const idKv = await lix.db
+		.selectFrom("key_value_all")
+		.where("key", "=", "lix_id")
+		.selectAll()
+		.executeTakeFirst();
+	expect(idKv?.value).toBe("test-lix-id");
+
+	const customKv = await lix.db
+		.selectFrom("key_value_all")
+		.where("key", "=", "custom_key")
+		.selectAll()
+		.executeTakeFirst();
+	expect(customKv?.value).toBe("custom_value");
+	expect(customKv?.lixcol_version_id).toBe("global");
+});
+
+test("provided key values default to the active version if lixcol_version_id is not specified", async () => {
+	const blob = await newLixFile({
+		keyValues: [
+			{ key: "test_key_1", value: "test_value_1" },
+			{ key: "test_key_2", value: "test_value_2" },
+		],
+	});
+
+	const lix = await openLix({ blob });
+
+	// Get the active version
+	const activeVersion = await lix.db
+		.selectFrom("active_version")
+		.select("version_id")
+		.executeTakeFirst();
+
+	expect(activeVersion).toBeDefined();
+	expect(activeVersion?.version_id).toBeDefined();
+
+	// Check that the key values are associated with the active version
+	const kv1 = await lix.db
+		.selectFrom("key_value_all")
+		.where("key", "=", "test_key_1")
+		.selectAll()
+		.executeTakeFirst();
+
+	expect(kv1?.value).toBe("test_value_1");
+	expect(kv1?.lixcol_version_id).toBe(activeVersion?.version_id);
+
+	const kv2 = await lix.db
+		.selectFrom("key_value_all")
+		.where("key", "=", "test_key_2")
+		.selectAll()
+		.executeTakeFirst();
+
+	expect(kv2?.value).toBe("test_value_2");
+	expect(kv2?.lixcol_version_id).toBe(activeVersion?.version_id);
+
+	// The active version should be "main" (not "global")
+	const mainVersion = await lix.db
+		.selectFrom("version")
+		.where("id", "=", activeVersion!.version_id)
+		.selectAll()
+		.executeTakeFirst();
+
+	expect(mainVersion?.name).toBe("main");
+});
+
+test("deterministic mode with randomLixId: true results in different lix_ids", async () => {
+	// Create two lix files with deterministic mode but randomLixId: true
+	const blob1 = await newLixFile({
+		keyValues: [
+			{
+				key: "lix_deterministic_mode",
+				value: { enabled: true, randomLixId: true },
+			},
+		],
+	});
+	const blob2 = await newLixFile({
+		keyValues: [
+			{
+				key: "lix_deterministic_mode",
+				value: { enabled: true, randomLixId: true },
+			},
+		],
+	});
+
+	// The lix_ids should be different when randomLixId is true
+	expect(blob1._lix.id).toBeDefined();
+	expect(blob2._lix.id).toBeDefined();
+	expect(blob1._lix.id).not.toBe(blob2._lix.id);
+});
+
+test("deterministic mode results in identical lix_ids", async () => {
+	// Create two lix files with deterministic mode enabled
+	const blob1 = await newLixFile({
+		keyValues: [
+			{
+				key: "lix_deterministic_mode",
+				value: { enabled: true },
+			},
+		],
+	});
+	const blob2 = await newLixFile({
+		keyValues: [
+			{
+				key: "lix_deterministic_mode",
+				value: { enabled: true },
+			},
+		],
+	});
+
+	// The lix_ids should be identical (deterministic-lix-id)
+	expect(blob1._lix.id).toBeDefined();
+	expect(blob2._lix.id).toBeDefined();
+	expect(blob1._lix.id).toBe(blob2._lix.id);
+	expect(blob1._lix.id).toBe("deterministic-lix-id");
+});
+
+test("deterministic mode creates fully deterministic lix", async () => {
+	// Create two lix files with deterministic mode enabled
+	const blob1 = await newLixFile({
+		keyValues: [
+			{
+				key: "lix_deterministic_mode",
+				value: { enabled: true },
+			},
+		],
+	});
+	const blob2 = await newLixFile({
+		keyValues: [
+			{
+				key: "lix_deterministic_mode",
+				value: { enabled: true },
+			},
+		],
+	});
+
+	const lix1 = await openLix({ blob: blob1 });
+	const lix2 = await openLix({ blob: blob2 });
+
+	// Check that all changes have identical IDs and timestamps
+	const changes1 = await lix1.db
+		.selectFrom("change")
+		.select(["id", "entity_id", "created_at"])
+		.orderBy("id")
+		.execute();
+	const changes2 = await lix2.db
+		.selectFrom("change")
+		.select(["id", "entity_id", "created_at"])
+		.orderBy("id")
+		.execute();
+
+	expect(changes1).toEqual(changes2);
+
+	// Check that all entity IDs are identical
+	const versions1 = await lix1.db
+		.selectFrom("version")
+		.select(["id", "name"])
+		.orderBy("id")
+		.execute();
+	const versions2 = await lix2.db
+		.selectFrom("version")
+		.select(["id", "name"])
+		.orderBy("id")
+		.execute();
+
+	expect(versions1).toEqual(versions2);
+
+	// Check timestamps are deterministic (epoch 0)
+	expect(changes1[0]?.created_at).toBe("1970-01-01T00:00:00.000Z");
+});
+
+test("deterministic mode config is persisted correctly", async () => {
+	const blob = await newLixFile({
+		keyValues: [
+			{
+				key: "lix_deterministic_mode",
+				value: { enabled: true, randomLixId: false },
+			},
+		],
+	});
+	const lix = await openLix({ blob });
+
+	// Check that lix_deterministic_mode exists in key_value_all
+	// Since no lixcol_version_id was specified, it should be in the main version
+	const result = await lix.db
+		.selectFrom("key_value_all")
+		.where("key", "=", "lix_deterministic_mode")
+		.select(["key", "value", "lixcol_version_id"])
+		.executeTakeFirst();
+
+	expect(result).toBeDefined();
+	expect(result?.key).toBe("lix_deterministic_mode");
+	expect(result?.value).toEqual({ enabled: true, randomLixId: false }); // JSON values are preserved
+});
+
+test("deterministic mode config with global version_id is persisted correctly", async () => {
+	const blob = await newLixFile({
+		keyValues: [
+			{
+				key: "lix_deterministic_mode",
+				value: { enabled: true, randomLixId: true },
+				lixcol_version_id: "global",
+			},
+		],
+	});
+	const lix = await openLix({ blob });
+
+	// Check that lix_deterministic_mode exists with global version_id
+	const result = await lix.db
+		.selectFrom("key_value_all")
+		.where("key", "=", "lix_deterministic_mode")
+		.where("lixcol_version_id", "=", "global")
+		.select(["key", "value"])
+		.executeTakeFirst();
+
+	expect(result).toBeDefined();
+	expect(result?.key).toBe("lix_deterministic_mode");
+	expect(result?.value).toEqual({ enabled: true, randomLixId: true }); // JSON values are preserved
 });