@cosmicdrift/kumiko-framework 0.328.0 → 0.328.1

package/dist/db/connection.js

@@ -0,0 +1,35 @@
+import postgres from "postgres";
+import { readPositiveIntEnv } from "../utils/env-parse.js";
+import { DEFAULT_DB_CLOSE_TIMEOUT_SECONDS } from "./api.js";
+export { createConnection } from "./api.js";
+// Legacy: postgres-js only. Neue Aufrufer: createConnection() aus api.ts.
+// guard:dup-ok — andere Layer als createPgConnection (gibt DbConnection zurück, nicht postgres-Instanz)
+export function createDbConnection(url, options = {}) {
+    const pgOptions = {};
+    if (options.maxConnections !== undefined)
+        pgOptions.max = options.maxConnections;
+    if (options.idleTimeoutSeconds !== undefined)
+        pgOptions.idle_timeout = options.idleTimeoutSeconds;
+    if (options.connectTimeoutSeconds !== undefined) {
+        pgOptions.connect_timeout = options.connectTimeoutSeconds;
+    }
+    const client = postgres(url, pgOptions);
+    return {
+        db: client,
+        client,
+        close: () => client.end({ timeout: options.closeTimeoutSeconds ?? DEFAULT_DB_CLOSE_TIMEOUT_SECONDS }),
+    };
+}
+export function dbConnectionOptionsFromEnv(env = process.env) {
+    const opts = {};
+    const max = readPositiveIntEnv(env, "DATABASE_POOL_MAX");
+    const idle = readPositiveIntEnv(env, "DATABASE_POOL_IDLE_TIMEOUT");
+    const connect = readPositiveIntEnv(env, "DATABASE_POOL_CONNECT_TIMEOUT");
+    if (max !== undefined)
+        opts.maxConnections = max;
+    if (idle !== undefined)
+        opts.idleTimeoutSeconds = idle;
+    if (connect !== undefined)
+        opts.connectTimeoutSeconds = connect;
+    return opts;
+}

package/dist/db/cursor.d.ts

@@ -0,0 +1,9 @@
+export type { CursorQueryOptions, CursorResult } from "@cosmicdrift/kumiko-types/cursor-types";
+export declare function encodeCursor(id: string | number): string;
+export declare function decodeCursor(cursor: string): string;
+export type DecodedKeysetCursor = {
+    readonly id: string;
+    readonly sortValue: string | null | undefined;
+};
+export declare function encodeKeysetCursor(sortValue: string | null, id: string): string;
+export declare function decodeKeysetCursor(cursor: string): DecodedKeysetCursor;

package/dist/db/cursor.js

@@ -0,0 +1,39 @@
+// 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) {
+    return Buffer.from(String(id)).toString("base64url");
+}
+export function decodeCursor(cursor) {
+    const decoded = Buffer.from(cursor, "base64url").toString();
+    if (decoded === "")
+        throw new Error(`Invalid cursor: ${cursor}`);
+    return decoded;
+}
+export function encodeKeysetCursor(sortValue, id) {
+    return encodeCursor(JSON.stringify({ v: sortValue, i: id }));
+}
+export function decodeKeysetCursor(cursor) {
+    const decoded = decodeCursor(cursor);
+    return parseKeysetPayload(decoded) ?? { id: decoded, sortValue: undefined };
+}
+function parseKeysetPayload(decoded) {
+    if (!decoded.startsWith("{"))
+        return null;
+    let raw;
+    try {
+        raw = JSON.parse(decoded);
+    }
+    catch {
+        return null;
+    }
+    if (typeof raw !== "object" || raw === null)
+        return null;
+    const { v, i } = raw;
+    if (typeof i !== "string" || i === "")
+        return null;
+    if (v !== null && typeof v !== "string")
+        return null;
+    return { id: i, sortValue: v };
+}

package/dist/db/dialect.d.ts

@@ -0,0 +1,100 @@
+import { type ColumnHandle, type SchemaTable } from "@cosmicdrift/kumiko-types/schema-table-types";
+import { Temporal } from "temporal-polyfill";
+import type { PgType } from "./entity-table-meta.js";
+export type { ColumnHandle, SchemaTable } from "@cosmicdrift/kumiko-types/schema-table-types";
+export type TableColumns<_T = any> = SchemaTable;
+export type SelectQuery = any;
+export declare function pgTypeToSqlType(pgType: PgType): string;
+type ColumnFinal = {
+    readonly sqlName: string;
+    readonly pgType: PgType;
+    readonly notNull: boolean;
+    readonly primaryKey: boolean;
+    readonly unique: boolean;
+    readonly identity: boolean;
+    readonly defaultSql?: string;
+    readonly bigintJsMode?: "number" | "bigint";
+};
+export type ColumnBuilder<TValue = unknown> = {
+    readonly __column: true;
+    readonly finalise: () => ColumnFinal;
+    notNull(): ColumnBuilder<TValue>;
+    primaryKey(): ColumnBuilder<TValue>;
+    default(value: TValue | SqlExpression | readonly unknown[] | number | string | boolean | null): ColumnBuilder<TValue>;
+    defaultRandom(): ColumnBuilder<TValue>;
+    defaultNow(): ColumnBuilder<TValue>;
+    generatedAlwaysAsIdentity(): ColumnBuilder<TValue>;
+    unique(name?: string): ColumnBuilder<TValue>;
+    $type<T>(): ColumnBuilder<T>;
+    $onUpdate(fn: () => unknown): ColumnBuilder<TValue>;
+};
+export declare function uuid(name: string): ColumnBuilder<string>;
+export declare function text(name: string): ColumnBuilder<string>;
+export declare function boolean(name: string): ColumnBuilder<boolean>;
+export declare function integer(name: string): ColumnBuilder<number>;
+export declare function doublePrecision(name: string): ColumnBuilder<number>;
+export declare function serial(name: string): ColumnBuilder<number>;
+export declare function bigint(name: string, opts?: {
+    mode?: "bigint" | "number";
+}): ColumnBuilder<bigint>;
+export declare function bigserial(name: string, _opts?: {
+    mode?: "bigint" | "number";
+}): ColumnBuilder<bigint>;
+export declare function jsonb(name: string): ColumnBuilder<Record<string, unknown>>;
+export declare function timestamp(name: string, _opts?: {
+    withTimezone?: boolean;
+    mode?: "string" | "date";
+}): ColumnBuilder<Temporal.Instant | string>;
+export declare function numeric(name: string, _opts?: {
+    precision?: number;
+    scale?: number;
+}): ColumnBuilder<string>;
+export declare function instant(name: string, opts?: {
+    precision?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+}): ColumnBuilder<Temporal.Instant>;
+export declare function plainDate(name: string): ColumnBuilder<Temporal.PlainDate>;
+export declare const decimalColumn: (name: string, precision: number, scale: number) => ColumnBuilder<number>;
+export declare const moneyAmount: (name: string) => ColumnBuilder<number>;
+export type IndexBuilder = {
+    readonly __index: true;
+    on(...cols: ColumnHandle[]): IndexBuilderWithCols;
+};
+export type IndexBuilderWithCols = {
+    readonly __index: true;
+    readonly name: string;
+    readonly unique: boolean;
+    readonly columns: readonly string[];
+    where(expr: SqlExpression): IndexBuilderWithCols;
+    readonly whereSql?: string;
+};
+export declare function index(name: string): IndexBuilder;
+export declare function uniqueIndex(name: string): IndexBuilder;
+export type PrimaryKeyDescriptor = {
+    readonly __pk: true;
+    readonly columns: readonly string[];
+    readonly name?: string;
+};
+export declare function primaryKey(opts: {
+    columns: readonly ColumnHandle[];
+    name?: string;
+}): PrimaryKeyDescriptor;
+export declare const SQL_EXPR_BRAND: unique symbol;
+export type SqlExpression = {
+    readonly kind: "sql-expr";
+    readonly text: string;
+    readonly params: readonly unknown[];
+    readonly [SQL_EXPR_BRAND]: true;
+};
+export declare function sql(strings: TemplateStringsArray, ...values: readonly unknown[]): SqlExpression;
+export declare namespace sql {
+    var raw: (text: string) => SqlExpression;
+}
+export type ColumnMap = Record<string, ColumnBuilder<unknown>>;
+type IndexOrPk = IndexBuilderWithCols | PrimaryKeyDescriptor;
+export declare function table<TCols extends ColumnMap>(tableName: string, cols: TCols, optsFn?: (t: {
+    [K in keyof TCols]: ColumnHandle;
+}) => Record<string, IndexOrPk> | ReadonlyArray<IndexOrPk>): SchemaTable;
+/** Reads the `kumiko:schema:Name` symbol from a table object.
+ *  Throws with `context` in the message so callers don't have to duplicate the guard. */
+export declare function extractTableName(table: unknown, context?: string): string;
+export declare function instantToDriver(value: Temporal.Instant | string): string;

package/dist/db/dialect.js

@@ -0,0 +1,386 @@
+// Native dialect — replaces drizzle-orm/pg-core re-exports.
+//
+// Produces table objects that simultaneously expose:
+//   1. EntityTableMeta shape (source/columns/indexes) for bun-db's
+//      extractTableInfo + the migrate-runner's renderTableDdl
+//   2. drizzle-compatible Symbol metadata so callers that introspect
+//      Symbol.for("kumiko:schema:Name") / Symbol.for("kumiko:schema:Columns") keep
+//      working (no caller updates needed)
+//   3. Top-level column-handle properties (table.id, table.tenantId, ...)
+//      so legacy code that does `table[field].name` still resolves to the
+//      snake_case SQL column name.
+//
+// The framework no longer imports drizzle-orm at runtime — schema-files
+// use only this module.
+//
+// Static import, not the ambient global: Bun doesn't expose Temporal on
+// globalThis, so instantToDriver crashed on timestamptz writes (#1480).
+import { KUMIKO_COLUMNS_SYMBOL, KUMIKO_META_SYMBOL, KUMIKO_NAME_SYMBOL, } from "@cosmicdrift/kumiko-types/schema-table-types";
+import { Temporal } from "temporal-polyfill";
+function isNumericPgType(t) {
+    return t.startsWith("numeric(");
+}
+export function pgTypeToSqlType(pgType) {
+    // numeric(p,s) carries its precision/scale in the type string — already
+    // valid SQL. The guard narrows it out so the switch below stays exhaustive
+    // over the fixed members (a forgotten member still fails the type-check).
+    if (isNumericPgType(pgType))
+        return pgType;
+    switch (pgType) {
+        case "uuid":
+            return "uuid";
+        case "text":
+            return "text";
+        case "boolean":
+            return "boolean";
+        case "integer":
+            return "integer";
+        case "double precision":
+            return "double precision";
+        case "bigint":
+            return "bigint";
+        case "serial":
+            return "serial";
+        case "bigserial":
+            return "bigserial";
+        case "jsonb":
+            return "jsonb";
+        case "timestamptz":
+            return "timestamp with time zone";
+        case "timestamptz(3)":
+            return "timestamp(3) with time zone";
+        case "date":
+            return "date";
+    }
+}
+function _toSnakeCase(name) {
+    return name.replace(/[A-Z]/g, (m) => `_${m.toLowerCase()}`).replace(/^_/, "");
+}
+function buildColumn(sqlName, pgType, opts) {
+    let notNull = false;
+    let primaryKey = false;
+    let unique = false;
+    let identity = false;
+    let defaultSql;
+    function literalDefault(value) {
+        if (value === undefined)
+            return null;
+        if (value === null)
+            return "NULL";
+        if (typeof value === "string")
+            return `'${value.replace(/'/g, "''")}'`;
+        if (typeof value === "number")
+            return String(value);
+        if (typeof value === "boolean")
+            return value ? "true" : "false";
+        if (typeof value === "bigint")
+            return value.toString();
+        if (value && typeof value === "object" && SQL_EXPR_BRAND in value) {
+            return value.text;
+        }
+        if (typeof value === "function")
+            return null; // function-defaults stay JS-side
+        // Object/array → jsonb literal
+        const serialised = JSON.stringify(value);
+        if (serialised === undefined)
+            return null;
+        return `'${serialised.replace(/'/g, "''")}'::jsonb`;
+    }
+    const builder = {
+        __column: true,
+        finalise() {
+            return {
+                sqlName,
+                pgType,
+                notNull,
+                primaryKey,
+                unique,
+                identity,
+                ...(defaultSql !== undefined && { defaultSql }),
+                ...(opts?.bigintJsMode !== undefined && { bigintJsMode: opts.bigintJsMode }),
+            };
+        },
+        notNull() {
+            notNull = true;
+            return builder;
+        },
+        primaryKey() {
+            primaryKey = true;
+            notNull = true;
+            return builder;
+        },
+        default(value) {
+            const rendered = literalDefault(value);
+            defaultSql = rendered === null ? undefined : rendered;
+            return builder;
+        },
+        defaultRandom() {
+            defaultSql = "gen_random_uuid()";
+            return builder;
+        },
+        defaultNow() {
+            defaultSql = "now()";
+            return builder;
+        },
+        generatedAlwaysAsIdentity() {
+            identity = true;
+            defaultSql = undefined;
+            return builder;
+        },
+        unique(_name) {
+            unique = true;
+            return builder;
+        },
+        $type() {
+            return builder;
+        },
+        $onUpdate(_fn) {
+            // Runtime $onUpdate is a no-op in the schema layer — the framework's
+            // event-driven projection write path sets modified_at explicitly.
+            return builder;
+        },
+    };
+    return builder;
+}
+// ---- Column factories ----
+export function uuid(name) {
+    return buildColumn(name, "uuid");
+}
+export function text(name) {
+    return buildColumn(name, "text");
+}
+export function boolean(name) {
+    return buildColumn(name, "boolean");
+}
+export function integer(name) {
+    return buildColumn(name, "integer");
+}
+export function doublePrecision(name) {
+    return buildColumn(name, "double precision");
+}
+export function serial(name) {
+    return buildColumn(name, "serial");
+}
+export function bigint(name, opts) {
+    const jsMode = opts?.mode === "number" ? "number" : "bigint";
+    return buildColumn(name, "bigint", { bigintJsMode: jsMode });
+}
+export function bigserial(name, _opts) {
+    return buildColumn(name, "bigserial");
+}
+export function jsonb(name) {
+    return buildColumn(name, "jsonb");
+}
+// Legacy alias kept for compat — timestamptz with no precision.
+export function timestamp(name, _opts) {
+    return buildColumn(name, "timestamptz");
+}
+// numeric → text (we don't currently use Decimal); kept for compat with
+// legacy schema imports that won't actually instantiate at runtime.
+export function numeric(name, _opts) {
+    return buildColumn(name, "text");
+}
+export function instant(name, opts) {
+    const pgType = opts?.precision === 3 ? "timestamptz(3)" : "timestamptz";
+    return buildColumn(name, pgType);
+}
+// PG `date` — no time-of-day, no timezone. Calendar-day fields (invoice
+// date, lease term) round-trip as Temporal.PlainDate, never through an
+// Instant — that detour is exactly what made `type:"date"` TZ-dependent on
+// both read and write (kumiko-framework#1924).
+export function plainDate(name) {
+    return buildColumn(name, "date");
+}
+// Real numeric(precision, scale) column — exact decimal storage (interest
+// rates, percentages, ratios). pg returns numeric as a STRING; coerceRow
+// parses it back to JS number on read (safe ≤ 2^53). Precision/scale live in
+// the pgType string, so DDL render + coercion need no extra metadata.
+export const decimalColumn = (name, precision, scale) => buildColumn(name, `numeric(${precision},${scale})`);
+// moneyAmount kept as a customType-style API but produces a bigint column.
+// bigintJsMode "bigint" — entity-table-meta renders money as bigint, and the
+// table-builder↔meta lockstep guard fails on a number-mode column. (Precision
+// past 2^53 is the underlying motivation, not the immediate breakage.)
+export const moneyAmount = (name) => buildColumn(name, "bigint", { bigintJsMode: "bigint" });
+function makeIndex(name, unique) {
+    return {
+        __index: true,
+        on(...cols) {
+            const colNames = cols.map((c) => c.name);
+            let whereSql;
+            const finalised = {
+                __index: true,
+                name,
+                unique,
+                columns: colNames,
+                get whereSql() {
+                    return whereSql;
+                },
+                where(expr) {
+                    whereSql = expr.text;
+                    return finalised;
+                },
+            };
+            return finalised;
+        },
+    };
+}
+// @wrapper-known semantic-alias
+export function index(name) {
+    return makeIndex(name, false);
+}
+// @wrapper-known semantic-alias
+export function uniqueIndex(name) {
+    return makeIndex(name, true);
+}
+export function primaryKey(opts) {
+    return {
+        __pk: true,
+        columns: opts.columns.map((c) => c.name),
+        ...(opts.name !== undefined && { name: opts.name }),
+    };
+}
+// ---- sql template ----
+//
+// A constrained sql template tag. Returns a SqlExpression carrying the
+// composed text + params. Used in DEFAULT expressions in schema files
+// (sql`now()`, sql`gen_random_uuid()`, sql`0`).
+//
+// 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() (bun-db/query.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
+// `{ kind: "sql-expr" }` from a client-controlled schema definition is never
+// spliced into SQL text anywhere.
+export const SQL_EXPR_BRAND = Symbol("sql-expr");
+export function sql(strings, ...values) {
+    const parts = [];
+    const params = [];
+    for (let i = 0; i < strings.length; i++) {
+        parts.push(strings[i] ?? "");
+        if (i < values.length) {
+            const v = values[i];
+            if (v && typeof v === "object" && SQL_EXPR_BRAND in v) {
+                parts.push(v.text);
+            }
+            else {
+                parts.push(String(v));
+            }
+        }
+    }
+    return { kind: "sql-expr", text: parts.join(""), params, [SQL_EXPR_BRAND]: true };
+}
+sql.raw = (text) => ({
+    kind: "sql-expr",
+    text,
+    params: [],
+    [SQL_EXPR_BRAND]: true,
+});
+export function table(tableName, cols, optsFn) {
+    // Finalise columns + build the column-handle map.
+    const handles = {};
+    const columnMetas = [];
+    const indexes = [];
+    for (const [field, builder] of Object.entries(cols)) {
+        const final = builder.finalise();
+        const handle = {
+            name: final.sqlName,
+            pgType: final.pgType,
+            getSQLType: () => pgTypeToSqlType(final.pgType), // @wrapper-known semantic-alias
+        };
+        handles[field] = handle;
+        const meta = {
+            name: final.sqlName,
+            pgType: final.pgType,
+            notNull: final.notNull,
+            ...(final.primaryKey && { primaryKey: true }),
+            ...(final.identity && { identity: true }),
+            ...(final.defaultSql !== undefined && { defaultSql: final.defaultSql }),
+            ...(final.bigintJsMode !== undefined && { bigintJsMode: final.bigintJsMode }),
+        };
+        columnMetas.push(meta);
+        // Per-column .unique() → single-column unique index
+        if (final.unique) {
+            indexes.push({
+                name: `${tableName}_${final.sqlName}_unique`,
+                columns: [final.sqlName],
+                unique: true,
+            });
+        }
+    }
+    // Evaluate index/pk callback with the column handles.
+    let compositePrimaryKey;
+    if (optsFn) {
+        const tHandle = handles;
+        const opts = optsFn(tHandle);
+        const entries = Array.isArray(opts)
+            ? opts.map((v, i) => [String(i), v])
+            : Object.entries(opts);
+        for (const [key, value] of entries) {
+            if (!value)
+                continue;
+            if ("__pk" in value && value.__pk === true) {
+                compositePrimaryKey = {
+                    name: value.name ?? `${tableName}_pk`,
+                    columns: value.columns,
+                };
+            }
+            else if ("__index" in value && value.__index === true) {
+                const idx = value;
+                indexes.push({
+                    name: idx.name,
+                    columns: idx.columns,
+                    ...(idx.unique && { unique: true }),
+                    ...(idx.whereSql !== undefined && { whereSql: idx.whereSql }),
+                });
+            }
+            else {
+                // Inline unique-column declaration via .unique() — not implemented yet.
+                // Schema files don't currently use that path; pinned by the table-types
+                // test fixture if it's ever added.
+                const _k = key;
+            }
+        }
+    }
+    // Build the SchemaTable. Object.assign to layer the column handles + symbols
+    // onto the EntityTableMeta-shaped object so introspection works.
+    const base = {
+        tableName,
+        columns: columnMetas,
+        indexes,
+        ...(compositePrimaryKey !== undefined && { compositePrimaryKey }),
+        source: "unmanaged",
+    };
+    const out = Object.assign({}, base, handles, {
+        [KUMIKO_NAME_SYMBOL]: tableName,
+        [KUMIKO_COLUMNS_SYMBOL]: handles,
+        [KUMIKO_META_SYMBOL]: base,
+    });
+    return out;
+}
+/** Reads the `kumiko:schema:Name` symbol from a table object.
+ *  Throws with `context` in the message so callers don't have to duplicate the guard. */
+export function extractTableName(table, context = "extractTableName") {
+    if (typeof table !== "object" || table === null) {
+        throw new Error(`${context}: table is not an object`);
+    }
+    const name = table[KUMIKO_NAME_SYMBOL];
+    if (typeof name !== "string") {
+        throw new Error(`${context}: table missing kumiko:schema:Name symbol`);
+    }
+    return name;
+}
+// Helper used by `instantToDriver` callers in legacy code — kept identical
+// to the previous behaviour. The native dialect handles parse/serialize
+// implicitly via the Bun driver; this function is a defensive coerce at
+// the API boundary.
+export function instantToDriver(value) {
+    if (typeof value === "string") {
+        const dateOnly = /^\d{4}-\d{2}-\d{2}$/.test(value);
+        const iso = dateOnly ? `${value}T00:00:00Z` : value;
+        return Temporal.Instant.from(iso).toString();
+    }
+    return value.toString();
+}

package/dist/db/eagerload.d.ts

@@ -0,0 +1,18 @@
+import type { EntityDefinition } from "../engine/types/index.js";
+import type { TenantDb } from "./tenant-db.js";
+export type EagerLoadEntityResolver = (entityName: string) => EntityDefinition | undefined;
+export type EagerloadedRow<T extends Record<string, unknown> = Record<string, unknown>> = T & {
+    readonly _refs?: Readonly<Record<string, Record<string, unknown> | ReadonlyArray<Record<string, unknown>> | undefined>>;
+};
+type ReferenceFieldEntry = {
+    readonly fieldName: string;
+    readonly refEntityName: string;
+    readonly multiple: boolean;
+};
+export declare function collectReferenceFields(entity: EntityDefinition): readonly ReferenceFieldEntry[];
+/** Eagerload für eine Liste von Rows. Mutiert nicht — gibt eine
+ *  flache Kopie der Rows mit hinzugefügtem `_refs`-Property zurück. */
+export declare function enrichWithReferences(rows: ReadonlyArray<Record<string, unknown>>, entity: EntityDefinition, resolveEntity: EagerLoadEntityResolver, db: TenantDb): Promise<Array<Record<string, unknown>>>;
+/** Single-Row-Variante für detail-Calls. */
+export declare function enrichRowWithReferences(row: Record<string, unknown>, entity: EntityDefinition, resolveEntity: EagerLoadEntityResolver, db: TenantDb): Promise<Record<string, unknown>>;
+export {};