uql-orm 0.55.0 → 0.57.0

package/dist/dialect/queryContext.js

@@ -10,14 +10,14 @@ export class SqlQueryContext {
     statement;
     sqlChunks = [];
     params;
-    aliasCounter = 0;
+    tableAliases = new Set();
     /**
      * @param dialect The SQL dialect used to determine how values should be formatted as placeholders.
      * @param params An existing values array to bind into instead of a fresh one - shared by a
      * fragment context built via {@link AbstractSqlDialect.buildFragment}, so a bound value's
      * placeholder is numbered correctly against the real query from the moment it's added, rather
      * than needing to be reconciled after the fact.
-     * @param statement The context this one renders a fragment of, which owns the alias counter: a
+     * @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.
      */
     constructor(dialect, params = [], statement) {
@@ -62,12 +62,17 @@ export class SqlQueryContext {
         this.params.push(...values.map((v) => this.dialect.normalizeValue(v)));
         return this;
     }
-    /**
-     * A fresh alias unique within the statement being built, e.g. `nextAlias('_uql_elem')` ->
-     * `'_uql_elem_1'`, `'_uql_elem_2'`, ...
-     */
-    nextAlias(prefix) {
-        return this.statement ? this.statement.nextAlias(prefix) : `${prefix}_${++this.aliasCounter}`;
+    claimAlias(name, parent) {
+        if (this.statement) {
+            return this.statement.claimAlias(name, parent);
+        }
+        const reserved = parent?.toLowerCase();
+        let alias = name;
+        for (let n = 2; this.tableAliases.has(alias.toLowerCase()) || alias.toLowerCase() === reserved; n++) {
+            alias = `${name}_${n}`;
+        }
+        this.tableAliases.add(alias.toLowerCase());
+        return alias;
     }
     /**
      * Returns the complete SQL query string by joining all accumulated chunks.

package/dist/dialect/queryJoins.d.ts

@@ -1,5 +1,4 @@
-import type { EntityMeta, Query, QuerySortMap, RelationMeta, Type } from '../type/index.js';
-import { type RelationQuery } from '../util/index.js';
+import type { EntityMeta, Query, QuerySortMap, RelationMeta, RelationQuery, Type } from '../type/index.js';
 /**
  * One relation a statement joins, keyed by the alias its columns are addressed by (`tax`,
  * `tax.category`). `projected` tells a `$populate` join, whose columns are selected, from one only
@@ -8,8 +7,10 @@ import { type RelationQuery } from '../util/index.js';
 export type QueryJoin = {
     /** The relation key on its parent, which is how MongoDB names the field a `$lookup` adds. */
     readonly key: string;
-    /** Dotted path from the queried entity, which is how the SQL dialects alias the join. */
+    /** Dotted path from the queried entity, which is what a joined row's columns answer under. */
     readonly path: string;
+    /** The alias the statement reads it through: its path, unless another table of the statement took it. */
+    readonly alias: string;
     readonly entity: Type<object>;
     readonly meta: EntityMeta<object>;
     readonly relation: RelationMeta;
@@ -38,14 +39,17 @@ export type QuerySortOptions = {
  * related column needs that relation joined just as much as selecting it does. The two sources meet
  * here, so the columns, the `ORDER BY` and the row lock cannot disagree about what is in the
  * statement. `$sort` contributes to-one relations only; the rest is rejected where it is rendered.
+ * `claimAlias` names each join's table, parents first.
  */
-export declare function resolveQueryJoins<E>(meta: EntityMeta<E>, q: Query<E>): QueryJoins;
+export declare function resolveQueryJoins<E>(meta: EntityMeta<E>, q: Query<E>, claimAlias?: (path: string) => string): QueryJoins;
 /**
  * Whether a join drops parents that have no match, which is the one thing a join does to *how many*
  * rows a read returns rather than how wide they are. A count that skips the joins has to be told, or
  * it counts the parents the read will never hand back.
  */
 export declare function hasRequiredJoin<E>(meta: EntityMeta<E>, q: Query<E>): boolean;
+/** Whether a statement aggregates a relation's rows: a to-many off its own row, or off a row it joins. */
+export declare function aggregatesRelations<E>(meta: EntityMeta<E>, q: Query<E>): boolean;
 /**
  * The join an ordering may address at `path`, with the relation's own sort map, or why it may not.
  * Every backend answers this the same way - a to-many has no single value to order by, a relation

package/dist/dialect/queryJoins.js

@@ -1,19 +1,20 @@
-import { getMeta } from '../entity/index.js';
-import { getKeys, getRelationRequestSummary, isToManyRelation, parseRelationAtKey, } from '../util/index.js';
+import { getMeta, relationOf } from '../entity/index.js';
+import { getKeys, getRelationRequestSummary, isToManyRelation, parseRelationAtKey } from '../util/index.js';
 export const NO_JOINS = new Map();
 /**
  * What the statement joins, from the whole query rather than from `$populate` alone: ordering by a
  * related column needs that relation joined just as much as selecting it does. The two sources meet
  * here, so the columns, the `ORDER BY` and the row lock cannot disagree about what is in the
  * statement. `$sort` contributes to-one relations only; the rest is rejected where it is rendered.
+ * `claimAlias` names each join's table, parents first.
  */
-export function resolveQueryJoins(meta, q) {
+export function resolveQueryJoins(meta, q, claimAlias = (path) => path) {
     if (!q.$populate && !q.$sort) {
         return NO_JOINS;
     }
     const joins = new Map();
-    addPopulateJoins(joins, meta, q.$populate);
-    addSortJoins(joins, meta, q.$sort);
+    addPopulateJoins(joins, claimAlias, meta, q.$populate);
+    addSortJoins(joins, claimAlias, meta, q.$sort);
     return joins;
 }
 /**
@@ -29,7 +30,19 @@ export function hasRequiredJoin(meta, q) {
     }
     return false;
 }
-function addJoin(joins, parent, key, relation, query, required, projected) {
+/** Whether a statement aggregates a relation's rows: a to-many off its own row, or off a row it joins. */
+export function aggregatesRelations(meta, q) {
+    if (getRelationRequestSummary(meta, q.$populate).toManyKeys.length) {
+        return true;
+    }
+    for (const join of resolveQueryJoins(meta, q).values()) {
+        if (getRelationRequestSummary(join.meta, join.query.$populate).toManyKeys.length) {
+            return true;
+        }
+    }
+    return false;
+}
+function addJoin(joins, claimAlias, parent, key, relation, query, required, projected) {
     const path = parent ? `${parent.path}.${key}` : key;
     const existing = joins.get(path);
     // `$populate` runs first, so an already-joined relation keeps its columns and its `$required`
@@ -41,6 +54,7 @@ function addJoin(joins, parent, key, relation, query, required, projected) {
     const join = {
         key,
         path,
+        alias: claimAlias(path),
         entity,
         meta: getMeta(entity),
         relation,
@@ -52,17 +66,15 @@ function addJoin(joins, parent, key, relation, query, required, projected) {
     joins.set(path, join);
     return join;
 }
-function addPopulateJoins(joins, meta, populate, parent) {
+function addPopulateJoins(joins, claimAlias, meta, populate, parent) {
     for (const key of getRelationRequestSummary(meta, populate).joinableKeys) {
-        const relation = meta.relations[key];
-        if (!relation)
-            continue;
+        const relation = relationOf(meta, key);
         const { query, required } = parseRelationAtKey(key, populate);
-        const join = addJoin(joins, parent, key, relation, query, required, true);
-        addPopulateJoins(joins, join.meta, query.$populate, join);
+        const join = addJoin(joins, claimAlias, parent, key, relation, query, required, true);
+        addPopulateJoins(joins, claimAlias, join.meta, query.$populate, join);
     }
 }
-function addSortJoins(joins, meta, sort, parent) {
+function addSortJoins(joins, claimAlias, meta, sort, parent) {
     if (!sort) {
         return;
     }
@@ -74,8 +86,8 @@ function addSortJoins(joins, meta, sort, parent) {
         if (!relation || isToManyRelation(relation) || !isSortMap(value)) {
             continue;
         }
-        const join = addJoin(joins, parent, key, relation, {}, false, false);
-        addSortJoins(joins, join.meta, value, join);
+        const join = addJoin(joins, claimAlias, parent, key, relation, {}, false, false);
+        addSortJoins(joins, claimAlias, join.meta, value, join);
     }
 }
 /**

package/dist/dialect/vectorSqlDialect.d.ts

@@ -78,8 +78,8 @@ export declare abstract class VectorSqlDialect extends AbstractDialect {
      */
     supportedVectorType(cast: VectorCast): VectorCast;
     /**
-     * Append a vector distance projection.
-     * Delegates to `appendVectorSort` so each dialect's distance syntax is written once.
+     * The distance a vector `$sort` projects, which the projection names after `$project`. Delegates to
+     * `appendVectorSort` so each dialect's distance syntax is written once.
      */
     protected appendVectorProjection<E>(ctx: QueryContext, meta: EntityMeta<E>, key: string, search: QueryVectorSearch): void;
     /**

package/dist/dialect/vectorSqlDialect.js

@@ -96,8 +96,8 @@ export class VectorSqlDialect extends AbstractDialect {
         return this.hasNarrowVectorTypes ? cast : 'vector';
     }
     /**
-     * Append a vector distance projection.
-     * Delegates to `appendVectorSort` so each dialect's distance syntax is written once.
+     * The distance a vector `$sort` projects, which the projection names after `$project`. Delegates to
+     * `appendVectorSort` so each dialect's distance syntax is written once.
      */
     appendVectorProjection(ctx, meta, key, search) {
         const alias = search.$project;
@@ -108,7 +108,6 @@ export class VectorSqlDialect extends AbstractDialect {
             throw new TypeError(`$project '${alias}' collides with a field of '${entityName(meta)}'`);
         }
         this.appendVectorSort(ctx, meta, key, search);
-        ctx.append(` AS ${this.escapeId(alias)}`);
     }
     /**
      * The distance expression, in whichever of the two shapes this dialect spells it. One method for

package/dist/entity/index.d.ts

@@ -1,3 +1,3 @@
 export * from './decorator/entity.js';
 export * from './decorator/members.js';
-export { defineEntity, defineField, defineFilter, defineHook, defineId, defineIndex, defineRelation, getEntities, getMeta, removeEntity, assertSoleId, fieldOf, idOf, namesKey, soleIdOf, } from './metadata/definition.js';
+export { defineEntity, defineField, defineFilter, defineHook, defineId, defineIndex, defineRelation, getEntities, getMeta, removeEntity, assertSoleId, fieldOf, idOf, namesKey, relationOf, soleIdOf, } from './metadata/definition.js';

package/dist/entity/index.js

@@ -1,3 +1,3 @@
 export * from './decorator/entity.js';
 export * from './decorator/members.js';
-export { defineEntity, defineField, defineFilter, defineHook, defineId, defineIndex, defineRelation, getEntities, getMeta, removeEntity, assertSoleId, fieldOf, idOf, namesKey, soleIdOf, } from './metadata/definition.js';
+export { defineEntity, defineField, defineFilter, defineHook, defineId, defineIndex, defineRelation, getEntities, getMeta, removeEntity, assertSoleId, fieldOf, idOf, namesKey, relationOf, soleIdOf, } from './metadata/definition.js';

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

@@ -1,4 +1,4 @@
-import type { EntityData, EntityIndexInput, EntityMembers, EntityMeta, EntityOptions, FieldKey, FieldMeta, FieldOptions, FilterOptions, HookEvent, IdKey, RelationOptions, Type, WrittenId } from '../../type/index.js';
+import type { EntityData, EntityIndexInput, EntityMembers, EntityMeta, EntityOptions, FieldKey, FieldMeta, FieldOptions, FilterOptions, HookEvent, IdKey, RelationKey, RelationMeta, RelationOptions, Type, WrittenId } from '../../type/index.js';
 export declare function defineField<E>(entity: Type<E>, key: string, opts?: FieldOptions): EntityMeta<E>;
 export declare function defineId<E>(entity: Type<E>, key: string, opts: FieldOptions): EntityMeta<E>;
 export declare function defineRelation<E>(entity: Type<E>, key: string, opts: RelationOptions): EntityMeta<E>;
@@ -31,7 +31,9 @@ export declare function assertSoleId<E>(meta: EntityMeta<E>, what: string): void
 /** The entity's one primary key, for a path that cannot express a composite. See {@link assertSoleId}. */
 export declare function soleIdOf<E>(meta: EntityMeta<E>, what: string): IdKey<E>;
 /** The field `key` names, for a caller that took `key` from the metadata itself. */
-export declare function fieldOf<E>(meta: EntityMeta<E>, key: string): FieldMeta;
+export declare function fieldOf<E>(meta: EntityMeta<E>, key: FieldKey<E>): FieldMeta;
+/** The relation `key` names, for a caller that took `key` from the metadata itself. */
+export declare function relationOf<E>(meta: EntityMeta<E>, key: RelationKey<E>): RelationMeta;
 /**
  * Whether the caller named every column of the row's primary key, so {@link idOf} can name the row.
  *

package/dist/entity/metadata/definition.js

@@ -1,6 +1,6 @@
 import { SOFT_DELETE_FILTER } from '../../type/index.js';
 import { isInlinedExpression } from '../../util/field.util.js';
-import { entityName, fieldOptionConflict, getKeys, ddlText, hasKeys, isToManyRelation, lowerFirst, normalizeIndexColumn, upperFirst, } from '../../util/index.js';
+import { entityName, fieldOptionConflict, getKeys, ddlText, hasKeys, isToManyRelation, lowerFirst, normalizeIndexColumn, upperFirst, definedEntries, } from '../../util/index.js';
 import { ownRegistrations } from '../decorator/bag.js';
 /**
  * A map held on `globalThis` through the global symbol registry, so a single one survives multiple
@@ -95,9 +95,7 @@ export function defineFilter(entity, name, opts) {
  * API converge on one registration path before anything is finalized.
  */
 export function applyMembers(entity, specs) {
-    for (const [key, spec] of Object.entries(specs?.fields ?? {})) {
-        if (!spec)
-            continue;
+    for (const [key, spec] of definedEntries(specs?.fields ?? {})) {
         if (spec.isId) {
             defineId(entity, key, spec);
         }
@@ -105,12 +103,11 @@ export function applyMembers(entity, specs) {
             defineField(entity, key, spec);
         }
     }
-    for (const [key, spec] of Object.entries(specs?.relations ?? {})) {
-        if (spec)
-            defineRelation(entity, key, spec);
+    for (const [key, spec] of definedEntries(specs?.relations ?? {})) {
+        defineRelation(entity, key, spec);
     }
-    for (const [event, methodNames] of Object.entries(specs?.hooks ?? {})) {
-        for (const methodName of methodNames ?? []) {
+    for (const [event, methodNames] of definedEntries(specs?.hooks ?? {})) {
+        for (const methodName of methodNames) {
             defineHook(entity, methodName, event);
         }
     }
@@ -143,9 +140,8 @@ export function defineEntity(entity, opts = {}) {
     for (const index of opts.indexes ?? []) {
         defineIndex(entity, index);
     }
-    for (const [name, filter] of Object.entries(opts.filters ?? {})) {
-        if (filter)
-            defineFilter(entity, name, filter);
+    for (const [name, filter] of definedEntries(opts.filters ?? {})) {
+        defineFilter(entity, name, filter);
     }
     if (!hasKeys(meta.fields)) {
         throw TypeError(`'${entity.name}' must have fields`);
@@ -227,6 +223,14 @@ export function fieldOf(meta, key) {
     }
     return field;
 }
+/** The relation `key` names, for a caller that took `key` from the metadata itself. */
+export function relationOf(meta, key) {
+    const relation = meta.relations[key];
+    if (!relation) {
+        throw new TypeError(`'${meta.entity.name}' has no relation '${key}'`);
+    }
+    return relation;
+}
 /**
  * Whether the caller named every column of the row's primary key, so {@link idOf} can name the row.
  *
@@ -303,11 +307,9 @@ export function getMeta(entity) {
     return fillRelations(meta);
 }
 function fillRelations(meta) {
-    for (const relKey in meta.relations) {
+    for (const [relKey, relation] of definedEntries(meta.relations)) {
         // The authored view: `mappedBy` may still be the callback and `references` unset until this settles them.
-        const relOpts = meta.relations[relKey];
-        if (!relOpts)
-            continue;
+        const relOpts = relation;
         const at = `'${meta.entity.name}.${relKey}'`;
         if (relOpts.mappedBy) {
             fillInverseSide(at, meta, relOpts);
@@ -335,9 +337,9 @@ function fillRelations(meta) {
 function fillOwningSide(at, meta, relKey, relOpts) {
     const relMeta = ensureMeta(relOpts.entity());
     if (relOpts.through) {
-        // Both columns live on the junction, whatever the cardinality: `fillToManyThroughRelation`,
-        // `deleteRelations` and every dialect read them as junction columns. A composite key contributes
-        // one pair per column of it, which is what makes the join address a whole key rather than part.
+        // Both columns live on the junction, whatever the cardinality: `deleteRelations` and every dialect
+        // read them as junction columns. A composite key contributes one pair per column of it, which is
+        // what makes the join address a whole key rather than part.
         relOpts.references = [
             ...meta.ids.map((key) => ({ local: junctionColumn(meta, key), foreign: key })),
             ...relMeta.ids.map((key) => ({ local: junctionColumn(relMeta, key), foreign: key })),
@@ -363,7 +365,7 @@ function fillOwningSide(at, meta, relKey, relOpts) {
     for (const { local, foreign } of relOpts.references) {
         fields[local] ??= {
             name: local,
-            type: relMeta.fields[foreign]?.type ?? Number,
+            type: fieldOf(relMeta, foreign).type ?? Number,
             references: relOpts.entity,
             referencedKey: foreign,
             typeFromReference: true,
@@ -413,9 +415,8 @@ function fillInverseSide(at, meta, relOpts) {
  * own cardinality and `cascade`.
  */
 function fillForeignKeyRelations(meta) {
-    const joined = new Set(getKeys(meta.relations).flatMap((key) => meta.relations[key]?.references.map(({ local }) => local) ?? []));
-    for (const fieldKey of getKeys(meta.fields)) {
-        const references = meta.fields[fieldKey]?.references;
+    const joined = new Set(definedEntries(meta.relations).flatMap(([, relation]) => relation.references.map(({ local }) => local)));
+    for (const [fieldKey, { references }] of definedEntries(meta.fields)) {
         if (!references || joined.has(fieldKey))
             continue;
         const target = ensureMeta(references());
@@ -445,7 +446,7 @@ function fillForeignKeyRelations(meta) {
 }
 /** `<entityName><IdColumn>`, not the `<relationKey>Id` an owning to-one derives: a junction row has no relation key to borrow from. */
 function junctionColumn(meta, idKey) {
-    return lowerFirst(entityName(meta)) + upperFirst(meta.fields[idKey]?.name ?? idKey);
+    return lowerFirst(entityName(meta)) + upperFirst(fieldOf(meta, idKey).name ?? idKey);
 }
 /** A callback only reads one property off the key map, and that property is the key, so one serves every entity. */
 const RELATION_KEY_MAP = new Proxy({}, { get: (_, key) => key });
@@ -478,11 +479,8 @@ function extendMeta(target, source) {
     if (source.hooks) {
         if (!target.hooks)
             target.hooks = {};
-        for (const event of Object.keys(source.hooks)) {
-            const sourceList = source.hooks[event];
-            if (sourceList?.length) {
-                target.hooks[event] = [...sourceList, ...(target.hooks[event] ?? [])];
-            }
+        for (const [event, sourceList] of definedEntries(source.hooks)) {
+            target.hooks[event] = [...sourceList, ...(target.hooks[event] ?? [])];
         }
     }
 }

package/dist/maria/mariaDialect.d.ts

@@ -1,5 +1,6 @@
+import { type RelationRows } from '../dialect/abstractSqlDialect.js';
 import { MysqlLikeSqlDialect } from '../dialect/mysqlLikeSqlDialect.js';
-import type { DialectFeatures, EntityMeta, FieldOptions, Query, QueryContext, QueryOptions, Type, VectorDistance, VectorMetric } from '../type/index.js';
+import type { DialectFeatures, EntityMeta, FieldOptions, Query, QueryContext, Type, VectorDistance, VectorMetric } from '../type/index.js';
 export declare class MariaDialect extends MysqlLikeSqlDialect {
     readonly dialectName = "mariadb";
     readonly insertIdSource = "returning";
@@ -10,6 +11,11 @@ export declare class MariaDialect extends MysqlLikeSqlDialect {
      * and `CREATE INDEX` takes `IF NOT EXISTS` - which MySQL's grammar has no place for.
      */
     protected readonly featureOverrides: Partial<DialectFeatures>;
+    /**
+     * A derived table here reads no column of the statement around it, so the aggregate reads the
+     * related table itself, and orders and pages inside `JSON_ARRAYAGG`, which takes both.
+     */
+    protected appendRelationArray(ctx: QueryContext, { entity, query, alias, joins }: RelationRows): void;
     protected upsertReturning<E>(meta: EntityMeta<E>): string;
     /**
      * MariaDB supports neither MySQL's `->`/`->>` shorthand nor the base's chained form. `JSON_VALUE`
@@ -36,12 +42,13 @@ export declare class MariaDialect extends MysqlLikeSqlDialect {
      */
     protected appendVectorValue(ctx: QueryContext, value: readonly unknown[]): void;
     /**
-     * `SET STATEMENT mhnsw_ef_search=N FOR SELECT ...` - MariaDB scopes a variable to one statement, so
-     * the tuning needs neither a transaction nor a restore afterwards, and cannot leak to the next
-     * query on this pooled connection. That is why it prefixes the SQL here instead of coming back
-     * from `vectorTuningStatements`, which is Postgres's `SET LOCAL` shape.
+     * `mhnsw_ef_search` too, where a vector search is tuned. A setting scoped to one statement needs
+     * neither a transaction nor a restore, and cannot leak to the next query on this pooled connection,
+     * which is why the tuning is not `vectorTuningStatements`, Postgres's `SET LOCAL` shape.
      */
-    find<E>(ctx: QueryContext, entity: Type<E>, q?: Query<E>, opts?: QueryOptions, totalAlias?: string): void;
+    protected statementSettings<E>(entity: Type<E>, q: Query<E>): string[];
+    /** `SET STATEMENT ... FOR`, which scopes a variable to the statement it prefixes. */
+    protected applySettings(sql: string, settings: readonly string[]): string;
     /** The reverse: selecting a `VECTOR` column raw yields that blob, so it is read back as text. */
     protected selectFieldExpr(escapedColumn: string, field: FieldOptions): string;
 }

package/dist/maria/mariaDialect.js

@@ -1,3 +1,4 @@
+import { relationTermKey } from '../dialect/abstractSqlDialect.js';
 import { jsonPath } from '../dialect/jsonSql.js';
 import { MysqlLikeSqlDialect } from '../dialect/mysqlLikeSqlDialect.js';
 import { getMeta } from '../entity/index.js';
@@ -18,6 +19,24 @@ export class MariaDialect extends MysqlLikeSqlDialect {
         vectorIndexRequiresNotNull: true,
         indexIfNotExists: true,
     };
+    /**
+     * A derived table here reads no column of the statement around it, so the aggregate reads the
+     * related table itself, and orders and pages inside `JSON_ARRAYAGG`, which takes both.
+     */
+    appendRelationArray(ctx, { entity, query, alias, joins }) {
+        const meta = getMeta(entity);
+        const terms = this.projection(ctx, entity, query, { prefix: alias, json: true }, joins);
+        const sortOpts = { prefix: alias, joins, distinct: query.$distinct };
+        const order = this.buildFragment(ctx, (fragmentCtx) => this.sort(fragmentCtx, entity, query.$sort, sortOpts));
+        const page = this.buildFragment(ctx, (fragmentCtx) => this.pager(fragmentCtx, query));
+        const from = this.buildFragment(ctx, (fragmentCtx) => {
+            this.selectRelationJoins(fragmentCtx, meta, alias, joins);
+            this.where(fragmentCtx, entity, query.$where, { prefix: alias });
+        });
+        const object = this.jsonObject(terms.map((term) => [relationTermKey(term), term.sql]));
+        const rows = `${query.$distinct ? 'DISTINCT ' : ''}${object}${order}${page}`;
+        ctx.append(`COALESCE((SELECT JSON_ARRAYAGG(${rows}) FROM ${this.tableRef(meta, alias).ref}${from}), JSON_ARRAY())`);
+    }
     upsertReturning(meta) {
         const returning = this.returningId(meta);
         return returning ? ` ${returning}` : '';
@@ -61,18 +80,19 @@ export class MariaDialect extends MysqlLikeSqlDialect {
         ctx.append(')');
     }
     /**
-     * `SET STATEMENT mhnsw_ef_search=N FOR SELECT ...` - MariaDB scopes a variable to one statement, so
-     * the tuning needs neither a transaction nor a restore afterwards, and cannot leak to the next
-     * query on this pooled connection. That is why it prefixes the SQL here instead of coming back
-     * from `vectorTuningStatements`, which is Postgres's `SET LOCAL` shape.
+     * `mhnsw_ef_search` too, where a vector search is tuned. A setting scoped to one statement needs
+     * neither a transaction nor a restore, and cannot leak to the next query on this pooled connection,
+     * which is why the tuning is not `vectorTuningStatements`, Postgres's `SET LOCAL` shape.
      */
-    find(ctx, entity, q = {}, opts, totalAlias) {
+    statementSettings(entity, q) {
         // `$candidates` first: `getMeta` would otherwise be resolved on every read, to discover that
         // almost none of them tune anything.
-        if (q.$candidates !== undefined && this.tunedVectorIndex(getMeta(entity), q)) {
-            ctx.append(`SET STATEMENT mhnsw_ef_search=${q.$candidates} FOR `);
-        }
-        super.find(ctx, entity, q, opts, totalAlias);
+        const tuned = q.$candidates !== undefined && this.tunedVectorIndex(getMeta(entity), q);
+        return [...(tuned ? [`mhnsw_ef_search=${q.$candidates}`] : []), ...super.statementSettings(entity, q)];
+    }
+    /** `SET STATEMENT ... FOR`, which scopes a variable to the statement it prefixes. */
+    applySettings(sql, settings) {
+        return `SET STATEMENT ${settings.join(', ')} FOR ${sql}`;
     }
     /** The reverse: selecting a `VECTOR` column raw yields that blob, so it is read back as text. */
     selectFieldExpr(escapedColumn, field) {

package/dist/migrate/builder/splitSqlStatements.js

@@ -26,11 +26,11 @@ export function splitSqlStatements(sql) {
     const masterRegex = /'(?:''|\\['\\]|[^'])*(?:'|(?=$))|"(?:""|\\["\\]|[^"])*(?:"|(?=$))|`(?:``|\\[`\\]|[^`])*(?:`|(?=$))|\$(?<tag>[a-zA-Z0-9_]*)\$[\s\S]*?(?:\$\k<tag>|(?=$))|--.*|\/\*[\s\S]*?(?:\*\/|(?=$))|;/g;
     for (const match of sql.matchAll(masterRegex)) {
         if (match[0] === ';') {
-            const stmt = sql.substring(lastIndex, match.index ?? 0).trim();
+            const stmt = sql.substring(lastIndex, match.index).trim();
             if (stmt) {
                 statements.push(stmt);
             }
-            lastIndex = (match.index ?? 0) + match[0].length;
+            lastIndex = match.index + match[0].length;
         }
     }
     const lastStmt = sql.substring(lastIndex).trim();

package/dist/migrate/cli.d.ts

@@ -1,11 +1,10 @@
 #!/usr/bin/env node
-import type { AbstractDialect } from '../dialect/index.js';
 import type { ForeignKeyAction } from '../schema/types.js';
-import type { Config } from '../type/index.js';
+import type { Config, MigratorDialect } from '../type/index.js';
 import { Migrator } from './migrator.js';
 import { createSchemaGeneratorAsync } from './schemaGeneratorAsync.js';
 /** Sync helper for SQL dialects only; returns `undefined` for MongoDB - use {@link createSchemaGeneratorAsync}. */
-export declare function getSchemaGenerator(dialect: AbstractDialect, defaultForeignKeyAction?: ForeignKeyAction): import("./schemaGenerator.js").SqlSchemaGenerator | undefined;
+export declare function getSchemaGenerator(dialect: MigratorDialect, defaultForeignKeyAction?: ForeignKeyAction): import("./schemaGenerator.js").SqlSchemaGenerator | undefined;
 export { createSchemaGeneratorAsync };
 export declare function main(args?: string[]): Promise<void>;
 export declare function runUp(migrator: Migrator, args: string[]): Promise<void>;

package/dist/migrate/cli.js

@@ -34,7 +34,6 @@ export async function main(args = process.argv.slice(2)) {
     try {
         const config = await loadConfig(customPath);
         assertCliConfig(config);
-        const dialectName = config.pool.dialect.dialectName ?? 'postgres';
         const options = {
             migrationsPath: config.migrationsPath ?? './migrations',
             tableName: config.tableName,
@@ -43,13 +42,7 @@ export async function main(args = process.argv.slice(2)) {
             defaultForeignKeyAction: config.defaultForeignKeyAction,
         };
         const migrator = new Migrator(config.pool, options);
-        if (!migrator.schemaGenerator) {
-            const generator = await createSchemaGeneratorAsync(config.pool.dialect, config.defaultForeignKeyAction);
-            if (!generator) {
-                throw new TypeError(`Could not find a schema generator for dialect: ${dialectName}`);
-            }
-            migrator.setSchemaGenerator(generator);
-        }
+        await migrator.ensureSchemaGenerator();
         switch (command) {
             case 'up':
                 await runUp(migrator, filteredArgs.slice(1));
@@ -314,8 +307,8 @@ function printDriftGroup(title, drifts, icon, showSuggestion) {
             if (drift.expected && drift.actual) {
                 console.log(`    Expected: ${drift.expected}, Actual: ${drift.actual}`);
             }
-            if (showSuggestion && drift.suggestion) {
-                console.log(`    → ${drift.suggestion}`);
+            if (showSuggestion) {
+                console.log(`    -> ${drift.suggestion}`);
             }
         }
         console.log('');
@@ -365,7 +358,7 @@ Configuration:
   Create a uql.config.ts or uql.config.js file in your project root.
   You can also specify a custom config path using --config or -c.
   The CLI requires pool.dialect (dialect id = pool.dialect.dialectName).
-  See the repo README section "Driver → pool → dialect class".
+  See the repo README section "Driver -> pool -> dialect class".
 
   export default {
     pool: new PgQuerierPool({ ... }),

package/dist/migrate/codegen/fieldOptionsSource.js

@@ -16,7 +16,7 @@ const OPTION_SOURCE = {
     type: (col) => {
         const columnType = canonicalToColumnType(col.type);
         return [
-            ...(columnType ? [`columnType: ${quoted(columnType)}`] : []),
+            `columnType: ${quoted(columnType)}`,
             ...(col.type.length && col.type.category === 'string' ? [`length: ${col.type.length}`] : []),
             ...(col.type.precision === undefined ? [] : [`precision: ${col.type.precision}`]),
             ...(col.type.precision !== undefined && col.type.scale !== undefined ? [`scale: ${col.type.scale}`] : []),

package/dist/migrate/ddl/index.d.ts

@@ -2,15 +2,11 @@ import type { AbstractSqlDialect } from '../../dialect/abstractSqlDialect.js';
 import { IndexDdl } from './indexDdl.js';
 import { TableDdl } from './tableDdl.js';
 export { IndexDdl } from './indexDdl.js';
+export { MsSqlIndexDdl } from './mssqlIndexDdl.js';
 export { MsSqlTableDdl } from './mssqlTableDdl.js';
 export { MariaIndexDdl, MySqlIndexDdl, MysqlLikeIndexDdl } from './mysqlIndexDdl.js';
 export { CockroachIndexDdl, PgIndexDdl } from './pgIndexDdl.js';
 export { TableDdl } from './tableDdl.js';
-/**
- * The index DDL a dialect gets, most specific first. `instanceof` rather than the `dialectName`
- * {@link tableDdlFor} reads, because each family's index DDL is typed to its dialect and the narrowing
- * is what hands it one. Anything else gets the portable form, which is SQLite's.
- */
 export declare function indexDdlFor(dialect: AbstractSqlDialect): IndexDdl;
 /**
  * The table DDL a dialect gets: SQL Server's, or the portable form every other engine takes. By

package/dist/migrate/ddl/index.js

@@ -1,40 +1,29 @@
-import { CockroachDialect } from '../../cockroachdb/cockroachDialect.js';
-import { MysqlLikeSqlDialect } from '../../dialect/mysqlLikeSqlDialect.js';
-import { PgLikeSqlDialect } from '../../dialect/pgLikeSqlDialect.js';
-import { MariaDialect } from '../../maria/mariaDialect.js';
-import { MySqlDialect } from '../../mysql/mysqlDialect.js';
 import { IndexDdl } from './indexDdl.js';
+import { MsSqlIndexDdl } from './mssqlIndexDdl.js';
 import { MsSqlTableDdl } from './mssqlTableDdl.js';
-import { MariaIndexDdl, MySqlIndexDdl, MysqlLikeIndexDdl } from './mysqlIndexDdl.js';
+import { MariaIndexDdl, MySqlIndexDdl } from './mysqlIndexDdl.js';
 import { CockroachIndexDdl, PgIndexDdl } from './pgIndexDdl.js';
 import { TableDdl } from './tableDdl.js';
 export { IndexDdl } from './indexDdl.js';
+export { MsSqlIndexDdl } from './mssqlIndexDdl.js';
 export { MsSqlTableDdl } from './mssqlTableDdl.js';
 export { MariaIndexDdl, MySqlIndexDdl, MysqlLikeIndexDdl } from './mysqlIndexDdl.js';
 export { CockroachIndexDdl, PgIndexDdl } from './pgIndexDdl.js';
 export { TableDdl } from './tableDdl.js';
 /**
- * The index DDL a dialect gets, most specific first. `instanceof` rather than the `dialectName`
- * {@link tableDdlFor} reads, because each family's index DDL is typed to its dialect and the narrowing
- * is what hands it one. Anything else gets the portable form, which is SQLite's.
+ * Each engine's index DDL, by the `dialectName` a subclass inherits: by name, so this entry carries no
+ * dialect, and exhaustive, so a new engine has to name its own. SQLite's is the portable form.
  */
+const INDEX_DDL = {
+    postgres: PgIndexDdl,
+    cockroachdb: CockroachIndexDdl,
+    mysql: MySqlIndexDdl,
+    mariadb: MariaIndexDdl,
+    mssql: MsSqlIndexDdl,
+    sqlite: IndexDdl,
+};
 export function indexDdlFor(dialect) {
-    if (dialect instanceof CockroachDialect) {
-        return new CockroachIndexDdl(dialect);
-    }
-    if (dialect instanceof PgLikeSqlDialect) {
-        return new PgIndexDdl(dialect);
-    }
-    if (dialect instanceof MySqlDialect) {
-        return new MySqlIndexDdl(dialect);
-    }
-    if (dialect instanceof MariaDialect) {
-        return new MariaIndexDdl(dialect);
-    }
-    if (dialect instanceof MysqlLikeSqlDialect) {
-        return new MysqlLikeIndexDdl(dialect);
-    }
-    return new IndexDdl(dialect);
+    return new INDEX_DDL[dialect.dialectName](dialect);
 }
 /**
  * The table DDL a dialect gets: SQL Server's, or the portable form every other engine takes. By