@ultimat3/entity 3.0.0 → 4.0.0

package/src/repo.ts

@@ -7,17 +7,19 @@
 //     table silently skips and repeats rows. A keyset cursor is stable because it names a
 //     position in the sort order, not a row count.
 
-import { systemClock } from '@ultimat3/core';
+import { keyOf } from './batch-read';
 import { conflictKeyOf, conflictKeys, upsertPlan } from './bulk-write';
+import { entityNow } from './clock';
 import { narrowMoney } from './columns';
 import { countsFrom, groupColumnOf } from './count-by';
-import { cursorFor, seekFrom, valueAt } from './cursor';
+import { cursorFor, kindOf, seekFrom, valueAt } from './cursor';
 import { type EntityCore, SOFT_DELETE_COLUMN } from './entity';
 import { notFound } from './errors';
+import { compareByKind, matchesPredicate } from './memory-match';
 import { deletePlan, idPlan, readPlan, singleKeyOf, updatePlan } from './plan';
 import type { Predicate, QueryPlan, SortKey } from './tenancy';
 import { assertRowTenant } from './tenancy';
-import type { IdOf } from './types';
+import type { IdOf, RowPatch } from './types';
 
 export interface Tx {
   readonly id: string;
@@ -52,12 +54,26 @@ export interface UpsertArgs<T = unknown> extends RepoOptions {
   readonly onMatch?: 'update' | 'nothing';
 }
 
-export interface FindManyArgs extends RepoOptions {
+/**
+ * `findById`'s options: `RepoOptions`, plus the one knob a point READ has and a write must not.
+ *
+ * `includeDeleted` lives here and deliberately NOT on `RepoOptions`. It has always been honoured
+ * on this path — `idPlan` spreads the options straight into `FindManyArgs`, and both drivers read
+ * `args.includeDeleted === true` — but `RepoOptions` never declared it, so the only documented way
+ * to read a soft-deleted row by its id did not typecheck. Putting it on `RepoOptions` instead would
+ * have offered it to `update(id, patch)` and `delete(id)`, which reach the same `idPlan`: that is
+ * the resurrection those two carry `deleted_at is null` to refuse.
+ */
+export interface FindByIdOptions extends RepoOptions {
+  /** Soft-deleted rows are hidden unless the caller asks for them. */
+  readonly includeDeleted?: boolean;
+}
+
+export interface FindManyArgs extends FindByIdOptions {
   readonly where?: readonly Predicate[];
   readonly orderBy?: readonly SortKey[];
   readonly limit?: number;
   readonly cursor?: string | null;
-  readonly includeDeleted?: boolean;
   readonly select?: readonly string[];
 }
 
@@ -76,7 +92,7 @@ export interface Page<T> {
  * both `string`, so a row-agnostic consumer sees the signature it always saw.
  */
 export interface Repo<T = unknown> {
-  findById(id: IdOf<T>, options?: RepoOptions): Promise<T | null>;
+  findById(id: IdOf<T>, options?: FindByIdOptions): Promise<T | null>;
   findMany(args?: FindManyArgs): Promise<Page<T>>;
   insert(values: T, options?: RepoOptions): Promise<T>;
   /**
@@ -93,7 +109,7 @@ export interface Repo<T = unknown> {
    * which is what `returning *` says on the Postgres side.
    */
   upsertAll(rows: readonly T[], args: UpsertArgs<T>): Promise<readonly T[]>;
-  update(id: IdOf<T>, patch: Partial<T>, options?: RepoOptions): Promise<T>;
+  update(id: IdOf<T>, patch: RowPatch<T>, options?: RepoOptions): Promise<T>;
   delete(id: IdOf<T>, options?: RepoOptions): Promise<void>;
   /**
    * Delete by filter, returning how many rows went. The only way to remove a row from an entity
@@ -101,14 +117,14 @@ export interface Repo<T = unknown> {
    * to be able to tell "nothing matched" from "it worked", and an empty filter is
    * `X_WRITE_UNFILTERED` rather than every row.
    */
-  deleteWhere(filter: Partial<T>, options?: RepoOptions): Promise<number>;
+  deleteWhere(filter: RowPatch<T>, options?: RepoOptions): Promise<number>;
   /**
    * Update by filter, returning how many rows were written. The `update(id, patch)` a composite
    * primary key cannot express — `participants.lastReadAt` is the reference case. Same two guards
    * as `deleteWhere`, plus `X_PATCH_EMPTY` for a patch that names no columns, and soft-deleted
    * rows are not reachable, exactly as they are not by `update(id, patch)`.
    */
-  updateWhere(filter: Partial<T>, patch: Partial<T>, options?: RepoOptions): Promise<number>;
+  updateWhere(filter: RowPatch<T>, patch: RowPatch<T>, options?: RepoOptions): Promise<number>;
   count(args?: FindManyArgs): Promise<number>;
   /**
    * The grouped count: one statement, one entry per distinct value of `column`, over exactly the
@@ -142,79 +158,22 @@ export interface Transactor {
 const field = (row: unknown, property: string): unknown =>
   typeof row === 'object' && row !== null ? (row as Record<string, unknown>)[property] : undefined;
 
-/**
- * `===` on two Dates compares identity, so `where({ publishedAt })` would match nothing here
- * and every row in Postgres. Equality has to mean the same thing in both drivers or the
- * in-memory one stops being a preview of production.
- */
-const sameValue = (left: unknown, right: unknown): boolean =>
-  left instanceof Date && right instanceof Date
-    ? left.getTime() === right.getTime()
-    : left === right;
-
-const matches = (row: unknown, predicate: Predicate): boolean => {
-  const actual = field(row, predicate.column);
-  switch (predicate.op) {
-    case 'eq':
-      return sameValue(actual, predicate.value);
-    case 'neq':
-      return !sameValue(actual, predicate.value);
-    case 'in':
-      return (
-        Array.isArray(predicate.value) &&
-        predicate.value.some((candidate) => sameValue(candidate, actual))
-      );
-    case 'gt':
-      return compare(actual, predicate.value) > 0;
-    case 'gte':
-      return compare(actual, predicate.value) >= 0;
-    case 'lt':
-      return compare(actual, predicate.value) < 0;
-    case 'lte':
-      return compare(actual, predicate.value) <= 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(String(predicate.value)).test(String(actual));
-    case 'is-null':
-      return actual === null || actual === undefined;
-    case 'is-not-null':
-      return actual !== null && actual !== undefined;
-  }
-};
-
-/**
- * `%` and `_` are the wildcards; everything else in the pattern is literal, as in SQL.
- *
- * A RUN of `%` is 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 an app forwards from a search box is then a CPU stall in the process, on the in-memory
- * driver. Postgres reads a run of `%` as one wildcard too, so this is the two drivers agreeing
- * rather than a defensive narrowing.
- */
-const likePattern = (pattern: string): RegExp =>
-  new RegExp(
-    `^${pattern
-      .replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
-      .replaceAll(/%+/g, '.*')
-      .replaceAll('_', '.')}$`,
-    's',
-  );
-
-const compare = (left: unknown, right: unknown): number => {
-  if (left instanceof Date && right instanceof Date) return left.getTime() - right.getTime();
-  if (typeof left === 'number' && typeof right === 'number') return left - right;
-  if (typeof left === 'bigint' && typeof right === 'bigint') {
-    return left < right ? -1 : left > right ? 1 : 0;
-  }
-  const [a, b] = [String(left), String(right)];
-  return a < b ? -1 : a > b ? 1 : 0;
-};
-
 /** Lexicographic over the sort keys, direction applied. `> 0` means "after the cursor". */
-const compareToSeek = (plan: QueryPlan, row: unknown, seek: readonly unknown[]): number => {
+const compareToSeek = <Row>(
+  entity: EntityCore<Row>,
+  plan: QueryPlan,
+  row: unknown,
+  seek: readonly unknown[],
+): number => {
   for (const [index, entry] of plan.orderBy.entries()) {
-    const order = compare(valueAt(row, entry.column), seek[index]);
+    // The COLUMN's kind, not the value's: the seek was revived from the same kind (`cursor.ts`),
+    // so a `bigint` column compares its stored decimal string against a revived `BigInt` as one
+    // number instead of as two pieces of text.
+    const order = compareByKind(
+      kindOf(entity, entry.column),
+      valueAt(row, entry.column),
+      seek[index],
+    );
     if (order !== 0) return entry.direction === 'desc' ? -order : order;
   }
   return 0;
@@ -232,7 +191,7 @@ const afterCursor = <Row>(
 ): number => {
   const seek = seekFrom(entity, plan);
   if (seek === undefined) return 0;
-  const start = found.findIndex((row) => compareToSeek(plan, row, seek) > 0);
+  const start = found.findIndex((row) => compareToSeek(entity, plan, row, seek) > 0);
   return start === -1 ? found.length : start;
 };
 
@@ -245,9 +204,20 @@ export const memoryRepo = <Row>(
   entity: EntityCore<Row>,
   seed: readonly Row[] = [],
 ): MemoryRepo<Row> => {
-  const keyOf = (row: unknown): string =>
-    entity.$primaryKey.map((property) => String(field(row, property))).join('
');
-  const rows = new Map<string, Row>(seed.map((row) => [keyOf(row), row]));
+  /**
+   * A stored row's key, spelled the way `batch-read.ts` spells an id — because Postgres compares a
+   * `uuid` as a VALUE and prints it lower-cased, so `findById(UPPER)` reads the row there while
+   * `String(...)` missed it here: `null` from a read and `X_NOT_FOUND` from a write, against a row
+   * that exists, reachable from a path parameter, a client-supplied id or a legacy import.
+   */
+  const storeKey = (row: unknown): string =>
+    entity.$primaryKey
+      .map((property) => keyOf(kindOf(entity, property) ?? '', field(row, property)))
+      .join('
');
+  /** The same key, from the id a caller named rather than from a row it has in hand. */
+  const idStoreKey = (id: unknown, operation: string): string =>
+    keyOf(kindOf(entity, singleKeyOf(entity, operation)) ?? '', id);
+  const rows = new Map<string, Row>(seed.map((row) => [storeKey(row), row]));
 
   const rowsOf = (plan: QueryPlan, args: FindManyArgs): Row[] => {
     const visible = (row: Row): boolean =>
@@ -256,11 +226,15 @@ export const memoryRepo = <Row>(
       field(row, SOFT_DELETE_COLUMN) === null ||
       field(row, SOFT_DELETE_COLUMN) === undefined;
     return [...rows.values()]
-      .filter((row) => plan.where.every((predicate) => matches(row, predicate)))
+      .filter((row) => plan.where.every((predicate) => matchesPredicate(entity, row, predicate)))
       .filter(visible)
       .sort((left, right) => {
         for (const entry of plan.orderBy) {
-          const order = compare(valueAt(left, entry.column), valueAt(right, entry.column));
+          const order = compareByKind(
+            kindOf(entity, entry.column),
+            valueAt(left, entry.column),
+            valueAt(right, entry.column),
+          );
           if (order !== 0) return entry.direction === 'desc' ? -order : order;
         }
         return 0;
@@ -283,7 +257,7 @@ export const memoryRepo = <Row>(
     // out of this tenant is refused by the same call that refuses an insert into another one.
     assertRowTenant(entity.$name, entity.$tenantColumn, operation, row);
     entity.$assert(row);
-    const key = keyOf(row);
+    const key = storeKey(row);
     const previous = rows.get(key);
     options?.tx?.onRollback(() => {
       if (previous === undefined) rows.delete(key);
@@ -297,7 +271,7 @@ export const memoryRepo = <Row>(
   // to name a row, so `update`/`delete` resolve through a plan rather than through the map.
   const addressed = (id: string, options: RepoOptions | undefined, operation: string): Row => {
     const plan = idPlan(entity, id, options, operation);
-    const current = rows.get(id);
+    const current = rows.get(idStoreKey(id, operation));
     // A soft-deleted row is hidden from writes too — `delete` on one is `X_NOT_FOUND`, not a
     // second stamp, which is what the Postgres driver's `deleted_at is null` clause already says.
     const hidden =
@@ -308,7 +282,7 @@ export const memoryRepo = <Row>(
     if (
       current === undefined ||
       hidden ||
-      !plan.where.every((predicate) => matches(current, predicate))
+      !plan.where.every((predicate) => matchesPredicate(entity, current, predicate))
     ) {
       throw notFound(entity.$name, id);
     }
@@ -334,7 +308,8 @@ export const memoryRepo = <Row>(
       const more = start + page.length < found.length;
       return {
         rows: page,
-        nextCursor: more && last !== undefined ? cursorFor(entity, plan, last, keyOf(last)) : null,
+        nextCursor:
+          more && last !== undefined ? cursorFor(entity, plan, last, storeKey(last)) : null,
       };
     },
 
@@ -407,14 +382,10 @@ export const memoryRepo = <Row>(
       const current = addressed(id, options, 'delete');
       // Soft delete hides the row without losing it; the column's presence is the switch.
       if (entity.$softDelete) {
-        write(
-          Object.assign({}, current, { [SOFT_DELETE_COLUMN]: systemClock.now() }),
-          options,
-          'delete',
-        );
+        write(Object.assign({}, current, { [SOFT_DELETE_COLUMN]: entityNow() }), options, 'delete');
         return;
       }
-      const key = keyOf(current);
+      const key = storeKey(current);
       options?.tx?.onRollback(() => rows.set(key, current));
       rows.delete(key);
     },
@@ -428,13 +399,13 @@ export const memoryRepo = <Row>(
       for (const row of doomed) {
         if (entity.$softDelete) {
           write(
-            Object.assign({}, row, { [SOFT_DELETE_COLUMN]: systemClock.now() }),
+            Object.assign({}, row, { [SOFT_DELETE_COLUMN]: entityNow() }),
             options,
             'deleteWhere',
           );
           continue;
         }
-        const key = keyOf(row);
+        const key = storeKey(row);
         options?.tx?.onRollback(() => rows.set(key, row));
         rows.delete(key);
       }
@@ -471,7 +442,7 @@ export const memoryRepo = <Row>(
 
     reset() {
       rows.clear();
-      for (const row of seed) rows.set(keyOf(row), row);
+      for (const row of seed) rows.set(storeKey(row), row);
     },
   };
 };

package/src/seed.ts

@@ -4,7 +4,8 @@
 // every machine), `upsert` where the table owns it and a natural key is all there is.
 
 import { createHash } from 'node:crypto';
-import { type Environment, resolveEnvironment, systemClock } from '@ultimat3/core';
+import { type Environment, resolveEnvironment } from '@ultimat3/core';
+import { entityNow } from './clock';
 import type { Driver } from './database';
 import { memoryDriver } from './database';
 import { type EntityCore, SOFT_DELETE_COLUMN } from './entity';
@@ -325,7 +326,7 @@ export const defineSeed = (
         },
 
         id: seedId,
-        now: systemClock.now(),
+        now: entityNow(),
         environment: resolveEnvironment({ env: options.env }),
         tier,
         dryRun,

package/src/types.ts

@@ -15,20 +15,30 @@
  * and a `bytea` blob cannot be declared at all without them, and an entity that cannot be declared
  * is a rewrite instead of an adoption.
  */
-export type ColumnKind =
-  | 'uuid'
-  | 'text'
-  | 'char'
-  | 'boolean'
-  | 'integer'
-  | 'bigint'
-  | 'numeric'
-  | 'timestamptz'
-  | 'date'
-  | 'jsonb'
-  | 'bytea'
-  | 'array'
-  | 'money';
+export const COLUMN_KINDS = [
+  'uuid',
+  'text',
+  'char',
+  'boolean',
+  'integer',
+  'bigint',
+  'numeric',
+  'timestamptz',
+  'date',
+  'jsonb',
+  'bytea',
+  'array',
+  'money',
+] as const;
+
+/**
+ * Derived from the array and never written twice — the same shape `PRIMITIVE_KINDS` in
+ * `@ultimat3/core`'s `registrar.ts` uses, and for the same reason: a package that has to answer
+ * "one case per kind" needs a RUNTIME list, and a list written beside the type is one that drifts
+ * from it. `@ultimat3/query`'s `shape-order.test.ts` spelled its own out and counted nine against
+ * thirteen — `9 === 9`, a test that could not fail.
+ */
+export type ColumnKind = (typeof COLUMN_KINDS)[number];
 
 export type ColumnDefault =
   | { readonly kind: 'value'; readonly value: string | number | boolean | null }
@@ -219,6 +229,38 @@ export type Insertable<C extends ColumnMap> = {
   readonly [K in DefaultedKeys<C> | NullableKeys<C>]?: InputOf<TypeOf<C[K]>>;
 };
 
+/**
+ * A patch or a filter: every property optional, **and every property allowed to be present and
+ * `undefined`**.
+ *
+ * `Partial<Row>` cannot say the second half. Under `exactOptionalPropertyTypes` — which this repo
+ * has on — `{ k?: T }` means "absent, or a `T`", so `{ postId: undefined }` is a type error, and
+ * that is the ONE value every filtered write in this package is built to refuse:
+ *
+ * - `plan.ts`'s `namedColumns` drops `value !== undefined`, so `deleteWhere({ postId: undefined })`
+ *   yields no predicate and throws `X_WRITE_UNFILTERED` rather than deleting the table. That
+ *   refusal exists for exactly one caller — a variable that came back `undefined` — and
+ *   `Partial<Row>` made the caller unable to spell it and the test unable to prove it.
+ * - `updateWhere(filter, { createdAt: undefined })` is `X_PATCH_EMPTY`, one argument over.
+ * - `bulk-write.ts`'s `owns()` is `Object.hasOwn`, so for a batch a present-`undefined` property
+ *   IS a named column — the opposite reading, deliberately, and equally unspellable.
+ *
+ * A type that forbids the value its own runtime is written to catch is a type that documents
+ * nothing: `bulk-write.test.ts` carried `as Partial<Item>` with the comment
+ * "`exactOptionalPropertyTypes` is why it takes a cast to say", which is the defect written down.
+ *
+ * Money goes through `InputOf`, for the reason `Insertable` does: a patch is a WRITE, and money's
+ * write shape is the wider one. `conflictKeyOf`'s own `cellKey` renders a `bigint` minor unit
+ * (`${part}n`), so refusing one here would have been a type refusing a value one function down
+ * spells out how to serialise. The row's own type stays in the union rather than being replaced by
+ * `InputOf<Row[K]>`: a conditional type over an unresolved `Row` never reduces, so `Row` itself
+ * stopped being assignable to its own patch and every internal caller reddened. Both spellings are
+ * accepted here, which is the honest statement anyway — a patch may carry either.
+ */
+export type RowPatch<Row> = {
+  readonly [K in keyof Row]?: Row[K] | InputOf<Row[K]> | undefined;
+};
+
 export interface IndexDef {
   readonly name: string;
   readonly columns: readonly string[];