@lix-js/sdk 0.0.1

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

@@ -0,0 +1,76 @@
+import { expect, test } from "vitest";
+import { openLixInMemory } from "../lix/open-lix-in-memory.js";
+import { newLixFile } from "../lix/new-lix.js";
+import type { DetectedChange, LixPlugin } from "../plugin/lix-plugin.js";
+import { createDiscussion } from "./create-discussion.js";
+import { createChangeSet } from "../change-set/create-change-set.js";
+import { changeQueueSettled } from "../change-queue/change-queue-settled.js";
+
+const mockPlugin: LixPlugin = {
+	key: "mock-plugin",
+	detectChangesGlob: "*",
+	detectChanges: async ({ after }) => {
+		return [
+			{
+				schema: {
+					key: "text",
+					type: "json",
+				},
+				entity_id: "test",
+				snapshot: {
+					text: after ? new TextDecoder().decode(after.data) : undefined,
+				},
+			} satisfies DetectedChange,
+		];
+	},
+};
+
+test("should be able to start a discussion on changes", async () => {
+	const lix = await openLixInMemory({
+		blob: await newLixFile(),
+		providePlugins: [mockPlugin],
+	});
+
+	const enc = new TextEncoder();
+
+	await lix.db
+		.insertInto("file")
+		.values({ id: "test", path: "/test.txt", data: enc.encode("test") })
+		.execute();
+
+	await changeQueueSettled({ lix });
+
+	const current_author = await lix.db
+		.selectFrom("active_account")
+		.selectAll()
+		.executeTakeFirstOrThrow();
+
+	const changes = await lix.db
+		.selectFrom("change")
+		.selectAll("change")
+		.execute();
+
+	await lix.db.transaction().execute(async (trx) => {
+		await createDiscussion({
+			lix: { db: trx },
+			changeSet: await createChangeSet({ lix: { db: trx }, changes }),
+			content: "comment on a change",
+			createdBy: { id: current_author.id },
+		});
+	});
+
+	const discussions = await lix.db
+		.selectFrom("discussion")
+		.selectAll()
+		.execute();
+
+	expect(discussions).toHaveLength(1);
+
+	const comments = await lix.db
+		.selectFrom("comment")
+		.selectAll()
+		.where("discussion_id", "=", discussions[0]!.id)
+		.execute();
+
+	expect(comments).toHaveLength(1);
+});

package/src/discussion/create-discussion.ts

@@ -0,0 +1,51 @@
+import type { Account } from "../account/database-schema.js";
+import type { ChangeSet, Comment, Discussion } from "../database/schema.js";
+import type { Lix } from "../lix/open-lix.js";
+
+/**
+ * Creates a new discussion with the first comment.
+ *
+ * @example
+ *   ```ts
+ *   const changeSet = await createChangeSet({ lix, changes: ["change1", "change2"] });
+ *   const discussion = await createDiscussion({ lix, changeSet, body: "first comment" });
+ *   ```
+ *
+ * @returns the created discussion
+ */
+export async function createDiscussion(args: {
+	lix: Pick<Lix, "db">;
+	changeSet: Pick<ChangeSet, "id">;
+	content: Comment["content"];
+	createdBy: Pick<Account, "id">;
+}): Promise<Discussion & { comment: Comment }> {
+	const executeInTransaction = async (trx: Lix["db"]) => {
+		const discussion = await trx
+			.insertInto("discussion")
+			.values({
+				change_set_id: args.changeSet.id,
+			})
+			.returningAll()
+			.executeTakeFirstOrThrow();
+
+		const comment = await trx
+			.insertInto("comment")
+			.values({
+				parent_id: null,
+				discussion_id: discussion.id,
+				content: args.content,
+				created_by: args.createdBy.id,
+			})
+			.returningAll()
+			.executeTakeFirstOrThrow();
+
+		return { ...discussion, comment };
+	};
+
+	// 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/discussion/index.ts

@@ -0,0 +1,2 @@
+export { createDiscussion } from "./create-discussion.js";
+export { createComment } from "./create-comment.js";

package/src/file/index.ts

@@ -0,0 +1 @@
+export { validateFilePath, isValidFilePath } from "./validate-file-path.js";

package/src/file/validate-file-path.test.ts

@@ -0,0 +1,44 @@
+import { test, expect } from "vitest";
+import { isValidFilePath } from "./validate-file-path.js";
+
+test("valid cases", () => {
+	const validCases = [
+		"/path/to/file",
+		"/path/to/file/with/multiple/segments",
+		"/path/to/file.with.dots",
+		"/path/to/file-with-hyphens_and_underscores",
+		"/path/with-file-extension.txt",
+	];
+
+	for (const validCase of validCases) {
+		expect(isValidFilePath(validCase)).toBe(true);
+		// testing for RFC 3986 URI
+		expect(URL.canParse(`file://${validCase}`)).toBe(true);
+	}
+});
+
+// invalid cases
+
+test("an empty path should be invalid", () => {
+	expect(isValidFilePath("")).toBe(false);
+});
+
+test("a path that contains only a slash should be invalid", () => {
+	expect(isValidFilePath("/")).toBe(false);
+});
+
+test("a path that does not start with a slash should be invalid", () => {
+	expect(isValidFilePath("path/to/file")).toBe(false);
+});
+
+test("a path that ends with a slash should be invalid", () => {
+	expect(isValidFilePath("/path/to/file/")).toBe(false);
+});
+
+test("a path that contains consecutive slashes should be invalid", () => {
+	expect(isValidFilePath("/path//to/file")).toBe(false);
+});
+
+test("a path that contains backslashes should be invalid", () => {
+	expect(isValidFilePath("/path\\to\\file")).toBe(false);
+});

package/src/file/validate-file-path.ts

@@ -0,0 +1,60 @@
+/**
+ * Idea is to have a minimal spec that can be extended over time.
+ *
+ * Every valid file path must also be a valid RFC 3986 URI.
+ */
+
+/**
+ * Validates a file path.
+ *
+ * @throws {Error} If the file path is invalid.
+ */
+export function validateFilePath(path: string): void {
+	// validate beginning
+
+	if (path.length === 0) {
+		throw new Error("File path must not be empty.");
+	}
+
+	if (path[0] !== "/") {
+		throw new Error(
+			"File path must start with a slash.\n\nNot starting a file path with a slash `/` leads to ambiguity whether or not the path is a directory or a file."
+		);
+	}
+
+	// validate middle
+
+	// validate ending
+
+	if (path.endsWith("/")) {
+		throw new Error(
+			"File path must not end with a slash.\n\nEnding a file with a slash leads to ambiguity whether or not the path is a directory or a file."
+		);
+	}
+
+	// validate general
+
+	if (path.includes("//")) {
+		throw new Error(
+			"File path must not contain consecutive slashes.\n\nConsecutive slashes lead to ambiguity whether or not the path is a directory or a file."
+		);
+	}
+
+	if (path.includes("\\")) {
+		throw new Error(
+			"File path must not contain backslashes.\n\nThe restriction might be loosened in the future."
+		);
+	}
+}
+
+/**
+ *
+ */
+export function isValidFilePath(path: string): boolean {
+	try {
+		validateFilePath(path);
+		return true;
+	} catch {
+		return false;
+	}
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+export * from "./account/index.js";
+export * from "./change/index.js";
+export * from "./change-set/index.js";
+export * from "./change-conflict/index.js";
+export * from "./change-queue/index.js";
+export * from "./change-schema/index.js";
+export * from "./database/index.js";
+export * from "./discussion/index.js";
+export * from "./file/index.js";
+export * from "./lix/index.js";
+export * from "./own-entity-change-control/index.js";
+export * from "./plugin/index.js";
+export * from "./query-filter/index.js";
+export * from "./server-api-handler/index.js";
+export * from "./snapshot/index.js";
+export * from "./version/index.js";

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

@@ -0,0 +1,119 @@
+import { sql } from "kysely";
+import { expect, test } from "vitest";
+import { openLixInMemory } from "../lix/open-lix-in-memory.js";
+import { validate as validateUuid } from "uuid";
+
+test("string values are accepted", async () => {
+	const lix = await openLixInMemory({});
+
+	const result = await lix.db
+		.insertInto("key_value")
+		.values({
+			key: "foo",
+			value: "bar",
+		})
+		.returningAll()
+		.execute();
+
+	expect(result).toMatchObject([
+		{
+			key: "foo",
+			value: "bar",
+		},
+	]);
+});
+
+test("duplicate keys lead to an error", async () => {
+	const lix = await openLixInMemory({});
+
+	await lix.db
+		.insertInto("key_value")
+		.values({
+			key: "foo",
+			value: "bar",
+		})
+		.returningAll()
+		.execute();
+
+	expect(
+		lix.db
+			.insertInto("key_value")
+			.values({
+				key: "foo",
+				value: "bar",
+			})
+			.returningAll()
+			.execute()
+	).rejects.toThrowErrorMatchingInlineSnapshot(
+		`[SQLite3Error: SQLITE_CONSTRAINT_PRIMARYKEY: sqlite3 result code 1555: UNIQUE constraint failed: key_value.key]`
+	);
+});
+
+test("using json as value should work", async () => {
+	const lix = await openLixInMemory({});
+
+	await lix.db
+		.insertInto("key_value")
+		.values([
+			{
+				key: "foo",
+				value: JSON.stringify({
+					bar: "baz",
+					age: 42,
+					location: "Berlin",
+				}),
+			},
+		])
+		.returningAll()
+		.execute();
+
+	const onlyOneProperty = await lix.db
+		.selectFrom("key_value")
+		.where("key", "=", "foo")
+		.select(sql`json_extract(value, '$.bar')`.as("bar"))
+		.executeTakeFirstOrThrow();
+
+	// The JSON parsing plugin needs improvements.
+	// not important for now
+	// const parsedAsJson = await db
+	// 	.selectFrom("key_value")
+	// 	.where("key", "=", "foo")
+	// 	.select(sql`json(value)`.as("value"))
+	// 	.executeTakeFirstOrThrow();
+
+	// expect(parsedAsJson).toMatchObject({
+	// 	value: {
+	// 		bar: "baz",
+	// 		age: 42,
+	// 		location: "Berlin",
+	// 	},
+	// });
+
+	expect(onlyOneProperty).toMatchObject({
+		bar: "baz",
+	});
+});
+
+test("it should default add a uuid lix_id if not exits", async () => {
+	const lix = await openLixInMemory({});
+
+	const result = await lix.db
+		.selectFrom("key_value")
+		.where("key", "=", "lix_id")
+		.selectAll()
+		.executeTakeFirstOrThrow();
+
+	expect(validateUuid(result.value)).toBe(true);
+});
+
+test("default value for #lix_sync to reduce conditional logic (the key is always set)", async () => {
+	const lix = await openLixInMemory({});
+
+	const result = await lix.db
+		.selectFrom("key_value")
+		.where("key", "=", "#lix_sync")
+		.selectAll()
+		.executeTakeFirstOrThrow();
+
+	expect(result.value).toBe("false");
+});

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

@@ -0,0 +1,54 @@
+import type { Insertable, Selectable, Updateable } from "kysely";
+import type { SqliteDatabase } from "sqlite-wasm-kysely";
+
+export function applyKeyValueDatabaseSchema(
+	sqlite: SqliteDatabase
+): SqliteDatabase {
+	return sqlite.exec`
+	CREATE TABLE IF NOT EXISTS key_value (
+		key TEXT PRIMARY KEY,
+		value TEXT NOT NULL
+	) STRICT;
+
+	INSERT OR IGNORE INTO key_value (key, value)
+	VALUES ('lix_id', uuid_v4());
+
+	-- default value for lix sync to false
+	-- if not exist to remove conditional logic
+	-- if the key exists or not
+	INSERT OR IGNORE INTO key_value (key, value)
+	VALUES ('#lix_sync', 'false');
+`;
+}
+
+export type KeyValue = Selectable<KeyValueTable>;
+export type NewKeyValue = Insertable<KeyValueTable>;
+export type KeyValueUpdate = Updateable<KeyValueTable>;
+export type KeyValueTable = {
+	/**
+	 * The key of the key-value pair.
+	 *
+	 * Lix prefixes its keys with "lix-" to avoid conflicts with user-defined keys.
+	 *
+	 * @example
+	 *   "namespace-cool-key"
+	 */
+	key: KeyValueKeys;
+	/**
+	 * The value of the key-value pair.
+	 *
+	 * Must be a string. A JSON is a string too ;)
+	 *
+	 * @example
+	 *   "some value"
+	 *   "{ "foo": "bar" }"
+	 *
+	 */
+	value: string;
+};
+
+type PredefinedKeys = "lix_id" | "lix_server_url" | "#lix_sync";
+// The string & {} ensures TypeScript recognizes KeyValueKeys
+// as a superset of string, preventing conflicts when using other string values.
+type KeyType = string & {};
+type KeyValueKeys = PredefinedKeys | KeyType;

package/src/lix/index.ts

@@ -0,0 +1,6 @@
+export { type Lix, openLix } from "./open-lix.js";
+export { openLixInMemory } from "./open-lix-in-memory.js";
+export { newLixFile } from "./new-lix.js";
+// not exporting merge for api stability milestone
+// will need an overhaul to be stable
+// export { merge } from "./merge.js";

package/src/lix/merge.get-leaf-changes-only-in-source.test.ts

@@ -0,0 +1,143 @@
+import { test, expect } from "vitest";
+import { getLeafChangesOnlyInSource } from "./merge.get-leaf-changes-only-in-source.js";
+import { openLixInMemory } from "./open-lix-in-memory.js";
+import { newLixFile } from "./new-lix.js";
+import type { NewChange } from "../database/schema.js";
+import { mockJsonSnapshot } from "../snapshot/mock-json-snapshot.js";
+
+test("it should get the leaf changes that only exist in source", async () => {
+	const sourceLix = await openLixInMemory({
+		blob: await newLixFile(),
+	});
+	const targetLix = await openLixInMemory({
+		blob: await newLixFile(),
+	});
+
+	const commonSnapshots = [
+		mockJsonSnapshot({ id: "mock-id", color: "red" }),
+		mockJsonSnapshot({ id: "mock-id", color: "blue" }),
+	];
+
+	const commonChanges: NewChange[] = [
+		{
+			id: "c1",
+			file_id: "mock",
+			entity_id: "value1",
+			plugin_key: "mock",
+			schema_key: "mock",
+			snapshot_id: commonSnapshots[0]!.id,
+		},
+		{
+			id: "c2",
+			file_id: "mock",
+			entity_id: "value1",
+			plugin_key: "mock",
+			schema_key: "mock",
+			snapshot_id: commonSnapshots[1]!.id,
+		},
+	];
+
+	const commonChangesEdges = [{ parent_id: "c1", child_id: "c2" }];
+
+	const snapshotsOnlyInSource = [
+		mockJsonSnapshot({ id: "mock-id", color: "pink" }),
+		mockJsonSnapshot({ id: "mock-id", color: "orange" }),
+		mockJsonSnapshot({ id: "mock-id", color: "yellow" }),
+	];
+
+	const changesOnlyInSource: NewChange[] = [
+		{
+			id: "s1",
+			file_id: "mock",
+			entity_id: "value1",
+			plugin_key: "mock",
+			schema_key: "mock",
+			snapshot_id: snapshotsOnlyInSource[0]!.id,
+		},
+		{
+			id: "s2",
+			entity_id: "value1",
+			file_id: "mock",
+			plugin_key: "mock",
+			schema_key: "mock",
+			snapshot_id: snapshotsOnlyInSource[1]!.id,
+		},
+		{
+			id: "s3",
+			entity_id: "value1",
+			file_id: "mock",
+			plugin_key: "mock",
+			schema_key: "mock",
+			snapshot_id: snapshotsOnlyInSource[2]!.id,
+		},
+	];
+
+	const changesOnlyInSourceEdges = [
+		{ parent_id: "s1", child_id: "s2" },
+		{ parent_id: "s2", child_id: "s3" },
+	];
+
+	const snapshotsOnlyInTarget = [
+		mockJsonSnapshot({ id: "mock-id", color: "black" }),
+	];
+
+	const changesOnlyInTarget: NewChange[] = [
+		{
+			id: "t1",
+			entity_id: "value1",
+			file_id: "mock",
+			plugin_key: "mock",
+			schema_key: "mock",
+			snapshot_id: snapshotsOnlyInTarget[0]!.id,
+		},
+	];
+
+	const changesOnlyInTargetEdges = [{ parent_id: "c2", child_id: "t1" }];
+
+	await targetLix.db
+		.insertInto("snapshot")
+		.values(
+			[...commonSnapshots, ...snapshotsOnlyInTarget].map((s) => {
+				return { content: s.content };
+			})
+		)
+		.execute();
+
+	await targetLix.db
+		.insertInto("change")
+		.values([...commonChanges, ...changesOnlyInTarget])
+		.execute();
+
+	await targetLix.db
+		.insertInto("change_edge")
+		.values([...commonChangesEdges, ...changesOnlyInTargetEdges])
+		.execute();
+
+	await sourceLix.db
+		.insertInto("snapshot")
+		.values(
+			[...commonSnapshots, ...snapshotsOnlyInSource].map((s) => {
+				return { content: s.content };
+			})
+		)
+		.execute();
+
+	await sourceLix.db
+		.insertInto("change")
+		.values([...commonChanges, ...changesOnlyInSource])
+		.execute();
+
+	await sourceLix.db
+		.insertInto("change_edge")
+		.values([...commonChangesEdges, ...changesOnlyInSourceEdges])
+		.execute();
+
+	const result = await getLeafChangesOnlyInSource({
+		sourceLix: sourceLix,
+		targetLix: targetLix,
+	});
+
+	// only the last change in the source is expected,
+	// not s1 and s2 which are parents of s3
+	expect(result.map((c) => c.id)).toEqual(["s3"]);
+});

package/src/lix/merge.get-leaf-changes-only-in-source.ts

@@ -0,0 +1,46 @@
+import type { Change } from "../database/schema.js";
+import type { LixReadonly } from "../plugin/lix-plugin.js";
+
+/**
+ * Gets the leaf changes that only exist in the source lix.
+ *
+ * @example
+ *   source changes = [c1, s1 (child of c1), s2 (child of s1), s3 (child of s2)]
+ *   target changes = [c1, t1 (child of c1)]
+ *   leaf changes only in source = [s3]
+ */
+// TODO optimize later to use a single sql query (attach mode)
+export async function getLeafChangesOnlyInSource(args: {
+	sourceLix: LixReadonly;
+	targetLix: LixReadonly;
+}): Promise<Change[]> {
+	const result: Change[] = [];
+
+	const leafChangesInSource = await args.sourceLix.db
+		.selectFrom("change")
+		.selectAll("change")
+		.where(
+			"change.id",
+			"not in",
+			args.sourceLix.db
+				.selectFrom("change")
+				.innerJoin("change_edge", "change_edge.child_id", "change.id")
+				.select("parent_id")
+				.where("parent_id", "is not", null)
+				.distinct()
+		)
+		.execute();
+
+	for (const change of leafChangesInSource) {
+		const changeExistsInTarget = await args.targetLix.db
+			.selectFrom("change")
+			.select("id")
+			.where("id", "=", change.id)
+			.executeTakeFirst();
+
+		if (!changeExistsInTarget) {
+			result.push(change);
+		}
+	}
+	return result;
+}