uql-orm 0.61.0 → 0.63.0

package/dist/type/entity.d.ts

@@ -1,6 +1,7 @@
-import type { CheckSchema, EnumValues, ForeignKeyAction, IndexType } from '../schema/types.js';
+import type { EnumValues, ForeignKeyAction, IndexType } from '../schema/types.js';
 import type { FilterOptions } from './query.js';
-import type { QueryRaw } from './queryRaw.js';
+import type { ColumnRef, QueryRaw } from './queryRaw.js';
+import type { QueryWhere } from './queryWhere.js';
 import type { Except, IsMany, Json, Scalar, Type, Unpacked } from './utility.js';
 import type { VectorDistance, VectorIndexOptions, VectorIndexType } from './vector.js';
 /**
@@ -299,7 +300,9 @@ export type TypeFor<V, T = NonNullable<V>> = IsJsonColumn<T> extends true ? Json
  * live there behind an `@internal` tag and a "do not set this" note, which is a comment standing in
  * for a type boundary.
  */
-export type FieldMeta<V = TsTypeOf<FieldType>> = FieldOptions<V> & {
+export type FieldMeta<V = TsTypeOf<FieldType>> = Except<FieldOptions<V>, 'computed'> & {
+    /** {@link FieldOptions.computed}, a callback resolved to the SQL it returns. */
+    readonly computed?: QueryRaw;
     /**
      * Set by `defineField` when the field gave `references` but no `type`, so schema generation resolves
      * the column from the referenced primary key rather than from whatever ended up in `type`. That is
@@ -317,7 +320,7 @@ export type FieldMeta<V = TsTypeOf<FieldType>> = FieldOptions<V> & {
  * and what a default is has to be that value, checked the same way the declared `type` is. `Scalar` by
  * default, for the places that handle a field without knowing which one it is.
  */
-export type FieldOptions<V = TsTypeOf<FieldType>> = {
+export type FieldOptions<V = TsTypeOf<FieldType>, E = unknown> = {
     readonly name?: string;
     readonly isId?: true;
     readonly type?: FieldType;
@@ -365,9 +368,9 @@ export type FieldOptions<V = TsTypeOf<FieldType>> = {
      * expression will do. With `stored`, it becomes a real column - `GENERATED ALWAYS AS (...) STORED` -
      * which the engine keeps up to date, so it can be indexed and read like any other.
      *
-     * @example `@Field({ type: String, computed: raw`"first" || ' ' || "last"`, stored: true })`
+     * @example `@Field({ type: String, computed: (user) => raw`${user.first} || ' ' || ${user.last}`, stored: true })`
      */
-    readonly computed?: QueryRaw;
+    readonly computed?: EntitySql<E>;
     /**
      * Whether {@link FieldOptions.computed} is a column the database keeps, rather than an expression
      * spliced into each statement. The dial to flip after profiling: `$select`, `$where` and `$sort`
@@ -466,9 +469,9 @@ export type TsTypeOf<T> = T extends StringConstructor ? string : T extends Numbe
  * `@Field({ references: () => Company })` would silently downgrade a `uuid` key to TEXT on every
  * column pointing at it.
  */
-export type FieldOptionsFor<V> = (FieldOptions<NonNullable<V>> & {
+export type FieldOptionsFor<V, E = unknown> = (FieldOptions<NonNullable<V>, E> & {
     readonly type: TypeFor<V>;
-}) | (FieldOptions<NonNullable<V>> & {
+}) | (FieldOptions<NonNullable<V>, E> & {
     readonly references: EntityGetter;
     readonly type?: TypeFor<V>;
 });
@@ -592,6 +595,38 @@ type RelationOptionsThroughOwner<E, O> = Pick<RelationOptions<E, O>, 'entity' |
 export type KeyMap<E> = {
     readonly [K in keyof E]-?: K;
 };
+/**
+ * The fields of `E` as {@link ColumnRef}s, for SQL that names them: `refs(User)` in a statement, the
+ * callback's parameter in a definition. Keyed over a type parameter constrained to `keyof E`, as
+ * {@link KeyMap} is over `keyof E`, which keeps each ref linked to its field for rename.
+ */
+export type RefMap<E, F extends keyof E = FieldKey<E>> = {
+    readonly [K in F]-?: ColumnRef<K & string>;
+};
+/**
+ * SQL a definition writes: `raw`, or a callback reading the entity's fields off its refs. The callback is
+ * declared as a method, bivariant in its refs, so one typed for its entity still fits where the entity is
+ * erased: the registry, which resolves it.
+ */
+export type EntitySql<E> = QueryRaw | {
+    sql(refs: RefMap<E>): QueryRaw;
+}['sql'];
+/**
+ * A predicate DDL carries, over the entity's own fields: a relation, full-text search and a sub-query
+ * have nothing a `CHECK` or a partial index can hold. An intersection rather than `Except`, which would
+ * remap the keys and lose each one's link to its field.
+ */
+export type EntityPredicate<E> = QueryWhere<E> & {
+    readonly [K in RelationKey<E>]?: never;
+} & {
+    readonly $text?: never;
+    readonly $exists?: never;
+    readonly $nexists?: never;
+};
+/** A definition's predicate: an {@link EntityPredicate}, or {@link EntitySql} for what one cannot say. */
+export type EntityWhere<E> = EntityPredicate<E> | EntitySql<E>;
+/** A definition's predicate as metadata keeps it, a callback resolved to its SQL, for the schema build to compile. */
+export type EntityWhereMeta<E> = EntityPredicate<E> | QueryRaw;
 export type RelationReferences = {
     readonly local: string;
     readonly foreign: string;
@@ -632,41 +667,24 @@ export type IndexTypeOptions = {
     distance?: never;
 };
 /**
- * One entry of an index: a column name by default, `raw(...)` to index an expression, or an object
- * when the entry needs more than a name.
- *
- * @example
- * ```ts
- * @Index((post) => [post.tenantId, { column: post.createdAt, order: 'desc' }]) // keyset pagination
- * @Index(() => [raw`lower("email")`], { unique: true })                      // case-insensitive uniqueness
- * @Index((post) => [{ column: post.body, length: 64 }])                       // MySQL needs a prefix on TEXT
- * @Index((post) => [post.data], { type: 'gin' })                              // JSONB containment
- * ```
- *
- * `C` is the entity's `FieldKey` on the `@Index`/`defineEntity` paths, where the decorated class says
- * which columns exist, and `E` the entity itself, which is what checks a JSON entry's path. Both
- * default to the unchecked form for the migration builder's `table.index(...)`, which names raw
- * table columns with no entity in scope.
- */
-export type IndexColumnInput<C extends string = string, E = unknown> = C | QueryRaw | IndexColumnOptions<C> | IndexJsonColumnOptions<C, E>;
-/**
- * The JSON entries, whose `path` is checked against the payload of the column the same entry names -
- * a mapped union, one arm per JSON field, so `{ column: 'kind', jsonPath: { path: 'thema.color' } }`
- * cannot compile. It matters more here than anywhere else in the index API: a path that is merely
- * *misspelled* still builds a perfectly valid index, one no query will ever match, and nothing at
- * runtime can tell that from the index you meant.
- *
- * `jsonArray`'s path is the array's own, so on a column that *is* the array (`Json<string[]>`) it
- * resolves to `never` and the property can only be omitted, which is exactly the truth.
- *
- * Falls back to the unchecked shape only where there is no entity to check against - the migration
- * builder. An entity with no JSON field at all offers no arm, which is also the truth.
+ * One index entry as the migration builder takes it: a column name, `raw` for an expression, or an object
+ * when the entry needs more. An entity's entries are this too, which is what `normalizeIndexColumn` reads.
+ */
+export type IndexColumnInput = string | QueryRaw | EntityIndexColumn;
+/**
+ * One entry of an entity's index, read off its refs: a column, `raw` for an expression, or an object when
+ * the entry needs more, a JSON entry's path checked against its column.
+ * @example `@Index((post) => [post.tenantId, { column: post.createdAt, order: 'desc' }, raw`lower(${post.email})`])`
  */
-type IndexJsonColumnOptions<C extends string, E> = unknown extends E ? IndexColumnModifiers & {
-    readonly column: C | QueryRaw;
-} : {
+export type EntityIndexColumnInput<E> = QueryRaw | IndexColumnOptions | IndexJsonColumnOptions<E>;
+/**
+ * The JSON entries, one arm per JSON field, each `path` checked against the payload of the column its own
+ * entry names: a misspelled path still builds a valid index that no query matches. On a column that is
+ * the array (`Json<string[]>`), `jsonArray`'s path resolves to `never`, so it can only be omitted.
+ */
+type IndexJsonColumnOptions<E> = {
     [K in JsonColumnKey<E>]: IndexColumnPlainModifiers & {
-        readonly column: K;
+        readonly column: ColumnRef<K & string>;
     } & ({
         readonly jsonPath: WithCheckedPath<IndexJsonPath, E, K>;
         readonly jsonArray?: never;
@@ -682,7 +700,7 @@ type IndexJsonColumnOptions<C extends string, E> = unknown extends E ? IndexColu
  * subject is that column.
  */
 type JsonColumnKey<E> = {
-    readonly [K in keyof E]-?: IsJson<NonNullable<E[K]>> extends true ? K : IsJson<JsonElement<E[K]>> extends true ? K : never;
+    readonly [K in keyof E]-?: IsJsonColumn<NonNullable<E[K]>> extends true ? K : never;
 }[Key<E>];
 /** The payload a path is checked against: the column's own brand, or that of the documents it holds. */
 type JsonColumnPayload<V> = IsJson<NonNullable<V>> extends true ? UnwrapJson<NonNullable<V>> : JsonPayload<V>;
@@ -762,15 +780,19 @@ export type IndexJsonArray = {
 };
 /** The modifiers that do not name a JSON path, and so need no entity to be checked against. */
 type IndexColumnPlainModifiers = Except<IndexColumnModifiers, 'jsonPath' | 'jsonArray'>;
-export type IndexColumnOptions<C extends string = string> = IndexColumnPlainModifiers & {
-    /** The column to index, or `raw(...)` for an expression. */
-    readonly column: C | QueryRaw;
+/**
+ * An entity's entry with plain modifiers. `jsonPath` and `jsonArray` are `never` here, since a JSON entry
+ * would otherwise match this shape too, its path unchecked.
+ */
+type IndexColumnOptions = IndexColumnPlainModifiers & {
+    /** A column read off the refs, or `raw` for an expression. */
+    readonly column: QueryRaw;
     readonly jsonPath?: never;
     readonly jsonArray?: never;
 };
 /**
- * One index entry, normalized: {@link IndexColumnInput}'s three authored shapes all reduce to this
- * before any dialect or generator sees them, so rendering never re-parses the sugar.
+ * One index entry, normalized: every authored shape reduces to this before any dialect or generator sees
+ * it, so rendering never re-parses the sugar.
  */
 export type IndexColumnSchema = IndexColumnModifiers & {
     /** A column name, or raw SQL when {@link expression} is set. */
@@ -778,18 +800,26 @@ export type IndexColumnSchema = IndexColumnModifiers & {
     /** Whether {@link column} is an expression to emit as-is rather than an identifier to quote. */
     readonly expression?: boolean;
 };
+/**
+ * One index entry as entity metadata keeps it: a member, or an expression left unrendered until the
+ * schema is built, where the dialect and the naming strategy resolve what it references. Rendered, it
+ * is an {@link IndexColumnSchema}.
+ */
+export type EntityIndexColumn = IndexColumnModifiers & {
+    readonly column: string | QueryRaw;
+};
 /**
  * An index as stored in entity metadata: authored options with the columns normalized.
  */
-export type EntityIndexMeta = {
+export type EntityIndexMeta<E = object> = {
     /** The indexed columns, in order. */
-    columns: readonly IndexColumnSchema[];
+    columns: readonly EntityIndexColumn[];
     /** Custom index name */
     name?: string;
     /** Whether index is unique; omit or `false` for a non-unique index (default). */
     unique?: boolean;
-    /** Partial index condition (WHERE clause) */
-    where?: string;
+    /** Partial index predicate, compiled when the schema is built. */
+    where?: EntityWhereMeta<E>;
     /**
      * Extra columns stored in the index but not part of its key, so a query reading only these is
      * answered from the index alone. Postgres-wire only (`INCLUDE`).
@@ -826,9 +856,9 @@ export type EntityMeta<E> = {
         [key: string]: RelationMeta | undefined;
     };
     /** Composite indexes defined via @Index decorator */
-    indexes?: EntityIndexMeta[];
-    /** `CHECK` constraints, their expressions already reduced to text. */
-    checks?: CheckSchema[];
+    indexes?: EntityIndexMeta<E>[];
+    /** `CHECK` constraints, compiled when the schema is built. */
+    checks?: EntityCheckMeta<E>[];
     /** Lifecycle hooks registered via @BeforeInsert, @AfterUpdate, etc. */
     hooks?: Partial<Record<HookEvent, HookRegistration[]>>;
     /**
@@ -840,13 +870,21 @@ export type EntityMeta<E> = {
     processedAt?: number;
 };
 /**
- * A table-level `CHECK`. The expression is `raw` with no interpolation, like an index expression:
- * this is DDL, so there is no placeholder a bound value could go into.
+ * A table-level `CHECK`: a predicate over the entity's fields, or SQL reading them off refs. A value in
+ * either is written as its literal, since DDL has no placeholder to bind one into.
+ *
+ * @example `{ where: { balance: { $gte: 0 } } }`
+ * @example `{ where: (wallet) => raw`${wallet.spent} <= ${wallet.balance}` }`
  */
-export type CheckOptions = {
+export type CheckOptions<E = unknown> = {
     /** Derived from the table and the constraint's position when absent. */
     readonly name?: string;
-    readonly expression: QueryRaw;
+    readonly where: EntityWhere<E>;
+};
+/** A `CHECK` as entity metadata keeps it, its callback resolved. */
+export type EntityCheckMeta<E = object> = {
+    readonly name?: string;
+    readonly where: EntityWhereMeta<E>;
 };
 /**
  * An entity's members as the registry takes them, keyed by plain strings - what a decorator bag, an
@@ -860,7 +898,7 @@ export type EntityMembers = {
 };
 /** An entity's fields as `defineEntity` takes them, keyed like every entity map (see `QuerySelect`). */
 type EntityFieldOptions<E, F extends keyof E = FieldKey<E>> = {
-    readonly [K in F]?: FieldOptionsFor<E[K]>;
+    readonly [K in F]?: FieldOptionsFor<E[K], E>;
 };
 /**
  * An entity's relations as `defineEntity` takes them. Keyed over every member rather than `RelationKey<E>`:
@@ -897,7 +935,7 @@ export type EntityOptions<E = unknown> = {
     readonly relations?: EntityRelationOptions<E>;
     readonly indexes?: readonly EntityIndexInput<E>[];
     /** Table-level `CHECK` constraints. See {@link CheckOptions}. */
-    readonly checks?: readonly CheckOptions[];
+    readonly checks?: readonly CheckOptions<E>[];
     /** Each lifecycle event and the methods it runs, read off the key map: `{ beforeInsert: (post) => [post.stamp] }`. */
     readonly hooks?: Partial<Record<HookEvent, (keys: KeyMap<E>) => readonly MethodKey<E>[]>>;
 };
@@ -906,28 +944,25 @@ export type EntityOptions<E = unknown> = {
  * and through {@link EntityIndexOptions} `@Index` and `defineEntity`. `Except` (not plain `Omit`) keeps
  * `type`/`distance` a discriminated pair: omitting `distance` on a vector index type is a compile error.
  */
-export type IndexOptions = Except<EntityIndexMeta, 'columns' | 'include' | 'where'> & {
-    /** Non-key columns stored in the index, by column name; a typo builds nothing, the server refusing it. */
-    readonly include?: readonly string[];
-    /**
-     * Partial-index predicate. `raw` with no interpolation, like an index expression: this is DDL, so
-     * there is no placeholder for a bound value. A bare string is the older spelling and still works.
-     */
-    readonly where?: string | QueryRaw;
+export type IndexOptions = Except<EntityIndexMeta, 'columns' | 'where'> & {
+    /** Partial-index predicate, as `raw` with no interpolation: the migration builder has no entity to compile one against. */
+    readonly where?: QueryRaw;
 };
 /**
- * {@link IndexOptions} on an entity, whose stored columns are read off its key map, `(post) => [post.slug]`,
+ * {@link IndexOptions} on an entity, whose stored columns are read off its refs, `(post) => [post.slug]`,
  * so they are checked against it and follow a rename. The migration builder names raw columns instead.
  */
-export type EntityIndexOptions<E> = Except<IndexOptions, 'include'> & {
-    readonly include?: (keys: KeyMap<E>) => readonly FieldKey<E>[];
+export type EntityIndexOptions<E> = Except<IndexOptions, 'include' | 'where'> & {
+    readonly include?: (refs: RefMap<E>) => readonly ColumnRef<FieldKey<E>>[];
+    /** Partial-index predicate. See {@link EntityWhere}. */
+    readonly where?: EntityWhere<E>;
 };
 /**
- * An index as authored on an entity, before `defineIndex` reads its columns off the key map. Only the
+ * An index as authored on an entity, before `defineIndex` reads its columns off the refs. Only the
  * member lists are callbacks: TypeScript never checks a callback's returned literal for excess properties,
  * so the options stay a literal of their own, where `uniqe: true` is a compile error.
  */
 export type EntityIndexInput<E> = EntityIndexOptions<E> & {
-    readonly columns: (keys: KeyMap<E>) => readonly IndexColumnInput<FieldKey<E>, E>[];
+    readonly columns: (refs: RefMap<E>) => readonly EntityIndexColumnInput<E>[];
 };
 export {};

package/dist/type/migration.d.ts

@@ -1,9 +1,9 @@
 import type { VectorCast } from '../dialect/vectorCast.js';
-import type { FullColumnDefinition, TableDefinition } from '../migrate/builder/types.js';
+import type { FullColumnDefinition, IndexDefinition, TableDefinition } from '../migrate/builder/types.js';
 import type { IndexFacet } from '../schema/indexDifferences.js';
 import type { SchemaAST } from '../schema/schemaAST.js';
 import type { ColumnNode, ForeignKeyAction, IndexNode, IndexType, TableNode } from '../schema/types.js';
-import type { EntityMeta, FieldOptions, IndexColumnSchema, LoggingOptions, Querier, SqlQuerier, Type, VectorIndexOptions } from './index.js';
+import type { EntityMeta, EntityWhereMeta, FieldOptions, IndexColumnSchema, LoggingOptions, Querier, SqlQuerier, Type, VectorIndexOptions } from './index.js';
 /**
  * Defines a migration using a simple object literal. `Q` is `MongoQuerier` for a MongoDB migration.
  */
@@ -295,6 +295,11 @@ export interface SchemaGenerator {
      * Get the SQL type for a field based on its options
      */
     getSqlType(fieldOptions: FieldOptions): string;
+    /**
+     * The text of SQL an entity declares - a check, a stored computed column, an index expression or
+     * predicate - rendered for this engine, which is what building an entity's schema needs from it.
+     */
+    compileDdl(sql: EntityWhereMeta<object>, entity: Type<object>): string;
     /**
      * Compare an entity with a database table node and return the differences.
      *
@@ -361,6 +366,8 @@ export interface SqlDdlGenerator extends SchemaGenerator {
     generateAddForeignKeySql(tableName: string, foreignKey: ForeignKeySchema): string;
     /** Generate DROP FOREIGN KEY statement */
     generateDropForeignKeySql(tableName: string, constraintName: string): string;
+    /** CREATE INDEX from a builder's {@link IndexDefinition}, its SQL rendered for this engine. */
+    generateCreateIndexFromDefinition(tableName: string, index: IndexDefinition): string;
 }
 /**
  * Interface for introspecting the current database schema

package/dist/type/query.d.ts

@@ -90,7 +90,7 @@ export interface UqlContext {
  * A filter's `$where` fragment: a plain fragment, or a function of the ambient {@link UqlContext}.
  * Return `undefined` when the condition can't resolve (see {@link FilterOptions.onMissing}).
  */
-export type FilterCondition<E> = QueryWhere<E> | ((context: UqlContext | undefined) => QueryWhere<E> | undefined);
+export type FilterWhere<E> = QueryWhere<E> | ((context: UqlContext | undefined) => QueryWhere<E> | undefined);
 /**
  * What to do when a filter's condition returns `undefined`. `skip` omits it (convenience filters);
  * `throw` fails closed (the default for `security` filters).
@@ -100,7 +100,7 @@ export type FilterOnMissing = 'skip' | 'throw';
  * Authoring shape for `@Entity({ filters })` / `@Filter` / `defineFilter`.
  */
 export type FilterOptions<E = unknown> = {
-    readonly condition: FilterCondition<E>;
+    readonly where: FilterWhere<E>;
     /** Applied to every query unless bypassed via `QueryOptions.filters`. Defaults to `true`. */
     readonly default?: boolean;
     /**
@@ -108,7 +108,7 @@ export type FilterOptions<E = unknown> = {
      * AND-merged so a client `$where` on the same field can't override it.
      */
     readonly security?: boolean;
-    /** What to do when the condition returns `undefined`. Defaults to `skip`, or `throw` for `security`. */
+    /** What to do when {@link where} returns `undefined`. Defaults to `skip`, or `throw` for `security`. */
     readonly onMissing?: FilterOnMissing;
 };
 /**

package/dist/type/queryLock.d.ts

@@ -1,16 +1,16 @@
-declare const QUERY_LOCK_WAITS: readonly ['block', 'nowait', 'skip'];
+declare const QUERY_LOCK_WAITS: readonly ['nowait', 'skip'];
 /**
- * What to do about a row someone else already holds. `block` (the default) waits for them; `nowait`
- * fails the statement at once; `skip` leaves the row out of the result, which is what makes a
+ * What to do about a row someone else already holds. `block` (what `true` asks for) waits for them;
+ * `nowait` fails the statement at once; `skip` leaves the row out of the result, which is what makes a
  * work-queue possible: each worker takes rows nobody else has.
  */
-export type QueryLockWait = (typeof QUERY_LOCK_WAITS)[number];
+export type QueryLockWait = 'block' | (typeof QUERY_LOCK_WAITS)[number];
 /**
- * `true` takes the lock and waits for anyone holding the rows; the object form chooses what to do
- * instead of waiting. `false` takes none, so a query built conditionally needs no branch.
+ * `true` takes the lock and waits for anyone holding the rows; `$wait` chooses what to do instead of
+ * waiting. `false` takes none, so a query built conditionally needs no branch.
  */
 export type QueryLock = boolean | {
-    readonly wait?: QueryLockWait;
+    readonly $wait: (typeof QUERY_LOCK_WAITS)[number];
 };
 /**
  * The wait policy this lock resolves to, or `undefined` when there is no lock. An unknown policy

package/dist/type/queryLock.js

@@ -1,4 +1,4 @@
-const QUERY_LOCK_WAITS = ['block', 'nowait', 'skip'];
+const QUERY_LOCK_WAITS = ['nowait', 'skip'];
 function isOneOf(vals, val) {
     return vals.includes(val);
 }
@@ -8,12 +8,14 @@ function isOneOf(vals, val) {
  * the SQL it would have produced.
  */
 export function parseQueryLock(lock) {
-    if (lock === undefined || lock === false) {
+    if (!lock) {
         return undefined;
     }
-    const wait = lock === true ? 'block' : (lock?.wait ?? 'block');
-    if (!isOneOf(QUERY_LOCK_WAITS, wait)) {
-        throw new TypeError(`unknown $lock wait policy: ${String(wait)}`);
+    if (lock === true) {
+        return 'block';
     }
-    return wait;
+    if (!isOneOf(QUERY_LOCK_WAITS, lock.$wait)) {
+        throw new TypeError(`unknown $lock wait policy: ${String(lock.$wait)}`);
+    }
+    return lock.$wait;
 }

package/dist/type/queryRaw.d.ts

@@ -1,43 +1,36 @@
 import type { QueryContext, QueryDialect } from './dialect.js';
-import type { Scalar } from './utility.js';
-/**
- * What may be passed towards a `raw` callback. Every key is optional here because the callers along the
- * way fill them in progressively; what reaches the callback is the complete set - see {@link QueryRawFn}.
- */
-export type QueryRawFnOptions = {
-    /**
-     * the current dialect.
-     */
-    dialect?: QueryDialect;
-    /**
-     * the prefix.
-     */
-    prefix?: string;
+import type { Type } from './utility.js';
+/** What a `raw` callback receives. See {@link QueryRawFn}. */
+export type QueryRawRenderOptions = {
+    /** The dialect rendering the SQL. */
+    dialect: QueryDialect;
+    /** The alias of the table in scope, unescaped; empty where there is none. */
+    prefix: string;
+    /** {@link prefix} escaped, with its trailing dot. */
+    escapedPrefix: string;
+    /** The query context the SQL is written into. */
+    ctx: QueryContext;
     /**
-     * the escaped prefix.
+     * The entity being rendered, which a ref read off a definition's map resolves its column against: a
+     * computed field's own, or the one whose schema is built. Absent where a statement renders SQL.
      */
-    escapedPrefix?: string;
-    /**
-     * the query context.
-     */
-    ctx?: QueryContext;
+    entity?: Type<unknown>;
 };
+/** {@link QueryRawRenderOptions} as the callers along the way fill them in, every one still optional. */
+export type QueryRawFnOptions = Partial<QueryRawRenderOptions>;
 /**
  * A `raw` callback: write into `ctx`, or return a string or number to have it appended. Anything else
  * it returns is ignored, which is why the return type is `unknown` rather than `void | Scalar` - the
  * latter rejected `({ ctx }) => ctx.append(...)`, the form every computed field is written in, because
  * TypeScript's "returning a value where void is expected" allowance does not apply to a union.
- *
- * `Required`, and the parameter not optional, because the one place that calls it (`getRawValue`)
- * passes all four every time.
  */
-export type QueryRawFn = (opts: Required<QueryRawFnOptions>) => unknown;
+export type QueryRawFn = (opts: QueryRawRenderOptions) => unknown;
 export declare const RAW_VALUE: unique symbol;
 export declare const RAW_ALIAS: unique symbol;
 export declare class QueryRaw {
-    readonly [RAW_VALUE]: Scalar | QueryRawFn;
+    readonly [RAW_VALUE]: QueryRawFn;
     readonly [RAW_ALIAS]?: string;
-    constructor(value: Scalar | QueryRawFn, alias?: string);
+    constructor(value: QueryRawFn, alias?: string);
     /** The same expression under an alias, for a `$select` projection. */
     as(alias: string): QueryRaw;
     /**
@@ -45,9 +38,16 @@ export declare class QueryRaw {
      * business, which is what lets a `raw` tagged template resolve an interpolated fragment without
      * the dialect having to expose a method for it.
      *
-     * The alias is not emitted here: it belongs to a `$select` projection, not to an expression, and
-     * a fragment nested inside another would otherwise emit one mid-expression. `getRawValue` appends
-     * it around this call.
+     * The alias is not emitted here: it names a `$select` projection, which writes it after the term,
+     * and anywhere else it would land mid-expression.
      */
-    render(opts: Required<QueryRawFnOptions>): void;
+    render(opts: QueryRawRenderOptions): void;
+}
+/**
+ * A field of an entity as SQL, read off `refs(Entity)` or a definition's refs: interpolated into `raw`, it
+ * renders as the field's column. Its `key` is how an index tells a column from an expression.
+ */
+export declare class ColumnRef<K extends string = string> extends QueryRaw {
+    readonly key: K;
+    constructor(key: K, value: QueryRawFn);
 }

package/dist/type/queryRaw.js

@@ -16,19 +16,24 @@ export class QueryRaw {
      * business, which is what lets a `raw` tagged template resolve an interpolated fragment without
      * the dialect having to expose a method for it.
      *
-     * The alias is not emitted here: it belongs to a `$select` projection, not to an expression, and
-     * a fragment nested inside another would otherwise emit one mid-expression. `getRawValue` appends
-     * it around this call.
+     * The alias is not emitted here: it names a `$select` projection, which writes it after the term,
+     * and anywhere else it would land mid-expression.
      */
     render(opts) {
-        const value = this[RAW_VALUE];
-        if (typeof value !== 'function') {
-            opts.ctx.append(opts.prefix + String(value));
-            return;
-        }
-        const emitted = value(opts);
+        const emitted = this[RAW_VALUE](opts);
         if (typeof emitted === 'string' || (typeof emitted === 'number' && !Number.isNaN(emitted))) {
             opts.ctx.append(String(emitted));
         }
     }
 }
+/**
+ * A field of an entity as SQL, read off `refs(Entity)` or a definition's refs: interpolated into `raw`, it
+ * renders as the field's column. Its `key` is how an index tells a column from an expression.
+ */
+export class ColumnRef extends QueryRaw {
+    key;
+    constructor(key, value) {
+        super(value);
+        this.key = key;
+    }
+}

package/dist/util/ddlExpression.util.d.ts

@@ -1,15 +1,10 @@
-import { type IndexColumnInput, type IndexColumnSchema, QueryRaw } from '../type/index.js';
+import { type EntityIndexColumn, type IndexColumnInput, type IndexColumnSchema, QueryRaw } from '../type/index.js';
 /**
- * SQL bound for DDL, as the text a generator renders. `raw` with no interpolation, or a bare string
- * where one is still accepted: DDL is evaluated once at creation time, so there is no query context
- * for the callback form and no placeholder a `CREATE` statement could bind a value into.
- *
- * `what` names the thing being declared, so the error says which one the caller got wrong.
+ * Reduces an authored index entry to the form metadata keeps, so a column, an expression and an options
+ * object reach the schema as one: a column read off the refs as its key, any other `raw` as it is.
  */
-export declare function ddlText(value: string | QueryRaw, what: string): string;
-export declare function ddlText(value: string | QueryRaw | undefined, what: string): string | undefined;
-/**
- * Reduces an authored index entry to its normalized form, so the three shapes users write - a column
- * name, an expression, or an options object - reach the dialects as one.
- */
-export declare function normalizeIndexColumn(entry: IndexColumnInput): IndexColumnSchema;
+export declare function normalizeIndexColumn(entry: IndexColumnInput): EntityIndexColumn;
+/** An index entry as the schema holds it, its expression rendered to text by `render`. */
+export declare function renderIndexColumn(entry: EntityIndexColumn, render: (sql: QueryRaw) => string): IndexColumnSchema;
+/** What an unnamed index's name is built from: each entry's column, or `expr<n>` for an expression, which has none. */
+export declare function indexNameParts(entries: readonly EntityIndexColumn[]): string[];

package/dist/util/ddlExpression.util.js

@@ -1,27 +1,18 @@
-import { QueryRaw, RAW_VALUE } from '../type/index.js';
-export function ddlText(value, what) {
-    if (!(value instanceof QueryRaw)) {
-        return value;
-    }
-    const sql = value[RAW_VALUE];
-    if (typeof sql !== 'string') {
-        throw new TypeError(`${what} needs raw() with no interpolation, not a function or a bound value`);
-    }
-    return sql;
-}
+import { ColumnRef, QueryRaw, } from '../type/index.js';
 /**
- * Reduces an authored index entry to its normalized form, so the three shapes users write - a column
- * name, an expression, or an options object - reach the dialects as one.
+ * Reduces an authored index entry to the form metadata keeps, so a column, an expression and an options
+ * object reach the schema as one: a column read off the refs as its key, any other `raw` as it is.
  */
 export function normalizeIndexColumn(entry) {
-    if (typeof entry === 'string') {
-        return { column: entry };
-    }
-    if (entry instanceof QueryRaw) {
-        return { column: ddlText(entry, 'an index expression'), expression: true };
-    }
-    const { column, ...rest } = entry;
-    return column instanceof QueryRaw
-        ? { ...rest, column: ddlText(column, 'an index expression'), expression: true }
-        : { ...rest, column };
+    const { column, ...modifiers } = typeof entry === 'string' || entry instanceof QueryRaw ? { column: entry } : entry;
+    return { ...modifiers, column: column instanceof ColumnRef ? column.key : column };
+}
+/** An index entry as the schema holds it, its expression rendered to text by `render`. */
+export function renderIndexColumn(entry, render) {
+    const { column } = entry;
+    return column instanceof QueryRaw ? { ...entry, column: render(column), expression: true } : { ...entry, column };
+}
+/** What an unnamed index's name is built from: each entry's column, or `expr<n>` for an expression, which has none. */
+export function indexNameParts(entries) {
+    return entries.map((entry, at) => (typeof entry.column === 'string' ? entry.column : `expr${at}`));
 }

package/dist/util/dialect.util.d.ts

@@ -83,7 +83,7 @@ export declare function findVectorSort<E>(sort: QuerySortMap<E> | undefined): {
  * The vector index declared on `key`, if any. Answers both "is there an ANN index to tune here" and
  * "which kind", which decide the name Atlas is queried by and the setting Postgres is tuned with.
  */
-export declare function findVectorIndex<E>(meta: EntityMeta<E>, key: string): EntityIndexMeta | undefined;
+export declare function findVectorIndex<E>(meta: EntityMeta<E>, key: string): EntityIndexMeta<E> | undefined;
 /**
  * Whether a `$where` filters by vector distance anywhere in its tree, `$and`/`$or`/`$not` included.
  * What tells Postgres that an HNSW scan needs to iterate rather than return one candidate list.