uql-orm 0.61.0 → 0.62.0

package/dist/type/dialect.d.ts

@@ -1,4 +1,4 @@
-import type { UpdatePayload } from './entity.js';
+import type { EntityMeta, UpdatePayload } from './entity.js';
 import type { Query, QueryConflictPaths, QueryFilter, QueryOptions, QuerySearch } from './query.js';
 import type { QueryAggMap, QueryAggregate, QueryGroupMap } from './queryAggregate.js';
 import type { Type } from './utility.js';
@@ -46,7 +46,13 @@ export interface QueryContext {
     createFragment(): QueryContext;
     readonly sql: string;
     readonly values: unknown[];
+    /** Whether a value is written as its literal rather than bound: DDL has no placeholder to bind into. */
+    readonly inlineValues: boolean;
 }
+export type QueryContextOptions = {
+    /** See {@link QueryContext.inlineValues}. */
+    readonly inlineValues?: boolean;
+};
 /**
  * Capabilities of the database driver (transport layer).
  */
@@ -219,11 +225,10 @@ export interface QueryDialect {
      */
     escape(val: unknown): string;
     /**
-     * add a value to the query.
-     * @param values the values array
-     * @param value the value to add
+     * The SQL `value` takes in `ctx`: a raw expression rendered in place, the literal where `ctx` inlines
+     * values, and otherwise a placeholder for the value bound.
      */
-    addValue(values: unknown[], value: unknown): string;
+    addValue(ctx: QueryContext, value: unknown): string;
     /**
      * normalizes a value according to the dialect.
      * @param value the value to normalize
@@ -232,7 +237,11 @@ export interface QueryDialect {
     /**
      * create a new query context.
      */
-    createContext(): QueryContext;
+    createContext(options?: QueryContextOptions): QueryContext;
+    /**
+     * The column a field of `meta` is stored in, named the way this dialect names columns.
+     */
+    columnOf<E>(meta: EntityMeta<E>, key: string): string;
 }
 /**
  * Supported SQL dialect identifiers.

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 { 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,48 @@ type RelationOptionsThroughOwner<E, O> = Pick<RelationOptions<E, O>, 'entity' |
 export type KeyMap<E> = {
     readonly [K in keyof E]-?: K;
 };
+declare const COLUMN_KEY: unique symbol;
+/**
+ * A field of an entity as SQL, read off a {@link RefMap}: interpolated into `raw`, it renders as that
+ * field's column. A `QueryRaw` like any other fragment, branded with the field `K` it names.
+ */
+export type ColumnRef<K extends string = string> = QueryRaw & {
+    readonly [COLUMN_KEY]?: 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>;
+};
+/**
+ * A callback reading an entity's fields off a {@link RefMap} for the SQL it returns. 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 SqlCallback<E> = {
+    sql(row: RefMap<E>): QueryRaw;
+}['sql'];
+/** SQL a definition writes: `raw`, or a {@link SqlCallback} for SQL that names the entity's fields. */
+export type EntitySql<E> = QueryRaw | SqlCallback<E>;
+/**
+ * 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,13 +677,13 @@ 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.
+ * One entry of an index: a column by default, a {@link SqlCallback} to index an expression, or an object
+ * when the entry needs more than that.
  *
  * @example
  * ```ts
  * @Index((post) => [post.tenantId, { column: post.createdAt, order: 'desc' }]) // keyset pagination
- * @Index(() => [raw`lower("email")`], { unique: true })                      // case-insensitive uniqueness
+ * @Index(() => [(post) => raw`lower(${post.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
  * ```
@@ -648,7 +693,7 @@ export type IndexTypeOptions = {
  * 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>;
+export type IndexColumnInput<C extends string = string, E = unknown> = C | SqlCallback<E> | IndexColumnOptions<C, E> | 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' } }`
@@ -663,7 +708,7 @@ export type IndexColumnInput<C extends string = string, E = unknown> = C | Query
  * builder. An entity with no JSON field at all offers no arm, which is also the truth.
  */
 type IndexJsonColumnOptions<C extends string, E> = unknown extends E ? IndexColumnModifiers & {
-    readonly column: C | QueryRaw;
+    readonly column: C;
 } : {
     [K in JsonColumnKey<E>]: IndexColumnPlainModifiers & {
         readonly column: K;
@@ -762,9 +807,9 @@ 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;
+export type IndexColumnOptions<C extends string = string, E = unknown> = IndexColumnPlainModifiers & {
+    /** The column to index, or a {@link SqlCallback} for an expression. */
+    readonly column: C | SqlCallback<E>;
     readonly jsonPath?: never;
     readonly jsonArray?: never;
 };
@@ -778,18 +823,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 +879,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 +893,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 +921,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 +958,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>[]>>;
 };
@@ -909,18 +970,17 @@ export type EntityOptions<E = unknown> = {
 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;
+    /** 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]`,
  * so they are checked against it and follow a rename. The migration builder names raw columns instead.
  */
-export type EntityIndexOptions<E> = Except<IndexOptions, 'include'> & {
+export type EntityIndexOptions<E> = Except<IndexOptions, 'include' | 'where'> & {
     readonly include?: (keys: KeyMap<E>) => readonly 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

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;
-    /**
-     * the escaped prefix.
-     */
-    escapedPrefix?: 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 query context.
+     * 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.
      */
-    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,8 @@ 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;
 }

package/dist/type/queryRaw.js

@@ -16,17 +16,11 @@ 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));
         }

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 the shapes users write - a column
+ * name, an expression's callback, an options object - reach the schema as one, each callback resolved.
  */
-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,25 @@
-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 { QueryRaw } from '../type/index.js';
+import { entitySql } from './raw.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 the shapes users write - a column
+ * name, an expression's callback, an options object - reach the schema as one, each callback resolved.
  */
 export function normalizeIndexColumn(entry) {
     if (typeof entry === 'string') {
         return { column: entry };
     }
-    if (entry instanceof QueryRaw) {
-        return { column: ddlText(entry, 'an index expression'), expression: true };
+    if (typeof entry === 'function') {
+        return { column: entitySql(entry) };
     }
-    const { column, ...rest } = entry;
-    return column instanceof QueryRaw
-        ? { ...rest, column: ddlText(column, 'an index expression'), expression: true }
-        : { ...rest, column };
+    const { column } = entry;
+    return { ...entry, column: typeof column === 'function' ? entitySql(column) : 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.

package/dist/util/dialect.util.js

@@ -222,7 +222,7 @@ export function hasVectorNear(where) {
     return Object.entries(where).some(([key, value]) => key === '$near' || hasVectorNear(value));
 }
 function indexCoversColumn(index, key) {
-    return index.columns.some((entry) => !(entry instanceof QueryRaw) && entry.column === key);
+    return index.columns.some((entry) => entry.column === key);
 }
 /** `satisfies` ties this to {@link JsonUpdateOp}, so renaming an operator breaks it at compile time. */
 const JSON_UPDATE_OPS = [
@@ -293,8 +293,7 @@ export function applyFilters(meta, whereMap, opts) {
         if (!active) {
             continue;
         }
-        const raw = filter.condition;
-        const condition = typeof raw === 'function' ? raw(context) : raw;
+        const condition = typeof filter.where === 'function' ? filter.where(context) : filter.where;
         if (condition === undefined) {
             const onMissing = filter.onMissing ?? (filter.security ? 'throw' : 'skip');
             if (onMissing === 'throw') {
@@ -444,7 +443,7 @@ export function textSearchFields(meta, search) {
     }
     const fulltext = (meta.indexes ?? []).filter((index) => index.type === 'fulltext');
     if (fulltext.length === 1) {
-        return fulltext[0].columns.map((entry) => entry.column);
+        return fulltext[0].columns.flatMap((entry) => (typeof entry.column === 'string' ? [entry.column] : []));
     }
     const name = entityName(meta);
     const declared = fulltext.length

package/dist/util/field.util.d.ts

@@ -32,7 +32,7 @@ export declare function isIntegerColumn(field: Pick<FieldOptions, 'type' | 'colu
  * Every read site asks this - the DDL skip, the projection, the `$where` and `ORDER BY` operands -
  * because an inlined field has no column to name, while a stored one is read like any other.
  */
-export declare function isInlinedExpression(field: FieldOptions): boolean;
+export declare function isInlinedExpression<F extends FieldOptions>(field: F): field is F & Required<Pick<F, 'computed'>>;
 /**
  * Whether the database supplies this field's value, so no insert or update may write it: a stored
  * computed column *is* a real column, read like one, but writing to it is an error on every engine.