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

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

@@ -1,23 +1,219 @@
 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() });
-
-	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",
-		})
+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);
+
+	// 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();
+
+	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();
+
+	console.log("lix_name key-value:", kv);
+
+	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();
 
-	const changes = await lix.db.selectFrom("change").selectAll().execute();
-	expect(changes).lengthOf(1);
-	expect(changes[0]?.created_at).toBeDefined();
+	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");
 });

package/src/lix/new-lix.ts

@@ -3,27 +3,414 @@ import {
 	contentFromDatabase,
 } from "sqlite-wasm-kysely";
 import { initDb } from "../database/init-db.js";
-import { closeLix } from "./close-lix.js";
+import { v7 as uuid_v7 } from "uuid";
+import { nanoid } from "../database/nano-id.js";
+import { LixVersionSchema, type Version } from "../version/schema.js";
+import {
+	LixChangeSetSchema,
+	LixChangeSetElementSchema,
+	type ChangeSet,
+	type ChangeSetElement,
+} from "../change-set/schema.js";
+import { LixLabelSchema, type Label } from "../label/schema.js";
+import { LixKeyValueSchema, type KeyValue } from "../key-value/schema.js";
+import { LixSchemaViewMap } from "../database/schema.js";
+import type { Change } from "../change/schema.js";
+import type { StoredSchema } from "../stored-schema/schema.js";
+import { createHooks } from "../hooks/create-hooks.js";
+import { humanId } from "human-id";
+import type { NewStateAll } from "../entity-views/types.js";
 
 /**
- * Creates a new lix file.
+ * A Blob with an attached `._lix` property for easy access to some lix properties.
+ *
+ * For example, the `._lix` property provides immediate access to essential metadata
+ * like `id` and `name` without needing to parse the file. This is particularly useful
+ * for scenarios where you need to identify a Lix file before fully opening it.
+ *
+ * @example
+ * // With `._lix`, the ID is instantly available:
+ * const blob = await newLixFile();
+ * console.log(blob._lix.id); // e.g., "z2k9j6d"
+ *
+ * @example
+ * // Without `._lix`, you would need to open the lix to get its ID:
+ * const blob = await newLixFile();
+ * // Open the lix to access its metadata
+ * const lix = await openLix({ blob });
+ * const id = await lix.db.selectFrom("key_value")
+ *   .where("key", "=", "lix_id")
+ *   .select("value")
+ *   .executeTakeFirst();
+ * await lix.close();
  *
- * The app is responsible for saving the project "whereever"
- * e.g. the user's computer, cloud storage, or OPFS in the browser.
  */
-export async function newLixFile(): Promise<Blob> {
+export interface NewLixBlob extends Blob {
+	_lix: {
+		id: string;
+		name: string;
+	};
+}
+
+/**
+ * Creates a new Lix file as a {@link NewLixBlob}.
+ *
+ * This function bootstraps an in-memory SQLite database with the necessary
+ * schema and metadata to represent a valid Lix project. The resulting
+ * blob is ready to be persisted to disk, IndexedDB, or other storage.
+ *
+ * The returned blob has a `._lix` property for immediate access to the
+ * lix identifier and name without needing to open the file.
+ *
+ * @example
+ * ```ts
+ * // Create a new lix file with default values
+ * const blob = await newLixFile();
+ * console.log(blob._lix.id); // e.g. "z2k9j6d"
+ * console.log(blob._lix.name); // e.g. "blue-gorilla"
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Create a new lix file with specific key-values
+ * const blob = await newLixFile({
+ *   keyValues: [
+ *     { key: "lix_name", value: "my-project", lixcol_version_id: "global" },
+ *     { key: "lix_id", value: "custom-id", lixcol_version_id: "global" },
+ *     { key: "my_custom_key", value: "my_custom_value", lixcol_version_id: "global" }
+ *   ],
+ * });
+ * console.log(blob._lix.id); // "custom-id"
+ * console.log(blob._lix.name); // "my-project"
+ * ```
+ */
+export async function newLixFile(args?: {
+	/**
+	 * Pre-populates the key-value store of the new lix file.
+	 *
+	 * Use this to set initial values for `lix_id`, `lix_name`, or other custom keys.
+	 * If `lix_id` or `lix_name` are not provided, they will be generated automatically.
+	 *
+	 * @example
+	 *  keyValues: [
+	 *    { key: "lix_name", value: "my-project", lixcol_version_id: "global" },
+	 *    { key: "lix_id", value: "custom-id", lixcol_version_id: "global" },
+	 *    { key: "my_custom_key", value: "my_custom_value", lixcol_version_id: "global" },
+	 *  ]
+	 */
+	keyValues?: NewStateAll<KeyValue>[];
+}): Promise<NewLixBlob> {
 	const sqlite = await createInMemoryDatabase({
 		readOnly: false,
 	});
 
+	const hooks = createHooks();
+
 	// applying the schema etc.
-	const db = initDb({ sqlite });
+	const db = initDb({ sqlite, hooks });
+
+	// Create bootstrap changes for initial data
+	const bootstrapChanges = createBootstrapChanges(args?.keyValues);
+
+	// Extract the lix_id from bootstrap changes
+	const lixId = bootstrapChanges.find(
+		(c) =>
+			c.schema_key === "lix_key_value" && c.snapshot_content?.key === "lix_id"
+	)?.snapshot_content.value;
+
+	const lixName = bootstrapChanges.find(
+		(c) =>
+			c.schema_key === "lix_key_value" && c.snapshot_content?.key === "lix_name"
+	)?.snapshot_content.value;
+
+	// Insert all bootstrap changes directly into the change tables
+	for (const change of bootstrapChanges) {
+		// Insert snapshot content if it exists
+		let snapshotId = "no-content";
+		if (change.snapshot_content) {
+			const result = sqlite.exec({
+				sql: `INSERT INTO internal_snapshot (content) VALUES (jsonb(?)) RETURNING id`,
+				bind: [JSON.stringify(change.snapshot_content)],
+				returnValue: "resultRows",
+			});
+			if (result && result.length > 0) {
+				snapshotId = result[0]![0] as string;
+			}
+		}
+
+		// Insert the change record
+		sqlite.exec({
+			sql: `INSERT INTO internal_change (id, entity_id, schema_key, schema_version, file_id, plugin_key, snapshot_id, created_at)
+				   VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+			bind: [
+				change.id,
+				change.entity_id,
+				change.schema_key,
+				change.schema_version,
+				change.file_id,
+				change.plugin_key,
+				snapshotId,
+				change.created_at,
+			],
+		});
+	}
+
+	// The initial version ID will be set by createBootstrapChanges
+	const initialVersionId = bootstrapChanges.find(
+		(c) => c.schema_key === "lix_version" && c.snapshot_content?.name === "main"
+	)?.entity_id;
+
+	sqlite.exec(`
+		INSERT INTO active_version (version_id)
+		SELECT '${initialVersionId}'
+		WHERE NOT EXISTS (SELECT 1 FROM active_version);
+`);
 
 	try {
-		return new Blob([contentFromDatabase(sqlite)]);
+		const blob = new Blob([contentFromDatabase(sqlite)]);
+		// Create a LixBlob by extending the blob with the lix property
+		const lixBlob = Object.assign(blob, {
+			_lix: {
+				id: lixId,
+				name: lixName,
+			},
+		}) as NewLixBlob;
+		return lixBlob;
 	} catch (e) {
 		throw new Error(`Failed to create new Lix file: ${e}`, { cause: e });
 	} finally {
-		closeLix({ lix: { db } });
+		await db.destroy();
 	}
 }
+
+type BootstrapChange = Omit<Change, "snapshot_id"> & {
+	snapshot_content: any;
+};
+
+/**
+ * Creates all bootstrap changes needed for a new lix file.
+ * All entities are created in a single change set to avoid dependency ordering issues.
+ */
+function createBootstrapChanges(
+	providedKeyValues?: NewStateAll<KeyValue>[]
+): BootstrapChange[] {
+	const changes: BootstrapChange[] = [];
+	const created_at = new Date().toISOString();
+
+	// Generate random IDs for initial entities
+	const initialVersionId = nanoid();
+	const initialChangeSetId = nanoid();
+	const initialWorkingChangeSetId = nanoid();
+	const initialGlobalVersionChangeSetId = nanoid();
+	const initialGlobalVersionWorkingChangeSetId = nanoid();
+
+	// Create all required change sets
+	const changeSets: ChangeSet[] = [
+		{
+			id: initialGlobalVersionChangeSetId,
+		},
+		{
+			id: initialGlobalVersionWorkingChangeSetId,
+		},
+		{
+			id: initialChangeSetId,
+		},
+		{
+			id: initialWorkingChangeSetId,
+		},
+	];
+
+	for (const changeSet of changeSets) {
+		changes.push({
+			id: uuid_v7(),
+			entity_id: changeSet.id,
+			schema_key: "lix_change_set",
+			schema_version: LixChangeSetSchema["x-lix-version"],
+			file_id: "lix",
+			plugin_key: "lix_own_entity",
+			snapshot_content: changeSet,
+			created_at,
+		});
+	}
+
+	// Create global version
+	changes.push({
+		id: uuid_v7(),
+		entity_id: "global",
+		schema_key: "lix_version",
+		schema_version: LixVersionSchema["x-lix-version"],
+		file_id: "lix",
+		plugin_key: "lix_own_entity",
+		snapshot_content: {
+			id: "global",
+			name: "global",
+			change_set_id: initialGlobalVersionChangeSetId,
+			working_change_set_id: initialGlobalVersionWorkingChangeSetId,
+			hidden: true,
+		} satisfies Version,
+		created_at,
+	});
+
+	// Create main version
+	changes.push({
+		id: uuid_v7(),
+		entity_id: initialVersionId,
+		schema_key: "lix_version",
+		schema_version: LixVersionSchema["x-lix-version"],
+		file_id: "lix",
+		plugin_key: "lix_own_entity",
+		snapshot_content: {
+			id: initialVersionId,
+			name: "main",
+			change_set_id: initialChangeSetId,
+			working_change_set_id: initialWorkingChangeSetId,
+			inherits_from_version_id: "global",
+			hidden: false,
+		} satisfies Version,
+		created_at,
+	});
+
+	// Create default checkpoint label
+	const checkpointLabelId = nanoid();
+	changes.push({
+		id: uuid_v7(),
+		entity_id: checkpointLabelId,
+		schema_key: "lix_label",
+		schema_version: LixLabelSchema["x-lix-version"],
+		file_id: "lix",
+		plugin_key: "lix_own_entity",
+		snapshot_content: {
+			id: checkpointLabelId,
+			name: "checkpoint",
+		} satisfies Label,
+		created_at,
+	});
+
+	// Create lix_id key-value pair
+	const lixId = providedKeyValues?.find((kv) => kv.key === "lix_id")?.value;
+	changes.push({
+		id: uuid_v7(),
+		entity_id: "lix_id",
+		schema_key: "lix_key_value",
+		schema_version: LixKeyValueSchema["x-lix-version"],
+		file_id: "lix",
+		plugin_key: "lix_own_entity",
+		snapshot_content: {
+			key: "lix_id",
+			value: lixId ?? nanoid(10),
+		} satisfies KeyValue,
+		created_at,
+	});
+
+	// create lix_name key-value pair
+	const lixName = providedKeyValues?.find((kv) => kv.key === "lix_name")?.value;
+	changes.push({
+		id: uuid_v7(),
+		entity_id: "lix_name",
+		schema_key: "lix_key_value",
+		schema_version: LixKeyValueSchema["x-lix-version"],
+		file_id: "lix",
+		plugin_key: "lix_own_entity",
+		snapshot_content: {
+			key: "lix_name",
+			value: lixName ?? humanId({ separator: "-", capitalize: false }),
+		} satisfies KeyValue,
+		created_at,
+	});
+
+	// Create any other provided key-values
+	if (providedKeyValues) {
+		for (const kv of providedKeyValues) {
+			if (kv.key === "lix_id" || kv.key === "lix_name" || !kv.key || !kv.value)
+				continue;
+
+			changes.push({
+				id: uuid_v7(),
+				entity_id: kv.key,
+				schema_key: "lix_key_value",
+				schema_version: LixKeyValueSchema["x-lix-version"],
+				file_id: "lix",
+				plugin_key: "lix_own_entity",
+				snapshot_content: {
+					key: kv.key,
+					value: kv.value,
+				} satisfies KeyValue,
+				created_at,
+			});
+		}
+	}
+
+	// Create all schema definitions
+	for (const schema of Object.values(LixSchemaViewMap)) {
+		changes.push({
+			id: uuid_v7(),
+			entity_id: schema["x-lix-key"],
+			schema_key: "lix_stored_schema",
+			schema_version: "1.0",
+			file_id: "lix",
+			plugin_key: "lix_own_entity",
+			snapshot_content: {
+				key: schema["x-lix-key"],
+				version: schema["x-lix-version"],
+				value: JSON.stringify(schema),
+			} satisfies StoredSchema,
+			created_at,
+		});
+	}
+
+	// Create change set elements linking all changes to the global change set
+	const originalChanges = [...changes]; // snapshot of original changes
+	const changeSetElementChanges: BootstrapChange[] = [];
+
+	// First, create change set elements for all original changes
+	for (const change of originalChanges) {
+		const changeSetElementChange = {
+			id: uuid_v7(),
+			entity_id: `${initialGlobalVersionChangeSetId}::${change.id}`,
+			schema_key: "lix_change_set_element",
+			schema_version: LixChangeSetElementSchema["x-lix-version"],
+			file_id: "lix",
+			plugin_key: "lix_own_entity",
+			snapshot_content: {
+				change_set_id: initialGlobalVersionChangeSetId,
+				change_id: change.id,
+				entity_id: change.entity_id,
+				schema_key: change.schema_key,
+				file_id: change.file_id,
+			} satisfies ChangeSetElement,
+			created_at,
+		};
+		changes.push(changeSetElementChange);
+		changeSetElementChanges.push(changeSetElementChange);
+	}
+
+	// TODO evaluate if we can come up with a better concept to avoid meta changes (if even desired)
+	//
+	// this is the cost of change set (elements). we need to track what's in a
+	// change set itself. The struggle is that working change set is by definition
+	// mutable, and probably other user interactions for a change set too.
+	//
+	//
+	// Create change set elements for the change set element changes themselves
+	// (one level of self-reference, then stop to avoid infinite recursion)
+	for (const changeSetElementChange of changeSetElementChanges) {
+		changes.push({
+			id: uuid_v7(),
+			entity_id: `${initialGlobalVersionChangeSetId}::${changeSetElementChange.id}`,
+			schema_key: "lix_change_set_element",
+			schema_version: LixChangeSetElementSchema["x-lix-version"],
+			file_id: "lix",
+			plugin_key: "lix_own_entity",
+			snapshot_content: {
+				change_set_id: initialGlobalVersionChangeSetId,
+				change_id: changeSetElementChange.id,
+				entity_id: changeSetElementChange.entity_id,
+				schema_key: changeSetElementChange.schema_key,
+				file_id: changeSetElementChange.file_id,
+			} satisfies ChangeSetElement,
+			created_at,
+		});
+	}
+
+	return changes;
+}