@ultimat3/entity 12.0.0 → 14.0.0

package/src/memory-match.ts

@@ -10,6 +10,7 @@ import { arrayContains, arrayOverlaps, jsonContains, jsonHasKey } from './contai
 import { kindOf, valueAt } from './cursor';
 import type { EntityCore } from './entity';
 import { EntityError } from './errors';
+import { searchInMemory } from './feature-errors';
 import { instantMicros } from './instant';
 import type { Predicate } from './tenancy';
 import type { ColumnKind } from './types';
@@ -158,6 +159,10 @@ export const matchesPredicate = <Row>(
   row: unknown,
   predicate: Predicate,
 ): boolean => {
+  // BEFORE anything is read off the row. A full-text match has no in-memory meaning — see
+  // `searchInMemory` — and `valueAt(row, '$search')` would answer `undefined`, which every
+  // comparison below reads as NULL and silently turns into "no rows".
+  if (predicate.op === 'matches') throw searchInMemory(entity.$name);
   // 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);

package/src/memory-repo.ts

@@ -11,7 +11,7 @@ import { foldAggregate } from './aggregate-fold';
 import { keyOf } from './batch-read';
 import { conflictKeyOf, conflictKeys, upsertPlan } from './bulk-write';
 import { entityNow } from './clock';
-import { narrowMoney } from './columns';
+import { narrowRow } from './columns';
 import { countsFrom, groupColumnOf } from './count-by';
 import { cursorFor, kindOf, seekFrom, valueAt } from './cursor';
 import { type EntityCore, SOFT_DELETE_COLUMN } from './entity';
@@ -21,6 +21,7 @@ import { deletePlan, idPlan, readPlan, singleKeyOf, updatePlan } from './plan';
 import type { FindManyArgs, MemoryRepo, RepoOptions, Transactor, Tx } from './repo';
 import type { QueryPlan } from './tenancy';
 import { assertRowTenant } from './tenancy';
+import type { RowWrite } from './types';
 
 const field = (row: unknown, property: string): unknown =>
   typeof row === 'object' && row !== null ? (row as Record<string, unknown>)[property] : undefined;
@@ -113,11 +114,19 @@ export const memoryRepo = <Row>(
     return { plan, found: rowsOf(plan, args) };
   };
 
-  const write = (given: Row, options: RepoOptions | undefined, operation: string): Row => {
+  /** Money's write shape narrowed once per batch, at the method the caller reached. */
+  const narrowed = (batch: readonly RowWrite<Row>[]): readonly Row[] =>
+    batch.map((row) => narrowRow<Row>(entity.$columns, row));
+
+  const write = (
+    given: RowWrite<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);
+    // driver narrows at the same position — its write methods' entry — so without this an
+    // in-memory row would be the one row in the framework `JSON.stringify` refuses.
+    const row = narrowRow<Row>(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
@@ -184,11 +193,15 @@ export const memoryRepo = <Row>(
       return write(values, options, 'insert');
     },
 
-    async insertAll(batch, options) {
+    async insertAll(given, 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.
+      //
+      // Narrowed FIRST, so what this loop judges is what `write` will store: `$assert` was handed
+      // the caller's `bigint` minor unit here and the narrowed `number` one call later.
+      const batch = narrowed(given);
       for (const row of batch) {
         assertRowTenant(entity.$name, entity.$tenantColumn, 'insertAll', row);
         entity.$assert(row);
@@ -196,10 +209,12 @@ export const memoryRepo = <Row>(
       return batch.map((row) => write(row, options, 'insertAll'));
     },
 
-    async upsertAll(batch, args) {
+    async upsertAll(given, 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.
+      // let a row naming another tenant through whenever it happened to collide. Narrowed first
+      // for the reason `insertAll` above is, and before `conflictKeyOf` reads a target too.
+      const batch = narrowed(given);
       for (const row of batch) {
         assertRowTenant(entity.$name, entity.$tenantColumn, 'upsertAll', row);
         entity.$assert(row);

package/src/pg-driver.ts

@@ -28,6 +28,7 @@ import {
 import { entityNow } from './clock';
 import { coalesceFindById } from './coalesce';
 import { moneyColumns } from './column';
+import { narrowRow } from './columns';
 import { countsFrom, groupColumnOf, groupValue, MAX_GROUPS } from './count-by';
 import { cursorFor, seekFrom, valueAt } from './cursor';
 import type { Driver } from './database';
@@ -58,6 +59,7 @@ import { deletePlan, idPlan, readPlan, updatePlan } from './plan';
 import type { FindManyArgs, Repo, Transactor, UpsertArgs } from './repo';
 import type { QueryPlan } from './tenancy';
 import { assertRowTenant } from './tenancy';
+import type { RowWrite } from './types';
 
 export interface PostgresDriverOptions {
   /**
@@ -121,6 +123,11 @@ export const postgresRepo = <Row>(
   const idOf = (row: Row): string =>
     entity.$primaryKey.map((property) => String(valueAt(row, property))).join('');
 
+  /** Where a batch stops being wide — before `writeRows` or `upsertPlan` read a row. `narrowRow`
+   *  says why the position matters, and `memoryRepo` narrows at the same one. */
+  const narrowed = (batch: readonly RowWrite<Row>[]): readonly Row[] =>
+    batch.map((row) => narrowRow<Row>(entity.$columns, row));
+
   const one = async (plan: QueryPlan, args: FindManyArgs): Promise<Row | null> => {
     const [found] = await client().query<PhysicalRow>(
       selectStatement(entity, plan, shapeOf(args), 1),
@@ -255,21 +262,24 @@ export const postgresRepo = <Row>(
     },
 
     async insert(values) {
-      const [written] = await writeRows('insert', [values], undefined);
-      // `returning *` is the row Postgres actually stored, defaults included.
-      return written ?? values;
+      const row = narrowRow<Row>(entity.$columns, values);
+      const [written] = await writeRows('insert', [row], undefined);
+      // `returning *` is the row Postgres actually stored, defaults included. The fallback is the
+      // NARROWED row: handing the caller's back would answer with a `bigint` minor unit.
+      return written ?? row;
     },
 
     async insertAll(batch) {
-      return writeRows('insertAll', batch, undefined);
+      return writeRows('insertAll', narrowed(batch), undefined);
     },
 
     async upsertAll(batch, args: UpsertArgs<Row>) {
-      const plan = upsertPlan(entity, batch, args.onConflict, args.onMatch ?? 'update');
+      const rows = narrowed(batch);
+      const plan = upsertPlan(entity, rows, args.onConflict, args.onMatch ?? 'update');
       // Refused here, not by the server: a batch that repeats a conflict target is `21000` in
       // Postgres and a silent overwrite in memory, and the two drivers have to mean one thing.
-      conflictKeys(entity, plan, batch);
-      return writeRows('upsertAll', batch, {
+      conflictKeys(entity, plan, rows);
+      return writeRows('upsertAll', rows, {
         columns: insertColumns(entity, plan.on),
         set: insertColumns(entity, plan.set),
       });

package/src/pg-sql.ts

@@ -10,6 +10,7 @@ import { columnFor } from './column';
 import { isNullableKey, kindOf } from './cursor';
 import type { EntityCore } from './entity';
 import { SOFT_DELETE_COLUMN } from './entity';
+import { searchUndeclared } from './feature-errors';
 import { microsToIso, seekAlias } from './instant';
 import { allColumns, arrayLiteral, columnsOf, physicalName } from './pg-row';
 import type { Predicate, QueryPlan, SortKey } from './tenancy';
@@ -28,7 +29,38 @@ export interface ReadShape {
 const columnRef = <Row>(entity: EntityCore<Row>, path: string): SqlFragment =>
   identifier(physicalName(entity, path));
 
+/**
+ * `websearch_to_tsquery`, and the choice is the point of the whole feature.
+ *
+ * `to_tsquery` reads its argument as tsquery SYNTAX — `&`, `|`, `!`, `<->`, `:*`, parentheses — so
+ * a term straight out of a search box is either a `42601` on the first unbalanced paren or, worse,
+ * an operator the caller did not write. `plainto_tsquery` is safe but ANDs every word and throws
+ * the user's own operators away silently. `websearch_to_tsquery` is the parser Postgres ships for
+ * untrusted input: it never raises a syntax error, and it gives `"quoted phrase"`, `or` and a
+ * leading `-` the meaning every search box on the web already has. Cats & dogs is three terms.
+ *
+ * The term crosses as a BOUND PARAMETER either way — nothing here interpolates it — so the choice
+ * is not what stops an injection; the parameter is. What the parser decides is whether the user's
+ * punctuation is read as syntax, which is the second half of the same question.
+ *
+ * The configuration is spliced through `raw()`, from `SEARCH_LANGUAGES`, exactly as `asc|desc` is:
+ * a closed set of one word, chosen by this file from the ENTITY's declaration and never from a
+ * value on the wire. `regconfig` cannot be a bound parameter and stay index-matchable anyway.
+ */
+const searchSql = <Row>(entity: EntityCore<Row>, predicate: Predicate): SqlFragment => {
+  const vector = entity.$search;
+  if (vector === null) throw searchUndeclared(entity.$name);
+  const column = identifier(vector.column);
+  // The term as TEXT, whatever arrived: `websearch_to_tsquery` takes text, and a number or a null
+  // reaching it as a parameter is a `42883` where the caller is owed "no rows".
+  const term = predicate.value === null || predicate.value === undefined ? '' : predicate.value;
+  return sql`${column} @@ websearch_to_tsquery(${raw(`'${vector.language}'`)}, ${String(term)})`;
+};
+
 const predicateSql = <Row>(entity: EntityCore<Row>, predicate: Predicate): SqlFragment => {
+  // BEFORE the column is resolved: a `matches` predicate names `SEARCH_PROPERTY`, which is not a
+  // column and must never be looked up as one.
+  if (predicate.op === 'matches') return searchSql(entity, predicate);
   const column = columnRef(entity, predicate.column);
   const value = predicate.value;
   switch (predicate.op) {

package/src/query.ts

@@ -8,13 +8,16 @@ 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 { transitionRow } from './transition';
 import type { ColumnMap, IdOf, Insertable, MoneyValue, RowPatch } from './types';
 
 /**
@@ -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. */
@@ -128,6 +148,32 @@ export interface ReadBuilder<Row> {
 }
 
 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
@@ -241,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 }] }),
 
@@ -401,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

@@ -6,7 +6,7 @@
 import type { IndexMethod } from '@ultimat3/db';
 import { entityDuplicate } from './errors';
 import type { InvariantKind } from './invariants';
-import type { OnDelete } from './types';
+import type { ColumnDefault, OnDelete } from './types';
 
 export interface ColumnDescription {
   readonly property: string;
@@ -25,6 +25,25 @@ 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;
+  /**
+   * The declared default, when there is one — the VALUE, not merely `hasDefault`'s boolean.
+   *
+   * Same reason as `onDelete` and `generated`: `@ultimat3/db` is tier 1 and cannot import this
+   * package, so a fact that is not on this projection reaches no DDL. `hasDefault` alone let the
+   * generator infer only `gen_random_uuid()` and `now()`; every other default was dropped in
+   * silence, and a regenerated `examples/dummy` lost nine of them. Absent on a column declaring
+   * none, so a description written before this existed reads the same and nothing regenerates.
+   */
+  readonly default?: ColumnDefault;
 }
 
 /**
@@ -55,6 +74,18 @@ export interface InvariantDescription {
   /** `null` for an `assert`: a JS predicate the database was never told about. */
   readonly sql: string | null;
   readonly where: string | null;
+  /**
+   * The physical columns this rule reads — the same list `Invariant.columns` holds, for every
+   * kind, never narrowed to `unique`.
+   *
+   * Same reason as `onDelete`, `generated` and `default` on `ColumnDescription`: `@ultimat3/db` is
+   * tier 1 and cannot import this package, so a fact absent here is a fact the generator has to
+   * recover from a rendering. Without it `uniqueColumns()` split a `unique` rule's `sql` on commas
+   * and re-validated each part as an identifier — a comma-split of text this package joined, which
+   * is the shape `parseIndexName` failed at when `posts_org_id_created_at_idx` became the single
+   * column `"org_id_created_at"`. Carried, so the split has nothing left to do.
+   */
+  readonly columns: readonly string[];
 }
 
 /**

package/src/repo.ts

@@ -9,7 +9,7 @@
 
 import type { AggregateFn } from './aggregate';
 import type { Predicate, SortKey } from './tenancy';
-import type { IdOf, RowPatch } from './types';
+import type { IdOf, RowPatch, RowWrite } from './types';
 
 export interface Tx {
   readonly id: string;
@@ -80,11 +80,16 @@ export interface Page<T> {
  * 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.
+ *
+ * The whole-row writes take `RowWrite<T>` and the filtered ones `RowPatch<T>`, which are one
+ * statement in two shapes: money's write type is wider than its row type, and every one of these
+ * five entry points narrows it — `narrowRow` — before anything reads the row. Taking `T` here made
+ * the documented `bigint` minor unit unspellable at the only call an app makes.
  */
 export interface Repo<T = unknown> {
   findById(id: IdOf<T>, options?: FindByIdOptions): Promise<T | null>;
   findMany(args?: FindManyArgs): Promise<Page<T>>;
-  insert(values: T, options?: RepoOptions): Promise<T>;
+  insert(values: RowWrite<T>, options?: RepoOptions): Promise<T>;
   /**
    * 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
@@ -92,13 +97,13 @@ export interface Repo<T = unknown> {
    * 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(rows: readonly RowWrite<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[]>;
+  upsertAll(rows: readonly RowWrite<T>[], args: UpsertArgs<T>): Promise<readonly T[]>;
   update(id: IdOf<T>, patch: RowPatch<T>, options?: RepoOptions): Promise<T>;
   delete(id: IdOf<T>, options?: RepoOptions): Promise<void>;
   /**

package/src/search.ts

@@ -0,0 +1,153 @@
+// The full-text search vector an entity DERIVES from its `.searchable()` columns: one generated
+// `tsvector` column, one language, one weight per source. Everything spliced into the expression
+// here comes from a closed set or from a physical column name `assertColumnName` already checked —
+// a search TERM never reaches this file, because a term is bound as a parameter (`pg-sql.ts`).
+
+import type { SearchWeight } from './types';
+
+/**
+ * Postgres' own default text search configurations, as `\dF` lists them on 13 and later. A CLOSED
+ * set because the configuration is the one part of `to_tsvector(config, text)` that cannot be a
+ * bound parameter inside a generated column — it is spliced — so it may only ever be a value this
+ * file already contains. A server without one of these answers `3F000` at `create table`, which is
+ * loud and lands on the author, not on a search.
+ */
+export const SEARCH_LANGUAGES = [
+  'arabic',
+  'armenian',
+  'basque',
+  'catalan',
+  'danish',
+  'dutch',
+  'english',
+  'finnish',
+  'french',
+  'german',
+  'greek',
+  'hindi',
+  'hungarian',
+  'indonesian',
+  'irish',
+  'italian',
+  'lithuanian',
+  'nepali',
+  'norwegian',
+  'portuguese',
+  'romanian',
+  'russian',
+  'serbian',
+  'simple',
+  'spanish',
+  'swedish',
+  'tamil',
+  'turkish',
+  'yiddish',
+] as const;
+
+export type SearchLanguage = (typeof SEARCH_LANGUAGES)[number];
+
+/** The one membership test. `includes` on the tuple, never a computed read of a table. */
+export const isSearchLanguage = (value: unknown): value is SearchLanguage =>
+  typeof value === 'string' && (SEARCH_LANGUAGES as readonly string[]).includes(value);
+
+export const SEARCH_WEIGHTS = ['A', 'B', 'C', 'D'] as const;
+
+export const isSearchWeight = (value: unknown): value is SearchWeight =>
+  typeof value === 'string' && (SEARCH_WEIGHTS as readonly string[]).includes(value);
+
+/** Postgres' own default weight, so an unweighted source ranks exactly as an unweighted vector. */
+export const DEFAULT_SEARCH_WEIGHT: SearchWeight = 'D';
+
+export const DEFAULT_SEARCH_LANGUAGE: SearchLanguage = 'english';
+
+export const DEFAULT_SEARCH_COLUMN = 'search_tsv';
+
+/**
+ * What a `matches` predicate names instead of a column. `$`-prefixed for the reason every member
+ * of `EntityCore` is: `assertColumnName` requires `[a-z_]` first, so no declared column can ever
+ * be spelled this, and a `matches` predicate can therefore never be confused with one on a real
+ * column. Nothing resolves it through `physicalName` — both drivers branch on the OPERATOR.
+ */
+export const SEARCH_PROPERTY = '$search';
+
+export interface SearchSource {
+  /** Physical column, already through `assertColumnName`. */
+  readonly column: string;
+  readonly weight: SearchWeight;
+}
+
+/** How an entity's search is declared, when the defaults do not fit the table it adopted. */
+export interface SearchInit {
+  /** The physical vector column, when `search_tsv` is taken or the table already named one. */
+  readonly column?: string;
+  readonly language?: SearchLanguage;
+}
+
+export interface SearchVector {
+  /** The physical `tsvector` column. Never a row property. */
+  readonly column: string;
+  readonly language: SearchLanguage;
+  readonly sources: readonly SearchSource[];
+  /** The `generated always as (…) stored` body. Deterministic in declaration order. */
+  readonly expression: string;
+}
+
+/**
+ * One `setweight(to_tsvector(…))` per source, concatenated in DECLARATION order.
+ *
+ * `setweight` even for a single unweighted source, so adding a second column never rewrites the
+ * first one's spelling — and a spelling change here is a `drop column` + `add column` on a table
+ * that may hold every row an app has. `coalesce(…, '')` because `to_tsvector` of NULL is NULL and
+ * `NULL || tsvector` is NULL: one nullable source would erase the whole vector for that row.
+ *
+ * Every function in it is immutable, which is what Postgres requires of a generated column —
+ * `to_tsvector(text)` with no configuration is NOT (it reads `default_text_search_config`), which
+ * is why the language is named here and never left to the server.
+ */
+export const searchExpression = (
+  language: SearchLanguage,
+  sources: readonly SearchSource[],
+): string =>
+  sources
+    .map(
+      (source) =>
+        `setweight(to_tsvector('${language}', coalesce("${source.column}", '')), '${source.weight}')`,
+    )
+    .join(' || ');
+
+/**
+ * The vector a set of already-resolved sources describes, or `null` when there are none.
+ *
+ * The physical names arrive resolved and the collision check arrives as `taken`, so this module
+ * imports nothing from `column.ts` — which imports THIS one for `.searchable()`. A cycle between
+ * the column chain and the thing a column modifier declares is avoidable, so it is avoided.
+ */
+export const searchVectorOf = (
+  sources: readonly SearchSource[],
+  init: SearchInit | undefined,
+  taken: (column: string) => boolean,
+  refuse: (subject: string, detail: string) => never,
+): SearchVector | null => {
+  if (sources.length === 0) {
+    if (init === undefined) return null;
+    return refuse(
+      'search',
+      'search is declared but no column is searchable — add .searchable() to a text() column, or drop the search option',
+    );
+  }
+  const language = init?.language ?? DEFAULT_SEARCH_LANGUAGE;
+  if (!isSearchLanguage(language)) {
+    return refuse(
+      'search',
+      `"${String(language)}" is not a Postgres text search configuration — one of: ${SEARCH_LANGUAGES.join(', ')}`,
+    );
+  }
+  const column = init?.column ?? DEFAULT_SEARCH_COLUMN;
+  if (taken(column)) {
+    return refuse(
+      'search',
+      `the search vector column "${column}" is already a declared column — rename it, or name another with search: { column: '<name>' }`,
+    );
+  }
+  return { column, language, sources, expression: searchExpression(language, sources) };
+};