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

package/src/index.ts

@@ -1,16 +1,20 @@
 export * from "./account/index.js";
 export * from "./change/index.js";
+export * from "./change-author/index.js";
 export * from "./change-set/index.js";
-export * from "./change-conflict/index.js";
-export * from "./file-queue/index.js";
-export * from "./change-schema/index.js";
 export * from "./database/index.js";
-export * from "./discussion/index.js";
+export * from "./entity-views/index.js";
 export * from "./file/index.js";
+export * from "./hooks/create-hooks.js";
+export * from "./key-value/schema.js";
+export * from "./label/index.js";
 export * from "./lix/index.js";
-export * from "./own-change-control/index.js";
+export * from "./log/index.js";
+export * from "./observe/index.js";
 export * from "./plugin/index.js";
 export * from "./query-filter/index.js";
+export * from "./schema-definition/index.js";
+export * from "./stored-schema/index.js";
 export * from "./server-protocol-handler/index.js";
-export * from "./snapshot/index.js";
+export * from "./thread/index.js";
 export * from "./version/index.js";

package/src/key-value/index.ts

@@ -0,0 +1 @@
+export { LixKeyValueSchema, type KeyValue } from "./schema.js";

package/src/key-value/schema.test.ts

@@ -0,0 +1,179 @@
+import { expect, test } from "vitest";
+import { openLix } from "../lix/open-lix.js";
+import { createVersion } from "../version/create-version.js";
+
+test("inserts, updates, deletes are handled", async () => {
+	const lix = await openLix({});
+
+	await lix.db
+		.insertInto("key_value")
+		.values({ key: "key0", value: "value0" })
+		.execute();
+
+	const viewAfterInsert = await lix.db
+		.selectFrom("key_value")
+		.where("key", "=", "key0")
+		.selectAll()
+		.executeTakeFirst();
+
+	expect(viewAfterInsert).toMatchObject({
+		key: "key0",
+		value: "value0",
+		// version_id: null,
+		// created_at: expect.any(String),
+	});
+
+	await lix.db
+		.updateTable("key_value")
+		.where("key", "=", "key0")
+		.set({ value: "value1" })
+		.execute();
+
+	await lix.db.deleteFrom("key_value").where("key", "=", "key0").execute();
+
+	const viewAfterDelete = await lix.db
+		.selectFrom("key_value")
+		.where("key", "=", "key0")
+		.selectAll()
+		.execute();
+
+	expect(viewAfterDelete).toMatchObject([]);
+
+	const changes = await lix.db
+		.selectFrom("change")
+
+		.where("schema_key", "=", "lix_key_value")
+		.where("change.entity_id", "=", "key0")
+		.selectAll()
+		.orderBy("change.created_at", "asc")
+		.execute();
+
+	expect(changes.map((change) => change.snapshot_content)).toMatchObject([
+		{
+			key: "key0",
+			value: "value0",
+		},
+		{
+			key: "key0",
+			value: "value1",
+		},
+		null,
+	]);
+});
+
+test("arbitrary json is allowed", async () => {
+	const lix = await openLix({});
+
+	const kvs = [
+		{ key: "key0", value: { foo: "bar" } },
+		{ key: "key1", value: ["foo", "bar"] },
+		{ key: "key2", value: "foo" },
+		{ key: "key3", value: 42 },
+		{ key: "key4", value: true },
+		{ key: "key5", value: null },
+	];
+
+	await lix.db.insertInto("key_value").values(kvs).execute();
+
+	const viewAfterInsert = await lix.db
+		.selectFrom("key_value")
+		.select(["key", "value"])
+		.where(
+			"key",
+			"in",
+			kvs.map((kv) => kv.key)
+		)
+		.execute();
+
+	expect(viewAfterInsert).toEqual(kvs);
+});
+
+test.todo("view should show changes across versions", async () => {
+	const lix = await openLix({});
+
+	// creating a new version
+	const versionA = await createVersion({ lix, id: "versionA" });
+
+	// inserting a key-value pair in version A
+	await lix.db
+		.insertInto("key_value_all")
+		.values({
+			key: "foo",
+			value: "bar",
+			lixcol_version_id: versionA.id,
+		})
+		.execute();
+
+	const kvAfterInsert = await lix.db
+		.selectFrom("key_value_all")
+		.where("key", "=", "foo")
+		.selectAll()
+		.execute();
+
+	expect(kvAfterInsert).toMatchObject([
+		{
+			key: "foo",
+			value: "bar",
+			lixcol_version_id: versionA.id,
+		},
+	]);
+
+	const versionAAfterKvInsert = await lix.db
+		.selectFrom("version")
+		.where("id", "=", versionA.id)
+		.selectAll()
+		.executeTakeFirstOrThrow();
+
+	// creating a new version from the active version
+	const versionB = await createVersion({
+		lix,
+		id: "versionB",
+		name: "versionB",
+		changeSet: { id: versionAAfterKvInsert.change_set_id },
+	});
+
+	const kvAfterInsertInVersionB = await lix.db
+		.selectFrom("key_value_all")
+		.where("key", "=", "foo")
+		.selectAll()
+		.execute();
+
+	expect(kvAfterInsertInVersionB).toMatchObject([
+		{
+			key: "foo",
+			value: "bar",
+			lixcol_version_id: versionA.id,
+		},
+		{
+			key: "foo",
+			value: "bar",
+			lixcol_version_id: versionB.id,
+		},
+	]);
+
+	await lix.db
+		.updateTable("key_value_all")
+		.where("key", "=", "foo")
+		.where("lixcol_version_id", "=", versionB.id)
+		.set({ value: "bar_updated" })
+		.execute();
+
+	const kvAfterUpdate = await lix.db
+		.selectFrom("key_value_all")
+		.where("key", "=", "foo")
+		.selectAll()
+		.execute();
+
+	expect(kvAfterUpdate).toMatchObject([
+		{
+			key: "foo",
+			value: "bar",
+			lixcol_version_id: versionA.id,
+		},
+		{
+			key: "foo",
+			value: "bar_updated",
+			lixcol_version_id: versionB.id,
+		},
+	]);
+});

package/src/key-value/schema.ts

@@ -0,0 +1,37 @@
+import type { SqliteWasmDatabase } from "sqlite-wasm-kysely";
+import type {
+	LixSchemaDefinition,
+	FromLixSchemaDefinition,
+} from "../schema-definition/definition.js";
+import { JSONTypeSchema } from "../schema-definition/json-type.js";
+import { createEntityViewsIfNotExists } from "../entity-views/entity-view-builder.js";
+
+export function applyKeyValueDatabaseSchema(sqlite: SqliteWasmDatabase): void {
+	return createEntityViewsIfNotExists({
+		lix: { sqlite },
+		schema: LixKeyValueSchema,
+		overrideName: "key_value",
+		pluginKey: "lix_own_entity",
+		hardcodedFileId: "lix",
+	});
+}
+
+export const LixKeyValueSchema = {
+	"x-lix-key": "lix_key_value",
+	"x-lix-version": "1.0",
+	"x-lix-primary-key": ["key"],
+	type: "object",
+	properties: {
+		key: { type: "string" },
+		value: JSONTypeSchema as any,
+	},
+	required: ["key", "value"],
+	additionalProperties: false,
+} as const;
+LixKeyValueSchema satisfies LixSchemaDefinition;
+
+// Pure business logic type (inferred from schema)
+export type KeyValue = FromLixSchemaDefinition<typeof LixKeyValueSchema> & {
+	// override the value to any to allow any JSON type (instead of unknown which is annoying)
+	value: any;
+};

package/src/label/create-label.test.ts

@@ -0,0 +1,234 @@
+import { test, expect } from "vitest";
+import { openLix } from "../lix/open-lix.js";
+import { createLabel } from "./create-label.js";
+import { createVersion } from "../version/create-version.js";
+
+test("should create a label with auto-generated ID", async () => {
+	const lix = await openLix({});
+
+	const labelName = "feature";
+	const label = await createLabel({
+		lix,
+		name: labelName,
+	});
+
+	// Verify the label was created
+	expect(label).toMatchObject({
+		name: labelName,
+	});
+	expect(label.id).toBeDefined();
+	expect(typeof label.id).toBe("string");
+
+	// Verify the label exists in the database
+	const dbLabel = await lix.db
+		.selectFrom("label")
+		.selectAll()
+		.where("id", "=", label.id)
+		.executeTakeFirstOrThrow();
+
+	expect(dbLabel).toMatchObject({
+		name: labelName,
+		id: label.id,
+	});
+});
+
+test("should create a label with custom ID", async () => {
+	const lix = await openLix({});
+
+	const customId = "custom-label-id";
+	const labelName = "bugfix";
+	const label = await createLabel({
+		lix,
+		id: customId,
+		name: labelName,
+	});
+
+	// Verify the label was created with the custom ID
+	expect(label).toMatchObject({
+		id: customId,
+		name: labelName,
+	});
+
+	// Verify the label exists in the database
+	const dbLabel = await lix.db
+		.selectFrom("label")
+		.selectAll()
+		.where("id", "=", customId)
+		.executeTakeFirstOrThrow();
+
+	expect(dbLabel).toMatchObject({
+		id: customId,
+		name: labelName,
+	});
+});
+
+test("should create a label with specific version_id", async () => {
+	const lix = await openLix({});
+
+	const version = await createVersion({
+		lix,
+		id: "test-version",
+	});
+
+	const labelName = "hotfix";
+	const label = await createLabel({
+		lix,
+		name: labelName,
+		lixcol_version_id: version.id,
+	});
+
+	// Verify the label was created with the specified lixcol_version_id
+	expect(label).toMatchObject({
+		name: labelName,
+		lixcol_version_id: version.id,
+	});
+
+	// Verify the label exists in the database (use label_all to access lixcol_version_id)
+	const dbLabel = await lix.db
+		.selectFrom("label_all")
+		.selectAll()
+		.where("id", "=", label.id)
+		.where("lixcol_version_id", "=", version.id)
+		.executeTakeFirstOrThrow();
+
+	expect(dbLabel).toMatchObject({
+		name: labelName,
+		lixcol_version_id: version.id,
+	});
+});
+
+test("should handle transaction correctly", async () => {
+	const lix = await openLix({});
+	const labelName = "transaction-test";
+
+	await lix.db.transaction().execute(async (trx) => {
+		const label = await createLabel({
+			lix: { ...lix, db: trx },
+			name: labelName,
+		});
+
+		expect(label.name).toBe(labelName);
+		expect(label.id).toBeDefined();
+
+		// Verify the label exists within the transaction
+		const dbLabel = await trx
+			.selectFrom("label")
+			.selectAll()
+			.where("id", "=", label.id)
+			.executeTakeFirstOrThrow();
+
+		expect(dbLabel.name).toBe(labelName);
+	});
+});
+
+test("should create multiple labels with unique IDs", async () => {
+	const lix = await openLix({});
+
+	const label1 = await createLabel({
+		lix,
+		name: "label-1",
+	});
+
+	const label2 = await createLabel({
+		lix,
+		name: "label-2",
+	});
+
+	// Verify labels have different IDs
+	expect(label1.id).not.toBe(label2.id);
+	expect(label1.name).toBe("label-1");
+	expect(label2.name).toBe("label-2");
+
+	// Verify both labels exist in the database
+	const labels = await lix.db
+		.selectFrom("label")
+		.selectAll()
+		.where("id", "in", [label1.id, label2.id])
+		.execute();
+
+	expect(labels).toHaveLength(2);
+	expect(labels.map((l) => l.name).sort()).toEqual(["label-1", "label-2"]);
+});
+
+test("should create multiple labels within a transaction", async () => {
+	const lix = await openLix({});
+
+	await lix.db.transaction().execute(async (trx) => {
+		const label1 = await createLabel({
+			lix: { ...lix, db: trx },
+			name: "tx-label-1",
+		});
+
+		const label2 = await createLabel({
+			lix: { ...lix, db: trx },
+			name: "tx-label-2",
+		});
+
+		// Labels should have unique IDs
+		expect(label1.id).not.toBe(label2.id);
+		expect(label1.name).toBe("tx-label-1");
+		expect(label2.name).toBe("tx-label-2");
+
+		// Verify both labels exist within the transaction
+		const labels = await trx
+			.selectFrom("label")
+			.selectAll()
+			.where("id", "in", [label1.id, label2.id])
+			.execute();
+
+		expect(labels).toHaveLength(2);
+	});
+});
+
+test("should use nanoid for ID generation", async () => {
+	const lix = await openLix({});
+
+	const label1 = await createLabel({
+		lix,
+		name: "nanoid-test-1",
+	});
+
+	const label2 = await createLabel({
+		lix,
+		name: "nanoid-test-2",
+	});
+
+	// Verify IDs are strings and unique (characteristic of nanoid)
+	expect(typeof label1.id).toBe("string");
+	expect(typeof label2.id).toBe("string");
+	expect(label1.id).not.toBe(label2.id);
+
+	// nanoid typically generates 21-character strings
+	expect(label1.id.length).toBeGreaterThan(0);
+	expect(label2.id.length).toBeGreaterThan(0);
+});
+
+test("should handle labels with same name but different IDs", async () => {
+	const lix = await openLix({});
+
+	const sameName = "duplicate-name";
+	const label1 = await createLabel({
+		lix,
+		name: sameName,
+	});
+
+	const label2 = await createLabel({
+		lix,
+		name: sameName,
+	});
+
+	// Verify labels have different IDs but same name
+	expect(label1.id).not.toBe(label2.id);
+	expect(label1.name).toBe(sameName);
+	expect(label2.name).toBe(sameName);
+
+	// Verify both labels exist in the database
+	const labels = await lix.db
+		.selectFrom("label")
+		.selectAll()
+		.where("name", "=", sameName)
+		.execute();
+
+	expect(labels).toHaveLength(2);
+	expect(labels.map((l) => l.id).sort()).toEqual([label1.id, label2.id].sort());
+});

package/src/label/create-label.ts

@@ -0,0 +1,61 @@
+import type { Lix } from "../lix/open-lix.js";
+import type { Label } from "./schema.js";
+import { nanoid } from "../database/nano-id.js";
+
+/**
+ * Creates a label that can be attached to change sets.
+ *
+ * Labels help categorise change sets, for example "checkpoint" or
+ * "reviewed". They are simple name identifiers stored per version.
+ *
+ * @example
+ * ```ts
+ * const label = await createLabel({ lix, name: "checkpoint" })
+ * ```
+ */
+
+export async function createLabel(args: {
+	lix: Pick<Lix, "db">;
+	id?: Label["id"];
+	name: Label["name"];
+	lixcol_version_id?: string;
+}): Promise<Label> {
+	const executeInTransaction = async (trx: Lix["db"]) => {
+		// Generate ID if not provided (views handle this, but we need it for querying back)
+		const labelId = args.id || nanoid();
+
+		// Insert the label (views don't support returningAll)
+		await trx
+			.insertInto("label_all")
+			.values({
+				id: labelId,
+				name: args.name,
+				lixcol_version_id:
+					args.lixcol_version_id ??
+					trx.selectFrom("active_version").select("version_id"),
+			})
+			.execute();
+
+		// Query back the inserted label
+		const label = await trx
+			.selectFrom("label_all")
+			.selectAll()
+			.where("id", "=", labelId)
+			.where(
+				"lixcol_version_id",
+				"=",
+				args.lixcol_version_id ??
+					trx.selectFrom("active_version").select("version_id")
+			)
+			.executeTakeFirstOrThrow();
+
+		return label;
+	};
+
+	// user provided an open transaction
+	if (args.lix.db.isTransaction) {
+		return executeInTransaction(args.lix.db);
+	} else {
+		return args.lix.db.transaction().execute(executeInTransaction);
+	}
+}

package/src/label/index.ts

@@ -0,0 +1,2 @@
+export { createLabel } from "./create-label.js";
+export { LixLabelSchema, type Label } from "./schema.js";

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,40 @@
+import type { SqliteWasmDatabase } from "sqlite-wasm-kysely";
+import type {
+	LixSchemaDefinition,
+	FromLixSchemaDefinition,
+} from "../schema-definition/definition.js";
+import { createEntityViewsIfNotExists } from "../entity-views/entity-view-builder.js";
+import { nanoid } from "../database/nano-id.js";
+
+export function applyLabelDatabaseSchema(
+	sqlite: SqliteWasmDatabase
+): SqliteWasmDatabase {
+	// Create both primary and _all views for label
+	createEntityViewsIfNotExists({
+		lix: { sqlite },
+		schema: LixLabelSchema,
+		overrideName: "label",
+		pluginKey: "lix_own_entity",
+		hardcodedFileId: "lix",
+		defaultValues: { id: () => nanoid() },
+	});
+
+	return sqlite;
+}
+
+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 Label = FromLixSchemaDefinition<typeof LixLabelSchema>;

package/src/lix/index.ts

@@ -1,7 +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";
-// 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";