uql-orm 0.65.1 → 0.67.0

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 { entitySql, entityWhere, fieldOptionConflict, getKeys, hasKeys, isToManyRelation, lowerFirst, memberRefs, normalizeIndexColumn, upperFirst, definedEntries, } from '../../util/index.js';
+import { entitySql, entityWhere, fieldOptionConflict, getKeys, hasKeys, isToManyRelation, memberRefs, normalizeIndexColumn, 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
@@ -108,7 +108,9 @@ export function defineFilter(entity, name, opts) {
     if (name === SOFT_DELETE_FILTER) {
         throw TypeError(`'${entity.name}' filter name '${SOFT_DELETE_FILTER}' is reserved; it is auto-registered from @Field({ softDelete })`);
     }
-    if (opts.security && opts.onMissing === 'skip') {
+    // Widened for a caller the types did not reach, which is the only one this can refuse.
+    const { security, onMissing } = opts;
+    if (security && onMissing === 'skip') {
         throw TypeError(`'${entity.name}' security filter '${name}' cannot use onMissing: 'skip' (it must fail closed)`);
     }
     (meta.filters ??= {})[name] = opts;
@@ -173,11 +175,8 @@ export function defineEntity(entity, opts = {}) {
     if (!hasKeys(meta.fields)) {
         throw TypeError(`'${entity.name}' must have fields`);
     }
-    // A later call composes onto the entity, so saying nothing about the table retracts nothing - which
-    // is why `derivedName` is only ever *set*, never recomputed from what a previous call left.
-    // It records that the class name stood in, telling a naming strategy there is something to derive;
-    // comparing the two cannot, since an entity may name its table exactly what its class is called and
-    // a spec's minted class is named after its table.
+    // A later call composes onto the entity, so a name is only ever set, and `derivedName` records that
+    // the class name stood in, which is what a naming strategy derives from.
     if (opts.name !== undefined) {
         meta.name = opts.name;
         meta.derivedName = false;
@@ -249,27 +248,11 @@ export function relationOf(meta, key) {
     }
     return relation;
 }
-/**
- * Whether the caller named every column of the row's primary key, so {@link idOf} can name the row.
- *
- * `!= null` rather than falsiness: `0` and an empty string are ids a row can legitimately carry, and
- * reading them as "no id" is how a write of that row turned into a second insert. Distinct from
- * "does the row carry this column", which an insert asks of `undefined` alone because that is what
- * decides whether the column appears in its `VALUES` list at all.
- */
+/** Whether the row names every column of its primary key, `0` and `''` included. */
 export function namesKey(meta, row) {
     return meta.ids.every((key) => row[key] != null);
 }
-/**
- * A row's primary key: the value itself for a single key, an object carrying every key for a
- * composite - which is {@link WrittenId}, and reads as the {@link EntityId} a `$where` takes.
- *
- * What a settled write names its rows by, and what a write hands back. Naming a composite row by one
- * of its columns would address every row agreeing on that one.
- *
- * `WrittenId` does not reduce for an unresolved `E`, so which branch this entity is in cannot be
- * proven here, only checked - which is what `ids.length` does.
- */
+/** A row's primary key: its value, or a map of every column on a composite, checked at run time. */
 export function idOf(meta, row) {
     const { ids } = meta;
     const id = ids.length === 1 ? row[ids[0]] : Object.fromEntries(ids.map((key) => [key, row[key]]));
@@ -326,9 +309,13 @@ function registeredMeta(entity) {
 function fillRelations(meta) {
     for (const [relKey, relation] of definedEntries(meta.relations)) {
         const at = `'${meta.entity.name}.${relKey}'`;
-        if (!settledReferences(at, meta, relKey, relation).length) {
+        const references = settledReferences(at, meta, relKey, relation);
+        if (!references.length) {
             throw new TypeError(`${at} has no columns to join on.`);
         }
+        if (!relation.through) {
+            assertJoins(at, meta, relation, references);
+        }
     }
     // A column `references` names is a foreign key with or without a relation over it, and one cannot point
     // at a composite key: refused on first read, as a relation that cannot join is, not at the schema build.
@@ -356,18 +343,11 @@ function settledReferences(at, meta, relKey, relOpts) {
         return fillInverseSide(at, meta, relOpts, mappedBy);
     if (through)
         return fillThrough(at, meta, relOpts, through);
-    return fillOwningSide(at, meta, relKey, relOpts);
-}
-/**
- * Settles each relation joining on its own entity's columns, every one but an inverse side and a `through`:
- * the columns they create and the foreign keys they hold are what another entity reads off this one.
- */
-function settleOwnColumns(meta) {
-    for (const [relKey, relation] of definedEntries(meta.relations)) {
-        if (!relation.mappedBy && !relation.through) {
-            settledReferences(`'${meta.entity.name}.${relKey}'`, meta, relKey, relation);
-        }
-    }
+    throw new TypeError(isToManyRelation(relOpts)
+        ? `${at} is a to-many relation with no way to join: it needs 'mappedBy' (the member on the other side), ` +
+            "'through' (a junction entity), or 'references' (the columns)."
+        : `${at} needs 'references', the foreign key column it joins by, or 'mappedBy', the member on the other ` +
+            'side holding it.');
 }
 /**
  * Each key of this entity, then each of the target, paired with the junction's one column referencing it.
@@ -382,48 +362,9 @@ function fillThrough(at, meta, relOpts, through) {
     ];
     return relOpts.references;
 }
-function fillOwningSide(at, meta, relKey, relOpts) {
-    if (isToManyRelation(relOpts)) {
-        throw new TypeError(`${at} is a to-many relation with no way to join: it needs 'mappedBy' (the field on the other side), ` +
-            "'through' (a junction entity), or 'references' (the columns).");
-    }
-    const relMeta = ensureMeta(relOpts.entity());
-    // `<rel>Id` for the one-key case it has always been; `<rel><Key>` per column otherwise. Both name a
-    // property, so both are spelled from the referenced *property* - a column name is what the naming
-    // strategy makes of this afterwards.
-    const sole = relMeta.ids.length === 1;
-    const references = relMeta.ids.map((key) => ({
-        local: sole ? `${relKey}Id` : `${relKey}${upperFirst(key)}`,
-        foreign: key,
-    }));
-    // A column the entity declares would be joined by its name alone, so renaming either one would leave
-    // the other behind, still compiling.
-    const fields = meta.fields;
-    if (references.some(({ local }) => fields[local])) {
-        const own = lowerFirst(meta.entity.name);
-        throw new TypeError(`${at} joins ${references.map(({ local }) => `'${local}'`).join(', ')} by name, which a rename does not ` +
-            `follow: link them with ${sole ? `'references: (${own}) => ${own}.${references[0].local}'` : "'references' pairs"}.`);
-    }
-    // `typeFromReference` so schema generation resolves the referenced primary key's exact type
-    // (columnType, length, chained keys) rather than trusting the fallback, as it does for an
-    // explicit `@Field({ references })`.
-    for (const { local, foreign } of references) {
-        fields[local] = {
-            name: local,
-            type: fieldOf(relMeta, foreign).type ?? Number,
-            references: relOpts.entity,
-            referencedKey: foreign,
-            typeFromReference: true,
-        };
-    }
-    relOpts.references = references;
-    return references;
-}
 function fillInverseSide(at, meta, relOpts, mappedBy) {
     const relMeta = registeredMeta(relOpts.entity());
     const other = `'${relMeta.entity.name}.${mappedBy}'`;
-    // The other side's own columns first: they declare, or create, what this side is mapped by.
-    settleOwnColumns(relMeta);
     if (relMeta.fields[mappedBy]) {
         if (meta.ids.length > 1) {
             throw new TypeError(`${at} is mapped by ${other}, one column, but the primary key of ` +
@@ -441,6 +382,10 @@ function fillInverseSide(at, meta, relOpts, mappedBy) {
     if (owner.mappedBy) {
         throw new TypeError(`${at} is mapped by ${other}, an inverse side too, so neither owns the foreign key.`);
     }
+    const ownerTarget = owner.entity();
+    if (!isA(meta.entity, ownerTarget)) {
+        throw new TypeError(`${at} is mapped by ${other}, a relation to '${ownerTarget.name}', not to '${meta.entity.name}'.`);
+    }
     const ownerReferences = settledReferences(other, relMeta, mappedBy, owner);
     // Two different flips: a junction's pairs are the owner's group followed by ours, so the two groups
     // swap - `toReversed` would also reverse each group, pairing a composite's columns crosswise. A
@@ -452,16 +397,52 @@ function fillInverseSide(at, meta, relOpts, mappedBy) {
     relOpts.through = owner.through;
     return relOpts.references;
 }
+/**
+ * Refuses a join on a column either entity does not store, and a one-column join whose foreign key, on
+ * whichever side holds it, points at another entity: it would match unrelated rows by their keys.
+ */
+function assertJoins(at, meta, relOpts, pairs) {
+    const target = registeredMeta(relOpts.entity());
+    // Only the owning side of a to-one holds its foreign key; an inverse side and a to-many join on the target's.
+    const holdsLocally = !relOpts.mappedBy && !isToManyRelation(relOpts);
+    const sides = [
+        { meta: columnsOf(meta), keys: pairs.map(({ local }) => local), joins: target.entity, holds: holdsLocally },
+        { meta: columnsOf(target), keys: pairs.map(({ foreign }) => foreign), joins: meta.entity, holds: !holdsLocally },
+    ];
+    for (const side of sides) {
+        for (const key of side.keys) {
+            const column = `'${side.meta.entity.name}.${key}'`;
+            const field = side.meta.fields[key];
+            if (!field || isInlinedExpression(field)) {
+                throw new TypeError(`${at} joins ${column}, which is not a column: declare it with '@Field'.`);
+            }
+            const referenced = side.holds && pairs.length === 1 ? field.references?.() : undefined;
+            if (referenced && !isA(side.joins, referenced)) {
+                throw new TypeError(`${at} joins ${column}, a foreign key to '${referenced.name}', not to '${side.joins.name}'.`);
+            }
+        }
+    }
+}
+/** `meta` with its fields read by any name, as a join's columns come. */
+function columnsOf(meta) {
+    return meta;
+}
+/** Whether `entity` is `base` or extends it, as an entity inheriting a relation does. */
+function isA(entity, base) {
+    return entity === base || entity.prototype instanceof base;
+}
 /**
  * The foreign keys an entity holds: each owning to-one's columns, and each `@Field({ references })` no
  * relation joins on, as the many-to-one it describes, once its target has registered a key. What the
- * schema build constrains and a junction joins by, read once the relations holding them are settled.
+ * schema build constrains and a junction joins by, settling the relations holding them first.
  */
 export function foreignKeysOf(meta) {
-    settleOwnColumns(meta);
     const owning = definedEntries(meta.relations)
-        .map(([, relation]) => relation)
-        .filter((relation) => !relation.mappedBy && !relation.through && !isToManyRelation(relation));
+        .filter(([, relation]) => !relation.mappedBy && !relation.through && !isToManyRelation(relation))
+        .map(([relKey, relation]) => {
+        settledReferences(`'${meta.entity.name}.${relKey}'`, meta, relKey, relation);
+        return relation;
+    });
     const joined = new Set(owning.flatMap(({ references }) => references.map(({ local }) => local)));
     const columns = definedEntries(meta.fields).flatMap(([key, field]) => {
         if (!field.references || joined.has(key))
@@ -471,8 +452,8 @@ export function foreignKeysOf(meta) {
             return [];
         if (target.ids.length > 1) {
             throw new TypeError(`'${meta.entity.name}.${key}' cannot reference '${target.entity.name}', whose primary key is composite ` +
-                `(${target.ids.join(', ')}): a column points at one. Use ` +
-                `'@ManyToOne({ entity: () => ${target.entity.name} })', which declares one column per key.`);
+                `(${target.ids.join(', ')}): a column points at one. Declare a column per key and pair each with it ` +
+                `in a '@ManyToOne' to '${target.entity.name}'.`);
         }
         return [{ entity: field.references, cardinality: 'm1', references: [{ local: key, foreign: target.ids[0] }] }];
     });
@@ -486,9 +467,9 @@ function junctionReferences(at, junction, side) {
         const referenced = `'${side.entity.name}.${key}'`;
         if (!pair) {
             const declare = side.ids.length > 1
-                ? `@ManyToOne({ entity: () => ${side.entity.name} })`
-                : `@Field({ references: () => ${side.entity.name} })`;
-            throw new TypeError(`${at} joins through '${junction.entity.name}', which has no column referencing ${referenced}: declare one, '${declare}'.`);
+                ? `a column per key, paired in a '@ManyToOne' to '${side.entity.name}'`
+                : `'@Field({ references: () => ${side.entity.name} })'`;
+            throw new TypeError(`${at} joins through '${junction.entity.name}', which has no column referencing ${referenced}: declare ${declare}.`);
         }
         if (others.length) {
             const columns = [pair, ...others].map(({ local }) => `'${local}'`).join(' and ');
@@ -503,11 +484,8 @@ function getIdKeys(meta) {
     return getKeys(meta.fields).filter((key) => meta.fields[key]?.isId);
 }
 /**
- * Merges `ancestor` and its own ancestors into `meta`, nearest first, so a further one never overwrites
- * a nearer. An `abstract class BaseEntity` carrying `@Field`s but no `@Entity()` has nobody to drain
- * its registrations, so do it here. Walking the *class* prototype chain rather than the metadata
- * object's is what makes this work on every transformer: tsc and esbuild chain metadata across
- * `extends`, SWC does not.
+ * Merges `ancestor` and its ancestors into `meta`, nearest first, draining an undecorated base's
+ * registrations. Walks the class chain, since not every compiler chains decorator metadata.
  */
 function inheritFrom(meta, ancestor) {
     for (let parent = ancestor; parent && parent !== Object; parent = parentOf(parent)) {

package/dist/http/handler.d.ts

@@ -29,13 +29,7 @@ export type HookContext<E extends object, Ctx = unknown> = {
     readonly meta: EntityMeta<E>;
     readonly op: CrudOperation;
     readonly method: HttpMethod;
-    /**
-     * parsed query - mutate in place or reassign to shape it (e.g. force a `$select`, inject a
-     * `$sort`). For actual tenant/row-level scoping, prefer `@Filter(..., { security: true })` on
-     * the entity instead: unlike a hook mutation, it is AND-merged (a client `$where` on the same
-     * key cannot silently win), fails closed when its context is missing, and applies uniformly
-     * across every query path including joined relations.
-     */
+    /** The parsed query, to reshape in place. Scope rows with a `security` filter instead, which a client cannot override. */
     query: Query<E>;
     /**
      * request payload - reassignable for sanitization or field injection.
@@ -51,13 +45,7 @@ export type ResponseHook<Ctx = unknown> = <E extends object>(ctx: HookContext<E,
 export type RequestHandlerOptions<Ctx = unknown> = {
     include?: Type<object>[];
     exclude?: Type<object>[];
-    /**
-     * The URL segment an entity is addressed by, defaulting to its kebab-cased class name.
-     *
-     * State it where the default cannot serve: a build that minifies class names renames every route,
-     * and two entities mapping one table in different schemas collide on one. The browser client takes
-     * the same option, so both ends can read one map.
-     */
+    /** The URL segment an entity is addressed by, its kebab-cased class name by default; the browser client takes the same option. */
     entityPath?: (entity: Type<unknown>) => string;
     /**
      * Allow augment any kind of request before it runs. Hooks may be async

package/dist/index.d.ts

@@ -4,4 +4,6 @@ export * from './entity/index.js';
 export * from './namingStrategy/index.js';
 export * from './querier/index.js';
 export * from './type/index.js';
-export * from './util/index.js';
+export { withDeleted } from './util/filters.util.js';
+export { DefaultLogger } from './util/logger.js';
+export { raw, refs } from './util/raw.js';

package/dist/index.js

@@ -4,4 +4,6 @@ export * from './entity/index.js';
 export * from './namingStrategy/index.js';
 export * from './querier/index.js';
 export * from './type/index.js';
-export * from './util/index.js';
+export { withDeleted } from './util/filters.util.js';
+export { DefaultLogger } from './util/logger.js';
+export { raw, refs } from './util/raw.js';

package/dist/libsql/libsqlDialect.d.ts

@@ -7,13 +7,6 @@ import type { VectorDistance, VectorMetric } from '../type/index.js';
  * functions, which `TursoDialect` inherits.
  */
 export declare class LibsqlDialect extends SqliteDialect {
-    /**
-     * libSQL has vector search built in, under its own names, so the sqlite-vec `vec_distance_*`
-     * functions this dialect would otherwise inherit are never present.
-     *
-     * @remarks `inner` and `l1` are left out: `vector_distance_dot` only exists in the newer Rust
-     * engine (see `TursoLocalDialect`) and no libSQL build has an L1 metric. Both raise the same
-     * "does not support vector distance metric" error as any other unsupported metric.
-     */
+    /** libSQL's built-in vector functions; no `inner` (only the Rust engine has it) and no `l1`. */
     readonly vectorMetrics: ReadonlyMap<VectorDistance, VectorMetric>;
 }

package/dist/libsql/libsqlDialect.js

@@ -6,14 +6,7 @@ import { SqliteDialect } from '../sqlite/sqliteDialect.js';
  * functions, which `TursoDialect` inherits.
  */
 export class LibsqlDialect extends SqliteDialect {
-    /**
-     * libSQL has vector search built in, under its own names, so the sqlite-vec `vec_distance_*`
-     * functions this dialect would otherwise inherit are never present.
-     *
-     * @remarks `inner` and `l1` are left out: `vector_distance_dot` only exists in the newer Rust
-     * engine (see `TursoLocalDialect`) and no libSQL build has an L1 metric. Both raise the same
-     * "does not support vector distance metric" error as any other unsupported metric.
-     */
+    /** libSQL's built-in vector functions; no `inner` (only the Rust engine has it) and no `l1`. */
     vectorMetrics = new Map([
         ['cosine', { fn: 'vector_distance_cos' }],
         ['l2', { fn: 'vector_distance_l2' }],

package/dist/maria/mariaDialect.d.ts

@@ -1,16 +1,14 @@
 import { type RelationRows } from '../dialect/abstractSqlDialect.js';
 import { MysqlLikeSqlDialect } from '../dialect/mysqlLikeSqlDialect.js';
-import type { DialectFeatures, EntityMeta, FieldOptions, Query, QueryContext, Type, VectorDistance, VectorMetric } from '../type/index.js';
+import type { EntityMeta, FieldOptions, Query, QueryContext, SqlDialectFeatures, Type, VectorDistance, VectorMetric } from '../type/index.js';
 export declare class MariaDialect extends MysqlLikeSqlDialect {
     readonly dialectName = "mariadb";
     readonly insertIdSource = "returning";
-    /** MariaDB has no `FOR ... OF`, so a lock cannot be narrowed to one table of a join. */
-    readonly supportsLockOf = false;
     /**
      * Unlike MySQL: `VECTOR(n)` takes its dimension, every column of a vector index has to be NOT NULL,
-     * and `CREATE INDEX` takes `IF NOT EXISTS` - which MySQL's grammar has no place for.
+     * `CREATE INDEX` takes `IF NOT EXISTS`, and a lock cannot be narrowed to one table of a join.
      */
-    protected readonly featureOverrides: Partial<DialectFeatures>;
+    readonly features: SqlDialectFeatures;
     /**
      * 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.

package/dist/maria/mariaDialect.js

@@ -1,6 +1,6 @@
 import { relationTermKey } from '../dialect/abstractSqlDialect.js';
 import { jsonPath } from '../dialect/jsonSql.js';
-import { MysqlLikeSqlDialect } from '../dialect/mysqlLikeSqlDialect.js';
+import { MYSQL_FEATURES, MysqlLikeSqlDialect } from '../dialect/mysqlLikeSqlDialect.js';
 import { getMeta } from '../entity/index.js';
 import { columnFamily } from '../util/field.util.js';
 import { MARIA_VECTOR_METRICS } from './mariaVectorMetrics.js';
@@ -8,16 +8,16 @@ export class MariaDialect extends MysqlLikeSqlDialect {
     dialectName = 'mariadb';
     // MariaDB 10.5+ has `INSERT ... RETURNING`, so ids come back exact per row - the upsert's too.
     insertIdSource = 'returning';
-    /** MariaDB has no `FOR ... OF`, so a lock cannot be narrowed to one table of a join. */
-    supportsLockOf = false;
     /**
      * Unlike MySQL: `VECTOR(n)` takes its dimension, every column of a vector index has to be NOT NULL,
-     * and `CREATE INDEX` takes `IF NOT EXISTS` - which MySQL's grammar has no place for.
+     * `CREATE INDEX` takes `IF NOT EXISTS`, and a lock cannot be narrowed to one table of a join.
      */
-    featureOverrides = {
+    features = {
+        ...MYSQL_FEATURES,
         vectorSupportsLength: true,
         vectorIndexRequiresNotNull: true,
         indexIfNotExists: true,
+        rowLockOf: false,
     };
     /**
      * A derived table here reads no column of the statement around it, so the aggregate reads the

package/dist/maria/mariadbQuerier.js

@@ -7,8 +7,8 @@ export class MariadbQuerier extends AbstractPoolQuerier {
     }
     async internalRun(query, values) {
         const res = await this.getConn().query(query, values);
-        // MariaDB may not set `affectedRows` when RETURNING is used; fall back to row count.
-        const changes = res.affectedRows ?? res.length ?? 0;
+        // An OK packet reports `affectedRows`; a `RETURNING` statement answers rows instead, and counts by them.
+        const changes = res.affectedRows ?? res.length;
         const rows = res.length ? Array.from(res, decodeBigInts) : [];
         return this.buildUpdateResult({ rows, changes, upsertStatus: res.affectedRows });
     }

package/dist/maria/mariadbQuerierPool.js

@@ -11,12 +11,7 @@ export class MariadbQuerierPool extends AbstractSqlQuerierPool {
         // BIGINT stays the driver's `bigint`, which `MariadbQuerier` decodes by the rule every driver here
         // shares (`decodeWideNumber`) - not `bigIntAsNumber`, which rounds past 2^53 without a word.
         this.pool = createPool(opts);
-        // `mariadb`'s own `createPool` already attaches a silent no-op 'error'
-        // listener (so a dropped connection can't crash the process), but its
-        // `Pool` type only declares `on` for 'acquire' | 'connection' | 'enqueue'
-        // | 'release' - 'error' genuinely fires at runtime (see `lib/pool.js`)
-        // but isn't in the declaration, hence the cast. Re-attaching our own
-        // listener here just makes the error visible instead of a silent no-op.
+        // `mariadb` fires 'error' at runtime without declaring it, hence the cast; this makes it visible.
         attachPoolErrorHandler(this.pool, 'Idle MariaDB pool connection encountered an error', extra?.logger);
     }
     async getQuerier() {

package/dist/migrate/builder/migrationBuilder.js

@@ -20,13 +20,7 @@ function createIndexOperation(tableName, columns, options = {}) {
         },
     };
 }
-/**
- * The one shape of an `addForeignKey` operation, `NO ACTION` defaults included.
- *
- * Three callers build it and differ only in what they do with the result: the table builder records
- * it through its parent, the recorder records it directly, and the executing builder also runs it.
- * Spelled out three times, a changed default would have had to be found in all three.
- */
+/** An `addForeignKey` operation, `NO ACTION` defaults included, for the three builders that record one. */
 function addForeignKeyOperation(tableName, columns, target, options = {}) {
     return {
         type: 'addForeignKey',
@@ -40,21 +34,11 @@ function addForeignKeyOperation(tableName, columns, target, options = {}) {
         },
     };
 }
-/**
- * Declare one column through the same vocabulary `createTable` uses. A throwaway {@link TableBuilder}
- * is that vocabulary: `addColumn`/`alterColumn` used to take a bare {@link IColumnBuilder}, which
- * cannot express a type, so every column they recorded was hard-coded `VARCHAR`.
- */
+/** One column declared through `createTable`'s vocabulary, a throwaway {@link TableBuilder}, so its type is stated. */
 function buildOneColumn(callback) {
     return callback(new TableBuilder('')).build();
 }
-/**
- * Collects the operations one `alterTable` callback declares, in the order it declared them.
- *
- * Collected rather than dispatched to the parent as they are made: the chaining methods are
- * synchronous by contract, so a builder that executes could only fire and forget, which returned from
- * `alterTable` with the statements still in flight and turned a failure into an unhandled rejection.
- */
+/** The operations one `alterTable` callback declares, collected in order, since its methods are synchronous. */
 class AlterTableBuilder {
     tableName;
     operations = [];

package/dist/migrate/builder/splitSqlStatements.d.ts

@@ -1,15 +1,2 @@
-/**
- * Splits a SQL blob on semicolons into separate statements.
- *
- * Uses a declarative Master-Regex scanner to rapidly
- * identify and skip "non-splittable" blocks (strings, comments, dollar-quotes) in a single pass.
- * This approach is $O(n)$, leverages native regex speed, and is trivially easy to audit.
- *
- * Handles:
- * - Single quotes: '...' (standard SQL, respects '' and \')
- * - Double quotes: "..." (identifiers or MySQL strings)
- * - Backticks: `...` (MySQL identifiers)
- * - Postgres Dollar quotes: $tag$...$tag$ or $$...$$
- * - Comments: -- and /* ... *\/
- */
+/** Splits SQL on semicolons, skipping strings, quoted identifiers, dollar-quoted blocks and comments in one regex pass. */
 export declare function splitSqlStatements(sql: string): string[];

package/dist/migrate/builder/splitSqlStatements.js

@@ -1,28 +1,8 @@
-/**
- * Splits a SQL blob on semicolons into separate statements.
- *
- * Uses a declarative Master-Regex scanner to rapidly
- * identify and skip "non-splittable" blocks (strings, comments, dollar-quotes) in a single pass.
- * This approach is $O(n)$, leverages native regex speed, and is trivially easy to audit.
- *
- * Handles:
- * - Single quotes: '...' (standard SQL, respects '' and \')
- * - Double quotes: "..." (identifiers or MySQL strings)
- * - Backticks: `...` (MySQL identifiers)
- * - Postgres Dollar quotes: $tag$...$tag$ or $$...$$
- * - Comments: -- and /* ... *\/
- */
+/** Splits SQL on semicolons, skipping strings, quoted identifiers, dollar-quoted blocks and comments in one regex pass. */
 export function splitSqlStatements(sql) {
     const statements = [];
     let lastIndex = 0;
-    // This regex matches:
-    // 1. Single quoted strings: '(?:''|\\['\\]|[^'])*(?:'|(?=$))
-    // 2. Double quoted identifiers: "(?:""|\\["\\]|[^"])*(?:"|(?=$))
-    // 3. Backticked identifiers: `(?:``|\\[`\\]|[^`])*(?:`|(?=$))
-    // 4. Postgres Dollar quoted blocks: \$(?<tag>[a-zA-Z0-9_]*)\$[\s\S]*?(?:\$\k<tag>|(?=$))
-    // 5. Single-line comments: --.*
-    // 6. Multi-line comments: \/\*[\s\S]*?(?:\*\/|(?=$))
-    // 7. Statement terminator: ;
+    // Quoted strings and identifiers, dollar quotes, comments, or a `;`: the one regex scanning them all.
     const masterRegex = /'(?:''|\\['\\]|[^'])*(?:'|(?=$))|"(?:""|\\["\\]|[^"])*(?:"|(?=$))|`(?:``|\\[`\\]|[^`])*(?:`|(?=$))|\$(?<tag>[a-zA-Z0-9_]*)\$[\s\S]*?(?:\$\k<tag>|(?=$))|--.*|\/\*[\s\S]*?(?:\*\/|(?=$))|;/g;
     for (const match of sql.matchAll(masterRegex)) {
         if (match[0] === ';') {

package/dist/migrate/builder/types.d.ts

@@ -67,14 +67,7 @@ export interface VectorColumnOptions extends BaseColumnOptions {
     /** Number of dimensions */
     dimensions?: number;
 }
-/**
- * A column as the builder describes one: {@link ColumnNode} without the graph links a DTO cannot carry.
- *
- * Derived rather than restated, so the two cannot drift. A column gained `enum` and this shape was
- * simply missing it, which is why a hand-written `createTable` could never constrain one. A field
- * added to the node now reaches here, and failing to render it is a compile error rather than a
- * column that quietly loses half its declaration.
- */
+/** A column as the builder describes one: a {@link ColumnNode} without its graph links. */
 export type ColumnDefinition = Omit<ColumnNode, 'table' | 'referencedBy' | 'references'>;
 /**
  * The foreign key a single column declares: {@link ForeignKeySchema} without the local columns, which
@@ -260,13 +253,7 @@ export interface IForeignKeyBuilder extends IColumnBuilder {
     /** Set ON UPDATE action */
     onUpdate(action: ForeignKeyAction): this;
 }
-/**
- * The column vocabulary: every column type the builder can declare, name first.
- *
- * Split out of {@link ITableBuilder} so `addColumn`/`alterColumn` can hand it to their callback. They
- * used to take an {@link IColumnBuilder}, which has no way to say what type a column is - so the
- * builder hard-coded `VARCHAR`, and every column a generated migration added or altered was a string.
- */
+/** Every column type the builder can declare, name first, handed to `addColumn`/`alterColumn` callbacks too. */
 export interface IColumnFactory {
     /** Add an auto-incrementing primary key */
     id(name?: string, options?: BaseColumnOptions): IColumnBuilder;

package/dist/migrate/cli-config.js

@@ -2,17 +2,8 @@ import { stat } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 /**
- * Loads the config with a plain `import()`, leaving TypeScript to whatever runs the CLI.
- *
- * @remarks uql deliberately bundles no transpiler. The config imports the entity classes, so whoever
- * loads it decides which decorator spec their decorators are invoked with, and only the runtime knows
- * the project's `tsconfig.json`. Bun and `node --import tsx` both get it right; a bundled loader would
- * be guessing, and `jiti` guessed wrong (it hardcodes the legacy transform, so standard decorators were
- * called as `(prototype, key)` and every field was silently dropped).
- *
- * Node's own type stripping covers a config that is only types plus a plain object, which is why the
- * error below distinguishes the two cases: decorators are not erasable syntax, so a config that reaches
- * decorated entity classes needs a runtime that actually transforms them.
+ * Loads the config with a plain `import()`, leaving TypeScript to the runtime: uql bundles no transpiler,
+ * since only the project knows its decorator spec. Node's type stripping handles no decorators.
  */
 async function importConfig(path) {
     const mod = (await import(pathToFileURL(path).href).catch((cause) => {

package/dist/migrate/cli.js

@@ -76,11 +76,7 @@ export async function main(args = process.argv.slice(2)) {
                 printHelp();
                 process.exit(1);
         }
-        // Close the connection pool
-        const pool = config.pool;
-        if (pool.end) {
-            await pool.end();
-        }
+        await config.pool.end();
     }
     catch (error) {
         console.error('Error:', error.message);
@@ -202,8 +198,7 @@ export async function runSync(migrator, args, config) {
     const force = args.includes('--force');
     const safe = !args.includes('--unsafe');
     const options = { force, safe, drop: !safe };
-    // Ahead of the warning as well as of the run: `--dry-run` means the same thing whatever else was
-    // asked for, and it used to be ignored beside `--force`.
+    // Ahead of the warning and the run: `--dry-run` means the same whatever else was asked for, `--force` included.
     if (args.includes('--dry-run')) {
         const statements = await migrator.planSync(options);
         console.log(statements.length ? `\n${statements.join('\n')}` : '\nSchema is already in sync.');

package/dist/migrate/codegen/entityCodeGenerator.d.ts

@@ -1,14 +1,3 @@
-/**
- * Entity Code Generator
- *
- * Generates TypeScript entity files from SchemaAST.
- * Supports:
- * - ES Module syntax
- * - TypeScript types
- * - Relations with proper decorators
- * - Indexes
- * - JSDoc comments for sync-added fields
- */
 import type { SchemaAST } from '../../schema/schemaAST.js';
 /**
  * Options for entity code generation.
@@ -107,10 +96,6 @@ export declare class EntityCodeGenerator {
      * Build incoming relation (OneToMany where other tables have FK to this).
      */
     private buildIncomingRelation;
-    /**
-     * Get decorator name for relation type.
-     */
-    private getRelationDecoratorName;
     /**
      * Format type for description.
      */