@cosmicdrift/kumiko-framework 0.13.0 → 0.15.0

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

@@ -0,0 +1,143 @@
+import { afterAll, describe, expect, test } from "bun:test";
+import { sql } from "../../db/dialect";
+import type { EntityTableMeta } from "../../db/entity-table-meta";
+import {
+  asRawClient,
+  countWhere,
+  deleteManyBatched,
+  incrementCounter,
+  insertMany,
+  selectMany,
+  upsertByPk,
+  upsertOnConflict,
+} from "../query";
+import { closeDb, getDb, renderCreateTable, uniqueTableName, withTable } from "./_helpers";
+
+afterAll(async () => {
+  await closeDb();
+});
+
+const scoreCols = [
+  { name: "score", pgType: "integer" as const, notNull: true, defaultSql: "0" },
+] as const;
+
+function makeCodePkMeta(tableName: string): EntityTableMeta {
+  return {
+    tableName,
+    source: "unmanaged",
+    indexes: [],
+    columns: [
+      { name: "code", pgType: "text", notNull: true, primaryKey: true },
+      { name: "score", pgType: "integer", notNull: true, defaultSql: "0" },
+    ],
+  };
+}
+
+async function withCodeTable<T>(
+  fn: (ctx: { db: unknown; meta: EntityTableMeta }) => Promise<T>,
+): Promise<T> {
+  const db = await getDb();
+  const tableName = uniqueTableName("upsert");
+  const meta = makeCodePkMeta(tableName);
+  await asRawClient(db).unsafe(renderCreateTable(meta));
+  try {
+    return await fn({ db, meta });
+  } finally {
+    await asRawClient(db).unsafe(`DROP TABLE IF EXISTS "${tableName}"`);
+  }
+}
+
+describe("countWhere", () => {
+  test("counts all rows when where is empty", async () => {
+    await withTable(scoreCols, async ({ db, meta }) => {
+      await insertMany(db, meta, [{ score: 1 }, { score: 2 }]);
+      expect(await countWhere(db, meta)).toBe(2);
+    });
+  });
+
+  test("counts filtered rows", async () => {
+    await withTable(scoreCols, async ({ db, meta }) => {
+      await insertMany(db, meta, [{ score: 1 }, { score: 5 }, { score: 5 }]);
+      expect(await countWhere(db, meta, { score: 5 })).toBe(2);
+    });
+  });
+});
+
+describe("upsertOnConflict / upsertByPk", () => {
+  test("upsertByPk inserts then updates on conflict", async () => {
+    await withCodeTable(async ({ db, meta }) => {
+      await upsertByPk(db, meta, { code: "alpha", score: 1 });
+      await upsertByPk(db, meta, { code: "alpha", score: 9 });
+      const rows = await selectMany<{ code: string; score: number }>(db, meta);
+      expect(rows).toHaveLength(1);
+      expect(rows[0]?.score).toBe(9);
+    });
+  });
+
+  test("upsertOnConflict with explicit conflictKeys", async () => {
+    await withCodeTable(async ({ db, meta }) => {
+      await upsertOnConflict(db, meta, { code: "beta", score: 2 }, { conflictKeys: ["code"] });
+      await upsertOnConflict(
+        db,
+        meta,
+        { code: "beta", score: 7 },
+        { conflictKeys: ["code"], update: { score: 7 } },
+      );
+      const row = (await selectMany<{ score: number }>(db, meta, { code: "beta" }))[0];
+      expect(row?.score).toBe(7);
+    });
+  });
+});
+
+describe("incrementCounter", () => {
+  test("atomically increments numeric columns on conflict", async () => {
+    await withCodeTable(async ({ db, meta }) => {
+      await incrementCounter(db, meta, { code: "t1", score: 10 }, { score: 10 });
+      await incrementCounter(db, meta, { code: "t1", score: 0 }, { score: 5 });
+      const row = (await selectMany<{ score: number }>(db, meta, { code: "t1" }))[0];
+      expect(row?.score).toBe(15);
+    });
+  });
+
+  test("supports set on conflict with sql expression", async () => {
+    await withCodeTable(async ({ db, meta }) => {
+      const withUpdated: EntityTableMeta = {
+        ...meta,
+        columns: [
+          ...meta.columns,
+          { name: "updated_at", pgType: "timestamptz", notNull: true, defaultSql: "now()" },
+        ],
+      };
+      await asRawClient(db).unsafe(`DROP TABLE IF EXISTS "${meta.tableName}"`);
+      await asRawClient(db).unsafe(renderCreateTable(withUpdated));
+      await incrementCounter(
+        db,
+        withUpdated,
+        { code: "x", score: 1 },
+        { score: 1 },
+        { conflictKeys: ["code"], set: { updatedAt: sql`NOW()` } },
+      );
+      const rows = await selectMany(db, withUpdated, { code: "x" });
+      expect(rows.length).toBe(1);
+    });
+  });
+});
+
+describe("deleteManyBatched", () => {
+  test("deletes in chunks until no rows match", async () => {
+    await withTable(scoreCols, async ({ db, meta }) => {
+      await insertMany(
+        db,
+        meta,
+        Array.from({ length: 10 }, (_, i) => ({ score: i < 7 ? 1 : 9 })),
+      );
+      expect(await countWhere(db, meta, { score: 1 })).toBe(7);
+
+      const result = await deleteManyBatched(db, meta, { score: 1 }, { limit: 3 });
+      expect(result.deleted).toBe(7);
+      expect(result.batches).toBe(3);
+      expect(await countWhere(db, meta, { score: 1 })).toBe(0);
+      expect(await countWhere(db, meta, { score: 9 })).toBe(3);
+    });
+  });
+});

package/src/bun-db/__tests__/batch-methods.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, test } from "bun:test";
+import { deleteManyBatched } from "../query";
+
+describe("deleteManyBatched (mock)", () => {
+  test("requires non-empty where", async () => {
+    const meta = {
+      source: "unmanaged" as const,
+      tableName: "read_items",
+      indexes: [],
+      columns: [
+        { name: "id", pgType: "uuid", notNull: true, primaryKey: true },
+        { name: "flag", pgType: "boolean", notNull: true },
+      ],
+    };
+    const db = { unsafe: async () => [] as unknown[] };
+    await expect(deleteManyBatched(db, meta, {}, { limit: 10 })).rejects.toThrow(
+      "where clause required",
+    );
+  });
+});

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

@@ -0,0 +1,19 @@
+// Provider-agnostic Test-DB: delegiert an createTestDb (postgres-js default).
+// Welcher Provider tatsächlich genutzt wird steuert DB_PROVIDER env-var,
+// gelesen in db/api.ts createConnection — global, einmalig zu Boot-Zeit.
+//
+// "Bun" im Namen ist historisch (Pattern-Discovery-Phase) — der Body ist
+// provider-neutral. Aliase BunTestDb/createBunTestDb existieren damit
+// die migrierten Test-Files importierbar bleiben ohne weitere Refactors.
+
+import { type CreateTestDbOptions, createTestDb, type TestDb } from "../../stack/db";
+
+export type { TestDb };
+export type BunTestDb = TestDb;
+
+export async function createBunTestDb(baseUrl?: string): Promise<TestDb> {
+  const opts: CreateTestDbOptions = baseUrl ? { baseUrl } : {};
+  return createTestDb(opts);
+}
+
+export { createTestDb };

package/src/bun-db/__tests__/bun-test-stack.ts

@@ -0,0 +1,6 @@
+// Provider-agnostic Test-Stack — re-exported from stack/test-stack.ts.
+// setupBunTestStack / BunTestStack sind Aliase für setupTestStack / TestStack.
+// "Bun" ist historisch, jetzt provider-neutral (DB_PROVIDER env).
+
+export type { TestStack as BunTestStack } from "../../stack/test-stack";
+export { setupTestStack as setupBunTestStack } from "../../stack/test-stack";

package/src/bun-db/__tests__/column-types.integration.test.ts

@@ -0,0 +1,132 @@
+// Column-Type-Roundtrip-Matrix: jeder pgType, der von Bun.SQL über
+// bun-db unterstützt werden muss — insert + fetch + JS-Wert-Vergleich.
+//
+// Beweist dass jeder Spalten-Typ aus EntityTableMeta in den bun-db
+// query-layer rein- und rausgeht ohne dass JS-Werte sich subtil ändern
+// (Type-coercion-bug, BigInt-precision-loss, jsonb-string-statt-object,
+// Temporal-Drift bei timestamptz, etc.).
+
+import { afterAll, describe, expect, test } from "bun:test";
+import { fetchOne, insertOne } from "../query";
+import { closeDb, withTable } from "./_helpers";
+
+afterAll(async () => {
+  await closeDb();
+});
+
+describe("column-type roundtrip", () => {
+  test("text", async () => {
+    await withTable([{ name: "val", pgType: "text", notNull: true }], async ({ db, meta }) => {
+      const ins = await insertOne<{ id: string; val: string }>(db, meta, { val: "hello" });
+      const row = await fetchOne<{ id: string; val: string }>(db, meta, { id: ins!.id });
+      expect(row?.val).toBe("hello");
+    });
+  });
+
+  test("text with unicode + emoji", async () => {
+    await withTable([{ name: "val", pgType: "text", notNull: true }], async ({ db, meta }) => {
+      const ins = await insertOne<{ id: string; val: string }>(db, meta, {
+        val: "Müller 🦊 中文",
+      });
+      const row = await fetchOne<{ id: string; val: string }>(db, meta, { id: ins!.id });
+      expect(row?.val).toBe("Müller 🦊 中文");
+    });
+  });
+
+  test("text empty string (not null)", async () => {
+    await withTable([{ name: "val", pgType: "text", notNull: false }], async ({ db, meta }) => {
+      const ins = await insertOne<{ id: string; val: string }>(db, meta, { val: "" });
+      const row = await fetchOne<{ id: string; val: string }>(db, meta, { id: ins!.id });
+      expect(row?.val).toBe("");
+    });
+  });
+
+  test("text null in nullable column", async () => {
+    await withTable([{ name: "val", pgType: "text", notNull: false }], async ({ db, meta }) => {
+      const ins = await insertOne<{ id: string; val: string | null }>(db, meta, { val: null });
+      const row = await fetchOne<{ id: string; val: string | null }>(db, meta, { id: ins!.id });
+      expect(row?.val).toBeNull();
+    });
+  });
+
+  test("boolean true + false", async () => {
+    await withTable([{ name: "flag", pgType: "boolean", notNull: true }], async ({ db, meta }) => {
+      const t = await insertOne<{ id: string; flag: boolean }>(db, meta, { flag: true });
+      const f = await insertOne<{ id: string; flag: boolean }>(db, meta, { flag: false });
+      const tr = await fetchOne<{ flag: boolean }>(db, meta, { id: t!.id });
+      const fr = await fetchOne<{ flag: boolean }>(db, meta, { id: f!.id });
+      expect(tr?.flag).toBe(true);
+      expect(fr?.flag).toBe(false);
+    });
+  });
+
+  test("integer ±max", async () => {
+    await withTable([{ name: "n", pgType: "integer", notNull: true }], async ({ db, meta }) => {
+      const max = await insertOne<{ id: string; n: number }>(db, meta, { n: 2147483647 });
+      const min = await insertOne<{ id: string; n: number }>(db, meta, { n: -2147483648 });
+      const zero = await insertOne<{ id: string; n: number }>(db, meta, { n: 0 });
+      expect((await fetchOne<{ n: number }>(db, meta, { id: max!.id }))?.n).toBe(2147483647);
+      expect((await fetchOne<{ n: number }>(db, meta, { id: min!.id }))?.n).toBe(-2147483648);
+      expect((await fetchOne<{ n: number }>(db, meta, { id: zero!.id }))?.n).toBe(0);
+    });
+  });
+
+  test("bigint ±max (as bigint)", async () => {
+    await withTable([{ name: "n", pgType: "bigint", notNull: true }], async ({ db, meta }) => {
+      // JS Number-Max = 2^53-1. Postgres bigint = ±2^63-1.
+      // bun-db boundary coerziert string→bigint (siehe commit 0be2db9b).
+      const bigPos = 9007199254740993n;
+      const ins = await insertOne<{ id: string; n: bigint }>(db, meta, { n: bigPos });
+      const row = await fetchOne<{ id: string; n: bigint }>(db, meta, { id: ins!.id });
+      expect(row?.n).toBe(bigPos);
+    });
+  });
+
+  test("uuid roundtrip", async () => {
+    await withTable([{ name: "ref", pgType: "uuid", notNull: true }], async ({ db, meta }) => {
+      const target = "00000000-0000-4000-8000-000000000001";
+      const ins = await insertOne<{ id: string; ref: string }>(db, meta, { ref: target });
+      const row = await fetchOne<{ ref: string }>(db, meta, { id: ins!.id });
+      expect(row?.ref).toBe(target);
+    });
+  });
+
+  test("timestamptz roundtrip via ISO string", async () => {
+    await withTable(
+      [{ name: "ts", pgType: "timestamptz", notNull: true }],
+      async ({ db, meta }) => {
+        const iso = "2026-05-24T08:30:00.000Z";
+        const ins = await insertOne<{ id: string; ts: unknown }>(db, meta, { ts: iso });
+        const row = await fetchOne<{ id: string; ts: Date | string }>(db, meta, { id: ins!.id });
+        // bun-db gibt Temporal.Instant zurück (siehe ec2c7fbf). Wir
+        // checken über instant.toString() bzw. Date-equivalence.
+        const fetched = row?.ts;
+        const ms =
+          fetched instanceof Date ? fetched.getTime() : new Date(String(fetched)).getTime();
+        expect(ms).toBe(new Date(iso).getTime());
+      },
+    );
+  });
+
+  test("jsonb empty object", async () => {
+    await withTable(
+      [{ name: "data", pgType: "jsonb", notNull: true, defaultSql: "'{}'::jsonb" }],
+      async ({ db, meta }) => {
+        const ins = await insertOne<{ id: string; data: object }>(db, meta, { data: {} });
+        const row = await fetchOne<{ data: object }>(db, meta, { id: ins!.id });
+        expect(row?.data).toEqual({});
+      },
+    );
+  });
+
+  test("jsonb empty array", async () => {
+    await withTable(
+      [{ name: "data", pgType: "jsonb", notNull: true, defaultSql: "'[]'::jsonb" }],
+      async ({ db, meta }) => {
+        const ins = await insertOne<{ id: string; data: unknown[] }>(db, meta, { data: [] });
+        const row = await fetchOne<{ data: unknown[] }>(db, meta, { id: ins!.id });
+        expect(row?.data).toEqual([]);
+      },
+    );
+  });
+});

package/src/bun-db/__tests__/compound-types.integration.test.ts

@@ -0,0 +1,134 @@
+// compound-types.integration.ts — Roundtrip-Tests für die entity-table-meta
+// Compound-Field-Types die 2+ Spalten produzieren.
+//
+// money (field.type "money"):
+//   <snake>            bigint  — Cent-Betrag (JS bigint, kein precision-loss)
+//   <snake>_currency   text    — ISO-4217-Code
+//   Read-keys (nach camelCase-Coercion in coerceRow): price / priceCurrency
+//
+// locatedTimestamp (field.type "locatedTimestamp"):
+//   <snake>_utc  timestamptz — UTC-Zeitstempel (→ Temporal.Instant nach coerceRow)
+//   <snake>_tz   text        — IANA-Timezone-Name
+//   Read-keys nach camelCase-Coercion: dueAtUtc / dueAtTz
+//
+// Schreiben: snake_case-Keys werden von columnOf() korrekt gemappt.
+// Lesen: coerceRow() renamed snake_case-DB-columns zu camelCase JS-keys.
+import { afterAll, describe, expect, test } from "bun:test";
+import { fetchOne, insertOne } from "../query";
+import { closeDb, withTable } from "./_helpers";
+
+afterAll(async () => {
+  await closeDb();
+});
+
+const moneyCols = [
+  { name: "price", pgType: "bigint" as const, notNull: true },
+  { name: "price_currency", pgType: "text" as const, notNull: true, defaultSql: "'EUR'" },
+] as const;
+
+const locatedTsCols = [
+  { name: "due_at_utc", pgType: "timestamptz" as const, notNull: true },
+  { name: "due_at_tz", pgType: "text" as const, notNull: true },
+] as const;
+
+describe("money — roundtrip", () => {
+  test("EUR-Betrag: insert + fetchOne gibt gleichen bigint + currency zurück", async () => {
+    await withTable(moneyCols, async ({ db, meta }) => {
+      const ins = await insertOne<{ id: string }>(db, meta, {
+        price: 1234n,
+        price_currency: "EUR",
+      });
+      const row = await fetchOne<{ price: bigint; priceCurrency: string }>(db, meta, {
+        id: ins!.id,
+      });
+      expect(row!.price).toBe(1234n);
+      expect(row!.priceCurrency).toBe("EUR");
+    });
+  });
+
+  test("CHF-Currency roundtrip", async () => {
+    await withTable(moneyCols, async ({ db, meta }) => {
+      const ins = await insertOne<{ id: string }>(db, meta, {
+        price: 9900n,
+        price_currency: "CHF",
+      });
+      const row = await fetchOne<{ price: bigint; priceCurrency: string }>(db, meta, {
+        id: ins!.id,
+      });
+      expect(row!.priceCurrency).toBe("CHF");
+      expect(row!.price).toBe(9900n);
+    });
+  });
+
+  test("JPY-Currency roundtrip (kein Cent, ganzer Yen)", async () => {
+    await withTable(moneyCols, async ({ db, meta }) => {
+      const ins = await insertOne<{ id: string }>(db, meta, {
+        price: 150000n,
+        price_currency: "JPY",
+      });
+      const row = await fetchOne<{ price: bigint; priceCurrency: string }>(db, meta, {
+        id: ins!.id,
+      });
+      expect(row!.priceCurrency).toBe("JPY");
+      expect(row!.price).toBe(150000n);
+    });
+  });
+
+  test("großer Betrag (> 2^53 cents — bigint-Boundary, precision-loss-Guard)", async () => {
+    await withTable(moneyCols, async ({ db, meta }) => {
+      // JS Number max-safe ist 9007199254740991. Wert jenseits dieser Grenze
+      // würde bei Number-Rückgabe still precision verlieren. bigint-Roundtrip
+      // muss exakt bleiben.
+      const bigCents = 9007199254740992n; // 2^53 — jenseits JS-Number-Grenze
+      const ins = await insertOne<{ id: string }>(db, meta, {
+        price: bigCents,
+        price_currency: "EUR",
+      });
+      const row = await fetchOne<{ price: bigint }>(db, meta, { id: ins!.id });
+      expect(row!.price).toBe(bigCents);
+    });
+  });
+});
+
+describe("locatedTimestamp — roundtrip", () => {
+  test("UTC-Zeitstempel + Timezone-Name roundtrip (Europe/Berlin)", async () => {
+    await withTable(locatedTsCols, async ({ db, meta }) => {
+      const iso = "2026-05-24T08:30:00.000Z";
+      const tz = "Europe/Berlin";
+      const ins = await insertOne<{ id: string }>(db, meta, {
+        due_at_utc: iso,
+        due_at_tz: tz,
+      });
+      const row = await fetchOne<{ dueAtUtc: Temporal.Instant; dueAtTz: string }>(db, meta, {
+        id: ins!.id,
+      });
+      // bun-db coerciert timestamptz → Temporal.Instant (coerceRow in query.ts)
+      expect(typeof row!.dueAtUtc.epochNanoseconds).toBe("bigint");
+      expect(row!.dueAtUtc.epochMilliseconds).toBe(new Date(iso).getTime());
+      expect(row!.dueAtTz).toBe(tz);
+    });
+  });
+
+  test("Timezone America/New_York bleibt als String erhalten", async () => {
+    await withTable(locatedTsCols, async ({ db, meta }) => {
+      const ins = await insertOne<{ id: string }>(db, meta, {
+        due_at_utc: "2026-01-15T13:00:00.000Z",
+        due_at_tz: "America/New_York",
+      });
+      const row = await fetchOne<{ dueAtTz: string }>(db, meta, { id: ins!.id });
+      expect(row!.dueAtTz).toBe("America/New_York");
+    });
+  });
+
+  test("UTC-Zeitstempel am Tag-Anfang (Mitternacht)", async () => {
+    await withTable(locatedTsCols, async ({ db, meta }) => {
+      const iso = "2026-01-01T00:00:00.000Z";
+      const ins = await insertOne<{ id: string }>(db, meta, {
+        due_at_utc: iso,
+        due_at_tz: "UTC",
+      });
+      const row = await fetchOne<{ dueAtUtc: Temporal.Instant }>(db, meta, { id: ins!.id });
+      expect(row!.dueAtUtc.epochMilliseconds).toBe(new Date(iso).getTime());
+    });
+  });
+});