@ultimat3/entity 11.3.0 → 13.0.0

package/src/pg-write-sql.ts

@@ -0,0 +1,129 @@
+// Single responsibility: compile a WRITE into parameterised SQL — insert, upsert, update, delete.
+// Split from `pg-sql.ts` when that file passed the 500-line ceiling: "which rows does this read
+// describe" and "what does this write put there" are two jobs, and only the second one needs to
+// know what a conflict target or a jsonb cell is.
+//
+// The same rule holds on both sides of the split and it is the reason either file exists: nothing
+// is interpolated. `sql` binds every scalar and every identifier is resolved through the entity,
+// so a column name can only ever be one the entity declared. `raw()` appears once here, for the
+// `default` cell of a many-row `values` list — a closed set of one word, written in this file and
+// never derived from a value.
+
+import { identifier, join, raw, type SqlFragment, sql } from '@ultimat3/db';
+import { columnName } from './column';
+import type { EntityCore } from './entity';
+import { conditions, type ReadShape } from './pg-sql';
+import type { QueryPlan } from './tenancy';
+
+/** `on conflict (…) do update set …`, or `do nothing` when there is nothing to overwrite. */
+export interface ConflictTarget {
+  /** Physical columns of the unique index a collision is judged against. */
+  readonly columns: readonly string[];
+  /** Physical columns a colliding row takes from the incoming one. Empty is `do nothing`. */
+  readonly set: readonly string[];
+}
+
+export interface InsertShape {
+  /** Every physical column written — one list, shared by every row of the statement. */
+  readonly columns: readonly string[];
+  /** How a collision resolves. Absent, it is the caller's error, exactly as it is for one row. */
+  readonly conflict?: ConflictTarget | undefined;
+}
+
+/**
+ * The cell of a row that did not name this column. `default` is the second and last `raw()` in
+ * this file and, like `asc|desc` above it, a closed set of one word: it is what makes a row inside
+ * a many-row `insert` mean what the same row means on its own, where an unnamed column is simply
+ * left out. The seek operator used to be a third — it is chosen in TypeScript now
+ * (`seekAfter`/`seekEqual`), because a timestamp seek is not one operator.
+ */
+const DEFAULT_CELL = raw('default');
+
+const conflictSql = (conflict: ConflictTarget): SqlFragment => {
+  const target = join(conflict.columns.map(identifier));
+  return conflict.set.length === 0
+    ? sql` on conflict (${target}) do nothing`
+    : sql` on conflict (${target}) do update set ${join(
+        conflict.set.map((column) => sql`${identifier(column)} = excluded.${identifier(column)}`),
+      )}`;
+};
+
+/**
+ * The one column that cannot be bound as itself. A `jsonb` value is a plain object, and the
+ * driver seam refuses one as a parameter (`X_SQL_UNSAFE` — `isBoundValue` takes scalars, a `Date`,
+ * a `Uint8Array` and arrays of those); so `bindValues` hands over the JSON TEXT and the cell says
+ * what to do with it.
+ *
+ * `::text::jsonb` and not `::jsonb`, and the double cast is load-bearing rather than defensive.
+ * Measured against Postgres 17.10 through Bun's `sql`: with `$1::jsonb` the server describes the
+ * parameter as `jsonb`, the client JSON-ENCODES the string it was given, and `{"a":1}` is stored
+ * as the JSON *string* `"{\"a\":1}"` — `jsonb_typeof` says `string`. Pinning the parameter to
+ * `text` first makes the client send the characters and the server parse them, which is the one
+ * spelling that stores an object.
+ */
+/** Physical names of this entity's `jsonb` columns. Resolved ONCE per statement, never per cell. */
+const jsonColumns = <Row>(entity: EntityCore<Row>): ReadonlySet<string> => {
+  const names = new Set<string>();
+  for (const [property, column] of Object.entries(entity.$columns)) {
+    if (column.$meta.kind === 'jsonb') names.add(columnName(property, column.$meta));
+  }
+  return names;
+};
+
+/**
+ * `${value}`, plus the cast that column needs. The `raw()` argument is a literal written here and
+ * nowhere else — the audit point that call is stays a two-word constant, never a value.
+ */
+const cell = (json: ReadonlySet<string>, column: string, value: unknown): SqlFragment =>
+  json.has(column) ? sql`${value}${raw('::text::jsonb')}` : sql`${value}`;
+
+/**
+ * One statement for any number of rows. A single row compiles to exactly the text it always did,
+ * which is the point: `insertAll([row])` and `insert(row)` are one code path, so there is no
+ * second insert builder for the two to drift apart in.
+ */
+export const insertStatement = <Row>(
+  entity: EntityCore<Row>,
+  rows: readonly ReadonlyMap<string, unknown>[],
+  shape: InsertShape,
+): SqlFragment => {
+  const json = jsonColumns(entity);
+  const tuples = rows.map(
+    (row) =>
+      sql`(${join(
+        shape.columns.map((column) =>
+          row.has(column) ? cell(json, column, row.get(column)) : DEFAULT_CELL,
+        ),
+      )})`,
+  );
+  const conflict = shape.conflict === undefined ? sql`` : conflictSql(shape.conflict);
+  return sql`insert into ${identifier(entity.$table)} (${join(
+    shape.columns.map(identifier),
+  )}) values ${join(tuples)}${conflict} returning *`;
+};
+
+/**
+ * `returning` is a parameter and has no default, because the three callers want three different
+ * answers and the wrong one is not visible in the result: `update(id, patch)` needs the stored row,
+ * a soft delete and a filtered write need a count, and `returning *` on a filtered write over a
+ * whole tenant streams every matched row into the process for nobody to read. A default would make
+ * that the quiet case.
+ */
+export const updateStatement = <Row>(
+  entity: EntityCore<Row>,
+  plan: QueryPlan,
+  values: ReadonlyMap<string, unknown>,
+  shape: ReadShape,
+  returning: boolean,
+): SqlFragment => {
+  const json = jsonColumns(entity);
+  return sql`update ${identifier(entity.$table)} set ${join(
+    [...values].map(([column, value]) => sql`${identifier(column)} = ${cell(json, column, value)}`),
+  )} where ${conditions(entity, plan, shape)}${returning ? sql` returning *` : sql``}`;
+};
+
+/** Only reached when the entity has no soft-delete column, so there is no filter to apply. */
+export const deleteStatement = <Row>(entity: EntityCore<Row>, plan: QueryPlan): SqlFragment =>
+  sql`delete from ${identifier(entity.$table)} where ${conditions(entity, plan, {
+    includeDeleted: true,
+  })}`;

package/src/plan.ts

@@ -3,6 +3,7 @@
 // which rows are in scope, what the total sort order is, how big a page is. A guard only one
 // driver applies is worse than none: the test passes and production leaks another tenant's rows.
 
+import { assertSeekable } from './cursor';
 import type { EntityCore } from './entity';
 import { EntityError, invariantViolated, patchEmpty, writeUnfiltered } from './errors';
 import type { FindManyArgs, RepoOptions } from './repo';
@@ -49,19 +50,32 @@ export const singleKeyOf = <Row>(entity: EntityCore<Row>, operation: string): st
  * 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.
  *
+ * The tiebreak takes the LAST DECLARED key's direction rather than an unconditional `asc`, and
+ * that is not a preference. `IndexInit.order` is ONE direction for a whole index, so
+ * `orderBy('createdAt', 'desc')` used to run `created_at desc, id asc` — an order this framework's
+ * own DSL cannot declare an index for, whatever the author wrote. It also decided the seek's
+ * shape: a mixed order has no row comparison, so the seek fell to the or-chain, which measured on
+ * Postgres 16 as a BitmapOr plus a Sort where `(created_at, id) < ($1, $2)` is an Index Only Scan.
+ * A caller who wants the mixed order still writes it — naming the key itself is what turns the
+ * append off.
+ *
  * 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.
+ * cannot carry a cursor — an undeclared column, or a nullable key in the TIEBREAK, never an
+ * ordinary nullable one — 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 })),
-];
+): readonly SortKey[] => {
+  const direction = ordered.at(-1)?.direction ?? 'asc';
+  return [
+    ...ordered,
+    ...entity.$primaryKey
+      .filter((property) => !ordered.some((entry) => entry.column === property))
+      .map((property) => ({ column: property, direction })),
+  ];
+};
 
 /**
  * What a page size has to be before a statement carries it: rows, whole, at least one and at most
@@ -83,8 +97,20 @@ export const assertPageSize = (entityName: string, rows: number): void => {
   });
 };
 
+/**
+ * Whether an ordering can carry a page position is a property of the ORDER, so it is decided here
+ * — where the order the driver will send is first known — and not in `cursorFor`, which runs only
+ * when a page found one row past its limit. That is what made the refusal depend on the table:
+ * `orderBy('publishedAt', 'desc').limit(20)` over a nullable column was green on fifteen seeded
+ * rows for as long as the test suite existed and `X_INVARIANT_VIOLATED` on the first read past
+ * twenty in production. `assertBatchable` has always judged `inBatches()` this way.
+ *
+ * `cursorFor` and `seekFrom` still call it: they are reached from a driver directly.
+ */
 export const planFor = <Row>(entity: EntityCore<Row>, args: FindManyArgs): QueryPlan => {
   if (args.limit !== undefined) assertPageSize(entity.$name, args.limit);
+  const orderBy = totalOrder(entity, args.orderBy ?? []);
+  assertSeekable(entity, orderBy);
   const scoped =
     args.orgId === undefined || entity.$tenantColumn === null
       ? []
@@ -92,7 +118,7 @@ export const planFor = <Row>(entity: EntityCore<Row>, args: FindManyArgs): Query
   return {
     entity: entity.$name,
     where: [...(args.where ?? []), ...scoped],
-    orderBy: totalOrder(entity, args.orderBy ?? []),
+    orderBy,
     limit: args.limit ?? DEFAULT_PAGE_SIZE,
     ...(args.cursor === undefined || args.cursor === null ? {} : { cursor: args.cursor }),
     ...(args.select === undefined ? {} : { select: args.select }),
@@ -109,7 +135,42 @@ export const readPlan = <Row>(
   entity: EntityCore<Row>,
   args: FindManyArgs,
   operation: string,
-): QueryPlan => scopedPlan(entity.$name, entity.$tenantColumn, operation, planFor(entity, args));
+): QueryPlan => {
+  const plan = planFor(entity, args);
+  // BEFORE tenancy, deliberately. Applied after, a tenant-scoped entity had no reachable call at
+  // all: unscoped it was `X_TENANCY_UNSCOPED` and scoped it was the refusal below, so the method
+  // was declared and unusable — the defect class this repo keeps re-shipping. One refusal, and it
+  // names which of the two situations the caller is in.
+  if (operation === 'approximateCount') assertEstimable(entity, plan);
+  return scopedPlan(entity.$name, entity.$tenantColumn, operation, plan);
+};
+
+/**
+ * An estimate is the TABLE's. `reltuples` knows nothing about a predicate, so a filtered chain
+ * asking for one would be answered a different question from the one it asked — and a caller
+ * reading `posts.where({ orgId }).approximateCount()` as "roughly how many of mine" would be
+ * handed every other tenant's rows too, which is the reading that matters.
+ *
+ * A TENANT-SCOPED entity is therefore refused outright, filters or none: its whole-table estimate
+ * is a number about every tenant, and a per-tenant row count is not a thing the planner holds.
+ * That refusal is not a limitation of this method, it is what the method means.
+ */
+const assertEstimable = <Row>(entity: EntityCore<Row>, plan: QueryPlan): void => {
+  if (entity.$tenantColumn !== null) {
+    throw new EntityError({
+      code: 'X_APPROXIMATE_COUNT_FILTERED',
+      cause: `${entity.$name}.approximateCount() is a whole-TABLE estimate and ${entity.$name} is scoped by ${entity.$tenantColumn} — the planner holds one number for every tenant together`,
+      fix: `${entity.$name}.count()   # the exact answer, scoped to the acting actor's tenant as every other read is`,
+    });
+  }
+  if (plan.where.length === 0) return;
+  const named = plan.where.map((each) => each.column).join(', ');
+  throw new EntityError({
+    code: 'X_APPROXIMATE_COUNT_FILTERED',
+    cause: `${entity.$name}.approximateCount() carries ${plan.where.length} predicate(s) (${named}) — the planner estimates the TABLE and knows nothing about them`,
+    fix: `${entity.$name}.count()   # the exact answer for a filtered chain; approximateCount() answers for the whole table only`,
+  });
+};
 
 /**
  * The plan for an id-addressed write. A write is a query too: without the same guard,

package/src/query.ts

@@ -8,14 +8,17 @@ import type { BatchIterator } from './batch';
 import { assertBatchable, batchIterator } from './batch';
 import { entityNow } from './clock';
 import type { EntityCore } from './entity';
+import { searchUndeclared } from './feature-errors';
 import { assertPageSize, DEFAULT_PAGE_SIZE, namedColumns } from './plan';
 import type { RelatedTables } from './preload';
 import { preloaded } from './preload';
 import type { Relation } from './relations';
 import { relationNamed } from './relations';
 import type { Page, Repo, RepoOptions, UpsertArgs } from './repo';
+import { SEARCH_PROPERTY } from './search';
 import type { Operator, Predicate, QueryPlan, SortDirection, SortKey } from './tenancy';
-import type { ColumnMap, IdOf, Insertable, RowPatch } from './types';
+import { transitionRow } from './transition';
+import type { ColumnMap, IdOf, Insertable, MoneyValue, RowPatch } from './types';
 
 /**
  * What a preloaded relation adds to a row. `unknown` because the name is a string resolved at
@@ -28,6 +31,23 @@ export interface ReadBuilder<Row> {
   /** Equality on the columns given. `where({ orgId })` is what satisfies the tenancy guard. */
   where(filter: RowPatch<Row>): ReadBuilder<Row>;
   andWhere(column: keyof Row & string, op: Operator, value: unknown): ReadBuilder<Row>;
+  /**
+   * Full-text search over the entity's generated `tsvector` — every `.searchable()` column at
+   * once, one GIN index, one predicate. `posts.where({ orgId }).search(input.q).limit(20).page()`.
+   *
+   * `term` is USER TEXT and is treated as such end to end: it crosses as a bound parameter and is
+   * parsed by `websearch_to_tsquery`, so `&`, `|`, `!`, `:*` and an unbalanced paren are characters
+   * to be matched, never operators and never a syntax error. There is deliberately no way to hand
+   * this layer a tsquery — a query language inside the query language is a second way to ask, and
+   * the one caller that would want it is the injection this method exists to make unreachable.
+   *
+   * It is an ordinary predicate, so the chain's tenancy, soft delete, projection, order, cursor
+   * and page size all mean here exactly what they mean without it. RELEVANCE is not an order this
+   * chain can serve: `ts_rank` is a computed value and the cursor carries columns, so the order
+   * stays the one the caller declared. An entity with no searchable column is `X_SEARCH_UNDECLARED`
+   * and the in-memory driver is `X_SEARCH_IN_MEMORY` — never a different answer from the two.
+   */
+  search(term: string): ReadBuilder<Row>;
   orderBy(column: keyof Row & string, direction?: SortDirection): ReadBuilder<Row>;
   limit(rows: number): ReadBuilder<Row>;
   /** The cursor from the previous page. */
@@ -59,8 +79,12 @@ export interface ReadBuilder<Row> {
    *
    * The loop closes it: `break`, `return` and a throw all stop the next statement, and
    * `await using` does the same for a handle kept in a variable. A chain that cannot carry a
-   * cursor — a nullable sort column — and a chain that also called `limit()` are refused here,
-   * not one batch later.
+   * cursor and a chain that also called `limit()` are refused here, not one batch later. An
+   * ORDINARY nullable sort column is not one of those: it orders `nulls last` ascending and
+   * `nulls first` descending, and the cursor carries that position. What is refused is a sort key
+   * that leaves the order un-total — an undeclared column, a money property named without its
+   * part, or a nullable PRIMARY-KEY column, where `null = null` is unknown and two such rows are
+   * one position to the seek (`cursor.ts`'s `assertSeekable`).
    */
   inBatches(size: number): BatchIterator<Row>;
   /** The terminal: one bounded page and the cursor that continues it. */
@@ -83,11 +107,73 @@ export interface ReadBuilder<Row> {
    * jsonb, money), and a chain matching more distinct values than one statement should answer with.
    */
   countBy<K extends keyof Row & string>(column: K): Promise<ReadonlyMap<Row[K], number>>;
+  /**
+   * The four SQL aggregates, over exactly the rows `count()` counts — the chain's filters, its
+   * tenancy and its soft-delete visibility, never its page. "Total spend this month" is
+   * `payments.where({ orgId }).andWhere('paidAt', 'gte', from).sum('amount')`, one statement,
+   * rather than a page loop or a hand-written query outside every guard this layer applies.
+   *
+   * **Never a float.** `sum` and `avg` answer decimal TEXT whatever the column was — the sum of a
+   * million `integer` rows is not an `integer` and `Number()` on it loses digits past 2^53 — and a
+   * money column answers a `MoneyValue` in integer minor units. `min`/`max` answer the row's own
+   * type, because the answer is one of the values that went in.
+   *
+   * `null` for an empty set in every one of them, which is what SQL answers: a `0` would claim
+   * rows were seen.
+   *
+   * Refused rather than answered: a kind with no aggregate the two drivers can agree on (`text`
+   * ordering is the database's collation here and JS code-unit order there), `avg` over money
+   * (every answer would be a silent rounding of a fraction of a minor unit), and an amount
+   * covering more than one currency or scale.
+   */
+  sum<K extends keyof Row & string>(
+    column: K,
+  ): Promise<(Row[K] extends MoneyValue | null ? MoneyValue : string) | null>;
+  avg<K extends keyof Row & string>(column: K): Promise<string | null>;
+  min<K extends keyof Row & string>(column: K): Promise<Row[K] | null>;
+  max<K extends keyof Row & string>(column: K): Promise<Row[K] | null>;
+  /**
+   * The planner's own row estimate for the table — `reltuples`, one row out of `pg_class`, and the
+   * only count that stays constant time as the table grows. `count()` walks every visible row
+   * because MVCC gives it no shortcut, so past a few million it is the read that trips a web
+   * role's `statement_timeout` and no index can make it cheaper.
+   *
+   * The whole TABLE, never the chain's filters — a filtered chain is `X_APPROXIMATE_COUNT_FILTERED`
+   * rather than an estimate that answers a different question than the one asked. `null` when the
+   * table has never been analysed, which is the absence of an estimate and not an estimate of zero.
+   */
+  approximateCount(): Promise<number | null>;
   /** The plan this chain describes. Safe to log — `describePlan()` elides values. */
   plan(): QueryPlan;
 }
 
 export interface Table<Row, C extends ColumnMap = ColumnMap> extends ReadBuilder<Row> {
+  /**
+   * Move one row through the state machine `column` declares, in ONE statement.
+   *
+   * `from` is the state the caller believes the row is in, and it rides in the statement's own
+   * predicate — so the state that was observed and the state that was written are one decision,
+   * made under the row's lock. A read-then-check-then-write is the same call with a window in it,
+   * and under two concurrent callers the second one writes a transition out of a state the row had
+   * already left. Here the second statement matches no row: `X_STATE_CONFLICT`, naming the state
+   * the row is really in.
+   *
+   * A move the machine does not hold is `X_STATE_TRANSITION_ILLEGAL` and never reaches the
+   * database — the table is a property of the declaration. A move out of a TERMINAL state is the
+   * same code saying so; a terminal state is one whose outgoing list is empty, which is the whole
+   * of the concept and the only part of it the framework owns. Which state is terminal, what any
+   * of them mean, who may make a move and what happens on arrival are the app's, every one.
+   *
+   * Tenant-scoped exactly as `updateWhere` is, because it IS one: a row in another org matches no
+   * statement and reads back as absent, so the answer is `X_NOT_FOUND` rather than a conflict that
+   * would confirm it exists.
+   */
+  transition<K extends keyof Row & string>(
+    column: K,
+    id: IdOf<Row>,
+    move: { readonly from: Row[K] & string; readonly to: Row[K] & string },
+    options?: RepoOptions,
+  ): Promise<Row>;
   insert(values: Insertable<C>, options?: RepoOptions): Promise<Row>;
   /**
    * Many rows, one statement — the bulk write a per-row `insert` loop is the N+1 of, and the line
@@ -201,6 +287,16 @@ const builder = <Source, Row>(
 
     andWhere: (column, op, value) => next({ where: [...state.where, { column, op, value }] }),
 
+    // Refused HERE as well as at the statement, because this is the line the author wrote: a chain
+    // over an entity that declares nothing searchable can never produce a match, and the repair is
+    // one edit to the schema rather than anything about this call.
+    search: (term) => {
+      if (entity.$search === null) throw searchUndeclared(entity.$name);
+      return next({
+        where: [...state.where, { column: SEARCH_PROPERTY, op: 'matches', value: term }],
+      });
+    },
+
     orderBy: (column, direction = 'asc') =>
       next({ orderBy: [...state.orderBy, { column, direction }] }),
 
@@ -276,6 +372,22 @@ const builder = <Source, Row>(
 
     count: () => repo.count(args()),
 
+    // The one cast on each of these, and it is the same seam `countBy` and `select()` have: the
+    // driver contract is row-agnostic because a column name is a runtime string there, while the
+    // chain knows which property it just named and therefore what comes back.
+    sum: async <K extends keyof Row & string>(column: K) =>
+      (await repo.aggregate('sum', column, args())) as
+        | (Row[K] extends MoneyValue | null ? MoneyValue : string)
+        | null,
+    avg: async (column: keyof Row & string) =>
+      (await repo.aggregate('avg', column, args())) as string | null,
+    min: async <K extends keyof Row & string>(column: K) =>
+      (await repo.aggregate('min', column, args())) as Row[K] | null,
+    max: async <K extends keyof Row & string>(column: K) =>
+      (await repo.aggregate('max', column, args())) as Row[K] | null,
+
+    approximateCount: () => repo.approximateCount(args()),
+
     async countBy<K extends keyof Row & string>(column: K) {
       // The one cast on this terminal, and it is the same seam `select()` has: the driver contract
       // is row-agnostic because a column name is a runtime string there, while the chain knows
@@ -345,4 +457,9 @@ export const tableFor = <Row, C extends ColumnMap>(
   deleteWhere: async (filter, options) => repo.deleteWhere(filter, options),
   updateWhere: async (filter, patch, options) =>
     repo.updateWhere(filter, touch(entity, patch), options),
+  // `touch` is passed rather than applied here: a transition IS an update, so an `onUpdateNow()`
+  // column has to move exactly as `update(id, patch)` moves it — which is also the audit of WHEN
+  // the row moved, using the stamp already declared instead of a second one beside it.
+  transition: async (column, id, move, options) =>
+    transitionRow(entity, repo, column, id, move, (patch) => touch(entity, patch), options),
 });

package/src/registry.ts

@@ -3,6 +3,7 @@
 // whole domain without importing it — and what makes a duplicate name a build error rather
 // than a silent last-one-wins.
 
+import type { IndexMethod } from '@ultimat3/db';
 import { entityDuplicate } from './errors';
 import type { InvariantKind } from './invariants';
 import type { OnDelete } from './types';
@@ -24,6 +25,15 @@ export interface ColumnDescription {
    * projection reaches no `alter table` at all. It reached none until 3.0.
    */
   readonly onDelete: OnDelete | null;
+  /**
+   * The `generated always as (<expr>) stored` body, when the DATABASE computes this column rather
+   * than a writer. Absent on every ordinary column, matching `IndexDescription.using`: a
+   * description written before this existed reads the same, so nothing regenerates.
+   *
+   * `@ultimat3/db` is tier 1 and cannot import this package, so — exactly like `onDelete` — a
+   * field that is not on this projection reaches no DDL at all.
+   */
+  readonly generated?: string;
 }
 
 /**
@@ -72,6 +82,12 @@ export interface IndexDescription {
   readonly where: string | null;
   /** `null` is Postgres' own default (`asc`), never written out. */
   readonly order: 'asc' | 'desc' | null;
+  /**
+   * The access method, `undefined` for the `btree` every index was before this existed. Absent
+   * rather than `null`, matching `IndexDescriptionLike.using` in `@ultimat3/db`: a snapshot that
+   * predates the field and an index that declares nothing read the same, so nothing regenerates.
+   */
+  readonly using?: IndexMethod | undefined;
 }
 
 export interface EntityDescription {