@ultimat3/entity 1.2.0 → 3.0.0

package/src/coalesce.ts

@@ -0,0 +1,189 @@
+// Single responsibility: collapse the point lookups one request issues in the same microtask into
+// a single `where id in (…)`, and hand a lookup a page already answered straight to the preload.
+// A list that resolves an author per row is the N+1 this removes, and it removes it without adding
+// a second way to read — `findById` keeps its signature and its meaning, and pays for one round
+// trip instead of one per row.
+
+import { type Ctx, tryUseContext } from '@ultimat3/core';
+import type { DbClient } from '@ultimat3/db';
+import {
+  type Answer,
+  type KeyColumn,
+  keyOf,
+  type PointRead,
+  readByIds,
+  scopeKey,
+  statementChunks,
+} from './batch-read';
+import type { EntityCore } from './entity';
+import { preloadedFindById } from './jit-preload';
+import { physicalName } from './pg-row';
+import type { ReadShape } from './pg-sql';
+import type { QueryPlan } from './tenancy';
+
+/** One caller's lookup: the row it asked for, and the two ends of the promise it is holding. */
+interface Pending {
+  readonly id: unknown;
+  /** What the answer will be filed under — `keyOf(id)`, not the id itself. */
+  readonly key: string;
+  readonly row: Promise<unknown>;
+  readonly settle: (row: unknown) => void;
+  readonly fail: (error: unknown) => void;
+}
+
+/** One statement in the making: the ids collected so far, and the read that will send them. */
+interface Batch {
+  /** Two lookups share a statement only when they read from the same place. */
+  readonly client: DbClient;
+  /** Keyed by `String(id)`, so the same id asked for twice is one bind and one row. */
+  readonly pending: Map<string, Pending>;
+  readonly load: (ids: readonly unknown[]) => Promise<ReadonlyMap<string, Answer>>;
+}
+
+/**
+ * Per request, keyed by ctx identity, so a batch dies with the request that opened it — the shape
+ * `@ultimat3/query`'s request memo has one tier up. `entity` cannot import that one (tier 2 to
+ * tier 3 is upward), so it owns this one.
+ */
+const requests = new WeakMap<object, Map<string, Batch>>();
+
+const batchesFor = (ctx: Ctx): Map<string, Batch> => {
+  const key: object = ctx;
+  const existing = requests.get(key);
+  if (existing !== undefined) return existing;
+  const created = new Map<string, Batch>();
+  requests.set(key, created);
+  return created;
+};
+
+const pendingFor = (id: unknown, key: string): Pending => {
+  // The executor runs synchronously, so both are assigned before this returns. TypeScript cannot
+  // see through the callback, which is all the definite assignments claim.
+  let settle!: (row: unknown) => void;
+  let fail!: (error: unknown) => void;
+  const row = new Promise<unknown>((resolve, reject) => {
+    settle = resolve;
+    fail = reject;
+  });
+  return { id, key, row, settle, fail };
+};
+
+const openBatch = (
+  batches: Map<string, Batch>,
+  key: string,
+  client: DbClient,
+  load: Batch['load'],
+): Batch => {
+  const batch: Batch = { client, pending: new Map(), load };
+  batches.set(key, batch);
+  // The window is one microtask: every lookup issued before the current synchronous run ends
+  // shares this statement. It closes here, before the statement is sent, so a lookup arriving
+  // mid-flight opens the next batch instead of joining ids already on the wire.
+  queueMicrotask(() => {
+    if (batches.get(key) === batch) batches.delete(key);
+    // `flush` settles every caller itself, so a rejection escaping it has nobody left to hand it
+    // to — and an unhandled rejection ends the Bun process, which turns one bad batch into the
+    // whole node. Nothing is swallowed here that a caller was not already given.
+    void flush(batch).catch(() => undefined);
+  });
+  return batch;
+};
+
+const flush = async (batch: Batch): Promise<void> => {
+  const waiting = [...batch.pending.values()];
+  batch.pending.clear();
+  try {
+    // One statement at a time: a batch wide enough to split must not take the pool with it.
+    for (const chunk of statementChunks(waiting)) {
+      try {
+        const answers = await batch.load(chunk.map((entry) => entry.id));
+        for (const entry of chunk) {
+          const answer = answers.get(entry.key);
+          // An id the statement did not answer for is a row that is not there — `findById`'s
+          // `null`, never a rejection, and never another caller's row.
+          if (answer === undefined) entry.settle(null);
+          else if ('error' in answer) entry.fail(answer.error);
+          else entry.settle(answer.row);
+        }
+      } catch (error) {
+        // The statement failed, so everyone in it gets the failure the single statement would
+        // have handed them. Every one was returned to a caller, so none goes unhandled.
+        for (const entry of chunk) entry.fail(error);
+      }
+    }
+  } catch (error) {
+    // Every promise in `waiting` was handed to a caller before this batch was ever scheduled, so
+    // anything escaping the loop above — `statementChunks` itself, or whatever a later edit puts
+    // beside it — would leave them awaiting a row that can no longer arrive. Unsettled forever is
+    // strictly worse than failed: a rejection is a stack trace, a hang is a request that never
+    // answers. Failing an entry an earlier chunk already settled is a no-op, so this is safe over
+    // the whole list. `jit-preload.ts` gets the same property by construction, settling with an
+    // `Answer` rather than a rejection; this path has a real promise per caller and cannot.
+    for (const entry of waiting) entry.fail(error);
+  }
+};
+
+/**
+ * The shared read this lookup joins, or `undefined` when there is none to join: no request in
+ * scope, a composite key, a scope this cannot compare, or a client the open batch does not read
+ * from. Declining is always correct — the caller sends the one statement it always sent.
+ *
+ * Two shapes, one seam. A page already read answers first (one statement for a whole sequential
+ * loop), and what no page can answer joins the microtask batch.
+ */
+export const coalesceFindById = <Row>(
+  entity: EntityCore<Row>,
+  client: DbClient,
+  plan: QueryPlan,
+  shape: ReadShape,
+  id: unknown,
+): Promise<Row | null> | undefined => {
+  const ctx = tryUseContext();
+  const [keyColumn] = entity.$primaryKey;
+  const declared = keyColumn === undefined ? undefined : entity.$columns[keyColumn];
+  if (
+    ctx === undefined ||
+    keyColumn === undefined ||
+    declared === undefined ||
+    entity.$primaryKey.length !== 1
+  ) {
+    return undefined;
+  }
+  // A seek positions a page, never a point lookup. If one ever reaches here the statement is not
+  // the one this batches.
+  if (shape.seek !== undefined) return undefined;
+  const at = plan.where.findIndex(
+    (predicate) =>
+      predicate.column === keyColumn && predicate.op === 'eq' && predicate.value === id,
+  );
+  if (at === -1) return undefined;
+  const scoped: QueryPlan = { ...plan, where: plan.where.filter((_, index) => index !== at) };
+  const key = scopeKey(entity, scoped, shape);
+  if (key === undefined) return undefined;
+
+  const keyColumnRef: KeyColumn = {
+    property: keyColumn,
+    column: physicalName(entity, keyColumn),
+    kind: declared.$meta.kind,
+  };
+  const read: PointRead<Row> = { entity, client, scoped, shape, key: keyColumnRef };
+  // A page whose foreign keys this id is one of answers for every row of that page at once, which
+  // is the only thing that batches a `for … of` loop: its `await` already ended the microtask.
+  const preloaded = preloadedFindById<Row>(ctx, read, key, id);
+  if (preloaded !== undefined) return preloaded;
+
+  const batches = batchesFor(ctx);
+  const open = batches.get(key);
+  // A pinned client and the ambient pool are two places to read from, and a batch is one
+  // statement: a lookup that does not share the open batch's client sends its own.
+  if (open !== undefined && open.client !== client) return undefined;
+  const batch = open ?? openBatch(batches, key, client, (ids) => readByIds(read, ids));
+
+  const filedAt = keyOf(keyColumnRef.kind, id);
+  const already = batch.pending.get(filedAt);
+  const pending = already ?? pendingFor(id, filedAt);
+  if (already === undefined) batch.pending.set(filedAt, pending);
+  // One batch is one entity — the key fixed that before the batch existed — so this re-attaches
+  // the row type the store erased rather than asserting anything new about it.
+  return pending.row as Promise<Row | null>;
+};

package/src/column.ts

@@ -7,11 +7,51 @@
 // physical name even though two schema modules import each other in a cycle.
 
 import { invariantViolated } from './errors';
-import type { AnyColumn, Column, ColumnDefault, ColumnMeta, TimestampColumn } from './types';
+import type {
+  AnyColumn,
+  Column,
+  ColumnDefault,
+  ColumnMeta,
+  MoneyColumnNames,
+  TimestampColumn,
+} from './types';
 
 export const snake = (value: string): string =>
   value.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLowerCase();
 
+/**
+ * The physical column, decided in ONE place: what `.column()` declared, else `snake(property)`.
+ *
+ * Every projection reads it here — the DDL, the binding, the decoder, the invariant resolver, the
+ * index names — because a second `snake(property)` anywhere is a statement naming a column the
+ * table does not have, and the first table that proves it is somebody's production database.
+ */
+export const columnName = (property: string, meta: ColumnMeta): string =>
+  meta.name ?? snake(property);
+
+/** Money's three physical columns, resolved. `scale: null` is a table that has no scale column. */
+export interface MoneyColumns {
+  readonly minor: string;
+  readonly currency: string;
+  readonly scale: string | null;
+}
+
+/**
+ * Per part, merged over the `<base>_minor` / `<base>_currency` / `<base>_scale` defaults — so a
+ * table that renamed one of the three does not have to restate the other two, and `.column()`
+ * moves the base for all of them at once.
+ */
+export const moneyColumns = (property: string, meta: ColumnMeta): MoneyColumns => {
+  const base = columnName(property, meta);
+  const declared: MoneyColumnNames = meta.parts ?? {};
+  return {
+    minor: declared.minor ?? `${base}_minor`,
+    currency: declared.currency ?? `${base}_currency`,
+    // `undefined` takes the default; `null` is the caller saying the column is not there at all.
+    scale: declared.scale === undefined ? `${base}_scale` : declared.scale,
+  };
+};
+
 export const GENERATED_UUID: ColumnDefault = { kind: 'generated', by: 'uuid-v7' };
 export const GENERATED_NOW: ColumnDefault = { kind: 'generated', by: 'now' };
 
@@ -49,13 +89,37 @@ export const bindColumn = (column: AnyColumn, table: string, property: string):
         'build a new column instead of sharing one between entities',
     );
   }
-  const binding: Binding = { table, property, name: snake(property) };
+  const binding: Binding = { table, property, name: columnName(property, column.$meta) };
   bindings.set(column, binding);
   return binding;
 };
 
 export const bindingOf = (column: AnyColumn): Binding | undefined => bindings.get(column);
 
+/**
+ * A declared foreign key, resolved to where its target actually landed — `null` when the column
+ * declares none. The thunk exists because two schema modules import each other in a cycle, so
+ * this can only be answered after both have evaluated; it is answered in ONE place so the DDL
+ * projection (`describe.ts`) and the relation map (`relations.ts`) can never disagree about what
+ * a `references()` points at.
+ */
+export const referenceBinding = (
+  entityName: string,
+  property: string,
+  meta: ColumnMeta,
+): Binding | null => {
+  if (meta.references === undefined) return null;
+  const target = bindingOf(meta.references());
+  if (target === undefined) {
+    throw invariantViolated(
+      entityName,
+      property,
+      'references a column that belongs to no entity — pass a column of an entity() result',
+    );
+  }
+  return target;
+};
+
 const literal = (value: unknown): ColumnDefault => {
   if (value === null) return { kind: 'value', value: null };
   if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
@@ -111,8 +175,30 @@ export const makeColumn = <T, Optional extends boolean>(
     ),
 
   default: (value) => makeColumn<T, true>({ ...meta, default: literal(value) }, parse, true),
+
+  column: (name) =>
+    makeColumn<T, Optional>({ ...meta, name: assertColumnName(name) }, parse, optional),
 });
 
+/**
+ * A physical name is spliced into DDL and into every statement as a quoted identifier, so it is
+ * checked where it is written rather than trusted there: an empty name produces `""`, and a name
+ * carrying a quote or a newline is the one value in a column declaration that could close the
+ * identifier. `[a-z_][a-z0-9_$]*`, which is what an unquoted Postgres identifier may be, and the
+ * bound is the same 63 bytes the server truncates at — a longer one silently addresses a
+ * different column.
+ */
+export const assertColumnName = (name: string): string => {
+  if (!/^[a-z_][a-z0-9_$]*$/.test(name) || name.length > 63) {
+    throw invariantViolated(
+      'column',
+      'column-name',
+      `"${name}" is not a physical column name: lower-case letters, digits and underscores, at most 63 of them`,
+    );
+  }
+  return name;
+};
+
 export const column = <T>(
   kind: ColumnMeta['kind'],
   parse: (value: unknown) => T,
@@ -131,4 +217,7 @@ export const makeTimestamp = <Optional extends boolean>(
   ...makeColumn<Date, Optional>(meta, parse, optional),
   defaultNow: () => makeTimestamp({ ...meta, default: GENERATED_NOW }, parse, true),
   onUpdateNow: () => makeTimestamp({ ...meta, onUpdate: GENERATED_NOW }, parse, optional),
+  // Overridden so `timestamp().column('created').defaultNow()` still has `defaultNow` — the
+  // general link returns the general column, and a builder with methods of its own keeps them.
+  column: (name) => makeTimestamp({ ...meta, name: assertColumnName(name) }, parse, optional),
 });

package/src/columns-data.ts

@@ -0,0 +1,205 @@
+// The column builders an EXISTING schema needs. `columns.ts` holds the opinionated set — one way
+// to store an id, an instant, money — and every one of them is a decision this framework made for
+// a table it was going to create. These are the shapes a table already has: a `jsonb` payload, a
+// `numeric(18,8)` rate, a calendar `date`, an `int8` id past 2^53, a `bytea` blob, a `text[]`.
+//
+// Two rules run through all of them. A value crossing the driver is parsed by the column that
+// declared it, because the two drivers disagree about what they hand back (`int8` is a string from
+// Bun's `sql` and a `bigint` from PGlite — measured); and nothing here is an `any` hole, so `json()`
+// takes a schema and validates through it.
+
+import { describeValue, formatIssues, type StandardSchemaV1, validate } from '@ultimat3/schema';
+import { isPlainDate, type PlainDate, plainDateUtc } from '@ultimat3/time';
+import { column } from './column';
+import { invariantViolated } from './errors';
+import type { AnyColumn, Column, ColumnMeta } from './types';
+
+const reject = (rule: string, detail: string): never => {
+  throw invariantViolated('column', rule, detail);
+};
+
+/** The rejected value as its SHAPE, never its content — `columns.ts` explains why at length. */
+const got = (value: unknown): string => `got ${describeValue(value)}`;
+
+/**
+ * A `jsonb` column whose CONTENTS are validated. The schema is required and that is the point: a
+ * `json()` returning `unknown` is the `any` hole this framework forbids, and a column is the worst
+ * place for one — the value arrives from the DATABASE as often as from a caller, so the row type
+ * would be a claim nothing ever checked.
+ *
+ * The object is bound as an object, never as a string: a JSON string parameter is stored as a JSON
+ * *string* by Postgres (measured — `'{"a":1}'` comes back as the text, not the object), so
+ * stringifying here would change the value's type in the table.
+ */
+export const json = <T>(schema: StandardSchemaV1<unknown, T>): Column<T> =>
+  column<T>('jsonb', (value) => {
+    const result = validate(schema, value);
+    if (result.issues === undefined) return result.value;
+    // The ISSUES, never the value: `formatIssues` renders path + message, and a column rejection
+    // reaches the caller and the log line where a value has no key left to redact.
+    return reject(
+      'json',
+      `does not match the column's schema — ${formatIssues(result.issues).join('; ')}`,
+    );
+  });
+
+const DIGITS = /^-?\d+$/;
+
+/**
+ * `bigint`, whose row type is a decimal STRING. Neither alternative survives contact:
+ * a JS `bigint` is what `JSON.stringify` throws on — the reason `money.minor` is a `number` — and
+ * a `number` silently loses digits past 2^53, which is precisely the range a legacy `int8` key or
+ * a snowflake id lives in. A string holds every value the column can and crosses every wire this
+ * framework generates.
+ *
+ * Both driver spellings arrive here and leave as one: Bun's `sql` returns `int8` as a string and
+ * PGlite returns a `bigint`, and a row that meant two things by driver is the drift this package
+ * exists to refuse.
+ */
+export const bigint = (): Column<string> =>
+  column<string>('bigint', (value) => {
+    if (typeof value === 'bigint') return value.toString();
+    if (typeof value === 'number') {
+      return Number.isSafeInteger(value)
+        ? String(value)
+        : reject(
+            'bigint',
+            `${String(value)} is past ±2^53, where a JS number is no longer exact — pass the digits as a string`,
+          );
+    }
+    return typeof value === 'string' && DIGITS.test(value)
+      ? value
+      : reject('bigint', `expected whole digits, ${got(value)}`);
+  });
+
+export interface DecimalOptions {
+  /** Emits `numeric(precision, scale)`. Both, or neither — a bare `numeric` is unbounded. */
+  readonly precision?: number;
+  readonly scale?: number;
+}
+
+/**
+ * `numeric(p, s)`, whose row type is the exact decimal STRING Postgres returns. Money is the one
+ * decimal this framework has an opinion about (integer minor units plus a currency, always); this
+ * is every other one — a tax rate, an FX rate, a measurement — where the precision is the column's
+ * and no JS number holds it.
+ *
+ * It is deliberately NOT arithmetic-friendly. A framework that handed back a float here would be
+ * the float-money bug with a different name, and one that shipped a decimal type would be shipping
+ * a numeric tower: the honest thing a driver already does is give you the digits.
+ */
+export const decimal = (options: DecimalOptions = {}): Column<string> => {
+  const { precision, scale } = options;
+  if ((precision === undefined) !== (scale === undefined)) {
+    reject('numeric', 'precision and scale are declared together — numeric(18, 8), or neither');
+  }
+  if (precision !== undefined && scale !== undefined) {
+    if (!Number.isInteger(precision) || precision < 1 || precision > 1000) {
+      reject('numeric', `precision must be 1..1000, ${got(precision)}`);
+    }
+    if (!Number.isInteger(scale) || scale < 0 || scale > precision) {
+      reject('numeric', `scale must be 0..precision, ${got(scale)}`);
+    }
+  }
+  const shape = /^-?\d+(\.\d+)?$/;
+  return column<string>(
+    'numeric',
+    (value) => {
+      const text = typeof value === 'number' ? decimalOfNumber(value) : value;
+      if (typeof text !== 'string' || !shape.test(text)) {
+        return reject('numeric', `expected a decimal number, ${got(value)}`);
+      }
+      const digits = text.replace('-', '').split('.');
+      const fraction = digits[1]?.length ?? 0;
+      if (scale !== undefined && fraction > scale) {
+        return reject(
+          'numeric',
+          `${text} has ${fraction} decimal places and the column stores ${scale} — Postgres would round it, silently`,
+        );
+      }
+      if (
+        precision !== undefined &&
+        (digits[0] ?? '').replace(/^0+(?=\d)/, '').length > precision - (scale ?? 0)
+      ) {
+        return reject('numeric', `${text} does not fit numeric(${precision}, ${scale ?? 0})`);
+      }
+      return text;
+    },
+    precision === undefined || scale === undefined ? {} : { precision, numericScale: scale },
+  );
+};
+
+/**
+ * A float is accepted only where it is exactly representable as written — anything else is the
+ * rounding this column exists to refuse, and refusing it at the write is the only place the caller
+ * still knows what they meant.
+ */
+const decimalOfNumber = (value: number): string =>
+  Number.isFinite(value) ? String(value) : 'not-a-number';
+
+/**
+ * A `date`: a calendar date, with no time and therefore no zone. The row type is
+ * `@ultimat3/time`'s `PlainDate`, which is why this is not `timestamp()` with the clock zeroed —
+ * `effective_on` is the date a rate applies, and stored as an instant it is a different date on
+ * either side of midnight for half the planet.
+ *
+ * A driver hands a `date` column back as a `Date` at UTC midnight (measured: Bun's `sql` and
+ * PGlite both), so that is the one conversion here, by its own name. The value written is the
+ * string: binding a `Date` to a `date` parameter fails outright on a server whose client zone has
+ * no name Postgres knows (`time zone "gmt-0500" not recognized`, measured on 17.10).
+ */
+export const date = (): Column<PlainDate> =>
+  column<PlainDate>('date', (value) => {
+    if (value instanceof Date) {
+      return Number.isNaN(value.getTime())
+        ? reject('date', `expected a calendar date, ${got(value)}`)
+        : plainDateUtc(value);
+    }
+    return isPlainDate(value)
+      ? value
+      : reject('date', `expected a YYYY-MM-DD calendar date, ${got(value)}`);
+  });
+
+/**
+ * `bytea`. The row type is a plain `Uint8Array` and both drivers are normalised into one: Bun's
+ * `sql` returns a `Buffer`, PGlite a `Uint8Array`, and the two serialise differently
+ * (`{"type":"Buffer","data":[…]}` against `{"0":…}`) — so a row read through one driver and the
+ * same row read through the other would not be the same object on any wire.
+ */
+export const bytes = (): Column<Uint8Array> =>
+  column<Uint8Array>('bytea', (value) => {
+    if (!(value instanceof Uint8Array)) {
+      return reject('bytea', `expected bytes, ${got(value)}`);
+    }
+    // Already the plain form: the overwhelmingly common case, and it costs one prototype read.
+    return Object.getPrototypeOf(value) === Uint8Array.prototype ? value : new Uint8Array(value);
+  });
+
+/**
+ * `<element>[]` — a Postgres array of a SCALAR column. The element is a column, so its own
+ * `$parse` decides every member: `arrayOf(text({ max: 40 }))` refuses a 41-character tag exactly
+ * where a `text()` column would.
+ *
+ * Money and arrays of arrays are refused rather than approximated: money is three physical columns
+ * and cannot be one array element, and a nested array has no unambiguous literal form.
+ */
+export const arrayOf = <T>(element: Column<T>): Column<readonly T[]> => {
+  const kind = element.$meta.kind;
+  if (kind === 'money' || kind === 'array') {
+    reject(
+      'array',
+      `arrayOf(${kind}) has no single column behind it — an array element is one scalar column`,
+    );
+  }
+  return column<readonly T[]>(
+    'array',
+    (value) => {
+      if (!Array.isArray(value)) return reject('array', `expected an array, ${got(value)}`);
+      return value.map((member) => element.$parse(member));
+    },
+    { element: element as AnyColumn },
+  );
+};
+
+/** The element's own kind, for the projections that need the physical type. */
+export const elementMeta = (meta: ColumnMeta): ColumnMeta | undefined => meta.element?.$meta;