@lix-js/sdk 0.5.1 → 0.6.0-preview.1

package/src/plugin/query-sync.ts

@@ -1,170 +0,0 @@
-import type { LixDatabaseSchema } from "../database/schema.js";
-import type { LixEngine } from "../engine/boot.js";
-import { internalQueryBuilder } from "../engine/internal-query-builder.js";
-
-/**
- * Build synchronous, Kysely-compatible SELECT queries for plugins.
- *
- * Why this exists
- * - Plugin `detectChanges()` often needs to read current state to preserve
- *   stable entity ids, compare snapshots, or infer ordering without reparsing
- *   files. A convenient, typed query builder helps keep that logic concise.
- * - The Lix engine may run in a separate thread/process relative to app code.
- *   SQLite itself executes queries synchronously; when the engine hosts
- *   `detectChanges()`, it cannot await asynchronous calls out to the app
- *   thread. `querySync` lets plugins build Kysely queries and execute them
- *   synchronously inside the engine via `executeSync`.
- *
- * How it works
- * - Returns a Kysely-like builder starting from `selectFrom(table)`.
- *   All the usual chaining methods work; only the final `.execute()` and
- *   helpers run synchronously.
- * - JSON parsing: to match normal Kysely behavior, `snapshot_content` is
- *   parsed to an object. Other JSON-typed columns are returned as raw JSON
- *   strings (consistent with `executeSync`); parse manually if needed.
- *
- * @example
- * // Inside a plugin's detectChanges
- * detectChanges: ({ after, querySync }) => {
- *   const rows = querySync("state")
- *     .where("file_id", "=", after.id)
- *     .select(["entity_id", "schema_key", "snapshot_content"])
- *     .execute(); // sync result array
- *
- *   const latestById = new Map(rows.map(r => [r.entity_id, r]));
- *   // ... use latestById to emit changes with stable entity ids ...
- *   return []
- * }
- */
-export type QuerySyncFunction = <
-	Table extends keyof LixDatabaseSchema & string,
->(
-	table: Table
-) => any;
-
-/**
- * Create a synchronous query builder factory bound to an engine.
- *
- * Returns a `querySync(table)` function that mirrors Kysely's
- * `selectFrom(table)` builder, but with synchronous execution via
- * `.execute()`, `.executeTakeFirst()`, and `.executeTakeFirstOrThrow()`.
- *
- * When to use
- * - Inside plugins: pass the returned `querySync` into `detectChanges()` so
- *   plugins can read current state synchronously while computing changes.
- * - In unit tests: construct `querySync` from an in‑process Lix (e.g.
- *   `InMemoryEnvironment`) using `createQuerySync({ engine: lix.engine! })`
- *   and call your plugin's `detectChanges({ querySync, ... })` directly.
- *
- * Engine availability
- * - In in‑process environments (like the default in‑memory environment),
- *   `lix.engine` is available and can be passed here.
- * - In worker/remote environments, `lix.engine` is undefined on the host
- *   thread. In those cases, use integration tests that drive the file
- *   handlers or a test environment that exposes the engine.
- *
- * JSON behavior
- * - `snapshot_content` is parsed to objects to match normal Kysely queries.
- *   Other JSON columns are returned as raw JSON strings; parse if needed.
- *
- * @example
- * // Unit testing a plugin's detectChanges directly
- * import { openLix, createQuerySync } from '@lix-js/sdk'
- * import { detectChanges } from '../src/detect-changes.js'
- *
- * const lix = await openLix({})
- * const querySync = createQuerySync({ engine: lix.engine! })
- *
- * const after = {
- *   id: 'file1',
- *   path: '/doc.md',
- *   data: new TextEncoder().encode('# Hello'),
- *   metadata: {}
- * }
- *
- * const changes = detectChanges({ querySync, after })
- * expect(Array.isArray(changes)).toBe(true)
- */
-export function createQuerySync(args: {
-	engine: Pick<LixEngine, "executeSync">;
-}): QuerySyncFunction {
-	/**
-	 * Starts a SELECT from the given table and returns a Kysely builder
-	 * whose `.execute()` runs synchronously.
-	 */
-	function querySync<Table extends keyof LixDatabaseSchema & string>(
-		table: Table
-	): any {
-		const base = internalQueryBuilder.selectFrom(table) as any;
-		return wrapBuilder(base, args.engine);
-	}
-
-	return querySync;
-}
-
-function wrapBuilder<T extends object>(
-	builder: T,
-	engine: Pick<LixEngine, "executeSync">
-): any {
-	return new Proxy(builder as any, {
-		get(target, prop, _receiver) {
-			if (prop === "execute") {
-				return () =>
-					parseSnapshotRows(engine.executeSync(target.compile()).rows);
-			}
-			if (prop === "executeTakeFirst") {
-				return () => {
-					const rows = parseSnapshotRows(
-						engine.executeSync(target.compile()).rows
-					);
-					return rows[0] ?? undefined;
-				};
-			}
-			if (prop === "executeTakeFirstOrThrow") {
-				return () => {
-					const rows = parseSnapshotRows(
-						engine.executeSync(target.compile()).rows
-					);
-					if (!rows[0]) throw new Error("No result");
-					return rows[0];
-				};
-			}
-
-			const value = target[prop];
-			if (typeof value === "function") {
-				return (...args: any[]) => {
-					const res = value.apply(target, args);
-					// If the method returns another builder (typical in Kysely),
-					// wrap it again to keep `.execute()` synchronous.
-					if (
-						res &&
-						typeof res === "object" &&
-						typeof res.compile === "function"
-					) {
-						return wrapBuilder(res, engine);
-					}
-					return res;
-				};
-			}
-			return value;
-		},
-	});
-}
-
-function parseSnapshotRows(rows: Array<any>): Array<any> {
-	return rows.map((r) => {
-		if (r && typeof r === "object" && "snapshot_content" in r) {
-			const v = (r as any).snapshot_content;
-			if (typeof v === "string") {
-				try {
-					return { ...r, snapshot_content: JSON.parse(v) };
-				} catch {
-					// fall through if not valid JSON
-				}
-			}
-		}
-		return r;
-	});
-}
-
-export type QuerySync = QuerySyncFunction;

package/src/query-filter/commit-is-ancestor-of.test.ts

@@ -1,234 +0,0 @@
-import { test, expect } from "vitest";
-import { openLix } from "../lix/open-lix.js";
-import { commitIsAncestorOf } from "./commit-is-ancestor-of.js";
-import { uuidV7 } from "../engine/functions/uuid-v7.js";
-
-// commits are authoritative: insert directly into commit_by_version (no pre-created change sets).
-
-test("selects all ancestors of the current commit", async () => {
-	const lix = await openLix({});
-
-	// Create a linear chain of commits: c0 <- c1 <- c2 (global)
-	const c0Id = await uuidV7({ lix });
-	await lix.db
-		.insertInto("commit_by_version")
-		.values({
-			id: c0Id,
-			change_set_id: "cs-" + c0Id,
-			lixcol_version_id: "global",
-		})
-		.execute();
-
-	const c1Id = await uuidV7({ lix });
-	await lix.db
-		.insertInto("commit_by_version")
-		.values({
-			id: c1Id,
-			change_set_id: "cs-" + c1Id,
-			parent_commit_ids: [c0Id],
-			lixcol_version_id: "global",
-		})
-		.execute();
-
-	const c2Id = await uuidV7({ lix });
-	await lix.db
-		.insertInto("commit_by_version")
-		.values({
-			id: c2Id,
-			change_set_id: "cs-" + c2Id,
-			parent_commit_ids: [c1Id],
-			lixcol_version_id: "global",
-		})
-		.execute();
-
-	// Should select c0, c1 as ancestors of c2
-	const results = await lix.db
-		.selectFrom("commit")
-		.where(commitIsAncestorOf({ id: c2Id }))
-		.select("id")
-		.execute();
-
-	expect(results.map((r) => r.id).sort()).toEqual([c0Id, c1Id].sort());
-});
-
-test("respects the optional depth limit", async () => {
-	const lix = await openLix({});
-
-	// c0 <- c1 <- c2
-	const c0Id = await uuidV7({ lix });
-	await lix.db
-		.insertInto("commit_by_version")
-		.values({
-			id: c0Id,
-			change_set_id: "cs-" + c0Id,
-			lixcol_version_id: "global",
-		})
-		.execute();
-
-	const c1Id = await uuidV7({ lix });
-	await lix.db
-		.insertInto("commit_by_version")
-		.values({
-			id: c1Id,
-			change_set_id: "cs-" + c1Id,
-			parent_commit_ids: [c0Id],
-			lixcol_version_id: "global",
-		})
-		.execute();
-
-	const c2Id = await uuidV7({ lix });
-	await lix.db
-		.insertInto("commit_by_version")
-		.values({
-			id: c2Id,
-			change_set_id: "cs-" + c2Id,
-			parent_commit_ids: [c1Id],
-			lixcol_version_id: "global",
-		})
-		.execute();
-
-	// With depth: 1, we expect c1 only
-	const results = await lix.db
-		.selectFrom("commit")
-		.where(commitIsAncestorOf({ id: c2Id }, { depth: 1 }))
-		.select("id")
-		.execute();
-
-	expect(results.map((r) => r.id).sort()).toEqual([c1Id].sort());
-});
-
-test("includeSelf true selects the current commit as well", async () => {
-	const lix = await openLix({});
-
-	// c0 <- c1 <- c2
-	const c0Id = await uuidV7({ lix });
-	await lix.db
-		.insertInto("commit_by_version")
-		.values({
-			id: c0Id,
-			change_set_id: "cs-" + c0Id,
-			lixcol_version_id: "global",
-		})
-		.execute();
-
-	const c1Id = await uuidV7({ lix });
-	await lix.db
-		.insertInto("commit_by_version")
-		.values({
-			id: c1Id,
-			change_set_id: "cs-" + c1Id,
-			parent_commit_ids: [c0Id],
-			lixcol_version_id: "global",
-		})
-		.execute();
-
-	const c2Id = await uuidV7({ lix });
-	await lix.db
-		.insertInto("commit_by_version")
-		.values({
-			id: c2Id,
-			change_set_id: "cs-" + c2Id,
-			parent_commit_ids: [c1Id],
-			lixcol_version_id: "global",
-		})
-		.execute();
-
-	// Should select c0, c1, c2
-	const results = await lix.db
-		.selectFrom("commit")
-		.where(commitIsAncestorOf({ id: c2Id }, { includeSelf: true }))
-		.select("id")
-		.execute();
-
-	expect(results.map((r) => r.id).sort()).toEqual([c0Id, c1Id, c2Id].sort());
-});
-
-test("can be combined with where(id = X) to check specific ancestry", async () => {
-	const lix = await openLix({});
-
-	// Create chain: c1 <- c2 <- c3
-	const c1Id = await uuidV7({ lix });
-	await lix.db
-		.insertInto("commit_by_version")
-		.values({
-			id: c1Id,
-			change_set_id: "cs-" + c1Id,
-			lixcol_version_id: "global",
-		})
-		.execute();
-
-	const c2Id = await uuidV7({ lix });
-	await lix.db
-		.insertInto("commit_by_version")
-		.values({
-			id: c2Id,
-			change_set_id: "cs-" + c2Id,
-			parent_commit_ids: [c1Id],
-			lixcol_version_id: "global",
-		})
-		.execute();
-
-	const c3Id = await uuidV7({ lix });
-	await lix.db
-		.insertInto("commit_by_version")
-		.values({
-			id: c3Id,
-			change_set_id: "cs-" + c3Id,
-			parent_commit_ids: [c2Id],
-			lixcol_version_id: "global",
-		})
-		.execute();
-
-	// Test: Check if c2 is an ancestor of c3 (should return c2)
-	const c2IsAncestorOfC3 = await lix.db
-		.selectFrom("commit")
-		.where("id", "=", c2Id)
-		.where(commitIsAncestorOf({ id: c3Id }))
-		.select("id")
-		.execute();
-
-	expect(c2IsAncestorOfC3).toHaveLength(1);
-	expect(c2IsAncestorOfC3[0]!.id).toBe(c2Id);
-
-	// Test: Check if c1 is an ancestor of c3 (should return c1)
-	const c1IsAncestorOfC3 = await lix.db
-		.selectFrom("commit")
-		.where("id", "=", c1Id)
-		.where(commitIsAncestorOf({ id: c3Id }))
-		.select("id")
-		.execute();
-
-	expect(c1IsAncestorOfC3).toHaveLength(1);
-	expect(c1IsAncestorOfC3[0]!.id).toBe(c1Id);
-
-	// Test: Check if c3 is an ancestor of c3 (should return empty - not inclusive by default)
-	const c3IsAncestorOfC3 = await lix.db
-		.selectFrom("commit")
-		.where("id", "=", c3Id)
-		.where(commitIsAncestorOf({ id: c3Id }))
-		.select("id")
-		.execute();
-
-	expect(c3IsAncestorOfC3).toHaveLength(0);
-
-	// Test: Check if c3 is an ancestor of c1 (should return empty - wrong direction)
-	const c3IsAncestorOfC1 = await lix.db
-		.selectFrom("commit")
-		.where("id", "=", c3Id)
-		.where(commitIsAncestorOf({ id: c1Id }))
-		.select("id")
-		.execute();
-
-	expect(c3IsAncestorOfC1).toHaveLength(0);
-
-	// Test: Check with includeSelf option
-	const c3IsAncestorOfC3Inclusive = await lix.db
-		.selectFrom("commit")
-		.where("id", "=", c3Id)
-		.where(commitIsAncestorOf({ id: c3Id }, { includeSelf: true }))
-		.select("id")
-		.execute();
-
-	expect(c3IsAncestorOfC3Inclusive).toHaveLength(1);
-	expect(c3IsAncestorOfC3Inclusive[0]!.id).toBe(c3Id);
-});

package/src/query-filter/commit-is-ancestor-of.ts

@@ -1,77 +0,0 @@
-import {
-	sql,
-	type SqlBool,
-	type ExpressionBuilder,
-	type ExpressionWrapper,
-} from "kysely";
-import type { LixDatabaseSchema } from "../database/schema.js";
-import type { LixCommit } from "../commit/schema-definition.js";
-
-/**
- * Filters commits that are ancestors of the given commit.
- *
- * By default, this is **exclusive**, meaning it returns only commits strictly
- * *before* the provided commit in the graph.
- *
- * Traverses the `commit_edge` graph recursively, starting from the provided commit
- * (or its parents if exclusive), and returns all commits reachable via parent edges.
- *
- * This filter is typically used to scope the graph before applying filters like `changeIsLeaf()`.
- *
- * ⚠️ This filter only defines the traversal scope — it does not filter changes directly.
- *
- * --- Options ---
- * - `includeSelf`: If `true`, includes the starting `commit` in the results. Defaults to `false`.
- * - `depth`: Limits the traversal depth. `depth: 1` selects only immediate parents (if exclusive)
- *   or the starting node and its immediate parents (if inclusive).
- *
- * --- Examples ---
- *
- * @example Selecting strict ancestors (default)
- * ```ts
- * db.selectFrom("commit")
- *   .where(commitIsAncestorOf({ id: "c3" }))
- *   .selectAll()
- * ```
- *
- * @example Selecting inclusive ancestors
- * ```ts
- * db.selectFrom("commit")
- *   .where(commitIsAncestorOf({ id: "c3" }, { includeSelf: true }))
- *   .selectAll()
- * ```
- *
- * @example Combining with commitIsDescendantOf to select commits between two points in time
- * ```ts
- * // Select all commits between startPoint and endPoint (inclusive)
- * db.selectFrom("commit")
- *   .where(commitIsDescendantOf({ id: "startPoint" }))
- *   .where(commitIsAncestorOf({ id: "endPoint" }))
- *   .selectAll()
- * ```
- */
-export function commitIsAncestorOf(
-	commit: Pick<LixCommit, "id">,
-	options?: { depth?: number; includeSelf?: boolean }
-): (
-	eb: ExpressionBuilder<LixDatabaseSchema, "commit">
-) => ExpressionWrapper<LixDatabaseSchema, "commit", SqlBool> {
-	const depthLimit = options?.depth;
-	const includeSelf = options?.includeSelf ?? false;
-
-	return () =>
-		sql<SqlBool>`
-			"commit".id IN (
-				WITH RECURSIVE ap(id, depth) AS (
-					SELECT id, 0 AS depth FROM "commit" WHERE id = ${sql.lit(commit.id)}
-					UNION ALL
-					SELECT commit_edge.parent_id, ap.depth + 1
-					FROM commit_edge
-					JOIN ap ON commit_edge.child_id = ap.id
-					${depthLimit !== undefined ? sql`WHERE ap.depth < ${sql.lit(depthLimit)}` : sql``}
-				)
-				-- Select based on the includeSelf flag
-				SELECT id FROM ap ${includeSelf ? sql`` : sql`WHERE depth > 0`}
-			)
-		` as any;
-}