@ultimat3/entity 3.0.0 → 4.0.0

package/src/memory-match.ts

@@ -0,0 +1,169 @@
+// Single responsibility: what a `Predicate` MEANS in the in-memory driver — equality, ordering and
+// LIKE. Every rule here exists so the answer matches the one Postgres gives for the same predicate
+// on the same column, which is why each is decided by the column's DECLARED KIND and never by the
+// JS type of whichever value is in hand: the database decides by the column's type, so a driver
+// deciding by `typeof` is answering a different question.
+
+import { compareDecimalText } from '@ultimat3/core';
+import { keyOf } from './batch-read';
+import { kindOf, valueAt } from './cursor';
+import type { EntityCore } from './entity';
+import { EntityError } from './errors';
+import type { Predicate } from './tenancy';
+import type { ColumnKind } from './types';
+
+/**
+ * The kinds whose ROW VALUE is a decimal string. `bigint()` and `decimal()` both hand back digits
+ * as text on purpose (`columns-data.ts`): a JS `bigint` is what `JSON.stringify` throws on and a
+ * `number` loses digits past 2^53, exactly where a legacy `int8` key lives.
+ *
+ * Which makes them the kinds no `typeof` branch can catch. `compare` had a `number`/`number` case
+ * and a `bigint`/`bigint` case and neither fired for these, so both fell to
+ * `String(left) < String(right)`: memory answered `["10","100","2","9"]` where Postgres answers
+ * `["2","9","10","100"]`, and a keyset page boundary was cut where the database never cuts one.
+ *
+ * This SET is the whole of what this package contributes; the comparison itself is
+ * `@ultimat3/core`'s `compareDecimalText`. The split is the point — the text arrives in more than
+ * one package and the DECLARED KIND does not, so a caller with no column kinds
+ * (`@ultimat3/query`, whose `OrderKey` is a name and a direction) deliberately never asks: a
+ * `text` column holding `"10"` and `"9"` is ordered lexically by Postgres, and a comparator
+ * guessing "both sides look like decimals" would trade this disagreement for that one.
+ */
+const DECIMAL_TEXT: ReadonlySet<ColumnKind> = new Set<ColumnKind>(['bigint', 'numeric']);
+
+const sign = <T extends number | bigint | string>(left: T, right: T): number =>
+  left < right ? -1 : left > right ? 1 : 0;
+
+/**
+ * Two values of one column, ordered as Postgres orders that column. `-1`, `0` or `1` — never a
+ * difference, so a `bigint` pair needs no subtraction it cannot express in a `number`.
+ */
+export const compareByKind = (
+  kind: ColumnKind | undefined,
+  left: unknown,
+  right: unknown,
+): number => {
+  if (left instanceof Date && right instanceof Date) return sign(left.getTime(), right.getTime());
+  if (kind !== undefined && DECIMAL_TEXT.has(kind)) {
+    // `undefined` when either side is not a plain decimal — that pair is not a numeric comparison,
+    // so it falls through to the branches below rather than being guessed at.
+    const exact = compareDecimalText(left, right);
+    if (exact !== undefined) return exact;
+  }
+  if (typeof left === 'number' && typeof right === 'number') return sign(left, right);
+  if (typeof left === 'bigint' && typeof right === 'bigint') return sign(left, right);
+  return sign(String(left), String(right));
+};
+
+/**
+ * Equality, in the two places `===` is not what the database means. A `Date` compares by identity,
+ * so `where({ publishedAt })` would match nothing here and every row there. And Postgres compares a
+ * `uuid` as a VALUE — it parses the text and prints it lower-cased — so an id handed in upper case
+ * matches the row there and used to miss it here, which is `findById(UPPER)` answering `null` in
+ * memory and the row in production. `keyOf` is where that rule already lived, for the batched read.
+ */
+export const sameValueOfKind = (
+  kind: ColumnKind | undefined,
+  left: unknown,
+  right: unknown,
+): boolean => {
+  if (left instanceof Date && right instanceof Date) return left.getTime() === right.getTime();
+  if (kind === 'uuid' && typeof left === 'string' && typeof right === 'string') {
+    return keyOf('uuid', left) === keyOf('uuid', right);
+  }
+  return left === right;
+};
+
+const REGEX_SPECIAL = /[.*+?^${}()|[\]\\]/g;
+
+const quote = (text: string): string => text.replace(REGEX_SPECIAL, '\\$&');
+
+/**
+ * Postgres answers a `LIKE` pattern ending in the escape character with `22025 — LIKE pattern must
+ * not end with escape character`, so a pattern that means nothing there means nothing here either.
+ * The pattern itself is never echoed: a filter value is app data, and this cause is rendered into
+ * a log line.
+ */
+const danglingEscape = (entityName: string): EntityError =>
+  new EntityError({
+    code: 'X_INVARIANT_VIOLATED',
+    cause: `${entityName}: a like pattern ends with a backslash, which is the escape character — Postgres answers that pattern with 22025 (LIKE pattern must not end with escape character)`,
+    fix: "double it — 'a\\\\' is the pattern that matches one literal backslash, and 'a\\%b' matches a literal %",
+  });
+
+/**
+ * A SQL `LIKE` pattern as a regex, with Postgres' DEFAULT escape handling: `%` and `_` are the
+ * wildcards, a backslash escapes either (or itself), and everything else is literal.
+ *
+ * The backslash used to be quoted for the regex BEFORE the wildcards were expanded, so `'a\%b'`
+ * matched the literal `a%b` in Postgres and `a\<anything>b` here — one pattern, two meanings, and
+ * the driver that disagreed was the one every test runs against.
+ *
+ * A RUN of `%` is still one `.*`, not one each: `%%%…x` compiled to twenty adjacent `.*` groups,
+ * and an anchored regex with twenty of them takes exponential time to fail on a long value — a
+ * filter value forwarded from a search box is then a CPU stall in the process. Postgres reads a run
+ * of `%` as one wildcard too, so this is the two drivers agreeing rather than a defensive
+ * narrowing.
+ */
+const likePattern = (entityName: string, pattern: string): RegExp => {
+  let source = '';
+  let at = 0;
+  while (at < pattern.length) {
+    const char = pattern[at];
+    if (char === '\\') {
+      const escaped = pattern[at + 1];
+      if (escaped === undefined) throw danglingEscape(entityName);
+      source += quote(escaped);
+      at += 2;
+      continue;
+    }
+    if (char === '%') {
+      while (pattern[at] === '%') at += 1;
+      source += '.*';
+      continue;
+    }
+    source += char === '_' ? '.' : quote(char ?? '');
+    at += 1;
+  }
+  return new RegExp(`^${source}$`, 's');
+};
+
+/** One predicate against one stored row, in the meaning the Postgres driver compiles it to. */
+export const matchesPredicate = <Row>(
+  entity: EntityCore<Row>,
+  row: unknown,
+  predicate: Predicate,
+): boolean => {
+  // The column's declared kind, resolved once — `price.minor` included, which is the path a money
+  // predicate and a money sort key both name.
+  const kind = kindOf(entity, predicate.column);
+  const actual = valueAt(row, predicate.column);
+  const same = (candidate: unknown): boolean => sameValueOfKind(kind, actual, candidate);
+  const order = (): number => compareByKind(kind, actual, predicate.value);
+  switch (predicate.op) {
+    case 'eq':
+      return same(predicate.value);
+    case 'neq':
+      return !same(predicate.value);
+    // `in` reads a LIST or nothing: an operand that is not an array matches no row, which is what
+    // `predicateSql` now compiles it to and what `@ultimat3/query` answers for the same operand.
+    case 'in':
+      return Array.isArray(predicate.value) && predicate.value.some(same);
+    case 'gt':
+      return order() > 0;
+    case 'gte':
+      return order() >= 0;
+    case 'lt':
+      return order() < 0;
+    case 'lte':
+      return order() <= 0;
+    // Real LIKE semantics, so `'draft%'` means "starts with" here exactly as it does in Postgres.
+    // Treating the pattern as a substring would make the two drivers disagree.
+    case 'like':
+      return likePattern(entity.$name, String(predicate.value)).test(String(actual));
+    case 'is-null':
+      return actual === null || actual === undefined;
+    case 'is-not-null':
+      return actual !== null && actual !== undefined;
+  }
+};

package/src/pg-driver.ts

@@ -7,7 +7,6 @@
 // being told — which is how `ctx.jobs.enqueue()` lands its outbox row atomically with the write
 // that caused it. `RepoOptions.tx` is the in-memory driver's undo hook and is ignored here.
 
-import { systemClock } from '@ultimat3/core';
 import {
   currentTx,
   type DbClient,
@@ -24,6 +23,7 @@ import {
   namedProperties,
   upsertPlan,
 } from './bulk-write';
+import { entityNow } from './clock';
 import { coalesceFindById } from './coalesce';
 import { countsFrom, groupColumnOf, groupValue, MAX_GROUPS } from './count-by';
 import { cursorFor, seekFrom, valueAt } from './cursor';
@@ -132,7 +132,7 @@ export const postgresRepo = <Row>(
       ? updateStatement(
           entity,
           plan,
-          new Map([[physicalName(entity, SOFT_DELETE_COLUMN), systemClock.now()]]),
+          new Map([[physicalName(entity, SOFT_DELETE_COLUMN), entityNow()]]),
           shapeOf({}),
           false,
         )

package/src/pg-row.ts

@@ -4,11 +4,11 @@
 // from the driver is re-parsed by the column that declared it rather than trusted — int8 arrives
 // as a string, timestamptz may arrive as one, and a silent `NaN` is worse than a loud throw.
 
-import { columnName, moneyColumns } from './column';
+import { columnFor, columnName, moneyColumns } from './column';
 import { narrowMoney } from './columns';
 import type { EntityCore } from './entity';
 import { invariantViolated } from './errors';
-import type { AnyColumn, MoneyValue } from './types';
+import type { AnyColumn, MoneyValue, RowPatch } from './types';
 
 export type PhysicalRow = Readonly<Record<string, unknown>>;
 
@@ -39,7 +39,7 @@ export const columnsOf = (property: string, column: AnyColumn): readonly string[
  */
 export const physicalName = <Row>(entity: EntityCore<Row>, path: string): string => {
   const [property = path, part] = path.split('.');
-  const column = entity.$columns[property];
+  const column = columnFor(entity.$columns, property);
   if (column === undefined) {
     throw invariantViolated(
       entity.$name,
@@ -73,7 +73,7 @@ export const allColumns = <Row>(entity: EntityCore<Row>): readonly string[] =>
  */
 export const bindValues = <Row>(
   entity: EntityCore<Row>,
-  values: Partial<Row>,
+  values: RowPatch<Row>,
 ): ReadonlyMap<string, unknown> => {
   const bound = new Map<string, unknown>();
   // `MoneyInput` lets a writer hand a `bigint`; the row type is `MoneyValue`. `memoryRepo` calls

package/src/pg-sql.ts

@@ -4,7 +4,7 @@
 // declared. That is the whole reason this file exists instead of a template literal per method.
 
 import { identifier, join, raw, type SqlFragment, sql } from '@ultimat3/db';
-import { columnName } from './column';
+import { columnFor, columnName } from './column';
 import type { EntityCore } from './entity';
 import { SOFT_DELETE_COLUMN } from './entity';
 import { allColumns, columnsOf, physicalName } from './pg-row';
@@ -33,10 +33,23 @@ const predicateSql = <Row>(entity: EntityCore<Row>, predicate: Predicate): SqlFr
       // `is distinct from` so a null on either side compares as a value, not as unknown.
       return sql`${column} is distinct from ${value}`;
     case 'in': {
-      const values = Array.isArray(value) ? value : [value];
-      return values.length === 0
-        ? NEVER
-        : sql`${column} in (${join(values.map((each) => sql`${each}`))})`;
+      // `in` reads a LIST or nothing. A scalar used to be wrapped into a one-element list, which
+      // matched a row here that `memoryRepo`'s `matches` refuses outright — 0 rows in memory, 1 in
+      // Postgres, from a call `andWhere(column, op, value: unknown)` compiles. One answer, and it
+      // is the one `@ultimat3/query`'s `filterClause` already gives: no rows.
+      if (!Array.isArray(value)) return NEVER;
+      // A NULL bound as a parameter is `col = null`, which is UNKNOWN and therefore excludes the
+      // very row the caller listed — while memory's `sameValue(null, null)` includes it. Postgres
+      // has no `in` that compares a null as a value, so the list is partitioned and the nulls are
+      // asked for as `is null`: the `(… in (…) or … is null)` pair `eq` and `neq` already emit.
+      const present = value.filter((each) => each !== null && each !== undefined);
+      const list =
+        present.length === 0
+          ? undefined
+          : sql`${column} in (${join(present.map((e) => sql`${e}`))})`;
+      const nulls = present.length === value.length ? undefined : sql`${column} is null`;
+      if (list === undefined) return nulls ?? NEVER;
+      return nulls === undefined ? list : sql`(${list} or ${nulls})`;
     }
     case 'gt':
       return sql`${column} > ${value}`;
@@ -137,7 +150,7 @@ const projection = <Row>(entity: EntityCore<Row>, plan: QueryPlan): SqlFragment
     ...plan.orderBy.map((entry) => entry.column.split('.')[0] ?? entry.column),
   ]);
   const names = [...wanted].flatMap((property) => {
-    const column = entity.$columns[property];
+    const column = columnFor(entity.$columns, property);
     return column === undefined ? [] : columnsOf(property, column);
   });
   return join(names.map(identifier));

package/src/plan.ts

@@ -8,6 +8,7 @@ import { EntityError, invariantViolated, patchEmpty, writeUnfiltered } from './e
 import type { FindManyArgs, RepoOptions } from './repo';
 import type { Predicate, QueryPlan, SortKey } from './tenancy';
 import { scopedPlan } from './tenancy';
+import type { RowPatch } from './types';
 
 /** A page is bounded by default; an unbounded read is a production incident waiting for traffic. */
 export const DEFAULT_PAGE_SIZE = 50;
@@ -146,7 +147,7 @@ export const namedColumns = (values: unknown): readonly (readonly [string, unkno
 /** The filter a filtered write is allowed to run with: never the empty one. */
 const boundedWhere = <Row>(
   entity: EntityCore<Row>,
-  filter: Partial<Row>,
+  filter: RowPatch<Row>,
   operation: string,
 ): Predicate[] => {
   const where = namedColumns(filter).map(
@@ -166,7 +167,7 @@ const boundedWhere = <Row>(
  */
 export const deletePlan = <Row>(
   entity: EntityCore<Row>,
-  filter: Partial<Row>,
+  filter: RowPatch<Row>,
   options: RepoOptions | undefined,
   operation: string,
 ): QueryPlan =>
@@ -179,8 +180,8 @@ export const deletePlan = <Row>(
  */
 export const updatePlan = <Row>(
   entity: EntityCore<Row>,
-  filter: Partial<Row>,
-  patch: Partial<Row>,
+  filter: RowPatch<Row>,
+  patch: RowPatch<Row>,
   options: RepoOptions | undefined,
   operation: string,
 ): QueryPlan => {

package/src/query.ts

@@ -4,9 +4,9 @@
 // concurrent writes an insert before the offset shifts every later page, so a client silently
 // skips and repeats rows.
 
-import { systemClock } from '@ultimat3/core';
 import type { BatchIterator } from './batch';
 import { assertBatchable, batchIterator } from './batch';
+import { entityNow } from './clock';
 import type { EntityCore } from './entity';
 import { assertPageSize, DEFAULT_PAGE_SIZE, namedColumns } from './plan';
 import type { RelatedTables } from './preload';
@@ -15,7 +15,7 @@ import type { Relation } from './relations';
 import { relationNamed } from './relations';
 import type { Page, Repo, RepoOptions, UpsertArgs } from './repo';
 import type { Operator, Predicate, QueryPlan, SortDirection, SortKey } from './tenancy';
-import type { ColumnMap, IdOf, Insertable } from './types';
+import type { ColumnMap, IdOf, Insertable, RowPatch } from './types';
 
 /**
  * What a preloaded relation adds to a row. `unknown` because the name is a string resolved at
@@ -26,7 +26,7 @@ export type Preloaded<Name extends string> = { readonly [K in Name]: unknown };
 
 export interface ReadBuilder<Row> {
   /** Equality on the columns given. `where({ orgId })` is what satisfies the tenancy guard. */
-  where(filter: Partial<Row>): ReadBuilder<Row>;
+  where(filter: RowPatch<Row>): ReadBuilder<Row>;
   andWhere(column: keyof Row & string, op: Operator, value: unknown): ReadBuilder<Row>;
   orderBy(column: keyof Row & string, direction?: SortDirection): ReadBuilder<Row>;
   limit(rows: number): ReadBuilder<Row>;
@@ -106,21 +106,21 @@ export interface Table<Row, C extends ColumnMap = ColumnMap> extends ReadBuilder
    */
   upsertAll(rows: readonly Insertable<C>[], args: UpsertArgs<Row>): Promise<readonly Row[]>;
   /** `IdOf<Row>`: an entity that declared `uuid<PostId>()` is addressed by a `PostId` only. */
-  update(id: IdOf<Row>, patch: Partial<Row>, options?: RepoOptions): Promise<Row>;
+  update(id: IdOf<Row>, patch: RowPatch<Row>, options?: RepoOptions): Promise<Row>;
   delete(id: IdOf<Row>, options?: RepoOptions): Promise<void>;
   /**
    * Delete by equality filter; resolves with the number of rows removed. The only way to remove a
    * row from an entity whose primary key is composite — `likes`, `blocks`, a join table — where
    * one id cannot name it. `deleteWhere({})` is `X_WRITE_UNFILTERED`, never every row.
    */
-  deleteWhere(filter: Partial<Row>, options?: RepoOptions): Promise<number>;
+  deleteWhere(filter: RowPatch<Row>, options?: RepoOptions): Promise<number>;
   /**
    * Update by equality filter; resolves with the number of rows written. The `update(id, patch)`
    * a composite primary key cannot express — `participants.updateWhere({ conversationId, userId },
    * { lastReadAt })` is the reference case. Empty filter: `X_WRITE_UNFILTERED`. Empty patch:
    * `X_PATCH_EMPTY`. `onUpdateNow()` columns are stamped exactly as `update(id, patch)` stamps them.
    */
-  updateWhere(filter: Partial<Row>, patch: Partial<Row>, options?: RepoOptions): Promise<number>;
+  updateWhere(filter: RowPatch<Row>, patch: RowPatch<Row>, options?: RepoOptions): Promise<number>;
 }
 
 interface State {
@@ -311,7 +311,7 @@ const touch = <Row, Patch>(entity: EntityCore<Row>, patch: Patch): Patch => {
   if (namedColumns(patch).length === 0) return patch;
   const stamped: Record<string, unknown> = {};
   for (const [property, column] of Object.entries(entity.$columns)) {
-    if (column.$meta.onUpdate !== undefined) stamped[property] = systemClock.now();
+    if (column.$meta.onUpdate !== undefined) stamped[property] = entityNow();
   }
   return Object.assign({}, patch, stamped);
 };

package/src/registry.ts

@@ -5,6 +5,7 @@
 
 import { entityDuplicate } from './errors';
 import type { InvariantKind } from './invariants';
+import type { OnDelete } from './types';
 
 export interface ColumnDescription {
   readonly property: string;
@@ -16,6 +17,13 @@ export interface ColumnDescription {
   readonly hasDefault: boolean;
   readonly check: string | null;
   readonly references: string | null;
+  /**
+   * The `references()` rule, `null` when the key declared none. Beside `references` rather than
+   * inside it because that field is a flat `"<table>.<column>"` string with no room for it, and
+   * `@ultimat3/db` is tier 1: it cannot import this package, so a rule that is not on this
+   * projection reaches no `alter table` at all. It reached none until 3.0.
+   */
+  readonly onDelete: OnDelete | null;
 }
 
 /**
@@ -35,6 +43,8 @@ export interface ReferenceDescription {
   readonly targetEntity: string;
   readonly targetProperty: string;
   readonly targetColumn: string;
+  /** What the database does to this row when the target goes. `null` is Postgres' `no action`. */
+  readonly onDelete: OnDelete | null;
 }
 
 export interface InvariantDescription {

package/src/relations.ts

@@ -204,7 +204,10 @@ export const relationsFor = (entityName: string): EntityRelations =>
  */
 export const relationNamed = (entityName: string, name: string): Relation => {
   const relations = relationsFor(entityName);
-  const relation = relations[name];
+  // `relations[name]` walks the prototype: `preload('toString')` used to hand back
+  // `Function.prototype.toString` AS a `Relation`, past the refusal, to be read for a `.through`
+  // it does not have. A relation map is derived from foreign keys, so a name is caller data here.
+  const relation = Object.hasOwn(relations, name) ? relations[name] : undefined;
   if (relation === undefined) {
     throw preloadUnknownRelation(entityName, name, Object.keys(relations));
   }