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

package/src/hooks/index.ts

@@ -0,0 +1 @@
+export type { LixHooks } from "./create-hooks.js";

package/src/index.ts

@@ -1,16 +1,23 @@
 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 "./commit/index.js";
 export * from "./database/index.js";
-export * from "./discussion/index.js";
+export * from "./deterministic/index.js";
+export * from "./entity/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 LixKeyValue as KeyValue } from "./schema.js";

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

@@ -0,0 +1,280 @@
+import { expect, test } from "vitest";
+import { openLix } from "../lix/open-lix.js";
+import { createVersion } from "../version/create-version.js";
+import { sql } from "kysely";
+
+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("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",
+		commit_id: versionAAfterKvInsert.commit_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,
+		},
+	]);
+});
+
+test("can update individual JSON properties using SQLite JSON functions", async () => {
+	const lix = await openLix({});
+
+	// Insert a complex JSON object
+	await lix.db
+		.insertInto("key_value")
+		.values({
+			key: "test_config",
+			value: {
+				enabled: true,
+				settings: {
+					theme: "dark",
+					language: "en",
+					notifications: true,
+				},
+				features: ["feature1", "feature2"],
+				count: 42,
+			},
+		})
+		.execute();
+
+	// First check the initial insert worked
+	const initialValue = await lix.db
+		.selectFrom("key_value")
+		.where("key", "=", "test_config")
+		.select("value")
+		.executeTakeFirst();
+
+	expect(initialValue?.value).toBeDefined();
+
+	// Update a single nested property using json_set
+	await lix.db
+		.updateTable("key_value")
+		.set({
+			value: sql`json_set(value, '$.settings.theme', 'light')`,
+		})
+		.where("key", "=", "test_config")
+		.execute();
+
+	const afterThemeUpdate = await lix.db
+		.selectFrom("key_value")
+		.where("key", "=", "test_config")
+		.select("value")
+		.executeTakeFirst();
+
+	expect(afterThemeUpdate?.value).toMatchObject({
+		enabled: true,
+		settings: {
+			theme: "light", // Changed
+			language: "en",
+			notifications: true,
+		},
+		features: ["feature1", "feature2"],
+		count: 42,
+	});
+
+	// Update multiple properties at once
+	await lix.db
+		.updateTable("key_value")
+		.set({
+			value: sql`json_set(value, '$.enabled', false, '$.count', 100, '$.settings.notifications', false)`,
+		})
+		.where("key", "=", "test_config")
+		.execute();
+
+	const afterMultiUpdate = await lix.db
+		.selectFrom("key_value")
+		.where("key", "=", "test_config")
+		.select("value")
+		.executeTakeFirst();
+
+	expect(afterMultiUpdate?.value).toMatchObject({
+		enabled: 0, // Changed - SQLite stores false as 0
+		settings: {
+			theme: "light",
+			language: "en",
+			notifications: 0, // Changed - SQLite stores false as 0
+		},
+		features: ["feature1", "feature2"],
+		count: 100, // Changed
+	});
+
+	// Read specific properties using JSON operators
+	const specificProps = await lix.db
+		.selectFrom("key_value")
+		.where("key", "=", "test_config")
+		.select([
+			sql<boolean>`value ->> '$.enabled'`.as("enabled"),
+			sql<string>`value ->> '$.settings.theme'`.as("theme"),
+			sql<number>`value ->> '$.count'`.as("count"),
+		])
+		.executeTakeFirst();
+
+	expect(specificProps).toEqual({
+		enabled: 0, // SQLite returns 0 for false
+		theme: "light",
+		count: 100,
+	});
+});

package/src/key-value/schema.ts

@@ -0,0 +1,98 @@
+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";
+import type { Lix } from "../index.js";
+
+export function applyKeyValueDatabaseSchema(
+	lix: Pick<Lix, "sqlite" | "db">
+): void {
+	return createEntityViewsIfNotExists({
+		lix,
+		schema: LixKeyValueSchema,
+		overrideName: "key_value",
+		pluginKey: "lix_own_entity",
+		hardcodedFileId: "lix",
+	});
+}
+
+/**
+ * Schema definition for key-value pairs in Lix.
+ *
+ * Key-value pairs provide a flexible storage mechanism for configuration,
+ * settings, and metadata within a Lix instance.
+ */
+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;
+
+/**
+ * Represents a key-value pair in Lix.
+ *
+ * The value can be any JSON-serializable type (string, number, boolean, object, array, null).
+ *
+ * **Important SQLite Limitation with Boolean Values:**
+ * SQLite does not have a native boolean type. When storing JSON values:
+ * - `true` is stored as `1`
+ * - `false` is stored as `0`
+ *
+ * This is a fundamental limitation of SQLite's JSON implementation. There is no way
+ * to distinguish between a boolean `true` and the number `1` after retrieval.
+ *
+ * When querying boolean values, use loose equality (`==`) or handle the numeric representation.
+ *
+ * @example
+ * ```typescript
+ * // Inserting key-value pairs
+ * await lix.db.insertInto("key_value").values({
+ *   key: "lix_sync_enabled",
+ *   value: true  // Will be stored as 1 in SQLite
+ * }).execute();
+ *
+ * await lix.db.insertInto("key_value").values({
+ *   key: "lix_server_url",
+ *   value: "https://api.example.com"
+ * }).execute();
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Querying boolean values
+ * const result = await lix.db
+ *   .selectFrom("key_value")
+ *   .where("key", "=", "lix_sync_enabled")
+ *   .select("value")
+ *   .executeTakeFirst();
+ *
+ * // result.value will be 1 (not true)
+ * const isEnabled = result?.value == true; // Use loose equality
+ * // or
+ * const isEnabled = result?.value === 1; // Check for numeric value
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Common Lix system keys
+ * // "lix_id" - Unique identifier for the Lix instance
+ * // "lix_name" - Human-readable name for the Lix instance
+ * // "lix_server_url" - URL of the sync server
+ * // "lix_deterministic_mode" - Boolean flag for deterministic ID generation
+ * // "lix_telemetry" - Telemetry setting ("on" or "off")
+ * ```
+ */
+export type LixKeyValue = 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 { LixLabel } from "./schema.js";
+import { nanoId } from "../deterministic/index.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" | "sqlite">;
+	id?: LixLabel["id"];
+	name: LixLabel["name"];
+	lixcol_version_id?: string;
+}): Promise<LixLabel> {
+	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({ lix: args.lix });
+
+		// 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 LixLabel as Label } from "./schema.js";