@cosmicdrift/kumiko-framework 0.387.0 → 0.389.0

package/dist/db/connection.js

@@ -1,7 +1,6 @@
-import postgres from "postgres";
 import { readPositiveIntEnv } from "../utils/env-parse.js";
 // A DB outage can leave an in-flight query referenced on a dead connection,
-// so a plain end() (no timeout = wait for queries to finish) hangs forever —
+// so a plain close() (no timeout = wait for queries to finish) hangs forever —
 // close() must always bound how long shutdown waits.
 export const DEFAULT_DB_CLOSE_TIMEOUT_SECONDS = 5;
 // Keyed by the pool so withoutStatementTimeout can open a sibling with identical connect options.
@@ -11,20 +10,28 @@ export function openUnboundedSiblingPool(db) {
         return undefined;
     return unboundedSiblingFactories.get(db)?.();
 }
+// Bun.SQL treats `true` and a TLS object without rejectUnauthorized as sslmode=require, which
+// skips certificate checks; postgres-js verified in both cases, so keep that unless turned off.
+function verifiedTls(ssl) {
+    if (ssl === true)
+        return "verify-full";
+    if (typeof ssl === "object" && !(ssl instanceof Blob) && ssl.rejectUnauthorized === undefined) {
+        return { ...ssl, rejectUnauthorized: true };
+    }
+    return ssl;
+}
 export function createDbConnection({ url, ...options }) {
-    const pgOptions = {};
+    const sqlOptions = {};
     if (options.maxConnections !== undefined)
-        pgOptions.max = options.maxConnections;
+        sqlOptions.max = options.maxConnections;
     if (options.idleTimeoutSeconds !== undefined) {
-        pgOptions.idle_timeout = options.idleTimeoutSeconds;
+        sqlOptions.idleTimeout = options.idleTimeoutSeconds;
     }
     if (options.connectTimeoutSeconds !== undefined) {
-        pgOptions.connect_timeout = options.connectTimeoutSeconds;
+        sqlOptions.connectionTimeout = options.connectTimeoutSeconds;
     }
     if (options.ssl !== undefined)
-        pgOptions.ssl = options.ssl;
-    if (options.onNotice !== undefined)
-        pgOptions.onnotice = options.onNotice;
+        sqlOptions.tls = verifiedTls(options.ssl);
     const serverParameters = {};
     if (options.statementTimeoutMs !== undefined) {
         serverParameters["statement_timeout"] = options.statementTimeoutMs;
@@ -36,48 +43,50 @@ export function createDbConnection({ url, ...options }) {
     if (options.lockTimeoutMs !== undefined)
         serverParameters["lock_timeout"] = options.lockTimeoutMs;
     if (Object.keys(serverParameters).length > 0)
-        pgOptions.connection = serverParameters;
-    const client = postgres(url, pgOptions);
+        sqlOptions.connection = serverParameters;
+    // Bun.SQL opens all `max` connections on the first query, so a pool always costs `max` backends.
+    const client = new Bun.SQL(url, sqlOptions);
     // A run that never settles (a caller gave up on it via its own timeout) never reaches the
     // sibling's own close; close() ends it so shutdown and DROP DATABASE are not blocked by it.
     const openSiblings = new Set();
     unboundedSiblingFactories.set(client, () => {
         // Two connections are enough for lock-in-tx plus DDL; the cap keeps parallel rebuilds from exhausting max_connections.
-        const sibling = postgres(url, {
-            ...pgOptions,
+        const sibling = new Bun.SQL(url, {
+            ...sqlOptions,
             max: 4,
-            connection: { ...pgOptions.connection, statement_timeout: 0 },
+            connection: { ...sqlOptions.connection, statement_timeout: 0 },
         });
         openSiblings.add(sibling);
         return {
             client: sibling,
             close: async (timeoutSeconds) => {
                 openSiblings.delete(sibling);
-                await sibling.end({ timeout: timeoutSeconds });
+                await sibling.close({ timeout: timeoutSeconds });
             },
         };
     });
     return {
         db: client,
         client,
+        listenClient: client,
         close: async () => {
             const timeout = options.closeTimeoutSeconds ?? DEFAULT_DB_CLOSE_TIMEOUT_SECONDS;
             unboundedSiblingFactories.delete(client);
             const pools = [client, ...openSiblings];
             openSiblings.clear();
-            const results = await Promise.allSettled(pools.map((pool) => pool.end({ timeout })));
+            const results = await Promise.allSettled(pools.map((pool) => pool.close({ timeout })));
             const failure = results.find((result) => result.status === "rejected");
             if (failure !== undefined)
                 throw failure.reason;
         },
     };
 }
-// DB_PROVIDER=bun selected the removed Bun.SQL driver; ignoring it would boot
-// postgres-js under a config that still claims Bun.SQL.
+// DB_PROVIDER once selected between drivers; a config that still sets it is stale,
+// so fail loudly instead of silently ignoring it.
 function assertNoRemovedDbProvider(env) {
     const provider = env["DB_PROVIDER"];
-    if (provider !== undefined && provider !== "" && provider !== "postgres") {
-        throw new Error(`DB_PROVIDER="${provider}" is no longer supported: postgres-js is the only driver. Remove DB_PROVIDER from the environment.`);
+    if (provider !== undefined && provider !== "") {
+        throw new Error(`DB_PROVIDER="${provider}" is no longer supported: Bun.SQL is the only driver. Remove DB_PROVIDER from the environment.`);
     }
 }
 export function dbConnectionOptionsFromEnv(env = process.env) {

package/dist/db/dialect.js

@@ -251,7 +251,7 @@ export function primaryKey(opts) {
 // Limits: no nested SqlExpression composition (drizzle's recursive
 // `sql\`${other}\``) — schema-files use single-level expressions only.
 // Unforgeable via JSON — a client-supplied jsonb value can fake `kind:
-// "sql-expr"` but can never carry a Symbol, so isSqlExpression() (db/query.ts)
+// "sql-expr"` but can never carry a Symbol, so isSqlExpression() (db/driver-value-preparation.ts)
 // can't be tricked into treating request data as a raw SQL literal. The same
 // brand gate is enforced here in the schema DSL (sql`...` interpolation +
 // literalDefault) and in entity-table-meta's sqlExpressionText — a duck-typed

package/dist/db/distinct-on.d.ts

@@ -1,5 +1,5 @@
 import type { OrderByClause } from "@cosmicdrift/kumiko-types/where-clause-types";
-import type { TableInfo } from "./query.ts";
+import type { TableInfo } from "./table-info.ts";
 type DistinctOnClause = {
     /** Physical column names, unquoted. */
     readonly columns: readonly string[];

package/dist/db/driver-row-coercion.d.ts

@@ -0,0 +1,2 @@
+import type { TableInfo } from "./table-info.ts";
+export declare function coerceDriverRow(row: Record<string, unknown>, info: TableInfo): Record<string, unknown>;

package/dist/db/driver-row-coercion.js

@@ -0,0 +1,186 @@
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+import { createFallbackLogger } from "../logging/index.js";
+import { parseJsonSafe } from "../utils/safe-json.js";
+import { isTemporalInstant, isTemporalPlainDate } from "./temporal-value-guards.js";
+// --- Value coercion at the driver boundary ------------------------------
+//
+// The driver returns timestamptz as JS Date (or ISO string depending on
+// driver config). Framework contract says timestamptz surfaces as
+// Temporal.Instant — without coercion every read hands callers a Date and
+// downstream code that does .epochMilliseconds / .add(...) crashes.
+//
+// Symmetric on write: Temporal.Instant doesn't bind directly as a driver
+// param — convert to ISO string when the column pgType is timestamptz.
+// Postgres bigint → JS: safe integers become `number` (matches createBigIntField /
+// drizzle mode:"number"); values outside ±2^53 stay `bigint` (money cents, raw
+// unmanaged columns). Uses BigInt equality check so 9007199254740993n never
+// silently rounds to a safe integer.
+function coerceBigIntFromDriver(value) {
+    let bi;
+    if (typeof value === "string") {
+        try {
+            bi = BigInt(value);
+        }
+        catch {
+            return value;
+        }
+    }
+    else {
+        bi = value;
+    }
+    const min = BigInt(Number.MIN_SAFE_INTEGER);
+    const max = BigInt(Number.MAX_SAFE_INTEGER);
+    if (bi >= min && bi <= max) {
+        const n = Number(bi);
+        if (BigInt(n) === bi)
+            return n;
+    }
+    return bi;
+}
+function instantFromDriver(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (isTemporalInstant(value))
+        return value;
+    // Number coercion via +date — equivalent to .getTime() without a Date-API
+    // method (guard-no-date-api). Date → epoch milliseconds, then to Temporal.Instant.
+    if (value instanceof Date)
+        return Temporal.Instant.fromEpochMilliseconds(+value);
+    if (typeof value === "string") {
+        try {
+            return Temporal.Instant.from(value);
+        }
+        catch {
+            return null;
+        }
+    }
+    if (typeof value === "number")
+        return Temporal.Instant.fromEpochMilliseconds(value);
+    return null;
+}
+// Verified empirically: a `date`
+// column comes back as a native JS Date, but ALWAYS anchored at UTC
+// midnight regardless of process TZ — epochMilliseconds is stable across
+// zones, only the local wall-clock read of that Date would drift the day
+// (e.g. America/Los_Angeles reads back the 14th for a stored 15th). Routing
+// through Instant→ZonedDateTimeISO("UTC")→PlainDate reads the calendar day
+// back deterministically without ever touching a local Date getter — the
+// same +value idiom instantFromDriver uses (guard-no-date-api: no
+// `.getTime()`), just anchored to a fixed zone instead of process-local.
+// A real `date` column always arrives as a UTC-midnight Date. Anything else means the column is
+// still timestamptz (declared `date` before its ALTER ran); the UTC anchor then silently shifts
+// the day, so say so once per column instead of returning the wrong day quietly.
+const warnedNonMidnightDateColumns = new Set();
+const MS_PER_DAY = 86_400_000;
+const dateColumnDriftLog = createFallbackLogger("bun-sql");
+function warnIfNotDateColumn(epochMs, column) {
+    // skip: midnight value is a correct date column, and an already-warned column is deduped
+    if (epochMs % MS_PER_DAY === 0 || warnedNonMidnightDateColumns.has(column))
+        return;
+    warnedNonMidnightDateColumns.add(column);
+    dateColumnDriftLog.warn(`column "${column}" is declared as date but returned a non-midnight timestamp; it is probably still timestamptz. Run the ALTER ... TYPE date migration, otherwise days can shift.`);
+}
+function plainDateFromDriver(value, column) {
+    if (value === null || value === undefined)
+        return null;
+    if (isTemporalPlainDate(value))
+        return value;
+    if (typeof value === "string") {
+        const isoDay = /^\d{4}-\d{2}-\d{2}/.exec(value)?.[0];
+        if (isoDay === undefined)
+            return null;
+        try {
+            return Temporal.PlainDate.from(isoDay);
+        }
+        catch {
+            return null;
+        }
+    }
+    if (value instanceof Date) {
+        warnIfNotDateColumn(+value, column);
+        return Temporal.Instant.fromEpochMilliseconds(+value).toZonedDateTimeISO("UTC").toPlainDate();
+    }
+    return null;
+}
+function coerceTimestamptz(value) {
+    const instant = instantFromDriver(value);
+    return instant !== null ? instant : value;
+}
+function coerceDate(value, column) {
+    const day = plainDateFromDriver(value, column);
+    return day !== null ? day : value;
+}
+function coerceJsonb(value) {
+    return typeof value === "string" ? parseJsonSafe(value, value) : value;
+}
+function coerceBigIntColumn(value, column, info) {
+    if (typeof value !== "string" && typeof value !== "bigint")
+        return value;
+    if (info.bigintJsModeOf(column) === "number")
+        return coerceBigIntFromDriver(value);
+    if (typeof value === "string") {
+        try {
+            return BigInt(value);
+        }
+        catch {
+            // leave as string on parse error
+            return value;
+        }
+    }
+    return value;
+}
+function numberUnlessNaN(value) {
+    if (typeof value !== "string" && typeof value !== "bigint")
+        return value;
+    const n = Number(value);
+    return Number.isNaN(n) ? value : n;
+}
+// Keyed by the driver's pgType string, not PgType: legacy tables report int4/smallint/int2.
+const DRIVER_VALUE_COERCERS = new Map([
+    ["timestamptz", coerceTimestamptz],
+    ["timestamptz(3)", coerceTimestamptz],
+    ["date", coerceDate],
+    ["jsonb", coerceJsonb],
+    ["bigint", coerceBigIntColumn],
+    ["bigserial", coerceBigIntColumn],
+    // Drivers may return int4 as bigint or numeric string.
+    // Drizzle coerced to number for numberField columns — match that.
+    ["integer", numberUnlessNaN],
+    ["int4", numberUnlessNaN],
+    ["smallint", numberUnlessNaN],
+    ["int2", numberUnlessNaN],
+]);
+// pg returns numeric(p,s) as a string to preserve precision; the
+// decimal-field contract surfaces it as JS number (safe ≤ 2^53). A
+// non-numeric string would be DB corruption — leave it untouched so it
+// surfaces loud downstream rather than becoming a silent NaN.
+function driverValueCoercerFor(pgType) {
+    if (pgType === undefined)
+        return undefined;
+    const coercer = DRIVER_VALUE_COERCERS.get(pgType);
+    if (coercer)
+        return coercer;
+    return pgType.startsWith("numeric") ? numberUnlessNaN : undefined;
+}
+export function coerceDriverRow(row, info) {
+    const out = {};
+    let changed = false;
+    for (const key of Object.keys(row)) {
+        // Blind-index columns are pure lookup artifacts — the
+        // deterministic HMAC must never leak into caller/API responses.
+        if ((key.endsWith("_bidx") || key.endsWith("Bidx")) && info.hasColumn(key)) {
+            changed = true;
+            continue;
+        }
+        const value = row[key];
+        const coercer = driverValueCoercerFor(info.pgTypeOf(key));
+        const coerced = coercer ? coercer(value, key, info) : value;
+        const fieldName = info.fieldOf(key);
+        if (fieldName !== key)
+            changed = true;
+        if (coerced !== value)
+            changed = true;
+        out[fieldName] = coerced;
+    }
+    return changed ? out : row;
+}

package/dist/db/driver-value-preparation.d.ts

@@ -0,0 +1,16 @@
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+export type PreparedValue = {
+    readonly kind: "param";
+    readonly sql: string;
+    readonly bound: unknown;
+} | {
+    readonly kind: "literal";
+    readonly literal: string;
+};
+export declare function isSqlExpression(v: unknown): v is {
+    kind: "sql-expr";
+    text: string;
+};
+export declare function prepareJsonbValue(value: unknown): PreparedValue | undefined;
+export declare function instantToTimestamptzParam(instant: Temporal.Instant): string;
+export declare function prepareValue(value: unknown, pgType: string | undefined): PreparedValue;

package/dist/db/driver-value-preparation.js

@@ -0,0 +1,101 @@
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+import { isPiiCiphertext } from "../crypto/pii-ciphertext-format.js";
+import { SQL_EXPR_BRAND } from "./dialect.js";
+import { isTemporalInstant, isTemporalPlainDate, isTemporalPlainDateTimeLike, } from "./temporal-value-guards.js";
+// Checks the brand Symbol, not the `kind` string — a client-supplied jsonb
+// value can fake `kind: "sql-expr"` over JSON but can never carry a Symbol,
+// so request data can't be smuggled in as a raw SQL literal.
+export function isSqlExpression(v) {
+    return typeof v === "object" && v !== null && SQL_EXPR_BRAND in v;
+}
+// A `date` column takes a plain "yyyy-mm-dd" string (or PlainDate.toString())
+// as-is — no Instant detour. Postgres parses a DATE literal without ever
+// consulting the session timezone, so this is TZ-independent by construction
+// (verified empirically — see plainDateFromDriver above for the read side).
+// Compat cushion: code (this field used to be an Instant) may still
+// hand a Temporal.Instant into a where-filter or write on a `date` column —
+// same UTC anchor as plainDateFromDriver's read side, so a filter built with
+// `Temporal.Now.instant()` keeps working instead of binding a raw Instant the
+// driver can't serialize.
+function prepareDateValue(value) {
+    if (isTemporalPlainDate(value)) {
+        return { kind: "param", sql: "", bound: value.toString() };
+    }
+    if (isTemporalPlainDateTimeLike(value)) {
+        return { kind: "param", sql: "", bound: value.toPlainDate().toString() };
+    }
+    if (isTemporalInstant(value)) {
+        const day = value.toZonedDateTimeISO("UTC").toPlainDate();
+        return { kind: "param", sql: "", bound: day.toString() };
+    }
+    return undefined;
+}
+// structured values bind directly with an ::jsonb cast; JSON.stringify first
+// would produce a JSON-string scalar instead of the structured value.
+export function prepareJsonbValue(value) {
+    // Bun.SQL types JS numbers as int4/float8 params, which Postgres refuses for a jsonb column.
+    // Non-finite numbers fall through so Postgres rejects them instead of storing JSON null.
+    if (typeof value === "boolean" || (typeof value === "number" && Number.isFinite(value))) {
+        return { kind: "param", sql: "::text::jsonb", bound: JSON.stringify(value) };
+    }
+    if (typeof value !== "object" || isTemporalInstant(value)) {
+        return undefined;
+    }
+    if (!Array.isArray(value)) {
+        return { kind: "param", sql: "::jsonb", bound: value };
+    }
+    // All-boolean arrays are inferred as boolean[] by the driver; route via text::jsonb.
+    if (value.length > 0 && value.every((entry) => typeof entry === "boolean")) {
+        return { kind: "param", sql: "::text::jsonb", bound: JSON.stringify(value) };
+    }
+    return { kind: "param", sql: "::jsonb", bound: value };
+}
+const INTEGER_PG_TYPES = new Set([
+    "integer",
+    "int4",
+    "smallint",
+    "int2",
+    "bigint",
+    "int8",
+    "serial",
+    "bigserial",
+]);
+// Postgres rounds sub-millisecond params into timestamptz(3); truncating to ms here keeps the
+// stored instant identical across drivers and equal to what a Date param would store.
+export function instantToTimestamptzParam(instant) {
+    return Temporal.Instant.fromEpochMilliseconds(instant.epochMilliseconds).toString();
+}
+function prepareDriverNeutralScalar(value, pgType) {
+    if ((pgType === "timestamptz" || pgType === "timestamptz(3)") && isTemporalInstant(value)) {
+        return { kind: "param", sql: "", bound: instantToTimestamptzParam(value) };
+    }
+    // Sent as text, so Postgres rejects 3.5 for an integer column instead of rounding it.
+    if (typeof value === "number" && pgType !== undefined && INTEGER_PG_TYPES.has(pgType)) {
+        return { kind: "param", sql: "", bound: String(value) };
+    }
+    return undefined;
+}
+export function prepareValue(value, pgType) {
+    if (isSqlExpression(value)) {
+        return { kind: "literal", literal: value.text };
+    }
+    // A PII-encrypted jsonb field is a JSON string scalar; a raw string bound to
+    // ::jsonb would be parsed as JSON text (or double-encoded).
+    if (pgType === "jsonb" && isPiiCiphertext(value)) {
+        return { kind: "param", sql: "::text::jsonb", bound: JSON.stringify(value) };
+    }
+    if (pgType === "jsonb" && value !== null) {
+        const prepared = prepareJsonbValue(value);
+        if (prepared)
+            return prepared;
+    }
+    const scalar = prepareDriverNeutralScalar(value, pgType);
+    if (scalar)
+        return scalar;
+    if (pgType === "date") {
+        const prepared = prepareDateValue(value);
+        if (prepared)
+            return prepared;
+    }
+    return { kind: "param", sql: "", bound: value };
+}

package/dist/db/entity-field-encryption.d.ts

@@ -3,6 +3,7 @@ import { type Logger } from "../logging/index.ts";
 import type { EnvelopeCipher } from "../secrets/envelope-cipher.ts";
 export declare function collectEncryptedFieldNames(entity: EntityDefinition): ReadonlySet<string>;
 export declare function isSensitiveLabelField(entity: EntityDefinition, field: string): boolean;
+export declare function holdsCiphertextOrSecret(entity: EntityDefinition, field: string): boolean;
 export declare function isListFilterAllowed(entity: EntityDefinition, field: string, filter: {
     readonly op: string;
     readonly value: unknown;

package/dist/db/entity-field-encryption.js

@@ -24,7 +24,7 @@ export function isSensitiveLabelField(entity, field) {
 }
 // A `sensitive` (find: "secret") field is never comparable either, even while its value is still
 // legacy plaintext.
-function holdsCiphertextOrSecret(entity, field) {
+export function holdsCiphertextOrSecret(entity, field) {
     const def = entity.fields[field];
     if (def === undefined)
         return false;