@cosmicdrift/kumiko-framework 0.42.0 → 0.44.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.42.0",
+  "version": "0.44.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/src/bun-db/__tests__/decimal-field.integration.test.ts

@@ -0,0 +1,81 @@
+// decimal-field.integration.ts — real-DB roundtrip for the numeric(p,s) column.
+//
+// The unit tests prove the read codec (coerceRow) and the DDL/Zod in isolation.
+// Only a live Postgres can prove the *write* direction: that a JS number binds
+// into a numeric(p,s) column and comes back — via pg's numeric STRING + the
+// coerceRow parse — as the exact same JS number. That symmetry is the thing
+// that breaks silently if either side is wrong, so it gets a real DB test.
+import { afterAll, describe, expect, test } from "bun:test";
+import { fetchOne, insertOne } from "../query";
+import { closeDb, withTable } from "./_helpers";
+
+afterAll(async () => {
+  await closeDb();
+});
+
+const decimalCols = [
+  { name: "sum", pgType: "numeric(14,2)" as const, notNull: true },
+  { name: "interest", pgType: "numeric(6,4)" as const, notNull: true },
+  { name: "rate", pgType: "numeric(12,2)" as const, notNull: false },
+] as const;
+
+describe("decimal — real-DB roundtrip", () => {
+  test("JS number → numeric(p,s) → exact JS number", async () => {
+    await withTable(decimalCols, async ({ db, meta }) => {
+      const ins = await insertOne<{ id: string }>(db, meta, {
+        sum: 1000.5,
+        interest: 2.5,
+        rate: 5.83,
+      });
+      const row = await fetchOne<{ sum: number; interest: number; rate: number }>(db, meta, {
+        id: ins!.id,
+      });
+      expect(typeof row!.sum).toBe("number");
+      expect(row!.sum).toBe(1000.5);
+      expect(row!.interest).toBe(2.5);
+      expect(row!.rate).toBe(5.83);
+    });
+  });
+
+  test("negative and zero values roundtrip", async () => {
+    await withTable(decimalCols, async ({ db, meta }) => {
+      const ins = await insertOne<{ id: string }>(db, meta, {
+        sum: -42.99,
+        interest: 0,
+        rate: 0.01,
+      });
+      const row = await fetchOne<{ sum: number; interest: number; rate: number }>(db, meta, {
+        id: ins!.id,
+      });
+      expect(row!.sum).toBe(-42.99);
+      expect(row!.interest).toBe(0);
+      expect(row!.rate).toBe(0.01);
+    });
+  });
+
+  test("pg enforces the scale — a fractional value beyond scale is rounded by the column", async () => {
+    await withTable(decimalCols, async ({ db, meta }) => {
+      // 2.55556 written into numeric(6,4) → pg rounds to 4 decimals (2.5556).
+      // Proves the column constraint is real DB-side, not just Zod-advisory.
+      const ins = await insertOne<{ id: string }>(db, meta, {
+        sum: 100,
+        interest: 2.55556,
+        rate: null,
+      });
+      const row = await fetchOne<{ interest: number }>(db, meta, { id: ins!.id });
+      expect(row!.interest).toBe(2.5556);
+    });
+  });
+
+  test("null in an optional numeric column stays null", async () => {
+    await withTable(decimalCols, async ({ db, meta }) => {
+      const ins = await insertOne<{ id: string }>(db, meta, {
+        sum: 100,
+        interest: 1,
+        rate: null,
+      });
+      const row = await fetchOne<{ rate: number | null }>(db, meta, { id: ins!.id });
+      expect(row!.rate).toBeNull();
+    });
+  });
+});

package/src/bun-db/query.ts

@@ -359,6 +359,17 @@ export function coerceRow<T extends Record<string, unknown>>(row: T, info: Table
       // Drizzle coerced to number for numberField columns — match that.
       const n = Number(value);
       if (!Number.isNaN(n)) coerced = n;
+    } else if (
+      typeof pgType === "string" &&
+      pgType.startsWith("numeric") &&
+      (typeof value === "string" || typeof value === "bigint")
+    ) {
+      // 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.
+      const n = Number(value);
+      if (!Number.isNaN(n)) coerced = n;
     }
     const fieldName = info.fieldOf(key);
     if (fieldName !== key) changed = true;

package/src/db/__tests__/decimal-field.test.ts

@@ -0,0 +1,109 @@
+import { describe, expect, test } from "bun:test";
+import { createDecimalField, createEntity } from "../../engine/factories";
+import { fieldToZod } from "../../engine/schema-builder";
+import { buildEntityTableMeta } from "../entity-table-meta";
+import { coerceRow, extractTableInfo } from "../query";
+import { renderTableDdl } from "../render-ddl";
+import { buildEntityTable } from "../table-builder";
+
+// decimal field — Postgres numeric(precision, scale). A new framework
+// primitive (not a port), so these are correctness-of-the-primitive checks:
+// column mapping, DDL, the pg-string→number read codec, and the write-boundary
+// Zod bounds. The read codec is the load-bearing one — pg returns numeric as a
+// STRING, and a missed conversion feeds consumers a string that silently
+// breaks arithmetic.
+
+const entity = createEntity({
+  table: "read_decimal_probe",
+  fields: {
+    sum: createDecimalField({ precision: 14, scale: 2, required: true }),
+    interest: createDecimalField({ precision: 6, scale: 4, required: true }),
+    rate: createDecimalField({ precision: 12, scale: 2 }),
+  },
+});
+
+describe("decimal field — column + DDL", () => {
+  test("maps to numeric(precision,scale) with required→NOT NULL", () => {
+    const cols = new Map(
+      buildEntityTableMeta("decimalProbe", entity).columns.map((c) => [c.name, c]),
+    );
+    expect(cols.get("sum")?.pgType).toBe("numeric(14,2)");
+    expect(cols.get("interest")?.pgType).toBe("numeric(6,4)");
+    expect(cols.get("rate")?.pgType).toBe("numeric(12,2)");
+    expect(cols.get("sum")?.notNull).toBe(true);
+    expect(cols.get("rate")?.notNull).toBe(false);
+  });
+
+  test("renders real numeric(p,s) DDL", () => {
+    const ddl = renderTableDdl(buildEntityTableMeta("decimalProbe", entity)).join("\n");
+    expect(ddl).toContain('"interest" numeric(6,4) NOT NULL');
+    expect(ddl).toContain('"rate" numeric(12,2)');
+  });
+});
+
+describe("decimal field — read codec (pg numeric string → JS number)", () => {
+  const info = extractTableInfo(buildEntityTable("decimalProbe", entity));
+
+  test("parses numeric strings to exact numbers", () => {
+    // Record<string, unknown> so coerceRow's pass-through return type doesn't
+    // pin the keys to `string` — the runtime value is the coerced number.
+    const input: Record<string, unknown> = { sum: "1000.50", interest: "2.5000", rate: "5.83" };
+    const row = coerceRow(input, info);
+    expect(row["sum"]).toBe(1000.5);
+    expect(row["interest"]).toBe(2.5);
+    expect(row["rate"]).toBe(5.83);
+    expect(typeof row["rate"]).toBe("number");
+  });
+
+  test("null passes through untouched", () => {
+    expect(coerceRow({ rate: null }, info).rate).toBeNull();
+  });
+
+  test("already-number values are left as-is", () => {
+    expect(coerceRow({ interest: 2.5 }, info).interest).toBe(2.5);
+  });
+});
+
+describe("decimal field — write-boundary Zod bounds", () => {
+  const schema = fieldToZod(createDecimalField({ precision: 6, scale: 2 }), []);
+
+  test("accepts values within precision and scale", () => {
+    for (const v of [5.83, 2.5, 1000.5, -42.99, 0, 9999.99]) {
+      expect(schema.safeParse(v).success).toBe(true);
+    }
+  });
+
+  test("rejects more decimal places than scale", () => {
+    expect(schema.safeParse(1.234).success).toBe(false);
+  });
+
+  test("rejects values exceeding the precision−scale integer digits", () => {
+    // precision 6, scale 2 → at most 4 integer digits → |value| < 10000.
+    expect(schema.safeParse(10000).success).toBe(false);
+    expect(schema.safeParse(-10000).success).toBe(false);
+  });
+});
+
+describe("decimal field — factory", () => {
+  test("requires precision and scale, defaults to optional", () => {
+    const f = createDecimalField({ precision: 8, scale: 3 });
+    expect(f.type).toBe("decimal");
+    expect(f.precision).toBe(8);
+    expect(f.scale).toBe(3);
+    expect(f.required).toBe(false);
+  });
+});
+
+describe("known limitation: precision past 2^53 (same trade-off as bigInt number-mode)", () => {
+  test("a numeric string beyond Number.MAX_SAFE_INTEGER loses precision on read", () => {
+    const e = createEntity({
+      table: "read_decimal_big",
+      fields: { big: createDecimalField({ precision: 20, scale: 0 }) },
+    });
+    const info = extractTableInfo(buildEntityTable("decimalBig", e));
+    // 2^53 + 1 → surfaced as JS number rounds to 2^53. Documented, not a bug:
+    // keep precision − scale ≤ 15 to stay exact (see DecimalFieldDef doc).
+    const input: Record<string, unknown> = { big: "9007199254740993" };
+    expect(coerceRow(input, info)["big"]).toBe(2 ** 53);
+  });
+});

package/src/db/__tests__/table-builder-meta-lockstep.test.ts

@@ -22,6 +22,7 @@ const entityWithDefaults = createEntity({
     tags: { type: "multiSelect", options: ["a", "b"] },
     attempt: { type: "number", required: true, default: 1 },
     bytes: { type: "bigInt", default: 0 },
+    rate: { type: "decimal", precision: 6, scale: 4, required: true, default: 1.5 },
     price: { type: "money" },
     meta: { type: "embedded", fields: {} },
     startedAt: { type: "timestamp", required: true },
@@ -59,6 +60,13 @@ describe("buildEntityTable ↔ buildEntityTableMeta lock-step", () => {
     expect(cols.get("bytes")?.defaultSql).toBe("0");
     expect(cols.get("title")?.defaultSql).toBe("'untitled'");
     expect(cols.get("active")?.defaultSql).toBe("true");
+    expect(cols.get("rate")?.defaultSql).toBe("1.5");
+  });
+
+  test("decimal field maps to numeric(precision,scale) on both paths", () => {
+    const cols = new Map((fromBuilder?.columns ?? []).map((c) => [c.name, c]));
+    expect(cols.get("rate")?.pgType).toBe("numeric(6,4)");
+    expect(cols.get("rate")?.notNull).toBe(true);
   });
 });
 

package/src/db/dialect.ts

@@ -54,7 +54,15 @@ export type SchemaTable = EntityTableMeta & {
   readonly [field: string]: unknown;
 };
 
+function isNumericPgType(t: PgType): t is `numeric(${number},${number})` {
+  return t.startsWith("numeric(");
+}
+
 export function pgTypeToSqlType(pgType: PgType): string {
+  // 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";
@@ -271,6 +279,17 @@ export function instant(
   return buildColumn(name, pgType) as ColumnBuilder<Temporal.Instant>;
 }
 
+// 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: string,
+  precision: number,
+  scale: number,
+): ColumnBuilder<number> =>
+  buildColumn(name, `numeric(${precision},${scale})`) as ColumnBuilder<number>;
+
 // 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

package/src/db/entity-table-meta.ts

@@ -40,7 +40,10 @@ export type PgType =
   | "bigserial"
   | "jsonb"
   | "timestamptz"
-  | "timestamptz(3)";
+  | "timestamptz(3)"
+  // Exact decimal — precision/scale are encoded in the type string so the
+  // DDL renderer and read-coercion need no side-channel metadata.
+  | `numeric(${number},${number})`;
 
 export type ColumnMeta = {
   readonly name: string; // snake_case PG column name
@@ -207,6 +210,17 @@ function fieldToColumnMeta(
         },
       ];
     }
+    case "decimal": {
+      const def = fieldDefaultLiteral(field);
+      return [
+        {
+          name: snake,
+          pgType: `numeric(${field.precision},${field.scale})`,
+          notNull: field.required === true,
+          ...(def !== undefined && { defaultSql: def }),
+        },
+      ];
+    }
     case "reference":
       if (field.multiple === true) {
         return [{ name: snake, pgType: "jsonb", notNull: true, defaultSql: "'[]'::jsonb" }];

package/src/db/table-builder.ts

@@ -14,6 +14,7 @@ import {
   boolean,
   type ColumnBuilder,
   type ColumnHandle,
+  decimalColumn,
   type IndexBuilderWithCols,
   index,
   instant,
@@ -104,6 +105,11 @@ function fieldToColumns(
       const col = field.default !== undefined ? base.default(field.default) : base;
       return { [name]: field.required ? col.notNull() : col };
     }
+    case "decimal": {
+      const base = decimalColumn(snakeName, field.precision, field.scale);
+      const col = field.default !== undefined ? base.default(field.default) : base;
+      return { [name]: field.required ? col.notNull() : col };
+    }
     case "bigInt": {
       // 64-bit-Integer fuer Audit-Counter, Byte-Sizes, Cumulative-Sums.
       // mode:"number" liefert JS-`number` (sicher bis 2^53 ≈ 9 PB) statt
@@ -283,42 +289,46 @@ type ColumnsForField<K extends string, F extends FieldDefinition> = F extends {
         ? F extends { required: true }
           ? { readonly [P in K]: Col<number> }
           : { readonly [P in K]: NullCol<number> }
-        : F extends { type: "money" }
+        : F extends { type: "decimal" }
           ? F extends { required: true }
-            ? { readonly [P in K]: Col<number> } & {
-                readonly [P in `${K}Currency`]: Col<string>;
-              }
-            : { readonly [P in K]: NullCol<number> } & {
-                readonly [P in `${K}Currency`]: Col<string>;
-              }
-          : F extends { type: "reference"; multiple: true }
-            ? { readonly [P in K]: Col<readonly string[]> }
-            : F extends { type: "reference" }
-              ? F extends { required: true }
-                ? { readonly [P in K]: Col<string> }
-                : { readonly [P in K]: NullCol<string> }
-              : F extends { type: "embedded" }
-                ? // jsonb default `{}`, immer notNull
-                  { readonly [P in K]: Col<Readonly<Record<string, unknown>>> }
-                : F extends { type: "date" | "timestamp" }
-                  ? F extends { required: true }
-                    ? { readonly [P in K]: Col<Temporal.Instant> }
-                    : { readonly [P in K]: NullCol<Temporal.Instant> }
-                  : F extends { type: "locatedTimestamp" }
+            ? { readonly [P in K]: Col<number> }
+            : { readonly [P in K]: NullCol<number> }
+          : F extends { type: "money" }
+            ? F extends { required: true }
+              ? { readonly [P in K]: Col<number> } & {
+                  readonly [P in `${K}Currency`]: Col<string>;
+                }
+              : { readonly [P in K]: NullCol<number> } & {
+                  readonly [P in `${K}Currency`]: Col<string>;
+                }
+            : F extends { type: "reference"; multiple: true }
+              ? { readonly [P in K]: Col<readonly string[]> }
+              : F extends { type: "reference" }
+                ? F extends { required: true }
+                  ? { readonly [P in K]: Col<string> }
+                  : { readonly [P in K]: NullCol<string> }
+                : F extends { type: "embedded" }
+                  ? // jsonb default `{}`, immer notNull
+                    { readonly [P in K]: Col<Readonly<Record<string, unknown>>> }
+                  : F extends { type: "date" | "timestamp" }
                     ? F extends { required: true }
-                      ? { readonly [P in `${K}Utc`]: Col<Temporal.Instant> } & {
-                          readonly [P in `${K}Tz`]: Col<string>;
-                        }
-                      : { readonly [P in `${K}Utc`]: NullCol<Temporal.Instant> } & {
-                          readonly [P in `${K}Tz`]: NullCol<string>;
-                        }
-                    : F extends { type: "file" | "image" }
+                      ? { readonly [P in K]: Col<Temporal.Instant> }
+                      : { readonly [P in K]: NullCol<Temporal.Instant> }
+                    : F extends { type: "locatedTimestamp" }
                       ? F extends { required: true }
-                        ? { readonly [P in K]: Col<string> }
-                        : { readonly [P in K]: NullCol<string> }
-                      : F extends { type: "files" | "images" }
-                        ? Record<never, never>
-                        : never;
+                        ? { readonly [P in `${K}Utc`]: Col<Temporal.Instant> } & {
+                            readonly [P in `${K}Tz`]: Col<string>;
+                          }
+                        : { readonly [P in `${K}Utc`]: NullCol<Temporal.Instant> } & {
+                            readonly [P in `${K}Tz`]: NullCol<string>;
+                          }
+                      : F extends { type: "file" | "image" }
+                        ? F extends { required: true }
+                          ? { readonly [P in K]: Col<string> }
+                          : { readonly [P in K]: NullCol<string> }
+                        : F extends { type: "files" | "images" }
+                          ? Record<never, never>
+                          : never;
 
 type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (
   k: infer I,

package/src/engine/factories.ts

@@ -2,6 +2,7 @@ import type {
   BigIntFieldDef,
   BooleanFieldDef,
   DateFieldDef,
+  DecimalFieldDef,
   EmbeddedFieldDef,
   EntityDefinition,
   EntityIndexDef,
@@ -140,6 +141,21 @@ export function createBigIntField<R extends true | false = false>(
   } as BigIntFieldDef & { required: R }; // @cast-boundary engine-payload
 }
 
+// Exact decimal column — numeric(precision, scale). precision/scale are
+// required (no truncating default). See DecimalFieldDef for the precision
+// caveat (surfaced as JS number, safe ≤ 2^53).
+export function createDecimalField<R extends true | false = false>(
+  config: { precision: number; scale: number } & Partial<
+    Omit<DecimalFieldDef, "type" | "precision" | "scale" | "required">
+  > & { required?: R },
+): DecimalFieldDef & { required: R } {
+  return {
+    type: "decimal",
+    required: false,
+    ...config,
+  } as DecimalFieldDef & { required: R }; // @cast-boundary engine-payload
+}
+
 export function createMoneyField<R extends true | false = false>(
   overrides?: Partial<Omit<MoneyFieldDef, "type" | "required">> & { required?: R },
 ): MoneyFieldDef & { required: R } {

package/src/engine/index.ts

@@ -80,6 +80,7 @@ export {
   createBigIntField,
   createBooleanField,
   createDateField,
+  createDecimalField,
   createEmbeddedField,
   createEntity,
   createFileField,
@@ -236,6 +237,7 @@ export type {
   CustomScreenDefinition,
   CustomScreenRoute,
   DateFieldDef,
+  DecimalFieldDef,
   DeleteContext,
   EditExtensionSection,
   EditFieldSpec,

package/src/engine/schema-builder.ts

@@ -60,6 +60,20 @@ export function fieldToZod(field: FieldDefinition, currencies: readonly string[]
       const schema = z.number();
       return field.default !== undefined ? schema.default(field.default) : schema;
     }
+    case "decimal": {
+      // Stored as numeric(precision, scale), surfaced as JS number. Bound the
+      // value at the write boundary so an over-range or over-scale input fails
+      // loud here instead of being silently rounded/rejected by Postgres.
+      const limit = 10 ** (field.precision - field.scale);
+      const schema = z
+        .number()
+        .gt(-limit)
+        .lt(limit)
+        .refine((n) => Number(n.toFixed(field.scale)) === n, {
+          message: `at most ${field.scale} decimal places`,
+        });
+      return field.default !== undefined ? schema.default(field.default) : schema;
+    }
     case "bigInt": {
       // JS-`number`-Round-trip via mode:"number"; sicher bis 2^53.
       // safe-integer-Cap ist explizit damit ein Caller, der einen

package/src/engine/types/fields.ts

@@ -223,6 +223,30 @@ export type BigIntFieldDef = {
   readonly access?: FieldAccess;
 } & PiiAnnotations;
 
+/**
+ * Exact decimal — Postgres `numeric(precision, scale)`. For values that need
+ * fractional precision the integer `number` field (32-bit int) and `money`
+ * field (BIGINT minor units + currency) can't hold: interest rates,
+ * percentages, ratios, measurements.
+ *
+ * `precision` = total significant digits, `scale` = digits after the decimal
+ * point (both required — no silent default that could truncate). pg returns
+ * `numeric` as a string to preserve precision; the read-codec surfaces it as
+ * a JS `number` (safe ≤ 2^53, same trade-off as `bigInt` mode:"number" — a
+ * value past that boundary loses precision, so keep `precision - scale` ≤ 15).
+ */
+export type DecimalFieldDef = {
+  readonly type: "decimal";
+  readonly precision: number;
+  readonly scale: number;
+  readonly required?: boolean;
+  readonly sortable?: boolean;
+  readonly filterable?: boolean;
+  readonly sensitive?: boolean;
+  readonly default?: number;
+  readonly access?: FieldAccess;
+} & PiiAnnotations;
+
 export type MoneyFieldDef = {
   readonly type: "money";
   readonly required?: boolean;
@@ -440,6 +464,7 @@ export type FieldDefinition =
   | MultiSelectFieldDef
   | NumberFieldDef
   | BigIntFieldDef
+  | DecimalFieldDef
   | MoneyFieldDef
   | ReferenceFieldDef
   | EmbeddedFieldDef

package/src/engine/types/index.ts

@@ -79,6 +79,7 @@ export type {
   BigIntFieldDef,
   BooleanFieldDef,
   DateFieldDef,
+  DecimalFieldDef,
   DefaultCurrency,
   EmbeddedFieldDef,
   EmbeddedSubFieldDef,