@cosmicdrift/kumiko-framework 0.14.0 → 0.15.0

package/src/bun-db/__tests__/jsonb-edge-cases.integration.test.ts

@@ -0,0 +1,235 @@
+// JSONB-Edge-Cases — wo Drift zwischen bun.sql und postgres-js entstanden ist.
+// Bun.SQL kann arrays/objects nicht direkt als jsonb binden; query.ts
+// macht JSON.stringify + ::jsonb cast (siehe query.ts:301-306). Diese
+// Tests beweisen dass dabei nichts subtil verloren geht — egal wie
+// komplex/edge das jsonb-Value ist.
+
+import { afterAll, describe, expect, test } from "bun:test";
+import { fetchOne, insertOne, updateMany } from "../query";
+import { closeDb, withTable } from "./_helpers";
+
+afterAll(async () => {
+  await closeDb();
+});
+
+// Hilfsfunktion: jsonb-Spalte mit pgType + Default. NotNull damit der
+// expliziter Test ist (NULL-jsonb verdeckt sonst Bind-Bugs).
+const jsonbCol = (defaultSql: string) => [
+  { name: "data", pgType: "jsonb" as const, notNull: true, defaultSql },
+];
+
+async function roundtripObject(db: unknown, meta: unknown, value: object): Promise<unknown> {
+  // biome-ignore lint/suspicious/noExplicitAny: tests pass any shape
+  const ins = (await insertOne<any>(db as never, meta as never, { data: value }))!;
+  const row = await fetchOne<{ data: unknown }>(db as never, meta as never, { id: ins.id });
+  return row?.data;
+}
+
+describe("jsonb — primitive shapes", () => {
+  test("nested object 3 levels deep", async () => {
+    await withTable(jsonbCol("'{}'::jsonb"), async ({ db, meta }) => {
+      const v = { level1: { level2: { level3: "deep" } } };
+      expect(await roundtripObject(db, meta, v)).toEqual(v);
+    });
+  });
+
+  test("array of strings", async () => {
+    await withTable(jsonbCol("'[]'::jsonb"), async ({ db, meta }) => {
+      const v = ["a", "b", "c"];
+      expect(await roundtripObject(db, meta, v)).toEqual(v);
+    });
+  });
+
+  test("array of numbers (ints + floats)", async () => {
+    await withTable(jsonbCol("'[]'::jsonb"), async ({ db, meta }) => {
+      const v = [1, 2.5, -3, 0, 1e10];
+      expect(await roundtripObject(db, meta, v)).toEqual(v);
+    });
+  });
+
+  test("array of booleans", async () => {
+    await withTable(jsonbCol("'[]'::jsonb"), async ({ db, meta }) => {
+      expect(await roundtripObject(db, meta, [true, false, true])).toEqual([true, false, true]);
+    });
+  });
+
+  test("array of objects (rows-pattern)", async () => {
+    await withTable(jsonbCol("'[]'::jsonb"), async ({ db, meta }) => {
+      const v = [
+        { id: "1", label: "Alpha" },
+        { id: "2", label: "Beta" },
+      ];
+      expect(await roundtripObject(db, meta, v)).toEqual(v);
+    });
+  });
+
+  test("mixed array (string|number|bool|null)", async () => {
+    await withTable(jsonbCol("'[]'::jsonb"), async ({ db, meta }) => {
+      const v = ["x", 1, true, null, 0];
+      expect(await roundtripObject(db, meta, v)).toEqual(v);
+    });
+  });
+});
+
+describe("jsonb — strings inside", () => {
+  test("string with double quotes (JSON-escape edge)", async () => {
+    await withTable(jsonbCol("'{}'::jsonb"), async ({ db, meta }) => {
+      const v = { note: 'He said "hello" loudly' };
+      expect(await roundtripObject(db, meta, v)).toEqual(v);
+    });
+  });
+
+  test("string with backslashes (Windows path)", async () => {
+    await withTable(jsonbCol("'{}'::jsonb"), async ({ db, meta }) => {
+      const v = { path: "C:\\Users\\marc\\Documents" };
+      expect(await roundtripObject(db, meta, v)).toEqual(v);
+    });
+  });
+
+  test("string with newlines + tabs", async () => {
+    await withTable(jsonbCol("'{}'::jsonb"), async ({ db, meta }) => {
+      const v = { body: "line1\nline2\tcol2" };
+      expect(await roundtripObject(db, meta, v)).toEqual(v);
+    });
+  });
+
+  test("string with Unicode + emoji", async () => {
+    await withTable(jsonbCol("'{}'::jsonb"), async ({ db, meta }) => {
+      const v = { name: "Müller", flag: "🇩🇪", chinese: "你好" };
+      expect(await roundtripObject(db, meta, v)).toEqual(v);
+    });
+  });
+
+  test("Stripe-style IDs", async () => {
+    await withTable(jsonbCol("'{}'::jsonb"), async ({ db, meta }) => {
+      const v = {
+        subscription: "sub_1Nq1qY2eZvKYlo2C0",
+        event: "evt_1Nq1qY2eZvKYlo2C0",
+        customer: "cus_1234567890",
+      };
+      expect(await roundtripObject(db, meta, v)).toEqual(v);
+    });
+  });
+
+  test("string with single quotes (SQL-injection-shape)", async () => {
+    await withTable(jsonbCol("'{}'::jsonb"), async ({ db, meta }) => {
+      const v = { malicious: "'; DROP TABLE users; --" };
+      expect(await roundtripObject(db, meta, v)).toEqual(v);
+    });
+  });
+
+  test("empty string + null distinction inside object", async () => {
+    await withTable(jsonbCol("'{}'::jsonb"), async ({ db, meta }) => {
+      const v = { empty: "", missing: null };
+      expect(await roundtripObject(db, meta, v)).toEqual(v);
+    });
+  });
+});
+
+describe("jsonb — numbers + special", () => {
+  test("bigint-grenzen als number (in JSON)", async () => {
+    await withTable(jsonbCol("'{}'::jsonb"), async ({ db, meta }) => {
+      // JSON nicht bigint-fähig, aber 2^53-1 ist max safe integer in JS
+      const v = { large: 9007199254740991, negativeLarge: -9007199254740991 };
+      expect(await roundtripObject(db, meta, v)).toEqual(v);
+    });
+  });
+
+  test("floats with precision", async () => {
+    await withTable(jsonbCol("'{}'::jsonb"), async ({ db, meta }) => {
+      const v = { pi: Number.parseFloat("3.141592653589793"), small: 0.0001 };
+      expect(await roundtripObject(db, meta, v)).toEqual(v);
+    });
+  });
+
+  test("ISO date strings stay strings (NOT auto-parsed to Date)", async () => {
+    await withTable(jsonbCol("'{}'::jsonb"), async ({ db, meta }) => {
+      // Wichtig: bun-db darf String-Werte in jsonb nicht zu Date coercen.
+      const v = { iso: "2026-05-24T08:30:00.000Z" };
+      const out = (await roundtripObject(db, meta, v)) as { iso: unknown };
+      expect(typeof out.iso).toBe("string");
+      expect(out.iso).toBe(v.iso);
+    });
+  });
+});
+
+describe("jsonb — booleans + null", () => {
+  test("boolean field inside object", async () => {
+    await withTable(jsonbCol("'{}'::jsonb"), async ({ db, meta }) => {
+      const v = { active: true, deleted: false };
+      const out = (await roundtripObject(db, meta, v)) as { active: unknown; deleted: unknown };
+      // typeof-Check verhindert "true"-string-statt-bool-Drift
+      expect(typeof out.active).toBe("boolean");
+      expect(typeof out.deleted).toBe("boolean");
+      expect(out.active).toBe(true);
+      expect(out.deleted).toBe(false);
+    });
+  });
+
+  test("null-value in object", async () => {
+    await withTable(jsonbCol("'{}'::jsonb"), async ({ db, meta }) => {
+      const v = { missing: null, present: "x" };
+      const out = (await roundtripObject(db, meta, v)) as { missing: unknown };
+      expect(out.missing).toBeNull();
+      expect(out).toEqual(v);
+    });
+  });
+});
+
+describe("jsonb — large + deeply nested", () => {
+  test("large object (~10KB)", async () => {
+    await withTable(jsonbCol("'{}'::jsonb"), async ({ db, meta }) => {
+      const v: Record<string, string> = {};
+      for (let i = 0; i < 100; i++) v[`k${i}`] = `value-${i}-${"x".repeat(50)}`;
+      expect(await roundtripObject(db, meta, v)).toEqual(v);
+    });
+  });
+
+  test("deeply nested (10 levels)", async () => {
+    await withTable(jsonbCol("'{}'::jsonb"), async ({ db, meta }) => {
+      let v: object = { leaf: "bottom" };
+      for (let i = 0; i < 10; i++) v = { [`level${i}`]: v };
+      expect(await roundtripObject(db, meta, v)).toEqual(v);
+    });
+  });
+
+  test("array of 50 objects", async () => {
+    await withTable(jsonbCol("'[]'::jsonb"), async ({ db, meta }) => {
+      const v = Array.from({ length: 50 }, (_, i) => ({
+        idx: i,
+        label: `row-${i}`,
+        flag: i % 2 === 0,
+      }));
+      expect(await roundtripObject(db, meta, v)).toEqual(v);
+    });
+  });
+});
+
+describe("jsonb — UPDATE roundtrip (separate from INSERT)", () => {
+  test("UPDATE replaces jsonb value entirely (not merge)", async () => {
+    await withTable(jsonbCol("'{}'::jsonb"), async ({ db, meta }) => {
+      const ins = (await insertOne<{ id: string }>(db, meta, { data: { a: 1, b: 2 } }))!;
+      await updateMany(db, meta, { data: { c: 3 } }, { id: ins.id });
+      const row = await fetchOne<{ data: unknown }>(db, meta, { id: ins.id });
+      expect(row?.data).toEqual({ c: 3 });
+    });
+  });
+
+  test("UPDATE with array value replaces full array", async () => {
+    await withTable(jsonbCol("'[]'::jsonb"), async ({ db, meta }) => {
+      const ins = (await insertOne<{ id: string }>(db, meta, { data: [1, 2, 3] }))!;
+      await updateMany(db, meta, { data: ["a", "b"] }, { id: ins.id });
+      const row = await fetchOne<{ data: unknown }>(db, meta, { id: ins.id });
+      expect(row?.data).toEqual(["a", "b"]);
+    });
+  });
+
+  test("UPDATE with empty {} → leeres Objekt überschrieben", async () => {
+    await withTable(jsonbCol("'{}'::jsonb"), async ({ db, meta }) => {
+      const ins = (await insertOne<{ id: string }>(db, meta, { data: { foo: "bar" } }))!;
+      await updateMany(db, meta, { data: {} }, { id: ins.id });
+      const row = await fetchOne<{ data: unknown }>(db, meta, { id: ins.id });
+      expect(row?.data).toEqual({});
+    });
+  });
+});

package/src/bun-db/__tests__/smoke.integration.test.ts

@@ -0,0 +1,43 @@
+// Smoke-Test: prüft dass _helpers.ts gegen die echte Test-DB funktioniert.
+// Wenn dieser File grün ist, kann sql-matrix.integration.ts dranbauen.
+
+import { afterAll, describe, expect, test } from "bun:test";
+import { deleteMany, fetchOne, insertOne, selectMany } from "../query";
+import { closeDb, withTable } from "./_helpers";
+
+afterAll(async () => {
+  await closeDb();
+});
+
+describe("_helpers smoke", () => {
+  test("withTable creates + drops a table, insert+fetch roundtrip", async () => {
+    await withTable([{ name: "label", pgType: "text", notNull: true }], async ({ db, meta }) => {
+      const inserted = await insertOne<{ id: string; label: string }>(db, meta, {
+        label: "hello",
+      });
+      expect(inserted?.label).toBe("hello");
+      expect(inserted?.id).toMatch(/^[0-9a-f-]{36}$/);
+
+      const fetched = await fetchOne<{ id: string; label: string }>(db, meta, {
+        id: inserted!.id,
+      });
+      expect(fetched?.label).toBe("hello");
+    });
+  });
+
+  test("selectMany returns all rows, deleteMany removes by where", async () => {
+    await withTable([{ name: "label", pgType: "text", notNull: true }], async ({ db, meta }) => {
+      await insertOne(db, meta, { label: "a" });
+      await insertOne(db, meta, { label: "b" });
+      await insertOne(db, meta, { label: "c" });
+
+      const all = await selectMany<{ label: string }>(db, meta);
+      expect(all.length).toBe(3);
+      expect(all.map((r) => r.label).sort()).toEqual(["a", "b", "c"]);
+
+      await deleteMany(db, meta, { label: "b" });
+      const remaining = await selectMany<{ label: string }>(db, meta);
+      expect(remaining.map((r) => r.label).sort()).toEqual(["a", "c"]);
+    });
+  });
+});

package/src/bun-db/__tests__/sql-methods.integration.test.ts

@@ -0,0 +1,231 @@
+// sql-methods.integration.ts — verhaltens-Beweis für alle bun-db query-API-Methoden.
+// Abgedeckt: selectMany, fetchOne, insertMany, updateMany, deleteMany, transaction.
+//
+// Known limitation: nested transactions (transaction() inside another transaction())
+// werden von Bun.sql NICHT unterstützt — "cannot call begin inside a transaction use
+// savepoint() instead". Test weggelassen, da query.ts keine savepoint()-Abstraktion
+// hat. transaction() kann nur von einem Top-Level-db-Handle aufgerufen werden.
+//
+// deleteMany({}) ohne WHERE-Clause: query.ts rendert keinen WHERE-Clause wenn
+// where-object leer ist → löscht ALLE Zeilen. Das ist ein Footgun; das Verhalten
+// ist hier explizit dokumentiert und getestet.
+import { afterAll, describe, expect, test } from "bun:test";
+import {
+  deleteMany,
+  fetchOne,
+  insertMany,
+  insertOne,
+  selectMany,
+  transaction,
+  updateMany,
+} from "../query";
+import { closeDb, withTable } from "./_helpers";
+
+afterAll(async () => {
+  await closeDb();
+});
+
+const textCols = [{ name: "val", pgType: "text" as const, notNull: true }] as const;
+
+describe("selectMany", () => {
+  test("leere Tabelle returnt []", async () => {
+    await withTable(textCols, async ({ db, meta }) => {
+      const rows = await selectMany(db, meta);
+      expect(rows).toEqual([]);
+    });
+  });
+
+  test("ohne where gibt alle Zeilen zurück", async () => {
+    await withTable(textCols, async ({ db, meta }) => {
+      await insertOne(db, meta, { val: "a" });
+      await insertOne(db, meta, { val: "b" });
+      await insertOne(db, meta, { val: "c" });
+      const rows = await selectMany(db, meta);
+      expect(rows.length).toBe(3);
+    });
+  });
+
+  test("mit where filtert korrekt", async () => {
+    await withTable(textCols, async ({ db, meta }) => {
+      await insertOne(db, meta, { val: "match" });
+      await insertOne(db, meta, { val: "no-match" });
+      const rows = await selectMany(db, meta, { val: "match" });
+      expect(rows.length).toBe(1);
+      expect((rows[0] as { val: string }).val).toBe("match");
+    });
+  });
+
+  test("orderBy asc", async () => {
+    await withTable(textCols, async ({ db, meta }) => {
+      await insertMany(db, meta, [{ val: "c" }, { val: "a" }, { val: "b" }]);
+      const rows = (await selectMany(
+        db,
+        meta,
+        {},
+        { orderBy: { col: "val", direction: "asc" } },
+      )) as readonly { val: string }[];
+      expect(rows.map((r) => r.val)).toEqual(["a", "b", "c"]);
+    });
+  });
+
+  test("orderBy desc", async () => {
+    await withTable(textCols, async ({ db, meta }) => {
+      await insertMany(db, meta, [{ val: "a" }, { val: "c" }, { val: "b" }]);
+      const rows = (await selectMany(
+        db,
+        meta,
+        {},
+        { orderBy: { col: "val", direction: "desc" } },
+      )) as readonly { val: string }[];
+      expect(rows.map((r) => r.val)).toEqual(["c", "b", "a"]);
+    });
+  });
+
+  test("limit begrenzt Anzahl Ergebnisse", async () => {
+    await withTable(textCols, async ({ db, meta }) => {
+      await insertMany(db, meta, [{ val: "x" }, { val: "y" }, { val: "z" }]);
+      const rows = await selectMany(db, meta, {}, { limit: 2 });
+      expect(rows.length).toBe(2);
+    });
+  });
+});
+
+describe("fetchOne", () => {
+  test("gefundene Zeile zurückgeben", async () => {
+    await withTable(textCols, async ({ db, meta }) => {
+      const inserted = await insertOne<{ id: string; val: string }>(db, meta, { val: "find-me" });
+      const row = await fetchOne<{ id: string; val: string }>(db, meta, { id: inserted!.id });
+      expect(row).toBeDefined();
+      expect(row!.val).toBe("find-me");
+    });
+  });
+
+  test("nicht-gefunden gibt undefined zurück", async () => {
+    await withTable(textCols, async ({ db, meta }) => {
+      const row = await fetchOne(db, meta, { id: "00000000-0000-4000-8000-000000000001" });
+      expect(row).toBeUndefined();
+    });
+  });
+});
+
+describe("insertMany", () => {
+  test("0 rows = no-op, gibt [] zurück", async () => {
+    await withTable(textCols, async ({ db, meta }) => {
+      const result = await insertMany(db, meta, []);
+      expect(result).toEqual([]);
+      const rows = await selectMany(db, meta);
+      expect(rows.length).toBe(0);
+    });
+  });
+
+  test("1 row", async () => {
+    await withTable(textCols, async ({ db, meta }) => {
+      const result = await insertMany<{ id: string; val: string }>(db, meta, [{ val: "single" }]);
+      expect(result.length).toBe(1);
+      expect(result[0]!.val).toBe("single");
+    });
+  });
+
+  test("5 rows auf einmal", async () => {
+    await withTable(textCols, async ({ db, meta }) => {
+      const input = Array.from({ length: 5 }, (_, i) => ({ val: `row-${i}` }));
+      const result = await insertMany<{ id: string; val: string }>(db, meta, input);
+      expect(result.length).toBe(5);
+      const all = await selectMany(db, meta);
+      expect(all.length).toBe(5);
+    });
+  });
+});
+
+describe("updateMany", () => {
+  test("zero match gibt [] zurück + keine Änderung", async () => {
+    await withTable(textCols, async ({ db, meta }) => {
+      await insertOne(db, meta, { val: "unchanged" });
+      const result = await updateMany(
+        db,
+        meta,
+        { val: "new" },
+        { id: "00000000-0000-4000-8000-000000000001" },
+      );
+      expect(result).toEqual([]);
+      const rows = await selectMany<{ val: string }>(db, meta);
+      expect(rows[0]!.val).toBe("unchanged");
+    });
+  });
+
+  test("single match updatet genau eine Zeile", async () => {
+    await withTable(textCols, async ({ db, meta }) => {
+      const ins = await insertOne<{ id: string }>(db, meta, { val: "before" });
+      await updateMany(db, meta, { val: "after" }, { id: ins!.id });
+      const row = await fetchOne<{ val: string }>(db, meta, { id: ins!.id });
+      expect(row!.val).toBe("after");
+    });
+  });
+
+  test("multi-row update ändert alle matches", async () => {
+    await withTable(textCols, async ({ db, meta }) => {
+      await insertMany(db, meta, [{ val: "old" }, { val: "old" }, { val: "keep" }]);
+      const result = await updateMany(db, meta, { val: "updated" }, { val: "old" });
+      expect(result.length).toBe(2);
+      const all = await selectMany<{ val: string }>(db, meta, { val: "updated" });
+      expect(all.length).toBe(2);
+    });
+  });
+});
+
+describe("deleteMany", () => {
+  test("zero match = keine Änderung", async () => {
+    await withTable(textCols, async ({ db, meta }) => {
+      await insertOne(db, meta, { val: "stay" });
+      await deleteMany(db, meta, { id: "00000000-0000-4000-8000-000000000001" });
+      const rows = await selectMany(db, meta);
+      expect(rows.length).toBe(1);
+    });
+  });
+
+  test("single delete entfernt genau eine Zeile (verifiziert mit selectMany)", async () => {
+    await withTable(textCols, async ({ db, meta }) => {
+      const ins = await insertOne<{ id: string }>(db, meta, { val: "delete-me" });
+      await insertOne(db, meta, { val: "keep" });
+      await deleteMany(db, meta, { id: ins!.id });
+      const rows = await selectMany(db, meta);
+      expect(rows.length).toBe(1);
+    });
+  });
+
+  test("deleteMany({}) löscht alle Zeilen (FOOTGUN: kein WHERE-Clause)", async () => {
+    await withTable(textCols, async ({ db, meta }) => {
+      await insertMany(db, meta, [{ val: "a" }, { val: "b" }, { val: "c" }]);
+      await deleteMany(db, meta, {});
+      const rows = await selectMany(db, meta);
+      expect(rows.length).toBe(0);
+    });
+  });
+});
+
+describe("transaction", () => {
+  test("commit: writes sind danach in DB sichtbar", async () => {
+    await withTable(textCols, async ({ db, meta }) => {
+      await transaction(db, async (tx) => {
+        await insertOne(tx, meta, { val: "committed" });
+      });
+      const rows = await selectMany<{ val: string }>(db, meta);
+      expect(rows.length).toBe(1);
+      expect(rows[0]!.val).toBe("committed");
+    });
+  });
+
+  test("rollback bei throw: writes sind WEG (verifiziert mit selectMany)", async () => {
+    await withTable(textCols, async ({ db, meta }) => {
+      await expect(
+        transaction(db, async (tx) => {
+          await insertOne(tx, meta, { val: "should-vanish" });
+          throw new Error("forced rollback");
+        }),
+      ).rejects.toThrow("forced rollback");
+      // Verifizieren dass die Zeile tatsächlich nicht da ist
+      const rows = await selectMany(db, meta);
+      expect(rows.length).toBe(0);
+    });
+  });
+});

package/src/bun-db/__tests__/where-patterns.integration.test.ts

@@ -0,0 +1,185 @@
+// where-patterns.integration.ts — vollständige WhereObject + WhereOperator-Matrix.
+//
+// WhereObject aus query.ts unterstützt:
+//   - primitive equality: string, number, boolean, uuid
+//   - null → IS NULL
+//   - bare array → IN (shortcut)
+//   - WhereOperator: { in: [...] }, { ne: x }, { gt/gte/lt/lte }, { like: str }
+//   - multi-field AND-Kombination
+//
+// JSONB top-level equality: wird getestet (JSON.stringify + ::jsonb cast in prepareValue).
+// Deep-path-queries (->>'key') sind out-of-scope für bun-db's WhereObject.
+import { afterAll, describe, expect, test } from "bun:test";
+import { insertMany, selectMany } from "../query";
+import { closeDb, withTable } from "./_helpers";
+
+afterAll(async () => {
+  await closeDb();
+});
+
+const strNumCols = [
+  { name: "label", pgType: "text" as const, notNull: true },
+  { name: "score", pgType: "integer" as const, notNull: true },
+] as const;
+
+const boolCols = [{ name: "active", pgType: "boolean" as const, notNull: false }] as const;
+
+const refCols = [{ name: "ref", pgType: "uuid" as const, notNull: false }] as const;
+
+describe("where — primitive equality", () => {
+  test("string equality", async () => {
+    await withTable(strNumCols, async ({ db, meta }) => {
+      await insertMany(db, meta, [
+        { label: "alpha", score: 1 },
+        { label: "beta", score: 2 },
+      ]);
+      const rows = await selectMany<{ label: string }>(db, meta, { label: "alpha" });
+      expect(rows.length).toBe(1);
+      expect(rows[0]!.label).toBe("alpha");
+    });
+  });
+
+  test("number equality", async () => {
+    await withTable(strNumCols, async ({ db, meta }) => {
+      await insertMany(db, meta, [
+        { label: "a", score: 42 },
+        { label: "b", score: 99 },
+      ]);
+      const rows = await selectMany<{ score: number }>(db, meta, { score: 42 });
+      expect(rows.length).toBe(1);
+      expect(rows[0]!.score).toBe(42);
+    });
+  });
+
+  test("boolean equality (true)", async () => {
+    await withTable(boolCols, async ({ db, meta }) => {
+      await insertMany(db, meta, [{ active: true }, { active: false }, { active: true }]);
+      const rows = await selectMany(db, meta, { active: true });
+      expect(rows.length).toBe(2);
+    });
+  });
+
+  test("boolean equality (false)", async () => {
+    await withTable(boolCols, async ({ db, meta }) => {
+      await insertMany(db, meta, [{ active: true }, { active: false }]);
+      const rows = await selectMany(db, meta, { active: false });
+      expect(rows.length).toBe(1);
+    });
+  });
+
+  test("uuid equality", async () => {
+    await withTable(refCols, async ({ db, meta }) => {
+      const target = "00000000-0000-4000-8000-000000000042";
+      const other = "00000000-0000-4000-8000-000000000099";
+      await insertMany(db, meta, [{ ref: target }, { ref: other }]);
+      const rows = await selectMany<{ ref: string }>(db, meta, { ref: target });
+      expect(rows.length).toBe(1);
+      expect(rows[0]!.ref).toBe(target);
+    });
+  });
+});
+
+describe("where — null / IS NULL", () => {
+  test("where: { col: null } → IS NULL", async () => {
+    await withTable(boolCols, async ({ db, meta }) => {
+      await insertMany(db, meta, [{ active: null }, { active: true }]);
+      const rows = await selectMany(db, meta, { active: null });
+      expect(rows.length).toBe(1);
+      expect((rows[0] as { active: unknown }).active).toBeNull();
+    });
+  });
+});
+
+describe("where — WhereOperator", () => {
+  test("{ in: [...] } → IN-Clause multi-match", async () => {
+    await withTable(strNumCols, async ({ db, meta }) => {
+      await insertMany(db, meta, [
+        { label: "a", score: 1 },
+        { label: "b", score: 2 },
+        { label: "c", score: 3 },
+      ]);
+      const rows = await selectMany(db, meta, { label: { in: ["a", "c"] } });
+      expect(rows.length).toBe(2);
+    });
+  });
+
+  test("bare array als IN-Shortcut", async () => {
+    await withTable(strNumCols, async ({ db, meta }) => {
+      await insertMany(db, meta, [
+        { label: "x", score: 10 },
+        { label: "y", score: 20 },
+        { label: "z", score: 30 },
+      ]);
+      // Array als WhereValue direkt ist valider IN-Shortcut (buildWhereClause L.2)
+      const rows = await selectMany(db, meta, { label: ["x", "z"] as unknown as string });
+      expect(rows.length).toBe(2);
+    });
+  });
+
+  test("{ ne: x } → NOT EQUAL", async () => {
+    await withTable(strNumCols, async ({ db, meta }) => {
+      await insertMany(db, meta, [
+        { label: "keep", score: 1 },
+        { label: "exclude", score: 2 },
+      ]);
+      const rows = await selectMany<{ label: string }>(db, meta, { label: { ne: "exclude" } });
+      expect(rows.length).toBe(1);
+      expect(rows[0]!.label).toBe("keep");
+    });
+  });
+
+  test("{ gt: x } → greater than", async () => {
+    await withTable(strNumCols, async ({ db, meta }) => {
+      await insertMany(db, meta, [
+        { label: "low", score: 5 },
+        { label: "mid", score: 50 },
+        { label: "high", score: 100 },
+      ]);
+      const rows = await selectMany(db, meta, { score: { gt: 10 } });
+      expect(rows.length).toBe(2);
+    });
+  });
+
+  test("{ lte: x } → less-or-equal", async () => {
+    await withTable(strNumCols, async ({ db, meta }) => {
+      await insertMany(db, meta, [
+        { label: "a", score: 1 },
+        { label: "b", score: 5 },
+        { label: "c", score: 10 },
+      ]);
+      const rows = await selectMany(db, meta, { score: { lte: 5 } });
+      expect(rows.length).toBe(2);
+    });
+  });
+
+  test("{ like: pattern } → LIKE-Match", async () => {
+    await withTable(strNumCols, async ({ db, meta }) => {
+      await insertMany(db, meta, [
+        { label: "hello-world", score: 1 },
+        { label: "hello-bun", score: 2 },
+        { label: "goodbye", score: 3 },
+      ]);
+      const rows = await selectMany(db, meta, { label: { like: "hello%" } });
+      expect(rows.length).toBe(2);
+    });
+  });
+});
+
+describe("where — multi-field AND", () => {
+  test("zwei Felder kombiniert (UND-Semantik)", async () => {
+    await withTable(strNumCols, async ({ db, meta }) => {
+      await insertMany(db, meta, [
+        { label: "target", score: 7 },
+        { label: "target", score: 99 },
+        { label: "other", score: 7 },
+      ]);
+      const rows = await selectMany<{ label: string; score: number }>(db, meta, {
+        label: "target",
+        score: 7,
+      });
+      expect(rows.length).toBe(1);
+      expect(rows[0]!.label).toBe("target");
+      expect(rows[0]!.score).toBe(7);
+    });
+  });
+});