uql-orm 0.60.0 → 0.62.0

package/dist/querier/queryError.d.ts

@@ -1,22 +1,25 @@
 import type { LoggerWrapper } from '../util/logger.js';
 /**
- * A driver error enriched with context by {@link enrichError}. `query` is always attached; `values`
- * only when the querier's logger is configured to surface them (see {@link enrichError}) - they can
- * carry sensitive data (PII, tokens, etc.) and would otherwise leak into whatever error-tracking
- * pipeline (Sentry, console.error, ...) serializes the error, without the developer opting in.
+ * A driver error tagged by {@link enrichError}: `query` always, `values` only when the logger already
+ * surfaces them, since they can carry PII or tokens into whatever serializes the error.
  */
 export interface QueryError extends Error {
     query?: string;
     values?: unknown[];
 }
 /**
- * Tags `err` with the query it failed on (as {@link QueryError}) and hands it back for the caller to
- * throw. `values` is only attached when `logger?.willLogValues()` is true, i.e. the app already has
- * query values surfacing somewhere (query-level or slow-query logging), so attaching them here does not
- * introduce a new leak surface. Shared by every query call site (timed queries, streams, transaction
- * statements) so the logic lives in one place.
- *
- * Returns rather than throws so `throw enrichError(...)` reads as the control flow it is, which also
- * means callers need no `never` annotation and no unreachable-code suppression.
+ * What a failed query ran into, named the same on every engine. `retryable` is a deadlock, a
+ * serialization failure, a lock timeout or a busy database: the transaction can simply run again.
+ */
+export type QueryErrorKind = 'uniqueViolation' | 'foreignKeyViolation' | 'notNullViolation' | 'checkViolation' | 'retryable';
+/**
+ * Names what `err` ran into on any engine, or `undefined` for anything else. Pure: the error is only
+ * read, so it works on any driver error, whether or not a querier saw it first.
+ */
+export declare function queryErrorKind(err: unknown): QueryErrorKind | undefined;
+/**
+ * Tags `err` with the query it failed on and hands it back, so `throw enrichError(...)` reads as the
+ * control flow it is. `values` are attached only when `logger?.willLogValues()`: they already surface
+ * in the logs then, so this opens no new leak.
  */
 export declare function enrichError(err: unknown, logger: LoggerWrapper | undefined, query: string, values?: unknown[]): unknown;

package/dist/querier/queryError.js

@@ -1,12 +1,71 @@
+/** Postgres, CockroachDB, PGlite and Neon in `code`; Bun SQL in `errno`. */
+const SQLSTATE_KINDS = new Map([
+    ['23505', 'uniqueViolation'],
+    ['23503', 'foreignKeyViolation'],
+    ['23502', 'notNullViolation'],
+    ['23514', 'checkViolation'],
+    ['40P01', 'retryable'],
+    ['40001', 'retryable'],
+    ['55P03', 'retryable'],
+]);
+/** MySQL and MariaDB, in a numeric `errno`. */
+const MYSQL_ERRNO_KINDS = new Map([
+    [1062, 'uniqueViolation'],
+    [1451, 'foreignKeyViolation'],
+    [1452, 'foreignKeyViolation'],
+    [1048, 'notNullViolation'],
+    [1364, 'notNullViolation'],
+    [3819, 'checkViolation'],
+    [4025, 'checkViolation'],
+    [1213, 'retryable'],
+    [1205, 'retryable'],
+    [3572, 'retryable'],
+]);
+/** MSSQL, in `number`; its 547 is a check conflict too when the message names a CHECK constraint. */
+const MSSQL_NUMBER_KINDS = new Map([
+    [2627, 'uniqueViolation'],
+    [2601, 'uniqueViolation'],
+    [547, 'foreignKeyViolation'],
+    [515, 'notNullViolation'],
+    [1205, 'retryable'],
+    [1222, 'retryable'],
+    [3960, 'retryable'],
+]);
+const MONGO_CODE_KINDS = new Map([
+    [11000, 'uniqueViolation'],
+    [121, 'checkViolation'],
+    [112, 'retryable'],
+]);
+/** The SQLite family reports only a message on every driver, D1 included. */
+const SQLITE_MESSAGE_KINDS = [
+    ['UNIQUE constraint failed', 'uniqueViolation'],
+    ['FOREIGN KEY constraint failed', 'foreignKeyViolation'],
+    ['NOT NULL constraint failed', 'notNullViolation'],
+    ['CHECK constraint failed', 'checkViolation'],
+    ['database is locked', 'retryable'],
+];
 /**
- * Tags `err` with the query it failed on (as {@link QueryError}) and hands it back for the caller to
- * throw. `values` is only attached when `logger?.willLogValues()` is true, i.e. the app already has
- * query values surfacing somewhere (query-level or slow-query logging), so attaching them here does not
- * introduce a new leak surface. Shared by every query call site (timed queries, streams, transaction
- * statements) so the logic lives in one place.
- *
- * Returns rather than throws so `throw enrichError(...)` reads as the control flow it is, which also
- * means callers need no `never` annotation and no unreachable-code suppression.
+ * Names what `err` ran into on any engine, or `undefined` for anything else. Pure: the error is only
+ * read, so it works on any driver error, whether or not a querier saw it first.
+ */
+export function queryErrorKind(err) {
+    if (typeof err !== 'object' || err === null) {
+        return undefined;
+    }
+    const { code, errno, number, errorLabels, message } = err;
+    const text = typeof message === 'string' ? message : '';
+    return (SQLSTATE_KINDS.get(code) ??
+        SQLSTATE_KINDS.get(errno) ??
+        MYSQL_ERRNO_KINDS.get(errno) ??
+        (number === 547 && text.includes('CHECK constraint') ? 'checkViolation' : MSSQL_NUMBER_KINDS.get(number)) ??
+        MONGO_CODE_KINDS.get(code) ??
+        (Array.isArray(errorLabels) && errorLabels.includes('TransientTransactionError') ? 'retryable' : undefined) ??
+        SQLITE_MESSAGE_KINDS.find(([fragment]) => text.includes(fragment))?.[1]);
+}
+/**
+ * Tags `err` with the query it failed on and hands it back, so `throw enrichError(...)` reads as the
+ * control flow it is. `values` are attached only when `logger?.willLogValues()`: they already surface
+ * in the logs then, so this opens no new leak.
  */
 export function enrichError(err, logger, query, values) {
     if (err instanceof Error) {

package/dist/schema/schemaASTBuilder.d.ts

@@ -6,7 +6,7 @@
  * - Database introspection results (TableSchema[])
  */
 import type { EntityGetter } from '../type/entity.js';
-import type { EntityMeta, FieldMeta, FieldOptions, Type } from '../type/index.js';
+import type { EntityMeta, EntityWhereMeta, FieldMeta, FieldOptions, Type } from '../type/index.js';
 import type { NamingStrategy } from '../type/namingStrategy.js';
 import { SchemaAST } from './schemaAST.js';
 import { type CanonicalType, type ForeignKeyAction } from './types.js';
@@ -24,6 +24,11 @@ export interface BuildSchemaASTOptions {
     namingStrategy?: NamingStrategy;
     /** Default action for foreign key ON DELETE and ON UPDATE clauses */
     defaultForeignKeyAction?: ForeignKeyAction;
+    /**
+     * The text of SQL an entity declares - a check, a stored computed column, an index expression or
+     * predicate - which only a dialect can render. `buildEntityAST` supplies it from the generator.
+     */
+    compileDdl?: (sql: EntityWhereMeta<object>, entity: Type<object>) => string;
 }
 /**
  * Build a SchemaAST from entity classes (decorated with `@Entity`, `@Field`, etc.).

package/dist/schema/schemaASTBuilder.js

@@ -6,7 +6,7 @@
  * - Database introspection results (TableSchema[])
  */
 import { getMeta, soleIdOf } from '../entity/metadata/definition.js';
-import { ddlText } from '../util/ddlExpression.util.js';
+import { indexNameParts, renderIndexColumn } from '../util/ddlExpression.util.js';
 import { isInlinedExpression } from '../util/field.util.js';
 import { isSoleIdField } from '../util/field.util.js';
 import { isAutoIncrement } from '../util/field.util.js';
@@ -30,6 +30,7 @@ export function buildSchemaAST(entities, options = {}) {
         resolveSchema: options.resolveSchema ?? ((m) => m.schema),
         resolveColumnName: options.resolveColumnName ?? ((k, f) => namingStrategy?.columnName(f.name ?? k) ?? f.name ?? k),
         defaultForeignKeyAction: options.defaultForeignKeyAction ?? DEFAULT_FOREIGN_KEY_ACTION,
+        compileDdl: options.compileDdl ?? refuseDdl,
     };
     for (const pass of [addTableFromEntity, addRelationshipsFromEntity, addIndexesFromEntity]) {
         for (const entity of entities) {
@@ -38,6 +39,10 @@ export function buildSchemaAST(entities, options = {}) {
     }
     return ctx.ast;
 }
+/** The `compileDdl` of a build given no dialect, which has nothing to render an entity's SQL with. */
+function refuseDdl() {
+    throw new TypeError('building the schema of an entity that declares SQL (a check, a stored computed column, an index expression or predicate) needs a dialect to render it: pass `compileDdl`, as `buildEntityAST` does');
+}
 /**
  * Resolve the canonical type for a field, inheriting from the referenced
  * entity's primary key when the field is a foreign-key reference
@@ -78,7 +83,7 @@ function addTableFromEntity(ctx, meta) {
     const tableName = ctx.resolveTableName(meta);
     const table = createTableNode(tableName, ctx.resolveSchema(meta));
     const { columns, primaryKey } = table;
-    table.checks?.push(...(meta.checks ?? []));
+    table.checks?.push(...(meta.checks ?? []).map(({ name, where }) => ({ name, expression: ctx.compileDdl(where, meta.entity) })));
     // Add columns from fields
     for (const [key, field] of definedEntries(meta.fields)) {
         // An inlined expression has no column; a stored one is a column like any other.
@@ -98,7 +103,7 @@ function addTableFromEntity(ctx, meta) {
             isPrimaryKey,
             isAutoIncrement: isAutoIncrement(field, isSoleKey),
             isUnique: field.unique ?? false,
-            generatedAs: ddlText(field.computed, `the computed column '${columnName}'`),
+            generatedAs: field.computed && ctx.compileDdl(field.computed, meta.entity),
             comment: field.comment,
             enum: field.enum,
             table,
@@ -237,27 +242,23 @@ function resolveIncludeColumn(ctx, meta, column) {
 function addCompositeIndex(ctx, table, meta, idxMeta) {
     // An entry survives if it is an expression (nothing to resolve) or names a column that exists;
     // an index left with none is dropped, the same as one naming only unknown columns always was.
-    const entries = idxMeta.columns
-        .map((entry) => {
-        if (entry.expression)
-            return entry;
+    const resolved = idxMeta.columns.flatMap((entry) => {
+        if (typeof entry.column !== 'string')
+            return [entry];
         const field = meta.fields[entry.column];
         const column = field && ctx.resolveColumnName(entry.column, field);
-        return column && table.columns.has(column) ? { ...entry, column } : undefined;
-    })
-        .filter((entry) => entry !== undefined);
-    if (!entries.length)
+        return column && table.columns.has(column) ? [{ ...entry, column }] : [];
+    });
+    if (!resolved.length)
         return;
-    // An index over expressions alone has no column names to build a default name from.
-    const named = entries.map((entry, at) => (entry.expression ? `expr${at}` : entry.column));
     ctx.ast.addIndex({
-        name: idxMeta.name ?? derivedIndexName(table.name, named),
+        name: idxMeta.name ?? derivedIndexName(table.name, indexNameParts(resolved)),
         table,
-        entries,
+        entries: resolved.map((entry) => renderIndexColumn(entry, (sql) => ctx.compileDdl(sql, meta.entity))),
         include: idxMeta.include?.map((column) => resolveIncludeColumn(ctx, meta, column)),
         unique: idxMeta.unique ?? false,
         type: idxMeta.type,
-        where: idxMeta.where,
+        where: idxMeta.where && ctx.compileDdl(idxMeta.where, meta.entity),
         distance: idxMeta.distance,
         m: idxMeta.m,
         efConstruction: idxMeta.efConstruction,

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;
 }