uql-orm 0.61.0 → 0.63.0

package/dist/dialect/abstractSqlDialect.d.ts

@@ -1,4 +1,4 @@
-import { type EntityData, type EntityMeta, type FieldKey, type FieldOptions, type IsolationLevel, type JsonColumnType, type JsonUpdateOp, type Query, type QueryAggMap, type QueryAggregate, type QueryBuildFn, type QueryComparisonOptions, type QueryConflictPaths, type QueryContext, type QueryDialect, type QueryExclude, type QueryFilter, type QueryGroupMap, type QueryGroupOp, type QueryHavingMap, type QueryOptions, type QueryPager, QueryRaw, type QueryRawFnOptions, type QuerySearch, type QuerySelectValue, type QuerySizeComparisonOps, type QuerySortMap, type QueryTextSearchOptions, type QueryVectorNear, type QueryWhere, type QueryWhereArray, type QueryWhereFieldOperatorMap, type QueryWhereOptions, type RelationMeta, type SqlDialectName, type SqlQueryDialect, type Type, type UpdatePayload } from '../type/index.js';
+import { type EntityData, type EntityMeta, type EntityWhereMeta, type FieldKey, type FieldOptions, type IsolationLevel, type JsonColumnType, type JsonUpdateOp, type Query, type QueryAggMap, type QueryAggregate, type QueryBuildFn, type QueryComparisonOptions, type QueryConflictPaths, type QueryContext, type QueryContextOptions, type QueryDialect, type QueryExclude, type QueryFilter, type QueryGroupMap, type QueryGroupOp, type QueryHavingMap, type QueryOptions, type QueryPager, QueryRaw, type QueryRawFnOptions, type QuerySearch, type QuerySelectValue, type QuerySizeComparisonOps, type QuerySortMap, type QueryTextSearchOptions, type QueryVectorNear, type QueryWhere, type QueryWhereArray, type QueryWhereFieldOperatorMap, type QueryWhereOptions, type RelationMeta, type SqlDialectName, type SqlQueryDialect, type Type, type UpdatePayload } from '../type/index.js';
 import { type ColumnFamily } from '../util/field.util.js';
 import type { HydrateKind } from './hydrateColumn.js';
 import { type JsonAccessMode } from './jsonSql.js';
@@ -128,7 +128,7 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
      */
     readonly maxFunctionArgs: number;
     getBeginTransactionStatements(isolationLevel?: IsolationLevel): string[];
-    createContext(): QueryContext;
+    createContext(options?: QueryContextOptions): QueryContext;
     /**
      * Builds SQL text in isolation via `build`, so the caller can embed it inline (e.g.
      * `"col" = <text>`) instead of appending it at the end of `ctx`. The fragment binds any value
@@ -139,8 +139,8 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
      * shared for the same reason - see {@link SqlQueryContext}.
      */
     protected buildFragment(ctx: QueryContext, build: QueryBuildFn): string;
-    /** A `raw()` operand, rendered in place: bound, it would reach the driver as the object itself. */
-    protected rawFragment(ctx: QueryContext, value: QueryRaw): string;
+    /** A `raw()` rendered in place, an operand or a projected term: bound, the driver would get the object. */
+    protected rawFragment(ctx: QueryContext, value: QueryRaw, prefix?: string, entity?: Type<unknown>): string;
     /**
      * Each operand rendered into its own fragment, keeping only those that emitted SQL.
      *
@@ -150,7 +150,7 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
      * the caller counts what comes back rather than what it passed in.
      */
     protected renderOperands<T>(ctx: QueryContext, operands: readonly T[], render: (ctx: QueryContext, operand: T) => void): string[];
-    addValue(values: unknown[], value: unknown): string;
+    addValue(ctx: QueryContext, value: unknown): string;
     /**
      * A parameter value as this engine's driver takes it: a boolean as the integer an engine with no
      * boolean type stores, and everything else as it is - a `bigint` included, which every driver here
@@ -188,8 +188,6 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
     selectTerms<E>(ctx: QueryContext, entity: Type<E>, select: QuerySelectValue<E> | undefined, opts?: SelectOptions, exclude?: QueryExclude<E>): SelectTerm[];
     /** One field's column, or the expression an inlined one stands for, as the projection reads it. */
     private fieldTerm;
-    /** A `raw()` rendered where it stands, without the alias a projection writes for it. */
-    private rawSql;
     /**
      * What follows `SELECT` before the projection. Empty everywhere but SQL Server, whose `FETCH` will
      * not take a zero and which spells "no rows" as `TOP (0)` instead.
@@ -649,6 +647,13 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
     protected abstract jsonPush(ctx: QueryContext, expr: string, push: Record<string, unknown>): string;
     /** Remove object keys. */
     protected abstract jsonUnset(ctx: QueryContext, expr: string, unset: readonly string[]): string;
+    /**
+     * The text of SQL a schema declares, as DDL carries it: values written as literals, and none left bound,
+     * since a `CREATE` statement has no placeholder to bind one into. An entity's SQL reads its fields, a
+     * predicate with no entity filter applied; a migration's is `raw` reading none.
+     */
+    compileDdl(sql: QueryRaw): string;
+    compileDdl<E>(sql: EntityWhereMeta<E>, entity: Type<E>): string;
     getRawValue(ctx: QueryContext, opts: QueryRawFnOptions & {
         value: QueryRaw;
     }): void;

package/dist/dialect/abstractSqlDialect.js

@@ -83,8 +83,8 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         // 'set-before' - MySQL/MariaDB pattern
         return [`SET TRANSACTION ISOLATION LEVEL ${level}`, this.beginTransactionCommand];
     }
-    createContext() {
-        return new SqlQueryContext(this);
+    createContext(options = {}) {
+        return new SqlQueryContext(this, [], undefined, options.inlineValues);
     }
     /**
      * Builds SQL text in isolation via `build`, so the caller can embed it inline (e.g.
@@ -100,9 +100,9 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         build(fragmentCtx);
         return fragmentCtx.sql;
     }
-    /** A `raw()` operand, rendered in place: bound, it would reach the driver as the object itself. */
-    rawFragment(ctx, value) {
-        return this.buildFragment(ctx, (fragmentCtx) => this.getRawValue(fragmentCtx, { value }));
+    /** A `raw()` rendered in place, an operand or a projected term: bound, the driver would get the object. */
+    rawFragment(ctx, value, prefix, entity) {
+        return this.buildFragment(ctx, (fragmentCtx) => this.getRawValue(fragmentCtx, { value, prefix, entity }));
     }
     /**
      * Each operand rendered into its own fragment, keeping only those that emitted SQL.
@@ -117,9 +117,15 @@ export class AbstractSqlDialect extends VectorSqlDialect {
             .map((operand) => this.buildFragment(ctx, (fragmentCtx) => render(fragmentCtx, operand)))
             .filter((part) => part !== '');
     }
-    addValue(values, value) {
-        values.push(this.normalizeValue(value));
-        return this.placeholder(values.length);
+    addValue(ctx, value) {
+        if (value instanceof QueryRaw) {
+            return this.rawFragment(ctx, value);
+        }
+        if (ctx.inlineValues) {
+            return this.escape(this.normalizeValue(value));
+        }
+        ctx.values.push(this.normalizeValue(value));
+        return this.placeholder(ctx.values.length);
     }
     /**
      * A parameter value as this engine's driver takes it: a boolean as the integer an engine with no
@@ -196,7 +202,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
             return [{ sql: `${this.escapeId(opts.prefix, true, true)}*`, bare: true }];
         }
         return keys.map((key) => key instanceof QueryRaw
-            ? { sql: this.rawSql(ctx, key, opts.prefix), key: key[RAW_ALIAS] }
+            ? { sql: this.rawFragment(ctx, key, opts.prefix), key: key[RAW_ALIAS] }
             : this.fieldTerm(ctx, meta, key, opts));
     }
     /** One field's column, or the expression an inlined one stands for, as the projection reads it. */
@@ -206,7 +212,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
             // Qualified even when nothing else in this statement is: the expression is spliced in, and one
             // that opens a correlated subquery has the inner table's columns in scope, so a bare `"id"`
             // would bind to *that* table instead of this one.
-            const sql = this.rawSql(ctx, field.computed, opts.prefix ?? this.resolveTableAlias(meta));
+            const sql = this.rawFragment(ctx, field.computed, opts.prefix ?? this.resolveTableAlias(meta), meta.entity);
             return { sql: opts.json ? this.carried(`(${sql})`, field) : sql, key };
         }
         const columnName = this.resolveColumnName(key, field);
@@ -214,15 +220,6 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         const sql = opts.json ? this.carried(column, field) : this.selectFieldExpr(column, field);
         return { sql, key, bare: sql === column && columnName === key };
     }
-    /** A `raw()` rendered where it stands, without the alias a projection writes for it. */
-    rawSql(ctx, value, prefix) {
-        return this.buildFragment(ctx, (fragmentCtx) => value.render({
-            ctx: fragmentCtx,
-            dialect: this,
-            prefix: prefix ?? '',
-            escapedPrefix: this.escapeId(prefix, true, true),
-        }));
-    }
     /**
      * What follows `SELECT` before the projection. Empty everywhere but SQL Server, whose `FETCH` will
      * not take a zero and which spells "no rows" as `TOP (0)` instead.
@@ -425,7 +422,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
             }
             this.getComparisonKey(ctx, entity, key, opts);
             ctx.append(' = ');
-            this.getRawValue(ctx, { value: val });
+            this.getRawValue(ctx, { value: val, prefix: opts.prefix });
             return;
         }
         if (key === '$text') {
@@ -479,7 +476,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         const childOperand = items.length > 1 || negate || opts.operand;
         const parts = this.renderOperands(ctx, items, (fragmentCtx, entry) => {
             if (entry instanceof QueryRaw) {
-                this.getRawValue(fragmentCtx, { value: entry });
+                this.getRawValue(fragmentCtx, { value: entry, prefix: opts.prefix });
             }
             else {
                 this.renderWhere(fragmentCtx, entity, entry, { prefix: opts.prefix, operand: childOperand, clause: false });
@@ -551,7 +548,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         }
         const fold = like.insensitive && this.caseInsensitiveMatch === 'fold';
         const value = String(val);
-        const ph = this.addValue(ctx.values, like.pattern(fold ? value.toLowerCase() : value));
+        const ph = this.addValue(ctx, like.pattern(fold ? value.toLowerCase() : value));
         const matchOp = like.insensitive && this.caseInsensitiveMatch === 'ilike' ? 'ILIKE' : this.likeFn;
         return `${fold ? `LOWER(${operand})` : operand} ${matchOp} ${ph}`;
     }
@@ -567,7 +564,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
     resolveOperandField(ctx, entity, key, opts) {
         const meta = getMeta(entity);
         const field = meta.fields[key];
-        return (this.inlinedOperand(ctx, field, opts.prefix ?? this.resolveTableAlias(meta)) ??
+        return (this.inlinedOperand(ctx, field, opts.prefix ?? this.resolveTableAlias(meta), entity) ??
             this.columnWithPrefix(key, field, opts.prefix));
     }
     /**
@@ -576,15 +573,9 @@ export class AbstractSqlDialect extends VectorSqlDialect {
      * Every clause that names such a field needs the expression itself, never the output alias: an
      * alias exists only when the field was also selected, which `$where` and `$sort` cannot assume.
      */
-    inlinedOperand(ctx, field, prefix) {
+    inlinedOperand(ctx, field, prefix, entity) {
         const inlined = field && isInlinedExpression(field) ? field.computed : undefined;
-        return inlined
-            ? this.buildFragment(ctx, (fragmentCtx) => this.getRawValue(fragmentCtx, {
-                value: inlined,
-                prefix,
-                escapedPrefix: this.escapeId(prefix, true, true),
-            }))
-            : undefined;
+        return inlined ? this.rawFragment(ctx, inlined, prefix, entity) : undefined;
     }
     compareFieldOperator(ctx, entity, key, op, val, opts = {}) {
         const field = this.resolveOperandField(ctx, entity, key, opts);
@@ -629,7 +620,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
     operatorCondition(ctx, operand, op, val) {
         const compareOp = AbstractSqlDialect.COMPARE_OP_MAP.get(op);
         if (compareOp) {
-            return `${operand}${compareOp}${this.addValue(ctx.values, val)}`;
+            return `${operand}${compareOp}${this.addValue(ctx, val)}`;
         }
         const like = this.likeCondition(ctx, operand, op, val);
         if (like) {
@@ -637,17 +628,17 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         }
         switch (op) {
             case '$eq':
-                return val === null ? `${operand} IS NULL` : `${operand} = ${this.addValue(ctx.values, val)}`;
+                return val === null ? `${operand} IS NULL` : `${operand} = ${this.addValue(ctx, val)}`;
             case '$ne':
-                return val === null ? `${operand} IS NOT NULL` : this.neExpr(operand, this.addValue(ctx.values, val));
+                return val === null ? `${operand} IS NOT NULL` : this.neExpr(operand, this.addValue(ctx, val));
             case '$regex':
-                return this.regexCondition(operand, this.addValue(ctx.values, val));
+                return this.regexCondition(operand, this.addValue(ctx, val));
             case '$in':
             case '$nin':
                 return operand + this.formatIn(ctx, inOperands(op, val), op === '$nin');
             case '$between': {
                 const [min, max] = val;
-                return `${operand} BETWEEN ${this.addValue(ctx.values, min)} AND ${this.addValue(ctx.values, max)}`;
+                return `${operand} BETWEEN ${this.addValue(ctx, min)} AND ${this.addValue(ctx, max)}`;
             }
             case '$isNull':
                 return operand + (val ? ' IS NULL' : ' IS NOT NULL');
@@ -685,7 +676,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         // operator out of the same table a comparison against a column does.
         const compareOp = AbstractSqlDialect.COMPARE_OP_MAP.get(op);
         if (compareOp) {
-            return `${fieldAccessor(jsonPath, 'numeric')}${compareOp}${this.addValue(ctx.values, value)}`;
+            return `${fieldAccessor(jsonPath, 'numeric')}${compareOp}${this.addValue(ctx, value)}`;
         }
         switch (op) {
             case '$eq':
@@ -697,7 +688,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
                     return `${jsonField} IS NOT NULL`;
                 return this.neExpr(comparand(value), this.jsonOperand(ctx, value, asJson));
             case '$regex':
-                return this.regexCondition(jsonField, this.addValue(ctx.values, value));
+                return this.regexCondition(jsonField, this.addValue(ctx, value));
             case '$in':
             case '$nin':
                 return this.jsonInNin(ctx, jsonField, comparand, op, value, asJson);
@@ -723,7 +714,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
     }
     /** The bound operand of a JSON comparison: JSON-encoded when comparing against the JSON value. */
     jsonOperand(ctx, value, asJson) {
-        return asJson ? this.jsonScalarParam(ctx, value) : this.addValue(ctx.values, value);
+        return asJson ? this.jsonScalarParam(ctx, value) : this.addValue(ctx, value);
     }
     /**
      * Whether the dialect's array containment ({@link jsonAll}) matches an object element that merely
@@ -790,9 +781,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         if (value instanceof QueryRaw) {
             return this.rawFragment(ctx, value);
         }
-        ctx.pushValue(JSON.stringify(value));
-        // The placeholder for the value just pushed, so a named or numbered one is spelled correctly.
-        return this.jsonCast(this.placeholder(ctx.values.length));
+        return this.jsonCast(this.addValue(ctx, JSON.stringify(value)));
     }
     /** {@link resolveOperandField}, appended. */
     getComparisonKey(ctx, entity, key, opts = {}) {
@@ -886,7 +875,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
     sortColumn(ctx, meta, key, prefix) {
         const field = meta.fields[key];
         if (field) {
-            const expr = this.inlinedOperand(ctx, field, prefix ?? this.resolveTableAlias(meta)) ??
+            const expr = this.inlinedOperand(ctx, field, prefix ?? this.resolveTableAlias(meta), meta.entity) ??
                 this.columnWithPrefix(key, field, prefix);
             return { expr, output: false };
         }
@@ -1210,7 +1199,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
                 if (value === undefined) {
                     this.appendDefaultInsertValue(ctx, fields[i]);
                 }
-                else if (kinds[i] === 'plain' && !(value instanceof QueryRaw)) {
+                else if (kinds[i] === 'plain') {
                     // The overwhelmingly common case in a bulk insert, so it binds without a dispatch.
                     ctx.addValue(value);
                 }
@@ -1531,6 +1520,22 @@ export class AbstractSqlDialect extends VectorSqlDialect {
     jsonPull(ctx, expr, escapedCol, pull) {
         return Object.entries(pull).reduce((acc, [key, value]) => this.jsonPullKey(ctx, acc, escapedCol, key, value), expr);
     }
+    compileDdl(sql, entity) {
+        const ctx = this.createContext({ inlineValues: true });
+        if (sql instanceof QueryRaw) {
+            sql.render({ ctx, dialect: this, prefix: '', escapedPrefix: '', entity });
+        }
+        else if (entity) {
+            this.renderWhere(ctx, entity, sql, { clause: false });
+        }
+        else {
+            throw new TypeError('a predicate compiles against the entity it is written for, and none was given');
+        }
+        if (ctx.values.length) {
+            throw new TypeError(`DDL has no placeholder to bind a value into, and this SQL left one bound: ${ctx.sql}`);
+        }
+        return ctx.sql;
+    }
     getRawValue(ctx, opts) {
         const { value, prefix = '', escapedPrefix } = opts;
         value.render({
@@ -1540,10 +1545,6 @@ export class AbstractSqlDialect extends VectorSqlDialect {
             prefix,
             escapedPrefix: escapedPrefix ?? this.escapeId(prefix, true, true),
         });
-        const alias = value[RAW_ALIAS];
-        if (alias) {
-            ctx.append(' ' + this.escapeId(alias, true));
-        }
     }
     /**
      * Resolves a dot-notation key to its JSON field metadata.
@@ -1917,7 +1918,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         // A COUNT is never NULL, so equality stays plain here instead of taking the shared renderer's
         // null-safe `$ne` (`IS DISTINCT FROM` on Postgres, `IS NOT` on SQLite). Same rows, shorter SQL.
         if (op === '$eq' || op === '$ne') {
-            ctx.append(` ${op === '$eq' ? '=' : '<>'} ${this.addValue(ctx.values, val)}`);
+            ctx.append(` ${op === '$eq' ? '=' : '<>'} ${this.addValue(ctx, val)}`);
             return;
         }
         this.appendOperatorCondition(ctx, '', op, val);
@@ -1958,7 +1959,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
     formatIn(ctx, values, negate) {
         if (values.length === 0)
             return negate ? ' NOT IN (NULL)' : ' IN (NULL)';
-        const phs = values.map((v) => this.addValue(ctx.values, v)).join(', ');
+        const phs = values.map((v) => this.addValue(ctx, v)).join(', ');
         return ` ${negate ? 'NOT IN' : 'IN'} (${phs})`;
     }
     toString() {

package/dist/dialect/mysqlLikeSqlDialect.js

@@ -247,7 +247,7 @@ export class MysqlLikeSqlDialect extends AbstractSqlDialect {
         return `${escapedColumn}->${jsonPath(jsonPathStr)}`;
     }
     jsonAll(ctx, jsonField, value) {
-        return `JSON_CONTAINS(${jsonField}, ${this.addValue(ctx.values, JSON.stringify(value))})`;
+        return `JSON_CONTAINS(${jsonField}, ${this.addValue(ctx, JSON.stringify(value))})`;
     }
     jsonSize(ctx, jsonField, value) {
         return this.buildFragment(ctx, (fragmentCtx) => this.buildSizeComparison(fragmentCtx, () => fragmentCtx.append(`JSON_LENGTH(${jsonField})`), value));

package/dist/dialect/pgLikeSqlDialect.d.ts

@@ -80,6 +80,7 @@ export declare abstract class PgLikeSqlDialect extends AbstractSqlDialect {
     protected get regexpOp(): string;
     protected readonly caseInsensitiveMatch = "ilike";
     protected get neOp(): string;
+    /** One array parameter, which a context that inlines values has none of: it lists them instead. */
     protected formatIn(ctx: QueryContext, values: unknown[], negate: boolean): string;
     protected numericCast(expr: string): string;
     protected appendJsonValue(ctx: QueryContext, value: unknown, type: JsonColumnType): void;

package/dist/dialect/pgLikeSqlDialect.js

@@ -126,7 +126,7 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
             .map((key) => this.escapeId(this.resolveColumnName(key, meta.fields[key])))
             .join(` || ' ' || `);
         // The config is bound once and its numbered placeholder reused by both calls.
-        const config = search.$config ? `${this.addValue(ctx.values, search.$config)}::regconfig, ` : '';
+        const config = search.$config ? `${this.addValue(ctx, search.$config)}::regconfig, ` : '';
         ctx.append(`TO_TSVECTOR(${config}${fields}) @@ WEBSEARCH_TO_TSQUERY(${config}`);
         ctx.addValue(search.$value);
         ctx.append(')');
@@ -158,10 +158,11 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
     get neOp() {
         return 'IS DISTINCT FROM';
     }
+    /** One array parameter, which a context that inlines values has none of: it lists them instead. */
     formatIn(ctx, values, negate) {
-        if (values.length === 0)
-            return negate ? ' NOT IN (NULL)' : ' IN (NULL)';
-        const ph = this.addValue(ctx.values, values);
+        if (values.length === 0 || ctx.inlineValues)
+            return super.formatIn(ctx, values, negate);
+        const ph = this.addValue(ctx, values);
         return negate ? ` <> ALL(${ph})` : ` = ANY(${ph})`;
     }
     numericCast(expr) {
@@ -210,7 +211,7 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
         }, expr);
     }
     jsonUnset(ctx, expr, unset) {
-        return `(${expr}) - ${this.addValue(ctx.values, [...unset])}::text[]`;
+        return `(${expr}) - ${this.addValue(ctx, [...unset])}::text[]`;
     }
     /** Postgres binds JSON with a numbered placeholder and an explicit cast, per driver capability. */
     jsonScalarParam(ctx, value) {
@@ -223,9 +224,9 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
         if (value instanceof QueryRaw)
             return this.rawFragment(ctx, value);
         if (value == null)
-            return `${this.addValue(ctx.values, null)}::${type}`;
+            return `${this.addValue(ctx, null)}::${type}`;
         const json = JSON.stringify(value);
-        const ph = this.addValue(ctx.values, json);
+        const ph = this.addValue(ctx, json);
         return this.features.explicitJsonCast ? `(${ph}::text)::${type}` : `${ph}::${type}`;
     }
 }

package/dist/dialect/queryContext.d.ts

@@ -9,6 +9,7 @@ import type { QueryContext, QueryDialect } from '../type/index.js';
 export declare class SqlQueryContext implements QueryContext {
     readonly dialect: QueryDialect;
     private readonly statement?;
+    readonly inlineValues: boolean;
     private readonly sqlChunks;
     private readonly params;
     private readonly tableAliases;
@@ -20,8 +21,9 @@ export declare class SqlQueryContext implements QueryContext {
      * than needing to be reconciled after the fact.
      * @param statement The context this one renders a fragment of, which owns the claimed aliases: a
      * fragment is part of one statement, so its aliases have to be unique across the whole of it.
+     * @param inlineValues See {@link QueryContext.inlineValues}; a fragment takes its statement's.
      */
-    constructor(dialect: QueryDialect, params?: unknown[], statement?: SqlQueryContext | undefined);
+    constructor(dialect: QueryDialect, params?: unknown[], statement?: SqlQueryContext | undefined, inlineValues?: boolean);
     createFragment(): QueryContext;
     /**
      * Appends raw SQL string fragments to the query.
@@ -31,11 +33,8 @@ export declare class SqlQueryContext implements QueryContext {
      */
     append(sql: string): this;
     /**
-     * Adds a value to the query parameters and appends its corresponding placeholder to the SQL.
-     * The placeholder format is determined by the dialect (e.g., '?' or '$1').
-     *
-     * @param value The value to be parameterized.
-     * @returns The current context instance for method chaining.
+     * Appends the SQL the dialect writes for `value`: a placeholder for the value bound, or its literal
+     * where this context inlines values.
      */
     addValue(value: unknown): this;
     /**

package/dist/dialect/queryContext.js

@@ -8,6 +8,7 @@
 export class SqlQueryContext {
     dialect;
     statement;
+    inlineValues;
     sqlChunks = [];
     params;
     tableAliases = new Set();
@@ -19,14 +20,16 @@ export class SqlQueryContext {
      * than needing to be reconciled after the fact.
      * @param statement The context this one renders a fragment of, which owns the claimed aliases: a
      * fragment is part of one statement, so its aliases have to be unique across the whole of it.
+     * @param inlineValues See {@link QueryContext.inlineValues}; a fragment takes its statement's.
      */
-    constructor(dialect, params = [], statement) {
+    constructor(dialect, params = [], statement, inlineValues = false) {
         this.dialect = dialect;
         this.statement = statement;
+        this.inlineValues = inlineValues;
         this.params = params;
     }
     createFragment() {
-        return new SqlQueryContext(this.dialect, this.params, this.statement ?? this);
+        return new SqlQueryContext(this.dialect, this.params, this.statement ?? this, this.inlineValues);
     }
     /**
      * Appends raw SQL string fragments to the query.
@@ -41,14 +44,11 @@ export class SqlQueryContext {
         return this;
     }
     /**
-     * Adds a value to the query parameters and appends its corresponding placeholder to the SQL.
-     * The placeholder format is determined by the dialect (e.g., '?' or '$1').
-     *
-     * @param value The value to be parameterized.
-     * @returns The current context instance for method chaining.
+     * Appends the SQL the dialect writes for `value`: a placeholder for the value bound, or its literal
+     * where this context inlines values.
      */
     addValue(value) {
-        this.sqlChunks.push(this.dialect.addValue(this.params, value));
+        this.sqlChunks.push(this.dialect.addValue(this, value));
         return this;
     }
     /**

package/dist/entity/decorator/entity.d.ts

@@ -1,4 +1,4 @@
-import type { EntityIndexOptions, EntityOptions, FieldKey, FilterOptions, IndexColumnInput, KeyMap, Type } from '../../type/index.js';
+import type { EntityIndexColumnInput, EntityIndexOptions, EntityOptions, FilterOptions, RefMap, Type } from '../../type/index.js';
 /**
  * Marks a class as an entity and finalizes its metadata.
  *
@@ -12,16 +12,12 @@ export declare function Entity<E>(opts?: EntityOptions<E>): (entity: Type<E>, co
 /**
  * Registers a named `$where` filter, applied to every query unless bypassed via `QueryOptions.filters`.
  *
- * @example `@Filter('active', { condition: { status: 'active' }, default: false })`
+ * @example `@Filter('active', { where: { status: 'active' }, default: false })`
  */
 export declare function Filter<E>(name: string, opts: FilterOptions<E>): (entity: Type<E>) => void;
 /**
- * Declares a composite index, its columns read off the key map. Stacks, so several may sit above one
- * class. `E` is inferred from the class the returned decorator is applied to, which is what types the
- * key map: `@Index((user) => [user.nope])` does not compile, and a rename reaches every column.
- *
- * @example `@Index((user) => [user.lastName, user.firstName], { name: 'users_fullname_idx' })`
- * @example `@Index((user) => [user.email], { unique: true })`
- * @example `@Index((user) => [user.status], { where: "status = 'active'" })`
+ * Declares a composite index, its columns read off the entity's refs, so `@Index((user) => [user.nope])`
+ * does not compile and a rename reaches every column. Stacks, so several may sit above one class.
+ * @example `@Index((user) => [user.lastName, raw`lower(${user.email})`], { unique: true })`
  */
-export declare function Index<E>(columns: (keys: KeyMap<E>) => readonly IndexColumnInput<FieldKey<NoInfer<E>>, NoInfer<E>>[], options?: EntityIndexOptions<NoInfer<E>>): (entity: Type<E>) => void;
+export declare function Index<E>(columns: (refs: RefMap<E>) => readonly EntityIndexColumnInput<E>[], options?: EntityIndexOptions<E>): (entity: Type<E>) => void;

package/dist/entity/decorator/entity.js

@@ -20,7 +20,7 @@ export function Entity(opts) {
 /**
  * Registers a named `$where` filter, applied to every query unless bypassed via `QueryOptions.filters`.
  *
- * @example `@Filter('active', { condition: { status: 'active' }, default: false })`
+ * @example `@Filter('active', { where: { status: 'active' }, default: false })`
  */
 export function Filter(name, opts) {
     return (entity) => {
@@ -28,13 +28,9 @@ export function Filter(name, opts) {
     };
 }
 /**
- * Declares a composite index, its columns read off the key map. Stacks, so several may sit above one
- * class. `E` is inferred from the class the returned decorator is applied to, which is what types the
- * key map: `@Index((user) => [user.nope])` does not compile, and a rename reaches every column.
- *
- * @example `@Index((user) => [user.lastName, user.firstName], { name: 'users_fullname_idx' })`
- * @example `@Index((user) => [user.email], { unique: true })`
- * @example `@Index((user) => [user.status], { where: "status = 'active'" })`
+ * Declares a composite index, its columns read off the entity's refs, so `@Index((user) => [user.nope])`
+ * does not compile and a rename reaches every column. Stacks, so several may sit above one class.
+ * @example `@Index((user) => [user.lastName, raw`lower(${user.email})`], { unique: true })`
  */
 export function Index(columns, options = {}) {
     return (entity) => {

package/dist/entity/decorator/members.d.ts

@@ -40,12 +40,13 @@ type EnumValue<Members, Declared> = Declared extends Members ? {
  *
  * @example `@Field({ type: String }) name?: string;`
  * @example `@Field({ references: () => User }) userId?: string;` (where `User.id` is a `uuid`)
+ * @example `@Field({ type: Number, computed: (line) => raw`${line.qty} * ${line.price}` }) total?: number;`
  */
-export declare function Field<O extends FieldOptions<DeclaredValue<O>> & ({
+export declare function Field<This, O extends FieldOptions<DeclaredValue<O>, This> & ({
     type: FieldType;
 } | {
     references: EntityGetter;
-}) & RejectUnknown<O, FieldOptions> & RejectIncompatible<O>>(opts: O): MemberDecorator<DeclaredValue<O> | undefined>;
+}) & RejectUnknown<O, FieldOptions> & RejectIncompatible<O>>(opts: O): MemberDecorator<DeclaredValue<O> | undefined, This>;
 /**
  * A key the type level cannot name, reported on each `@Id` that leaves it unnamed. Where no `idKey`
  * brand and no conventional name applies, `IdKey` falls back to every field, and `IdValue`,

package/dist/entity/decorator/members.js

@@ -8,6 +8,7 @@ import { memberRegistrations } from './bag.js';
  *
  * @example `@Field({ type: String }) name?: string;`
  * @example `@Field({ references: () => User }) userId?: string;` (where `User.id` is a `uuid`)
+ * @example `@Field({ type: Number, computed: (line) => raw`${line.qty} * ${line.price}` }) total?: number;`
  */
 export function Field(opts) {
     return (_value, context) => {

package/dist/entity/metadata/definition.d.ts

@@ -11,8 +11,8 @@ export declare function defineRelation<E, T extends object>(entity: Type<E>, key
 export declare function relationRegistration<T extends object, O>({ mappedBy, references, ...opts }: RelationOptions<T, O>): RelationRegistration;
 export declare function defineHook<E>(entity: Type<E>, methodName: string, event: HookEvent): EntityMeta<E>;
 /**
- * Declares a composite index, its columns read off the key map. `unique` and the authored column sugar
- * are normalized here, which is what lets the dialects render one shape instead of re-parsing it.
+ * Declares a composite index, its columns read off the entity's refs. `unique` and the authored column
+ * sugar are normalized here, which is what lets the dialects render one shape instead of re-parsing it.
  */
 export declare function defineIndex<E>(entity: Type<E>, index: EntityIndexInput<E>): EntityMeta<E>;
 export declare function defineFilter<E>(entity: Type<E>, name: string, opts: FilterOptions<E>): EntityMeta<E>;