refactor: rename change queue to file queue

.changeset/itchy-moose-whisper.md

@@ -0,0 +1,10 @@
+---
+"@lix-js/sdk": patch
+---
+
+refactor: rename `change_queue` to `file_queue` https://github.com/opral/lix-sdk/issues/168
+
+```diff
+-db.selectFrom("change_queue")
++db.selectFrom("file_queue")
+```

packages/lix-sdk/src/database/apply-schema.ts

@@ -28,7 +28,7 @@ export function applySchema(args: { sqlite: SqliteDatabase }): SqliteDatabase {
     CHECK (is_valid_file_path(path))
   ) STRICT;
 
-  CREATE TABLE IF NOT EXISTS change_queue (
+  CREATE TABLE IF NOT EXISTS file_queue (
     id INTEGER PRIMARY KEY AUTOINCREMENT,
     file_id TEXT NOT NULL,
     data_before BLOB,
@@ -41,18 +41,18 @@ export function applySchema(args: { sqlite: SqliteDatabase }): SqliteDatabase {
 
   CREATE TRIGGER IF NOT EXISTS file_insert BEFORE INSERT ON file
   BEGIN
-    INSERT INTO change_queue(
+    INSERT INTO file_queue(
       file_id, path_after, data_after, metadata_after
     )
     VALUES (
       NEW.id, NEW.path, NEW.data, NEW.metadata
     );
-    SELECT triggerChangeQueue();
+    SELECT triggerFileQueue();
   END;
 
   CREATE TRIGGER IF NOT EXISTS file_update BEFORE UPDATE ON file
   BEGIN
-    INSERT INTO change_queue(
+    INSERT INTO file_queue(
       file_id, 
       path_before, data_before, metadata_before, 
       path_after, data_after, metadata_after
@@ -64,14 +64,14 @@ export function applySchema(args: { sqlite: SqliteDatabase }): SqliteDatabase {
       NEW.path, NEW.data, NEW.metadata
     );
 
-    SELECT triggerChangeQueue();
+    SELECT triggerFileQueue();
   END;
 
   CREATE TRIGGER IF NOT EXISTS file_delete BEFORE DELETE ON file
   BEGIN
-    INSERT INTO change_queue(file_id)
+    INSERT INTO file_queue(file_id)
     VALUES (OLD.id);
-    SELECT triggerChangeQueue();
+    SELECT triggerFileQueue();
   END;
 
   CREATE TABLE IF NOT EXISTS change (

packages/lix-sdk/src/database/init-db.test.ts

@@ -17,7 +17,7 @@ test("file ids should default to uuid", async () => {
 
 	// init the trigger function (usually defined by lix only)
 	sqlite.createFunction({
-		name: "triggerChangeQueue",
+		name: "triggerFileQueue",
 		arity: 0,
 		// @ts-expect-error - dynamic function
 		xFunc: () => {},
@@ -143,7 +143,7 @@ test("files should be able to have metadata", async () => {
 	const db = initDb({ sqlite });
 
 	sqlite.createFunction({
-		name: "triggerChangeQueue",
+		name: "triggerFileQueue",
 		arity: 0,
 		// @ts-expect-error - dynamic function
 		xFunc: () => {
@@ -338,7 +338,7 @@ test("invalid file paths should be rejected", async () => {
 
 	// init the trigger function (usually defined by lix only)
 	sqlite.createFunction({
-		name: "triggerChangeQueue",
+		name: "triggerFileQueue",
 		arity: 0,
 		// @ts-expect-error - dynamic function
 		xFunc: () => {},

packages/lix-sdk/src/database/init-db.ts

@@ -23,7 +23,7 @@ export function initDb(args: {
 			ParseJsonBPluginV1({
 				// jsonb columns
 				file: ["metadata"],
-				change_queue: ["metadata_before", "metadata_after"],
+				file_queue: ["metadata_before", "metadata_after"],
 				snapshot: ["content"],
 				mutation_log: ["row_id"],
 			}),

packages/lix-sdk/src/database/mutation-log/database-schema.ts

@@ -14,7 +14,7 @@ export const tablesByDepencies: string[] = [
 	"change",
 
 	// Depends on: file
-	"change_queue",
+	"file_queue",
 	// Depends on: change
 	"change_author",
 	// Depends on: change

packages/lix-sdk/src/database/schema.ts

@@ -17,7 +17,7 @@ export type LixDatabaseSchema = {
 
 	// file
 	file: LixFileTable;
-	change_queue: ChangeQueueTable;
+	file_queue: FileQueueTable;
 
 	// change
 	change: ChangeTable;
@@ -50,10 +50,10 @@ export type LixDatabaseSchema = {
 	mutation_log: MutationLogTable;
 };
 
-export type ChangeQueueEntry = Selectable<ChangeQueueTable>;
-export type NewChangeQueueEntry = Insertable<ChangeQueueTable>;
-export type ChangeQueueEntryUpdate = Updateable<ChangeQueueTable>;
-type ChangeQueueTable = {
+export type FileQueueEntry = Selectable<FileQueueTable>;
+export type NewFileQueueEntry = Insertable<FileQueueTable>;
+export type FileQueueEntryUpdate = Updateable<FileQueueTable>;
+type FileQueueTable = {
 	id: Generated<number>;
 	file_id: string;
 	path_before: string | null;

packages/lix-sdk/src/file-queue/file-handlers.ts

@@ -1,4 +1,4 @@
-import type { ChangeQueueEntry } from "../database/schema.js";
+import type { FileQueueEntry } from "../database/schema.js";
 import type { DetectedChange } from "../plugin/lix-plugin.js";
 import type { Lix } from "../lix/open-lix.js";
 import { sql } from "kysely";
@@ -31,7 +31,7 @@ async function glob(args: {
 // creates initial changes for new files
 export async function handleFileInsert(args: {
 	lix: Pick<Lix, "db" | "plugin" | "sqlite">;
-	changeQueueEntry: ChangeQueueEntry;
+	changeQueueEntry: FileQueueEntry;
 }): Promise<void> {
 	const detectedChanges: Array<DetectedChange & { pluginKey: string }> = [];
 
@@ -116,15 +116,15 @@ export async function handleFileInsert(args: {
 		);
 
 		await trx
-			.deleteFrom("change_queue")
+			.deleteFrom("file_queue")
 			.where("id", "=", args.changeQueueEntry.id)
 			.execute();
 	});
 }
 
 export async function handleFileUpdate(args: {
 	lix: Pick<Lix, "db" | "plugin" | "sqlite">;
-	changeQueueEntry: ChangeQueueEntry;
+	changeQueueEntry: FileQueueEntry;
 }): Promise<void> {
 	const detectedChanges: Array<DetectedChange & { pluginKey: string }> = [];
 
@@ -210,7 +210,7 @@ export async function handleFileUpdate(args: {
 		);
 
 		await trx
-			.deleteFrom("change_queue")
+			.deleteFrom("file_queue")
 			.where("id", "=", args.changeQueueEntry.id)
 			.execute();
 	});
@@ -227,7 +227,7 @@ export async function handleFileUpdate(args: {
  */
 export async function handleFileDelete(args: {
 	lix: Pick<Lix, "db" | "plugin" | "sqlite">;
-	changeQueueEntry: ChangeQueueEntry;
+	changeQueueEntry: FileQueueEntry;
 }): Promise<void> {
 	await args.lix.db.transaction().execute(async (trx) => {
 		const currentVersion = await trx
@@ -266,7 +266,7 @@ export async function handleFileDelete(args: {
 		);
 
 		await trx
-			.deleteFrom("change_queue")
+			.deleteFrom("file_queue")
 			.where("id", "=", args.changeQueueEntry.id)
 			.execute();
 	});

packages/lix-sdk/src/file-queue/file-queue-process.test.ts

@@ -2,7 +2,7 @@ import { expect, test, vi } 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 type { ChangeQueueEntry, LixFile } from "../database/schema.js";
+import type { FileQueueEntry, LixFile } from "../database/schema.js";
 import { fileQueueSettled } from "./file-queue-settled.js";
 
 test("should use queue and settled correctly", async () => {
@@ -52,7 +52,7 @@ test("should use queue and settled correctly", async () => {
 		.values({ id: "test", path: "/test.txt", data: dataInitial })
 		.execute();
 
-	const queue = await lix.db.selectFrom("change_queue").selectAll().execute();
+	const queue = await lix.db.selectFrom("file_queue").selectAll().execute();
 
 	expect(queue).toEqual([
 		expect.objectContaining({
@@ -61,13 +61,13 @@ test("should use queue and settled correctly", async () => {
 			path_after: "/test.txt",
 			data_after: dataInitial,
 			data_before: null,
-		} satisfies Partial<ChangeQueueEntry>),
+		} satisfies Partial<FileQueueEntry>),
 	]);
 
 	await fileQueueSettled({ lix });
 
 	expect(
-		(await lix.db.selectFrom("change_queue").selectAll().execute()).length
+		(await lix.db.selectFrom("file_queue").selectAll().execute()).length
 	).toBe(0);
 
 	// TODO QUEUE check if the replacement of file_internal was expected
@@ -118,14 +118,14 @@ test("should use queue and settled correctly", async () => {
 		.execute();
 
 	// const beforeQueueTick = await lix.db
-	// 	.selectFrom("change_queue")
+	// 	.selectFrom("file_queue")
 	// 	.selectAll()
 	// 	.execute();
 
 	// expect(beforeQueueTick.length).toBe(1);
 
 	// const afterQueueTick = await lix.db
-	// 	.selectFrom("change_queue")
+	// 	.selectFrom("file_queue")
 	// 	.selectAll()
 	// 	.execute();
 
@@ -149,7 +149,7 @@ test("should use queue and settled correctly", async () => {
 		.where("id", "=", "test")
 		.execute();
 
-	const queue2 = await lix.db.selectFrom("change_queue").selectAll().execute();
+	const queue2 = await lix.db.selectFrom("file_queue").selectAll().execute();
 
 	expect(queue2).toEqual([
 		// change update 1 is the same as change update 2
@@ -161,21 +161,21 @@ test("should use queue and settled correctly", async () => {
 			metadata_after: null,
 			data_before: dataUpdate1,
 			data_after: dataUpdate2,
-		} satisfies Partial<ChangeQueueEntry>),
+		} satisfies Partial<FileQueueEntry>),
 		expect.objectContaining({
 			id: 4,
 			file_id: "test",
 			path_after: "/test.txt",
 			metadata_after: null,
 			data_before: dataUpdate2,
 			data_after: dataUpdate3,
-		} satisfies Partial<ChangeQueueEntry>),
+		} satisfies Partial<FileQueueEntry>),
 	]);
 
 	await fileQueueSettled({ lix });
 
 	expect(
-		(await lix.db.selectFrom("change_queue").selectAll().execute()).length
+		(await lix.db.selectFrom("file_queue").selectAll().execute()).length
 	).toBe(0);
 
 	const updatedChanges = await lix.db
@@ -404,7 +404,7 @@ test("should handle file deletions correctly", async () => {
 	await lix.db.deleteFrom("file").where("id", "=", "file0").execute();
 
 	// Ensure the queue reflects the deletion entry
-	const queue = await lix.db.selectFrom("change_queue").selectAll().execute();
+	const queue = await lix.db.selectFrom("file_queue").selectAll().execute();
 
 	expect(queue).toEqual([
 		expect.objectContaining({
@@ -413,15 +413,15 @@ test("should handle file deletions correctly", async () => {
 			data_before: null,
 			path_after: null,
 			data_after: null,
-		} satisfies Partial<ChangeQueueEntry>),
+		} satisfies Partial<FileQueueEntry>),
 	]);
 
 	// Run the fil queue settlement process
 	await fileQueueSettled({ lix });
 
 	// Verify the fil queue is empty
 	expect(
-		(await lix.db.selectFrom("change_queue").selectAll().execute()).length
+		(await lix.db.selectFrom("file_queue").selectAll().execute()).length
 	).toBe(0);
 
 	// Verify the changes reflect the deletion

packages/lix-sdk/src/file-queue/file-queue-process.ts

@@ -6,12 +6,12 @@ import {
 } from "./file-handlers.js";
 import type { Lix } from "../lix/open-lix.js";
 
-export async function initChangeQueue(args: {
+export async function initFileQueueProcess(args: {
 	lix: Pick<Lix, "db" | "plugin" | "sqlite">;
 	rawDatabase: SqliteDatabase;
 }): Promise<void> {
 	args.rawDatabase.createFunction({
-		name: "triggerChangeQueue",
+		name: "triggerFileQueue",
 		arity: 0,
 		// @ts-expect-error - dynamic function
 		xFunc: () => {
@@ -43,7 +43,7 @@ export async function initChangeQueue(args: {
 			}
 
 			const entry = await args.lix.db
-				.selectFrom("change_queue")
+				.selectFrom("file_queue")
 				.selectAll()
 				.orderBy("id asc")
 				.limit(1)
@@ -71,7 +71,7 @@ export async function initChangeQueue(args: {
 			// console.log("getrting { numEntries }");
 
 			const { numEntries } = await args.lix.db
-				.selectFrom("change_queue")
+				.selectFrom("file_queue")
 				.select((eb) => eb.fn.count<number>("id").as("numEntries"))
 				.executeTakeFirstOrThrow();
 

packages/lix-sdk/src/file-queue/file-queue-settled.test.ts

@@ -6,7 +6,7 @@ test("should wait until the file queue is settled", async () => {
 	const lix = await openLixInMemory({});
 
 	await lix.db
-		.insertInto("change_queue")
+		.insertInto("file_queue")
 		.values([
 			{
 				id: 1,
@@ -25,16 +25,16 @@ test("should wait until the file queue is settled", async () => {
 		])
 		.execute();
 
-	// Start a background task to remove entries from the change_queue after a delay
+	// Start a background task to remove entries from the file_queue after a delay
 	setTimeout(async () => {
-		await lix.db.deleteFrom("change_queue").where("id", "=", 1).execute();
-		await lix.db.deleteFrom("change_queue").where("id", "=", 2).execute();
+		await lix.db.deleteFrom("file_queue").where("id", "=", 1).execute();
+		await lix.db.deleteFrom("file_queue").where("id", "=", 2).execute();
 	}, 110);
 
 	await fileQueueSettled({ lix });
 
 	const remainingEntries = await lix.db
-		.selectFrom("change_queue")
+		.selectFrom("file_queue")
 		.selectAll()
 		.execute();
 
@@ -44,12 +44,12 @@ test("should wait until the file queue is settled", async () => {
 test("should return immediately if the file queue is already empty", async () => {
 	const lix = await openLixInMemory({});
 
-	await lix.db.deleteFrom("change_queue").execute();
+	await lix.db.deleteFrom("file_queue").execute();
 
 	await fileQueueSettled({ lix });
 
 	const remainingEntries = await lix.db
-		.selectFrom("change_queue")
+		.selectFrom("file_queue")
 		.selectAll()
 		.execute();
 	expect(remainingEntries).toEqual([]);

packages/lix-sdk/src/file-queue/file-queue-settled.ts

@@ -15,7 +15,7 @@ export async function fileQueueSettled(args: {
 
 	while (hasEntries) {
 		const entries = await args.lix.db
-			.selectFrom("change_queue")
+			.selectFrom("file_queue")
 			.selectAll()
 			.limit(1)
 			.execute();