@ultimat3/entity 1.2.0 → 2.0.0

package/src/plan.ts

@@ -4,15 +4,28 @@
 // driver applies is worse than none: the test passes and production leaks another tenant's rows.
 
 import type { EntityCore } from './entity';
-import { invariantViolated } from './errors';
+import { EntityError, invariantViolated, patchEmpty, writeUnfiltered } from './errors';
 import type { FindManyArgs, RepoOptions } from './repo';
-import type { Predicate, QueryPlan } from './tenancy';
-import { assertScoped } from './tenancy';
+import type { Predicate, QueryPlan, SortKey } from './tenancy';
+import { scopedPlan } from './tenancy';
 
 /** A page is bounded by default; an unbounded read is a production incident waiting for traffic. */
 export const DEFAULT_PAGE_SIZE = 50;
 
-/** Id-addressed operations need exactly one key. A composite key is a `findMany({ where })`. */
+/**
+ * And a page the caller DID bound is bounded too. The default above only covers a read nobody
+ * sized; `limit(input.pageSize)` on a number that arrived over the wire is the same incident with
+ * an argument in front of it — the statement binds it, the server answers with every row, and the
+ * driver allocates and decodes all of them before the handler sees one. So the ceiling is a memory
+ * bound, not a preference, and it lives here rather than in either driver because both read one
+ * number or they stop meaning the same thing.
+ *
+ * Above `DEFAULT_BACKFILL_BATCH` (1,000) by an order of magnitude on purpose: a sweep declaring a
+ * wider batch is a tuning decision, and only a page nobody could have meant is refused.
+ */
+export const MAX_PAGE_SIZE = 10_000;
+
+/** Id-addressed operations need exactly one key. A composite key is addressed by every column. */
 export const singleKeyOf = <Row>(entity: EntityCore<Row>, operation: string): string => {
   const [only] = entity.$primaryKey;
   if (entity.$primaryKey.length !== 1 || only === undefined) {
@@ -20,45 +33,82 @@ export const singleKeyOf = <Row>(entity: EntityCore<Row>, operation: string): st
       entity.$name,
       operation,
       `${entity.$name} has a composite primary key (${entity.$primaryKey.join(', ')}) — ` +
-        'use findMany({ where }) instead of an id',
+        // The old wording sent every reader, whatever they were doing, to `findMany({ where })`,
+        // which is a read: a composite-key row looked unwritable because the one error that fires
+        // on `delete(id)`/`update(id, …)` named no write. Every surface gets named now.
+        'name every key column: findMany({ where }) to read, ' +
+        'updateWhere({ … }, patch) to patch, deleteWhere({ … }) to remove',
     );
   }
   return only;
 };
 
+/**
+ * The sort keys a read actually runs with: the caller's, then whatever the primary key still adds.
+ * The primary key is always the final key — a cursor needs a total order, or two rows with the same
+ * sort value straddle a page boundary.
+ *
+ * Exported because a chain can be judged before it runs: `inBatches()` refuses an ordering that
+ * cannot carry a cursor, and it has to be looking at the order the driver will send rather than at
+ * the one the caller typed.
+ */
+export const totalOrder = <Row>(
+  entity: EntityCore<Row>,
+  ordered: readonly SortKey[],
+): readonly SortKey[] => [
+  ...ordered,
+  ...entity.$primaryKey
+    .filter((property) => !ordered.some((entry) => entry.column === property))
+    .map((property) => ({ column: property, direction: 'asc' as const })),
+];
+
+/**
+ * What a page size has to be before a statement carries it: rows, whole, at least one and at most
+ * `MAX_PAGE_SIZE`. The three refusals `assertBatchable` already applies to `inBatches(size)`, and
+ * deliberately the same code and the same voice — `limit(0)` and `inBatches(0)` are one mistake in
+ * two calls, and two codes would make a caller decide which to catch.
+ *
+ * Called from `limit()` on the chain, so the refusal lands on the line the author wrote, AND from
+ * `planFor` below, so `findMany({ limit })` straight at the repository — a generated client, a
+ * query, a third-party driver's caller — cannot route around it. One function, so the two can
+ * never disagree about what a page may be.
+ */
+export const assertPageSize = (entityName: string, rows: number): void => {
+  if (Number.isSafeInteger(rows) && rows >= 1 && rows <= MAX_PAGE_SIZE) return;
+  throw new EntityError({
+    code: 'X_INVARIANT_VIOLATED',
+    cause: `${entityName}.limit(${String(rows)}) — a page is a whole number of rows, at least one and at most ${MAX_PAGE_SIZE}`,
+    fix: `${entityName}.limit(${DEFAULT_PAGE_SIZE})   # or, to visit every row the filter matches, ${entityName}.inBatches(1000) — one page per statement, and never a table in memory`,
+  });
+};
+
 export const planFor = <Row>(entity: EntityCore<Row>, args: FindManyArgs): QueryPlan => {
+  if (args.limit !== undefined) assertPageSize(entity.$name, args.limit);
   const scoped =
     args.orgId === undefined || entity.$tenantColumn === null
       ? []
       : [{ column: entity.$tenantColumn, op: 'eq', value: args.orgId } satisfies Predicate];
-  const ordered = args.orderBy ?? [];
   return {
     entity: entity.$name,
     where: [...(args.where ?? []), ...scoped],
-    // The primary key is always the final sort key: a cursor needs a total order, or two
-    // rows with the same sort value straddle a page boundary.
-    orderBy: [
-      ...ordered,
-      ...entity.$primaryKey
-        .filter((property) => !ordered.some((entry) => entry.column === property))
-        .map((property) => ({ column: property, direction: 'asc' as const })),
-    ],
+    orderBy: totalOrder(entity, args.orderBy ?? []),
     limit: args.limit ?? DEFAULT_PAGE_SIZE,
     ...(args.cursor === undefined || args.cursor === null ? {} : { cursor: args.cursor }),
     ...(args.select === undefined ? {} : { select: args.select }),
   };
 };
 
-/** The plan for a read. Throws `X_TENANCY_UNSCOPED` before a single row is considered. */
+/**
+ * The plan for a read, scoped to the acting actor's tenant before a single row is considered. The
+ * caller's own `orgId` is not what scopes it — it is checked against the actor and refused when it
+ * disagrees (`X_TENANCY_ACTOR_MISMATCH`), because an `orgId` that arrived as action input is a
+ * value the caller chose.
+ */
 export const readPlan = <Row>(
   entity: EntityCore<Row>,
   args: FindManyArgs,
   operation: string,
-): QueryPlan => {
-  const plan = planFor(entity, args);
-  assertScoped(entity.$name, entity.$tenantColumn, operation, plan);
-  return plan;
-};
+): QueryPlan => scopedPlan(entity.$name, entity.$tenantColumn, operation, planFor(entity, args));
 
 /**
  * The plan for an id-addressed write. A write is a query too: without the same guard,
@@ -80,3 +130,63 @@ export const idPlan = <Row>(
     },
     operation,
   );
+
+/**
+ * The columns a filter or a patch actually names. An `undefined` property is dropped rather than
+ * used: `deleteWhere({ postId })` where `postId` came back undefined must reduce to an empty
+ * filter and be refused, never to `post_id = null` — or worse, on a driver that ignores the bind,
+ * to no predicate at all. `updateWhere(filter, { lastReadAt })` is the same mistake, one argument
+ * along, so both guards count the same way.
+ */
+export const namedColumns = (values: unknown): readonly (readonly [string, unknown])[] =>
+  Object.entries(
+    typeof values === 'object' && values !== null ? (values as Record<string, unknown>) : {},
+  ).filter(([, value]) => value !== undefined);
+
+/** The filter a filtered write is allowed to run with: never the empty one. */
+const boundedWhere = <Row>(
+  entity: EntityCore<Row>,
+  filter: Partial<Row>,
+  operation: string,
+): Predicate[] => {
+  const where = namedColumns(filter).map(
+    ([column, value]): Predicate => ({ column, op: 'eq', value }),
+  );
+  if (where.length === 0) throw writeUnfiltered(entity.$name, operation, entity.$primaryKey);
+  return where;
+};
+
+/**
+ * The plan for a filtered delete. The guard order is the point: an empty filter is refused before
+ * tenancy runs, so `deleteWhere({}, { orgId })` cannot pass by virtue of the org predicate the
+ * framework added — that predicate bounds the blast radius to one tenant, which is still every
+ * row that tenant has.
+ *
+ * `limit` is the read default and is not a bound on the delete: neither driver pages a delete.
+ */
+export const deletePlan = <Row>(
+  entity: EntityCore<Row>,
+  filter: Partial<Row>,
+  options: RepoOptions | undefined,
+  operation: string,
+): QueryPlan =>
+  readPlan(entity, { ...options, where: boundedWhere(entity, filter, operation) }, operation);
+
+/**
+ * The plan for a filtered update. Same filter guard as the delete, from the same function, plus
+ * the patch: a write that names no columns is refused rather than counted, because "4 rows
+ * updated" for a statement that set nothing is the answer nobody can act on.
+ */
+export const updatePlan = <Row>(
+  entity: EntityCore<Row>,
+  filter: Partial<Row>,
+  patch: Partial<Row>,
+  options: RepoOptions | undefined,
+  operation: string,
+): QueryPlan => {
+  const where = boundedWhere(entity, filter, operation);
+  if (namedColumns(patch).length === 0) {
+    throw patchEmpty(entity.$name, operation, Object.keys(entity.$columns));
+  }
+  return readPlan(entity, { ...options, where }, operation);
+};

package/src/preload.ts

@@ -0,0 +1,184 @@
+// Single responsibility: the eager preload. `preload('author')` is one extra
+// `select … where <key> in (…)` over the values the page already carries, and its rows attached to
+// that page under the relation's name — the declarative form of what a point lookup batches for
+// itself, and the exact line an N+1 warning tells the reader to write.
+//
+// Nothing new is declared: the relation is the `references()` already written (`relations.ts`).
+// The other table is read through the same driver this one came from, so a preload against the
+// in-memory driver means what a preload against Postgres means.
+
+import { keyOf, MAX_IDS_PER_STATEMENT, statementChunks } from './batch-read';
+import { valueAt } from './cursor';
+import type { EntityCore } from './entity';
+import { EntityError } from './errors';
+import type { Relation } from './relations';
+import type { Repo } from './repo';
+import type { Predicate } from './tenancy';
+
+/** The other side of a relation: the entity, and where its rows live. */
+export interface RelatedTable {
+  readonly entity: EntityCore;
+  readonly repo: Repo<unknown>;
+}
+
+/**
+ * How one table reaches another. `database()` supplies it over the set it was declared with and
+ * through the driver that set was given, so a preload reads rows from where this table's own rows
+ * come from — and a table can no more preload an entity the set never named than it can be indexed
+ * off `db` by one.
+ */
+export type RelatedTables = (entityName: string) => RelatedTable | undefined;
+
+/**
+ * Not `invariantViolated`: its fix opens `x entity explain`, which describes invariants nobody
+ * wrote here. What repairs this is one edit to the `database()` call — a relation whose other end
+ * is outside the set is a set that is missing an entity, and the preload declines rather than
+ * reaching around the handle for it.
+ */
+const unreachable = (entityName: string, relation: Relation): EntityError =>
+  new EntityError({
+    code: 'X_INVARIANT_VIOLATED',
+    cause: `${entityName}.preload('${relation.name}') reads ${relation.to}, which this table cannot reach — a table reads the entities its own database() call named`,
+    fix: `x entities list --json   # then widen the database() call that built db.${entityName} to database({ ${entityName}, ${relation.to} }, options)`,
+  });
+
+/**
+ * The tenant predicate the page was read under, carried onto the related read when BOTH entities
+ * are scoped by a column of that same name. Never across two differently-named tenant columns: a
+ * value that scopes one entity is a guess on another, and a guess here is a cross-tenant read.
+ *
+ * Both ends are checked, not just the target's. A source scoped by `workspaceId` may still carry
+ * an ordinary `orgId` predicate of its own — a filter, not its tenancy — and matching on the
+ * target's column name alone would lift that filter into the target's tenant scope and hand the
+ * preload rows from a tenant nobody proved this reader owns.
+ *
+ * Carrying nothing is not a failure of this function — the related read builds its own plan, so
+ * `assertScoped` refuses it there, in the words a caller can act on.
+ */
+const tenantScope = (
+  source: EntityCore,
+  target: EntityCore,
+  where: readonly Predicate[],
+): readonly Predicate[] => {
+  const column = target.$tenantColumn;
+  if (column === null || source.$tenantColumn !== column) return [];
+  const carried = where.find((predicate) => predicate.column === column && predicate.op === 'eq');
+  return carried === undefined ? [] : [carried];
+};
+
+/**
+ * Every row on the other side, in as few statements as the bind count allows: one per 500 keys —
+ * the bound a batched point read already lives under — and one more only when a page comes back
+ * genuinely full. A `belongsTo` over a page of 50 is exactly one statement.
+ *
+ * The page loop is what keeps a `hasMany` honest: a relation with more rows than one page holds
+ * costs another statement rather than silently returning the first page of them.
+ */
+const relatedRows = async (
+  target: RelatedTable,
+  relation: Relation,
+  values: readonly unknown[],
+  scope: readonly Predicate[],
+): Promise<readonly unknown[]> => {
+  const rows: unknown[] = [];
+  for (const chunk of statementChunks(values)) {
+    let cursor: string | null = null;
+    do {
+      const page = await target.repo.findMany({
+        where: [{ column: relation.remoteKey, op: 'in', value: chunk }, ...scope],
+        limit: MAX_IDS_PER_STATEMENT,
+        cursor,
+      });
+      rows.push(...page.rows);
+      cursor = page.nextCursor;
+    } while (cursor !== null);
+  }
+  return rows;
+};
+
+/** Related rows filed under the key they attach to — in the order the read returned them. */
+const indexed = async (
+  target: RelatedTable,
+  relation: Relation,
+  kind: string,
+  values: readonly unknown[],
+  scope: readonly Predicate[],
+): Promise<ReadonlyMap<string, readonly unknown[]>> => {
+  const index = new Map<string, unknown[]>();
+  if (values.length === 0) return index;
+  const found = await relatedRows(target, relation, values, scope);
+  for (const row of found) {
+    const at = keyOf(kind, valueAt(row, relation.remoteKey));
+    const bucket = index.get(at);
+    if (bucket === undefined) index.set(at, [row]);
+    else bucket.push(row);
+  }
+  return index;
+};
+
+/** The distinct keys a page carried, spelled as the batch spells them. A null key is not a key. */
+const distinctKeys = (kind: string, keys: readonly unknown[]): readonly unknown[] => {
+  const seen = new Set<string>();
+  const values: unknown[] = [];
+  for (const key of keys) {
+    if (key === null || key === undefined) continue;
+    const at = keyOf(kind, key);
+    if (seen.has(at)) continue;
+    seen.add(at);
+    values.push(key);
+  }
+  return values;
+};
+
+export interface PreloadRead<Source> {
+  readonly entity: EntityCore<Source>;
+  /** `undefined` for a table built by hand — `tableFor(entity, repo)` reaches no other table. */
+  readonly related: RelatedTables | undefined;
+  readonly relations: readonly Relation[];
+  /** The page's own predicates: what the related read inherits its tenant scope from. */
+  readonly where: readonly Predicate[];
+}
+
+/**
+ * The page, with every named relation attached to it. `source` carries the key values (a
+ * projection may have dropped them from the rows the caller sees) and `rows` are the rows the
+ * caller gets, in the same order — the attachment is by position, so the two are always one page.
+ *
+ * A relation resolves to a row or `null` when it is a `belongsTo` and to an array when it is a
+ * `hasMany`, always present: "this post has no author" and "nobody preloaded the author" must not
+ * read the same at the call site. Relations resolve concurrently — two `preload()` calls are two
+ * statements in flight, never one after the other — and attach in the order they were named.
+ */
+export const preloaded = async <Source, Row>(
+  read: PreloadRead<Source>,
+  source: readonly Source[],
+  rows: readonly Row[],
+): Promise<readonly Row[]> => {
+  if (read.relations.length === 0 || rows.length === 0) return rows;
+  const resolved = await Promise.all(
+    read.relations.map(async (relation) => {
+      const target = read.related?.(relation.to);
+      if (target === undefined) throw unreachable(read.entity.$name, relation);
+      // The declaring column's own kind: a foreign key mirrors the key it points at, so both ends
+      // of the edge are spelled the way a batched point read already spells them.
+      const kind = read.entity.$columns[relation.localKey]?.$meta.kind ?? '';
+      const keys = source.map((row) => valueAt(row, relation.localKey));
+      const scope = tenantScope(read.entity, target.entity, read.where);
+      const index = await indexed(target, relation, kind, distinctKeys(kind, keys), scope);
+      return { relation, kind, keys, index };
+    }),
+  );
+  // A copy per row: the in-memory driver hands back the row it stores, and attaching to that one
+  // would write a relation into the table itself.
+  const attached = rows.map((row) => ({ ...row }) as Record<string, unknown>);
+  for (const { relation, kind, keys, index } of resolved) {
+    for (const [position, row] of attached.entries()) {
+      const key = keys[position];
+      const found = key === null || key === undefined ? undefined : index.get(keyOf(kind, key));
+      row[relation.name] = relation.kind === 'hasMany' ? (found ?? []) : (found?.[0] ?? null);
+    }
+  }
+  // Built from the caller's own rows, one property added per relation named — which is exactly
+  // what `Row & { [name]: unknown }` says at the call site.
+  return attached as readonly Row[];
+};