@cosmicdrift/kumiko-framework 0.14.0 → 0.15.0

package/src/db/api.ts

@@ -0,0 +1,46 @@
+// DB-API: Unified Types und Connection-Factory.
+// Provider-agnostic code verwendet ausschliesslich diese Types.
+// Provider-Implementierungen: postgres-provider.ts, bun-provider.ts.
+//
+// `asRawClient(db)` aus bun-db/query.ts normalisiert beide Provider
+// zu { unsafe, begin } — business code ist provider-neutral.
+//
+// Default: postgres-js. Set DB_PROVIDER=bun für Bun.SQL (experimentell).
+
+export type DbConnectionOptions = {
+  readonly maxConnections?: number;
+  readonly idleTimeoutSeconds?: number;
+  readonly connectTimeoutSeconds?: number;
+};
+
+// Connection-Handle: db für Queries, client für Legacy-Zugriff (LISTEN/NOTIFY-Peer
+// bei Bun.SQL), close für Pool-Shutdown.
+export type DbConnection = {
+  /** Provider Connection — Calls gehen über asRawClient() oder direkt. */
+  // biome-ignore lint/suspicious/noExplicitAny: cross-provider connection — postgres-js | Bun.SQL
+  readonly db: any;
+  /** Legacy postgres-js Client (für LISTEN peer) */
+  // biome-ignore lint/suspicious/noExplicitAny: postgres-js client
+  readonly client: any;
+  /** Optionaler Bun.SQL LISTEN peer */
+  // biome-ignore lint/suspicious/noExplicitAny: postgres-js LISTEN peer
+  readonly listenClient?: any;
+  /** Pool schliessen */
+  close: () => Promise<void>;
+};
+
+let _provider: undefined | (() => Promise<typeof import("./postgres-provider")>);
+
+export async function createConnection(
+  url: string,
+  options: DbConnectionOptions = {},
+): Promise<DbConnection> {
+  const p = process.env["DB_PROVIDER"];
+  if (p === "bun" || p === "bun-sql") {
+    const { createBunConnection } = await import("./bun-provider");
+    return createBunConnection(url, options);
+  }
+  // postgres-js: sync, kein async import nötig
+  const { createPgConnection } = await import("./postgres-provider");
+  return createPgConnection(url, options);
+}

package/src/db/apply-entity-event.ts

@@ -47,7 +47,7 @@
 //   - "skipped" → Event ist kein Auto-Verb (Domain-Event auf demselben
 //     Aggregate). Caller no-op.
 
-import { eq } from "drizzle-orm";
+import { deleteMany, insertOne, updateMany } from "../db/query";
 import type { EntityDefinition } from "../engine/types";
 import { InternalError } from "../errors";
 import type { StoredEvent } from "../event-store";
@@ -112,57 +112,65 @@ export async function applyEntityEvent(
           message: `applyEntityEvent: payload.tenantId set but invalid (${JSON.stringify(payloadTenantId)}). Tenant-isolation-kritisch: silent fallback auf event.tenantId würde Cross-Tenant-Drift erzeugen.`,
         });
       }
-      const [row] = await tx
-        .insert(table)
-        .values({
-          ...event.payload,
-          tenantId,
-          id: event.aggregateId,
-          version: event.version,
-          insertedAt: event.createdAt,
-          insertedById: event.createdBy,
-        })
-        .returning();
-      return { kind: "applied", verb, row: (row as DbRow | undefined) ?? null };
+      const row = await insertOne<DbRow>(tx, table, {
+        ...event.payload,
+        tenantId,
+        id: event.aggregateId,
+        version: event.version,
+        insertedAt: event.createdAt,
+        insertedById: event.createdBy,
+      });
+      return { kind: "applied", verb, row: row ?? null };
     }
 
     case "updated": {
       // payload-Shape: { changes, previous } — siehe event-store-executor.ts.
-      const changes = (event.payload["changes"] ?? {}) as Record<string, unknown>; // @cast-boundary engine-payload
-      const [row] = await tx
-        .update(table)
-        .set({
+      const rawChanges = (event.payload["changes"] ?? {}) as Record<string, unknown>; // @cast-boundary engine-payload
+      // Plural file fields (files/images) have no entity-table column — the
+      // array of UUIDs lives in the event payload only. Strip them from the
+      // UPDATE so Postgres doesn't error with "column X does not exist".
+      const changes: Record<string, unknown> = {};
+      for (const [key, value] of Object.entries(rawChanges)) {
+        const fieldType = entity.fields[key]?.type;
+        if (fieldType === "files" || fieldType === "images") continue;
+        changes[key] = value;
+      }
+      const rows = await updateMany<DbRow>(
+        tx,
+        table,
+        {
           ...changes,
           version: event.version,
           modifiedAt: event.createdAt,
           modifiedById: event.createdBy,
-        })
-        .where(eq(table["id"], event.aggregateId))
-        .returning();
-      return { kind: "applied", verb, row: (row as DbRow | undefined) ?? null };
+        },
+        { id: event.aggregateId },
+      );
+      return { kind: "applied", verb, row: rows[0] ?? null };
     }
 
     case "deleted": {
       if (softDelete) {
-        const [row] = await tx
-          .update(table)
-          .set({
+        const rows = await updateMany<DbRow>(
+          tx,
+          table,
+          {
             isDeleted: true,
             deletedAt: event.createdAt,
             deletedById: event.createdBy,
             version: event.version,
             modifiedAt: event.createdAt,
             modifiedById: event.createdBy,
-          })
-          .where(eq(table["id"], event.aggregateId))
-          .returning();
-        return { kind: "applied", verb, row: (row as DbRow | undefined) ?? null };
+          },
+          { id: event.aggregateId },
+        );
+        return { kind: "applied", verb, row: rows[0] ?? null };
       }
       // Hard-Delete: DELETE-Statement gibt keine returning-Row her und
       // der Live-Pfad nutzt eh `existing` (pre-delete-Snapshot) für die
       // Response. Beim Replay ist das fine, der Caller braucht die Row
       // nicht weiter.
-      await tx.delete(table).where(eq(table["id"], event.aggregateId));
+      await deleteMany(tx, table, { id: event.aggregateId });
       return { kind: "applied", verb, row: null };
     }
 
@@ -170,19 +178,20 @@ export async function applyEntityEvent(
       // Restore ist nur bei softDelete sinnvoll. Hard-Delete-Entities sollten
       // keine restored-Events erhalten — falls doch, defensive skip.
       if (!softDelete) return { kind: "skipped" };
-      const [row] = await tx
-        .update(table)
-        .set({
+      const rows = await updateMany<DbRow>(
+        tx,
+        table,
+        {
           isDeleted: false,
           deletedAt: null,
           deletedById: null,
           version: event.version,
           modifiedAt: event.createdAt,
           modifiedById: event.createdBy,
-        })
-        .where(eq(table["id"], event.aggregateId))
-        .returning();
-      return { kind: "applied", verb, row: (row as DbRow | undefined) ?? null };
+        },
+        { id: event.aggregateId },
+      );
+      return { kind: "applied", verb, row: rows[0] ?? null };
     }
   }
 }

package/src/db/assert-exists-in.ts

@@ -1,4 +1,4 @@
-import { and, eq, type SQL } from "drizzle-orm";
+import { fetchOne } from "../db/query";
 import type { TenantId } from "../engine/types/identifiers";
 import { NotFoundError } from "../errors";
 import type { DbConnection } from "./connection";
@@ -28,22 +28,11 @@ export async function assertExistsIn(
     entityName?: string;
   },
 ): Promise<NotFoundError | null> {
-  const conditions = [eq(entity[options.field], options.value)];
+  const where: Record<string, unknown> = { [options.field]: options.value };
+  if (options.tenantId !== undefined) where["tenantId"] = options.tenantId;
+  if (options.where) Object.assign(where, options.where);
 
-  if (options.tenantId !== undefined) {
-    conditions.push(eq(entity["tenantId"], options.tenantId));
-  }
-
-  if (options.where) {
-    for (const [key, val] of Object.entries(options.where)) {
-      conditions.push(eq(entity[key], val));
-    }
-  }
-
-  const [row] = await db
-    .select()
-    .from(entity)
-    .where(and(...conditions) as SQL); // @cast-boundary db-operator
+  const row = await fetchOne(db, entity, where);
 
   if (!row) {
     const entityName = options.entityName ?? String(options.field).replace(/Id$/, "");

package/src/db/bun-provider.ts

@@ -0,0 +1,37 @@
+// Bun.SQL Provider — experimentell.
+// Default: postgres-js. Dieser Provider nur aktiv wenn DB_PROVIDER=bun.
+// Bekannter Bug: Extended-Query-Protocol Caching verursacht
+// PostgresError "bind message has 11 result formats but query has 1 columns"
+// bei sequentiellen Queries mit unterschiedlicher Spaltenzahl innerhalb
+// derselben Connection.
+//
+// Bun.SQL hat kein LISTEN — postgres-js-Peer für event-dispatcher.
+
+import postgres from "postgres";
+import type { DbConnection, DbConnectionOptions } from "./api";
+
+export function createBunConnection(url: string, options: DbConnectionOptions = {}): DbConnection {
+  const bunOpts: { max?: number; idleTimeout?: number; connectionTimeout?: number } = {};
+  if (options.maxConnections !== undefined) bunOpts.max = options.maxConnections;
+  if (options.idleTimeoutSeconds !== undefined) bunOpts.idleTimeout = options.idleTimeoutSeconds;
+  if (options.connectTimeoutSeconds !== undefined)
+    bunOpts.connectionTimeout = options.connectTimeoutSeconds;
+  const db = new Bun.SQL(url, bunOpts);
+
+  // LISTEN peer — 1 connection reicht für NOTIFY-Wakeups
+  const pgOpts: Parameters<typeof postgres>[1] = { max: 1 };
+  if (options.idleTimeoutSeconds !== undefined) pgOpts.idle_timeout = options.idleTimeoutSeconds;
+  if (options.connectTimeoutSeconds !== undefined)
+    pgOpts.connect_timeout = options.connectTimeoutSeconds;
+  const listenClient = postgres(url, pgOpts);
+
+  return {
+    db,
+    client: listenClient,
+    listenClient,
+    close: async () => {
+      await db.end();
+      await listenClient.end();
+    },
+  };
+}

package/src/db/config-seed.ts

@@ -5,7 +5,7 @@ import type { ConfigSeedDef, Registry } from "../engine/types";
 import type { DbConnection } from "./connection";
 import type { EncryptionProvider } from "./encryption";
 import { createEventStoreExecutor } from "./event-store-executor";
-import type { DrizzleTable } from "./table-builder";
+import type { EntityTable } from "./table-builder";
 import { createTenantDb } from "./tenant-db";
 
 // Namespace UUID for deterministic seed aggregate IDs. Same namespace +
@@ -24,10 +24,10 @@ const CONFIG_SEED_NS = "6f1e9d8c-2a5b-4c7d-9e3f-1a2b3c4d5e6f";
  * Idempotent, race-safe via DB-level unique constraints, and visible to
  * multi-stream-projection subscribers as normal configValue.created events.
  */
-export async function seedConfigValues(
+export async function seedConfigValues<E extends EntityDefinition>(
   seeds: readonly ConfigSeedDef[],
-  table: DrizzleTable,
-  entity: EntityDefinition,
+  table: EntityTable<E>,
+  entity: E,
   registry: Registry,
   db: DbConnection,
   encryption?: EncryptionProvider,

package/src/db/connection.ts

@@ -1,67 +1,30 @@
-import { drizzle } from "drizzle-orm/postgres-js";
+// DB-Connection-Types: provider-agnostic via db/api.ts.
+// createConnection delegiert an postgres-provider (default) oder bun-provider (DB_PROVIDER=bun).
 import postgres from "postgres";
 import { readPositiveIntEnv } from "../utils/env-parse";
 
-export type DbConnection = ReturnType<typeof drizzle>;
+export { createConnection, type DbConnectionOptions } from "./api";
 
-// Drizzle's transaction callback receives a tx handle with the same query API
-// as the top-level DbConnection. Extracted via Parameters so we stay in sync
-// with whatever Drizzle defines without hard-coding the internal type name.
-export type DbTx = Parameters<Parameters<DbConnection["transaction"]>[0]>[0];
-
-// Code paths that operate on either a connection or an active transaction
-// (e.g. TenantDb, dispatcher pipeline) accept both.
+// Legacy Types — für Aufrufer die direkt diese Module importieren
+// biome-ignore lint/suspicious/noExplicitAny: Bun.SQL global type
+export type DbConnection = ReturnType<typeof postgres> | any;
+// biome-ignore lint/suspicious/noExplicitAny: postgres-js namespace lookup
+export type DbTx = postgres.TransactionSql<any> | any;
 export type DbRunner = DbConnection | DbTx;
-
-// Dynamic Drizzle tables (buildDrizzleTable with `any` column schema) lose
-// their per-column types at the Drizzle boundary. Query results come back as
-// arbitrary records. `DbRow` marks those typing-loss sites so readers see the
-// limitation without re-spelling `Record<string, unknown>` at every callsite.
-// Use `DbRow` for rows read via dynamic tables; a concrete entity-row type
-// is preferred whenever the table is statically typed.
 export type DbRow = Record<string, unknown>;
-
-// The raw postgres.js client. Exposed alongside the Drizzle wrapper so the
-// event-dispatcher (or other components that need LISTEN / pg-specific
-// features Drizzle doesn't surface) can subscribe without re-opening a
-// connection from the URL.
 export type PgClient = ReturnType<typeof postgres>;
 
-// Connection-pool options — thin wrapper around the postgres.js fields the
-// framework explicitly supports. Omitted keys fall back to postgres.js
-// defaults (max=10, idle_timeout=PGIDLE_TIMEOUT env, connect_timeout=
-// PGCONNECT_TIMEOUT env). See `docs/plans/architecture/scaling.md` for
-// sizing guidance per deployment shape.
-export type DbConnectionOptions = {
-  // Max concurrent connections in the pool. postgres.js defaults to 10 —
-  // fine for a single app process against a small DB. Multi-worker or
-  // high-concurrency API deploys should scale this with `num_workers *
-  // per-request-concurrency` and stay below the DB's own max_connections
-  // (typical managed postgres: 100–400).
-  readonly maxConnections?: number;
-  // Seconds before an idle connection is closed. Null/undefined → keep
-  // connections warm forever (postgres.js default when the env var is
-  // unset). Managed pgBouncer tiers usually want this explicitly set to
-  // something like 30–60 so a single burst doesn't hold connections
-  // indefinitely.
-  readonly idleTimeoutSeconds?: number;
-  // Seconds to wait while establishing a new connection. Fails the query
-  // with a timeout error rather than hanging indefinitely when the DB is
-  // unreachable — critical for `/health/ready` to actually flip to 503
-  // within its 2s probe budget.
-  readonly connectTimeoutSeconds?: number;
-};
+export type PgListenClient = ReturnType<typeof postgres>;
 
+// Legacy: postgres-js only. Neue Aufrufer: createConnection() aus api.ts.
 export function createDbConnection(
   url: string,
-  options: DbConnectionOptions = {},
+  options: import("./api").DbConnectionOptions = {},
 ): {
   db: DbConnection;
   client: PgClient;
   close: () => Promise<void>;
 } {
-  // Only forward fields the caller set — empty object otherwise preserves
-  // postgres.js's env-var-driven defaults (PGIDLE_TIMEOUT / PGCONNECT_TIMEOUT).
   const pgOptions: Parameters<typeof postgres>[1] = {};
   if (options.maxConnections !== undefined) pgOptions.max = options.maxConnections;
   if (options.idleTimeoutSeconds !== undefined) pgOptions.idle_timeout = options.idleTimeoutSeconds;
@@ -70,10 +33,9 @@ export function createDbConnection(
   }
 
   const client = postgres(url, pgOptions);
-  const db = drizzle(client);
 
   return {
-    db,
+    db: client,
     client,
     close: async () => {
       await client.end();
@@ -81,15 +43,10 @@ export function createDbConnection(
   };
 }
 
-// Parse the supported env vars into a DbConnectionOptions object. Useful
-// for a main.ts that wants to read DATABASE_POOL_MAX / DATABASE_POOL_
-// IDLE_TIMEOUT / DATABASE_POOL_CONNECT_TIMEOUT without re-implementing
-// the number-coercion + validation. Unrecognised / non-numeric values
-// throw — misconfig surfaces at boot, not mid-request.
 export function dbConnectionOptionsFromEnv(
   env: Readonly<Record<string, string | undefined>> = process.env,
-): DbConnectionOptions {
-  const opts: DbConnectionOptions & {
+): import("./api").DbConnectionOptions {
+  const opts: import("./api").DbConnectionOptions & {
     maxConnections?: number;
     idleTimeoutSeconds?: number;
     connectTimeoutSeconds?: number;

package/src/db/cursor.ts

@@ -1,6 +1,4 @@
-import { and, asc, desc, eq, gt, inArray, type SQL, sql } from "drizzle-orm";
 import type { EntityId, TenantId } from "../engine/types/identifiers";
-import type { SelectQuery as PgSelect } from "./dialect";
 
 export type CursorQueryOptions = {
   tenantId: TenantId;
@@ -9,24 +7,20 @@ export type CursorQueryOptions = {
   filterIds?: readonly EntityId[];
   sort?: string;
   sortDirection?: "asc" | "desc";
-  extraWhere?: SQL;
 };
 
 export type CursorResult<T> = {
   rows: T[];
   nextCursor: string | null;
   /** Optional total row count — nur present wenn der Caller `totalCount: true`
-   *  in der Query setzt. Pager-UI braucht's für "Page X of Y"; Infinite-
-   *  Scroll und Default-Lists lassen den extra COUNT(*) weg. */
+   *  in der Query setzt. */
   total?: number;
 };
 
-// String-basiert damit sowohl UUIDs (Default seit Sprint F) als auch
-// Integer-Auto-Increment-IDs (Legacy/Spezialfälle) durch denselben
-// Cursor-Pfad laufen. Stable-Sort-Voraussetzung: die id-Spalte muss
-// lexikografisch monoton zur Insertion-Order sein. UUIDv7 erfüllt das
-// (time-ordered Prefix); UUIDv4 nicht — wer den nutzt, kriegt
-// inkorrekte cursor-Reihenfolge, das ist erwartet (Default ist v7).
+// String-basiert damit UUIDs (Default seit Sprint F) + Integer-Auto-Increment
+// durch denselben Cursor-Pfad laufen. UUIDv7 erfüllt die lex-Monotonie
+// (time-ordered Prefix); UUIDv4 nicht — wer den nutzt, kriegt inkorrekte
+// cursor-Reihenfolge (Default ist v7).
 export function encodeCursor(id: string | number): string {
   return Buffer.from(String(id)).toString("base64url");
 }
@@ -36,48 +30,3 @@ export function decodeCursor(cursor: string): string {
   if (decoded === "") throw new Error(`Invalid cursor: ${cursor}`);
   return decoded;
 }
-
-export function applyCursorQuery<T extends PgSelect>(
-  query: T,
-  // biome-ignore lint/suspicious/noExplicitAny: Drizzle dynamic tables lose column types
-  table: any,
-  options: CursorQueryOptions,
-): T {
-  const conditions: SQL[] = [eq(table.tenantId, options.tenantId)];
-
-  if (table.isDeleted) {
-    conditions.push(eq(table.isDeleted, false));
-  }
-
-  if (options.cursor) {
-    conditions.push(gt(table.id, decodeCursor(options.cursor)));
-  }
-
-  if (options.filterIds !== undefined) {
-    if (options.filterIds.length === 0) {
-      // No matching IDs — return empty result via raw `false`. Statisch
-      // false ist type-agnostisch (int-PK / uuid-PK egal); ein eq(id, "")
-      // oder eq(id, -1) würde je nach Spalten-Type einen Cast-Error
-      // werfen.
-      conditions.push(sql`false`);
-    } else {
-      conditions.push(inArray(table.id, options.filterIds as readonly string[])); // @cast-boundary db-operator
-    }
-  }
-
-  if (options.extraWhere) {
-    conditions.push(options.extraWhere);
-  }
-
-  const limit = options.limit ?? 50;
-
-  let result = query.where(and(...conditions)).limit(limit);
-
-  if (options.sort && table[options.sort]) {
-    const column = table[options.sort];
-    result =
-      options.sortDirection === "desc" ? result.orderBy(desc(column)) : result.orderBy(asc(column));
-  }
-
-  return result as T; // @cast-boundary engine-bridge
-}