@ultimat3/entity 1.2.0 → 3.0.0

package/src/relations.ts

@@ -0,0 +1,212 @@
+// The relations an entity already declared. A `.references(() => orgs.id)` is a foreign key AND
+// an association; reading it as both is what lets a preload exist with no second declaration
+// syntax to keep in sync with the first — the FK already written IS the relation.
+//
+// Derivation, plus the one place that reads the registry for it: a `hasMany` is a fact about the
+// whole set, and no single entity can see the foreign keys pointing AT it. How an edge is
+// traversed is a separate decision, made by its own caller.
+//
+// The edges come in already resolved, as `RegistryEntry.references()` records. Nothing here
+// parses `describe()`'s `"<table>.<column>"` rendering: that string carries physical names only,
+// and a traversal reads row properties.
+
+import { invariantViolated, preloadUnknownRelation } from './errors';
+import type { ReferenceDescription, RegistryEntry } from './registry';
+import { registeredEntities, registryGeneration } from './registry';
+
+export type RelationKind = 'belongsTo' | 'hasMany';
+
+/**
+ * One edge, read from one side. `local` is always a property of `from` and `remote` always a
+ * property of `to`, whichever way the edge is being read — so a traversal is one sentence in both
+ * directions: collect `localKey` off the rows in hand, then ask `to` for the rows whose
+ * `remoteColumn` is in that set.
+ */
+export interface Relation {
+  readonly kind: RelationKind;
+  /** Unique within `from`. This is the name a preload names. */
+  readonly name: string;
+  /** The entity the relation hangs off — the side holding the rows you already have. */
+  readonly from: string;
+  /** The entity the related rows come from. May be outside the set the map was built over. */
+  readonly to: string;
+  readonly localKey: string;
+  readonly localColumn: string;
+  readonly remoteKey: string;
+  readonly remoteColumn: string;
+  /** The FK column is nullable, so a `belongsTo` resolving to nothing is data, not a broken FK. */
+  readonly nullable: boolean;
+}
+
+/** Every relation reachable from one entity, by name. ONE flat namespace across both kinds. */
+export type EntityRelations = Readonly<Record<string, Relation>>;
+
+/** Keyed by entity name, in sorted order — a projection is a build input and must diff cleanly. */
+export type RelationMap = Readonly<Record<string, EntityRelations>>;
+
+interface ForeignKey extends ReferenceDescription {
+  /** The entity that declared `references()`. Never the target. */
+  readonly entity: string;
+}
+
+interface Candidate {
+  /** Taken when nothing else in this entity wants it. */
+  readonly preferred: string;
+  /** Taken by EVERY member of a group whose `preferred` collides — never by one of them. */
+  readonly fallback: string;
+  readonly relation: Omit<Relation, 'name'>;
+}
+
+const ID_SUFFIX = 'Id';
+
+/** `authorId` -> `author`: the FK's own name, minus the part that only says "this is a key". */
+const withoutId = (property: string): string =>
+  property.length > ID_SUFFIX.length && property.endsWith(ID_SUFFIX)
+    ? property.slice(0, -ID_SUFFIX.length)
+    : property;
+
+const capitalize = (value: string): string => value.charAt(0).toUpperCase() + value.slice(1);
+
+const foreignKeysOf = (entry: RegistryEntry): readonly ForeignKey[] =>
+  entry.references().map((reference) => ({ entity: entry.name, ...reference }));
+
+const belongsTo = (fk: ForeignKey): Candidate => ({
+  preferred: withoutId(fk.property),
+  fallback: fk.property,
+  relation: {
+    kind: 'belongsTo',
+    from: fk.entity,
+    to: fk.targetEntity,
+    localKey: fk.property,
+    localColumn: fk.column,
+    remoteKey: fk.targetProperty,
+    remoteColumn: fk.targetColumn,
+    nullable: fk.nullable,
+  },
+});
+
+const hasMany = (fk: ForeignKey): Candidate => ({
+  preferred: fk.entity,
+  fallback: `${fk.entity}By${capitalize(withoutId(fk.property))}`,
+  relation: {
+    kind: 'hasMany',
+    from: fk.targetEntity,
+    to: fk.entity,
+    localKey: fk.targetProperty,
+    localColumn: fk.targetColumn,
+    remoteKey: fk.property,
+    remoteColumn: fk.column,
+    nullable: fk.nullable,
+  },
+});
+
+/** Where the FK is written, whichever side the relation is read from — what a rename must edit. */
+const declaredAt = (relation: Omit<Relation, 'name'>): string =>
+  relation.kind === 'belongsTo'
+    ? `${relation.from}.${relation.localKey}`
+    : `${relation.to}.${relation.remoteKey}`;
+
+/**
+ * Two tiers, and the second is taken by the whole colliding group rather than by the newcomer:
+ * whether `posts` keeps its name must not depend on which foreign key was declared first.
+ *
+ * The tiers resolve every realistic schema. Within one group a `belongsTo` falls back to its own
+ * property (`author` or `authorId`) and a `hasMany` to `<source>By<Fk>`, which cannot be equal;
+ * two `belongsTo` differ by property and two `hasMany` share a source, so they differ by FK. What
+ * survives is a name a THIRD group also kept, or two FKs on one entity whose names differ only by
+ * an `Id` suffix — both are one rename away, and both are refused rather than silently collapsed
+ * into one relation.
+ */
+const named = (entityName: string, candidates: readonly Candidate[]): EntityRelations => {
+  const wanted = new Map<string, number>();
+  for (const candidate of candidates) {
+    wanted.set(candidate.preferred, (wanted.get(candidate.preferred) ?? 0) + 1);
+  }
+  const relations = new Map<string, Relation>();
+  for (const candidate of candidates) {
+    const contested = (wanted.get(candidate.preferred) ?? 0) > 1;
+    const name = contested ? candidate.fallback : candidate.preferred;
+    const taken = relations.get(name);
+    if (taken !== undefined) {
+      throw invariantViolated(
+        entityName,
+        'relations',
+        `${declaredAt(taken)} and ${declaredAt(candidate.relation)} both resolve to the relation ` +
+          `"${name}" — rename one of the two columns`,
+      );
+    }
+    relations.set(name, { ...candidate.relation, name });
+  }
+  return Object.fromEntries([...relations].sort(([a], [b]) => (a < b ? -1 : 1)));
+};
+
+/**
+ * Every relation among these entities, keyed by entity name.
+ *
+ * A `belongsTo` is a fact about the entity's own column, so it is recorded even when its target
+ * is outside the set — the caller resolves `to` when it traverses. A `hasMany` is a fact about a
+ * pair, so only the inbound keys of entities that were passed in can produce one.
+ */
+export const relationsOf = (entries: readonly RegistryEntry[]): RelationMap => {
+  // By name: the registry already refuses two entities with one name, so the same entry handed
+  // in twice is one entity — not two sets of foreign keys colliding with themselves.
+  const unique = new Map(entries.map((entry) => [entry.name, entry]));
+  // One pass, filed under both ends as it goes. Rescanning every foreign key once per entity is
+  // the whole schema squared, paid again on the first read after every late registration.
+  const outbound = new Map<string, Candidate[]>();
+  const inbound = new Map<string, Candidate[]>();
+  for (const name of unique.keys()) {
+    outbound.set(name, []);
+    inbound.set(name, []);
+  }
+  for (const entry of unique.values()) {
+    for (const fk of foreignKeysOf(entry)) {
+      outbound.get(fk.entity)?.push(belongsTo(fk));
+      // A target outside the set contributes no `hasMany`: nothing here holds its inbound keys.
+      inbound.get(fk.targetEntity)?.push(hasMany(fk));
+    }
+  }
+  const map: Record<string, EntityRelations> = {};
+  for (const name of [...unique.keys()].sort()) {
+    // Outbound before inbound, so a collision resolves the same way whichever pass found it.
+    map[name] = named(name, [...(outbound.get(name) ?? []), ...(inbound.get(name) ?? [])]);
+  }
+  return map;
+};
+
+/** Rebuilt on the first read after any registration, never on a read that changed nothing. */
+let cached: { readonly generation: number; readonly map: RelationMap } | undefined;
+
+/**
+ * The relations of every registered entity — the set query time means by "the relations".
+ *
+ * Memoised against the registry generation rather than computed once: a schema module imported
+ * after the first read registers one more entity, and a `hasMany` that entity contributes would
+ * otherwise be missing for the rest of the process. Deriving costs one pass over the foreign keys,
+ * so a read that follows a registration simply pays it again.
+ */
+export const relationMap = (): RelationMap => {
+  const generation = registryGeneration();
+  if (cached !== undefined && cached.generation === generation) return cached.map;
+  const map = relationsOf(registeredEntities());
+  cached = { generation, map };
+  return map;
+};
+
+/** Every relation reachable from one entity. An unregistered name has none — that is not an error. */
+export const relationsFor = (entityName: string): EntityRelations =>
+  relationMap()[entityName] ?? {};
+
+/**
+ * One relation, by the name a caller wrote. A preload names its relation as a *string*, so an
+ * unknown one is only actionable if the refusal carries the names that do exist — and they exist
+ * nowhere to go and read, being derived from `references()` rather than declared.
+ */
+export const relationNamed = (entityName: string, name: string): Relation => {
+  const relations = relationsFor(entityName);
+  const relation = relations[name];
+  if (relation === undefined) {
+    throw preloadUnknownRelation(entityName, name, Object.keys(relations));
+  }
+  return relation;
+};

package/src/repo.ts

@@ -7,11 +7,17 @@
 //     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 { conflictKeyOf, conflictKeys, upsertPlan } from './bulk-write';
+import { narrowMoney } from './columns';
+import { countsFrom, groupColumnOf } from './count-by';
 import { cursorFor, seekFrom, valueAt } from './cursor';
 import { type EntityCore, SOFT_DELETE_COLUMN } from './entity';
 import { notFound } from './errors';
-import { idPlan, readPlan, singleKeyOf } from './plan';
+import { deletePlan, idPlan, readPlan, singleKeyOf, updatePlan } from './plan';
 import type { Predicate, QueryPlan, SortKey } from './tenancy';
+import { assertRowTenant } from './tenancy';
+import type { IdOf } from './types';
 
 export interface Tx {
   readonly id: string;
@@ -21,10 +27,31 @@ export interface Tx {
 
 export interface RepoOptions {
   readonly tx?: Tx;
-  /** Required for tenant-scoped entities; the guard throws without it. */
+  /**
+   * The tenant, and never the authority for it: inside a request the plan is scoped to the acting
+   * actor's org whether this is passed or not, and a value that disagrees with the actor is
+   * `X_TENANCY_ACTOR_MISMATCH` rather than the tenant the query runs under. It is still required
+   * outside every request context — a script has no actor to derive from.
+   */
   readonly orgId?: string;
 }
 
+/** What `upsertAll` does with a row that lands on one already stored. */
+export interface UpsertArgs<T = unknown> extends RepoOptions {
+  /**
+   * The unique constraint a collision is judged against, named as entity properties — never a
+   * constraint name, which is a migration artefact this layer cannot resolve. At least one column:
+   * "any constraint" is not something a caller can reason about.
+   */
+  readonly onConflict: readonly (keyof T & string)[];
+  /**
+   * `'update'` (the default) overwrites the stored row with the incoming values, except the
+   * conflict target and the primary key. `'nothing'` leaves the stored row exactly as it is and
+   * omits it from the result, so the result is always "the rows this call wrote".
+   */
+  readonly onMatch?: 'update' | 'nothing';
+}
+
 export interface FindManyArgs extends RepoOptions {
   readonly where?: readonly Predicate[];
   readonly orderBy?: readonly SortKey[];
@@ -43,14 +70,69 @@ export interface Page<T> {
 /**
  * `T` defaults to `unknown` so a row-agnostic consumer (the generated admin, the manifest
  * emitter) can name the shape without knowing the entity.
+ *
+ * The id parameters are `IdOf<T>`, not `string`: an entity that declared `uuid<PostId>()` is
+ * addressed by a `PostId` and by nothing else. `IdOf<unknown>` and `IdOf<{ id: string }>` are
+ * both `string`, so a row-agnostic consumer sees the signature it always saw.
  */
 export interface Repo<T = unknown> {
-  findById(id: string, options?: RepoOptions): Promise<T | null>;
+  findById(id: IdOf<T>, options?: RepoOptions): Promise<T | null>;
   findMany(args?: FindManyArgs): Promise<Page<T>>;
   insert(values: T, options?: RepoOptions): Promise<T>;
-  update(id: string, patch: Partial<T>, options?: RepoOptions): Promise<T>;
-  delete(id: string, options?: RepoOptions): Promise<void>;
+  /**
+   * Many rows, one statement — the bulk form a per-row `insert` loop is the N+1 of. Resolves with
+   * the rows as stored, defaults included, in the order given; an empty batch writes nothing and
+   * resolves with `[]`. Nothing here resolves a collision — `upsertAll` is the call that does.
+   * Past Postgres's bind count the batch becomes several statements, so wrap it in
+   * `withTransaction` when all-or-nothing matters.
+   */
+  insertAll(rows: readonly T[], options?: RepoOptions): Promise<readonly T[]>;
+  /**
+   * `insertAll` that resolves a collision instead of failing on it. Resolves with the rows this
+   * call actually wrote — under `onMatch: 'nothing'` a row already stored is skipped and absent,
+   * 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>;
+  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
+   * with a composite primary key, where `delete(id)` cannot name one. Never `void`: a caller has
+   * 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>;
+  /**
+   * 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>;
   count(args?: FindManyArgs): Promise<number>;
+  /**
+   * The grouped count: one statement, one entry per distinct value of `column`, over exactly the
+   * rows `count(args)` counts — the aggregate a `count()` per row is the N+1 of. A value nothing
+   * matched is absent rather than `0`: the caller knows which keys they asked about, and a map
+   * that invents them cannot say which ones the table has never seen.
+   *
+   * `column` is a property name, spelled as `select` spells one — the typed form is
+   * `ReadBuilder.countBy`, which knows the row. Ordered by count, biggest group first.
+   */
+  countBy(column: string, args?: FindManyArgs): Promise<ReadonlyMap<unknown, number>>;
+}
+
+/**
+ * What `memoryRepo()` returns: a `Repo`, plus the one member a database-backed repository has no
+ * business having. TEST SEAM — nothing on the framework's own request path calls `reset()`.
+ */
+export interface MemoryRepo<Row> extends Repo<Row> {
+  /**
+   * Drops every stored row, in place. In place is the whole point: `database()` resolves each
+   * table's repository once, so a test harness that replaced the driver's repositories would be
+   * emptying objects the app under test no longer reads.
+   */
+  reset(): void;
 }
 
 export interface Transactor {
@@ -101,12 +183,20 @@ const matches = (row: unknown, predicate: Predicate): boolean => {
   }
 };
 
-/** `%` and `_` are the wildcards; everything else in the pattern is literal, as in SQL. */
+/**
+ * `%` 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('%', '.*')
+      .replaceAll(/%+/g, '.*')
       .replaceAll('_', '.')}$`,
     's',
   );
@@ -151,7 +241,10 @@ const afterCursor = <Row>(
  * migration and tests use it everywhere. Postgres is the production driver and implements
  * this same interface.
  */
-export const memoryRepo = <Row>(entity: EntityCore<Row>, seed: readonly Row[] = []): Repo<Row> => {
+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]));
@@ -179,7 +272,16 @@ export const memoryRepo = <Row>(entity: EntityCore<Row>, seed: readonly Row[] =
     return { plan, found: rowsOf(plan, args) };
   };
 
-  const write = (row: Row, options: RepoOptions | undefined): Row => {
+  const write = (given: Row, options: RepoOptions | undefined, operation: string): Row => {
+    // `MoneyInput` lets a writer hand a `bigint`; a stored row holds the value type. The Postgres
+    // driver narrows in `bindValues` and reads its answer back through `returning *`, so without
+    // this an in-memory row would be the one row in the framework `JSON.stringify` refuses.
+    const row = narrowMoney(entity.$columns, given);
+    // Beside `$assert`, and before the row lands: a write is judged by the tenant it names as well
+    // as by the invariants it declares, and the Postgres driver runs the same pair in `writeRows`.
+    // `update` reaches here with the STORED row merged under its patch, so a patch that moves a 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 previous = rows.get(key);
@@ -237,18 +339,79 @@ export const memoryRepo = <Row>(entity: EntityCore<Row>, seed: readonly Row[] =
     },
 
     async insert(values, options) {
-      return write(values, options);
+      return write(values, options, 'insert');
+    },
+
+    async insertAll(batch, options) {
+      // The whole batch is judged before any of it lands: Postgres refuses the statement as one,
+      // so a row an invariant rejects — or one naming a tenant this actor may not write — must not
+      // leave the rows before it stored here either. `write` re-checks both per row; this loop is
+      // what makes the batch all-or-nothing, which is the half a per-row check cannot give.
+      for (const row of batch) {
+        assertRowTenant(entity.$name, entity.$tenantColumn, 'insertAll', row);
+        entity.$assert(row);
+      }
+      return batch.map((row) => write(row, options, 'insertAll'));
+    },
+
+    async upsertAll(batch, args) {
+      // The INCOMING rows, judged before any of them is matched: under `onMatch: 'nothing'` a
+      // colliding row is skipped and never reaches `write()`, so checking only what lands would
+      // let a row naming another tenant through whenever it happened to collide.
+      for (const row of batch) {
+        assertRowTenant(entity.$name, entity.$tenantColumn, 'upsertAll', row);
+        entity.$assert(row);
+      }
+      const plan = upsertPlan(entity, batch, args.onConflict, args.onMatch ?? 'update');
+      const keys = conflictKeys(entity, plan, batch);
+      // The stored rows under the same key, so "does this collide" is the question the unique
+      // index answers in Postgres and not a scan per row. A soft-deleted row still occupies its
+      // key here, because the index it would collide with there is not partial either — and a row
+      // whose target holds a null occupies none, because the index is `NULLS DISTINCT`.
+      const stored = new Map<string, Row>();
+      for (const row of rows.values()) {
+        const key = conflictKeyOf(entity, plan.on, row);
+        if (key !== undefined) stored.set(key, row);
+      }
+      const written: Row[] = [];
+      for (const [position, row] of batch.entries()) {
+        const key = keys[position];
+        const existing = key === undefined ? undefined : stored.get(key);
+        // `do nothing` writes no row, and `returning *` therefore names none: a skipped row is
+        // absent from the result rather than present and unchanged.
+        if (existing !== undefined && plan.set.length === 0) continue;
+        const merged =
+          existing === undefined
+            ? row
+            : Object.assign(
+                {},
+                existing,
+                Object.fromEntries(plan.set.map((property) => [property, field(row, property)])),
+              );
+        // `UpsertArgs extends RepoOptions`, so the args ARE the options — one bag, and a `tx`
+        // passed to an upsert registers its undo exactly as it does for every other write here.
+        const result = write(merged, args, 'upsertAll');
+        // Filed as it lands, so a later row of the same batch collides with an earlier one exactly
+        // as it would with a row the request stored a moment before it.
+        if (key !== undefined) stored.set(key, result);
+        written.push(result);
+      }
+      return written;
     },
 
     async update(id, patch, options) {
-      return write(Object.assign({}, addressed(id, options, 'update'), patch), options);
+      return write(Object.assign({}, addressed(id, options, 'update'), patch), options, 'update');
     },
 
     async delete(id, options) {
       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]: new Date() }), options);
+        write(
+          Object.assign({}, current, { [SOFT_DELETE_COLUMN]: systemClock.now() }),
+          options,
+          'delete',
+        );
         return;
       }
       const key = keyOf(current);
@@ -256,9 +419,60 @@ export const memoryRepo = <Row>(entity: EntityCore<Row>, seed: readonly Row[] =
       rows.delete(key);
     },
 
+    async deleteWhere(filter, options) {
+      // `rowsOf` is the read path: the same predicates, the same tenant scoping, and the same
+      // soft-delete visibility. A row already stamped is not matched, so a second call cannot
+      // move `deletedAt` forward — which is what the Postgres driver's `deleted_at is null`
+      // clause says there.
+      const doomed = rowsOf(deletePlan(entity, filter, options, 'deleteWhere'), {});
+      for (const row of doomed) {
+        if (entity.$softDelete) {
+          write(
+            Object.assign({}, row, { [SOFT_DELETE_COLUMN]: systemClock.now() }),
+            options,
+            'deleteWhere',
+          );
+          continue;
+        }
+        const key = keyOf(row);
+        options?.tx?.onRollback(() => rows.set(key, row));
+        rows.delete(key);
+      }
+      return doomed.length;
+    },
+
+    async updateWhere(filter, patch, options) {
+      // `rowsOf` again, so a soft-deleted row is as unreachable here as it is through
+      // `addressed()` — patching a row the app has already deleted is not an update, it is a
+      // resurrection nobody asked for. `write` re-asserts the invariants on each result.
+      const found = rowsOf(updatePlan(entity, filter, patch, options, 'updateWhere'), {});
+      for (const row of found) write(Object.assign({}, row, patch), options, 'updateWhere');
+      return found.length;
+    },
+
     async count(args = {}) {
       return select(args, 'count').found.length;
     },
+
+    async countBy(column, args = {}) {
+      // Refused before a row is read, and by the same function the Postgres driver calls: a column
+      // a map cannot be keyed by is that mistake in both drivers or in neither.
+      groupColumnOf(entity, column, 'countBy');
+      const { found } = select(args, 'countBy');
+      const groups = new Map<unknown, number>();
+      for (const row of found) {
+        // `?? null`, so a property this row never carried lands in the same group Postgres puts a
+        // NULL row in — and `0`, `''` and `false` stay the values they are.
+        const value = field(row, column) ?? null;
+        groups.set(value, (groups.get(value) ?? 0) + 1);
+      }
+      return countsFrom(entity, column, 'countBy', [...groups]);
+    },
+
+    reset() {
+      rows.clear();
+      for (const row of seed) rows.set(keyOf(row), row);
+    },
   };
 };