uql-orm 0.55.0 → 0.57.0

package/dist/migrate/introspection/mysqlIntrospector.js

@@ -24,11 +24,8 @@ export class MysqlSchemaIntrospector extends AbstractSqlSchemaIntrospector {
     `;
     }
     parseTableExistsResult(results) {
-        const row = results[0];
-        if (row?.count !== undefined) {
-            return (this.toNumber(row.count) ?? 0) > 0;
-        }
-        return false;
+        // No row, or no count in it, reads as `NaN`, which is not above zero.
+        return Number(results[0]?.count) > 0;
     }
     getColumnsQuery(_tableName) {
         return /*sql*/ `
@@ -97,7 +94,7 @@ export class MysqlSchemaIntrospector extends AbstractSqlSchemaIntrospector {
     async mapColumnsResult(_read, _tableName, results) {
         return results.map((row) => ({
             name: row.column_name,
-            type: (row.column_type || '').toUpperCase(),
+            type: row.column_type.toUpperCase(),
             nullable: row.is_nullable === 'YES',
             defaultValue: this.parseDefaultValue(row.column_default),
             isPrimaryKey: row.column_key === 'PRI',
@@ -122,8 +119,8 @@ export class MysqlSchemaIntrospector extends AbstractSqlSchemaIntrospector {
     async mapForeignKeysResult(_read, _tableName, results) {
         return results.map((row) => ({
             name: row.constraint_name,
-            columns: (row.columns || '').split(','),
-            references: { table: row.referenced_table, columns: (row.referenced_columns || '').split(',') },
+            columns: row.columns.split(','),
+            references: { table: row.referenced_table, columns: row.referenced_columns.split(',') },
             onDelete: this.normalizeReferentialAction(row.delete_rule),
             onUpdate: this.normalizeReferentialAction(row.update_rule),
         }));

package/dist/migrate/introspection/sqliteIntrospector.js

@@ -22,11 +22,8 @@ export class SqliteSchemaIntrospector extends AbstractSqlSchemaIntrospector {
     `;
     }
     parseTableExistsResult(results) {
-        const row = results[0];
-        if (row?.count !== undefined) {
-            return (this.toNumber(row.count) ?? 0) > 0;
-        }
-        return false;
+        // No row, or no count in it, reads as `NaN`, which is not above zero.
+        return Number(results[0]?.count) > 0;
     }
     /**
      * `table_xinfo`, not `table_info`: the latter omits generated columns entirely, so a table carrying

package/dist/migrate/migrator.d.ts

@@ -1,4 +1,4 @@
-import type { DialectName, LoggingOptions, Migration, MigrationDefinition, MigrationResult, MigrationStorage, MigratorOptions, MongoQuerier, Querier, QuerierPool, SchemaDiff, SchemaGenerator, SchemaIntrospector, SyncOptions, Type } from '../type/index.js';
+import type { DialectName, LoggingOptions, Migration, MigrationDefinition, MigrationResult, MigrationStorage, MigratorDialect, MigratorOptions, MongoQuerier, Querier, QuerierPool, SchemaDiff, SchemaGenerator, SchemaIntrospector, SyncOptions, Type } from '../type/index.js';
 import { LoggerWrapper } from '../util/index.js';
 import type { IMigrationBuilder } from './builder/types.js';
 /**
@@ -18,9 +18,12 @@ export declare class Migrator {
     schemaIntrospector?: SchemaIntrospector;
     private readonly _defaultForeignKeyAction?;
     private _mongoSchemaLoadPromise?;
-    constructor(pool: QuerierPool, options?: MigratorOptions);
-    /** Loads MongoDB schema generator on first use; SQL generators are set in the constructor (or via {@link setSchemaGenerator}). */
-    private ensureSchemaGenerator;
+    constructor(pool: QuerierPool<Querier, MigratorDialect>, options?: MigratorOptions);
+    /**
+     * Loads MongoDB's schema generator on first use, so the optional `mongodb` peer loads only then. SQL
+     * generators are set in the constructor (or via {@link setSchemaGenerator}).
+     */
+    ensureSchemaGenerator(): Promise<void>;
     /**
      * Set the schema generator for DDL operations
      */

package/dist/migrate/migrator.js

@@ -10,7 +10,6 @@ import { buildSqlQuerierMigrationModule, EMPTY_MANUAL_MIGRATION_DOWN_INNER, EMPT
 import { runMongoCommand } from './generator/mongoCommand.js';
 import { introspectorFor } from './introspection/registry.js';
 import { createSchemaGenerator } from './schemaGenerator.js';
-import { createSchemaGeneratorAsync } from './schemaGeneratorAsync.js';
 import { DatabaseMigrationStorage } from './storage/databaseStorage.js';
 /**
  * Main class for managing database migrations
@@ -37,7 +36,7 @@ export class Migrator {
     _mongoSchemaLoadPromise;
     constructor(pool, options = {}) {
         this.pool = pool;
-        this.dialectName = pool.dialect.dialectName ?? 'postgres';
+        this.dialectName = pool.dialect.dialectName;
         this._defaultForeignKeyAction = options.defaultForeignKeyAction;
         this.storage =
             options.storage ??
@@ -51,18 +50,17 @@ export class Migrator {
         this.schemaGenerator =
             options.schemaGenerator ?? (this.dialectName === 'mongodb' ? undefined : this.createGenerator());
     }
-    /** Loads MongoDB schema generator on first use; SQL generators are set in the constructor (or via {@link setSchemaGenerator}). */
+    /**
+     * Loads MongoDB's schema generator on first use, so the optional `mongodb` peer loads only then. SQL
+     * generators are set in the constructor (or via {@link setSchemaGenerator}).
+     */
     async ensureSchemaGenerator() {
         if (this.schemaGenerator || this.dialectName !== 'mongodb') {
             return;
         }
-        if (!this._mongoSchemaLoadPromise) {
-            this._mongoSchemaLoadPromise = createSchemaGeneratorAsync(this.pool.dialect, this._defaultForeignKeyAction).then((gen) => {
-                if (gen) {
-                    this.schemaGenerator = gen;
-                }
-            });
-        }
+        this._mongoSchemaLoadPromise ??= import('./generator/mongoSchemaGenerator.js').then(({ MongoSchemaGenerator }) => {
+            this.schemaGenerator = new MongoSchemaGenerator(this.pool.dialect.namingStrategy, this._defaultForeignKeyAction);
+        });
         await this._mongoSchemaLoadPromise;
     }
     /**
@@ -302,12 +300,9 @@ export class Migrator {
     }
     async findEntityForTable(tableName) {
         await this.ensureSchemaGenerator();
-        if (!this.schemaGenerator) {
-            return undefined;
-        }
         for (const entity of this.entities) {
             const meta = getMeta(entity);
-            const name = this.schemaGenerator.resolveTableName(meta);
+            const name = this.generator.resolveTableName(meta);
             if (name === tableName) {
                 return entity;
             }

package/dist/migrate/schemaGenerator.d.ts

@@ -1,8 +1,8 @@
-import { type AbstractDialect, AbstractSqlDialect } from '../dialect/index.js';
+import type { AbstractSqlDialect } from '../dialect/index.js';
 import type { SchemaAST } from '../schema/schemaAST.js';
 import { type DiffOptions } from '../schema/schemaASTDiffer.js';
 import type { CanonicalType, ColumnNode, ForeignKeyAction, IndexNode, TableNode } from '../schema/types.js';
-import type { ColumnSchema, CreateSchemaOptions, DialectFeatures, DropSchemaOptions, EntityMeta, FieldMeta, FieldOptions, ForeignKeySchema, IndexSchema, NamingStrategy, SchemaDiff, SchemaGenerator, SqlDdlGenerator, Type } from '../type/index.js';
+import type { ColumnSchema, CreateSchemaOptions, DialectFeatures, DropSchemaOptions, EntityMeta, FieldMeta, FieldOptions, ForeignKeySchema, IndexSchema, MigratorDialect, NamingStrategy, SchemaDiff, SchemaGenerator, SqlDdlGenerator, Type } from '../type/index.js';
 import type { FullColumnDefinition, TableDefinition } from './builder/types.js';
 import { type IndexDdl, type TableDdl } from './ddl/index.js';
 /**
@@ -222,4 +222,4 @@ export declare function buildEntityAST(generator: Pick<SchemaGenerator, 'resolve
  * Synchronous factory for SQL schema generators only.
  * For MongoDB, use `createSchemaGeneratorAsync` from `./schemaGeneratorAsync.js` so the optional `mongodb` peer is not loaded at import time.
  */
-export declare function createSchemaGenerator(dialect: AbstractDialect, defaultForeignKeyAction?: ForeignKeyAction): SqlSchemaGenerator | undefined;
+export declare function createSchemaGenerator(dialect: MigratorDialect, defaultForeignKeyAction?: ForeignKeyAction): SqlSchemaGenerator | undefined;

package/dist/migrate/schemaGenerator.js

@@ -1,6 +1,5 @@
-import { AbstractSqlDialect } from '../dialect/index.js';
 import { getMeta, soleIdOf } from '../entity/index.js';
-import { areTypesEqual, canonicalToSql, engineType, fieldOptionsToCanonical, isVectorCategory, } from '../schema/canonicalType.js';
+import { canonicalToSql, engineType, fieldOptionsToCanonical, isVectorCategory } from '../schema/canonicalType.js';
 import { indexSignature } from '../schema/indexDifferences.js';
 import { buildSchemaAST } from '../schema/schemaASTBuilder.js';
 import { diffRelationshipNodes, diffTable } from '../schema/schemaASTDiffer.js';
@@ -474,8 +473,6 @@ export class SqlSchemaGenerator {
         if (current == null || desired == null)
             return current == null && desired == null;
         const normalize = (value) => {
-            if (value === null)
-                return 'null';
             // Render first: the desired side may be a symbolic expression, the current side is always the
             // engine's own text, and `{"kind":"now"}` matches no spelling of `CURRENT_TIMESTAMP`.
             const val = SqlExpression.isExpression(value) ? formatDefaultValue(value, this.dialect) : value;
@@ -518,10 +515,8 @@ export class SqlSchemaGenerator {
             constraints.push(`CONSTRAINT ${this.escapeId(name)} CHECK (${check.expression})`);
         });
         for (const rel of table.outgoingRelations) {
-            if (rel.from.columns.length > 0) {
-                const refTable = this.dialect.escapeQualifiedId(rel.to.table.name, rel.to.table.schema);
-                constraints.push(this.foreignKeyConstraint(table.name, foreignKeyOf(rel), refTable));
-            }
+            const refTable = this.dialect.escapeQualifiedId(rel.to.table.name, rel.to.table.schema);
+            constraints.push(this.foreignKeyConstraint(table.name, foreignKeyOf(rel), refTable));
         }
         const ifNotExists = options.ifNotExists && this.features.ifNotExists ? 'IF NOT EXISTS ' : '';
         let createSql = `CREATE TABLE ${ifNotExists}${this.dialect.escapeQualifiedId(table.name, table.schema)} (\n`;
@@ -547,8 +542,10 @@ export class SqlSchemaGenerator {
         }
         statements.push(createSql);
         statements.push(...this.generateCommentStatements(table));
+        // A table created only if missing creates its indexes the same way, or re-creating a schema fails on the first.
+        const indexOptions = { ifNotExists: !!options.ifNotExists && this.features.indexIfNotExists };
         for (const idx of table.indexes) {
-            statements.push(this.generateCreateIndexFromNode(idx));
+            statements.push(this.generateCreateIndexFromNode(idx, indexOptions));
         }
         return statements;
     }
@@ -730,8 +727,5 @@ export function buildEntityAST(generator, entities, defaultForeignKeyAction) {
  * For MongoDB, use `createSchemaGeneratorAsync` from `./schemaGeneratorAsync.js` so the optional `mongodb` peer is not loaded at import time.
  */
 export function createSchemaGenerator(dialect, defaultForeignKeyAction) {
-    if (!(dialect instanceof AbstractSqlDialect)) {
-        return undefined;
-    }
-    return new SqlSchemaGenerator(dialect, defaultForeignKeyAction);
+    return dialect.dialectName === 'mongodb' ? undefined : new SqlSchemaGenerator(dialect, defaultForeignKeyAction);
 }

package/dist/migrate/schemaGeneratorAsync.d.ts

@@ -1,8 +1,7 @@
-import type { AbstractDialect } from '../dialect/abstractDialect.js';
 import type { ForeignKeyAction } from '../schema/types.js';
-import type { SchemaGenerator } from '../type/index.js';
+import type { MigratorDialect, SchemaGenerator } from '../type/index.js';
 /**
  * Async factory for schema generators. Use this for MongoDB so the optional peer
  * `mongodb` is only loaded when this path runs. SQL dialects delegate to {@link createSchemaGenerator}.
  */
-export declare function createSchemaGeneratorAsync(dialect: AbstractDialect, defaultForeignKeyAction?: ForeignKeyAction): Promise<SchemaGenerator | undefined>;
+export declare function createSchemaGeneratorAsync(dialect: MigratorDialect, defaultForeignKeyAction?: ForeignKeyAction): Promise<SchemaGenerator | undefined>;

package/dist/mongo/mongoDialect.d.ts

@@ -65,16 +65,18 @@ export declare class MongoDialect extends AbstractDialect {
      */
     private appendRelationLookup;
     /**
-     * The correlated `$lookup` for one relation, as `temp`: through its junction for a ManyToMany, or
-     * straight at the target otherwise. `tail` decides what the lookup leaves behind - a row to test
-     * for existence, or a `$count` - so a filter and an ordering build the same stage.
+     * The correlated `$lookup` for the target rows of one relation `where` narrows, as `temp`: straight at
+     * the target, or for a many-to-many from inside its junction's rows. The caller's filter bypass is not
+     * passed down, as on the SQL dialects. `tail` decides what the lookup leaves behind - a row to test for
+     * existence, or a `$count` - so a filter and an ordering build the same stage.
      */
     private relationLookup;
     /**
-     * ManyToMany counts/tests junction rows, so the target is reached from inside the junction's own
-     * lookup - the junction's filters apply too, since a soft-deleted link is not a link.
+     * The junction a many-to-many reaches its targets through: the lookup keys matching a parent's rows of
+     * it, its own filters, since a soft-deleted link is not a link, and the field holding each target's id.
+     * Each end is one field matched against one `_id`, so both sides must be sole-keyed.
      */
-    private junctionLookup;
+    private junctionOf;
     /**
      * Compares the looked-up row count, which is `[{ n: <count> }]` or `[]` when nothing matched - hence
      * the `$ifNull` fallback to 0, so `{ $size: 0 }` matches parents with no related row at all.
@@ -99,7 +101,7 @@ export declare class MongoDialect extends AbstractDialect {
     protected mapTableNameRow(row: {
         table_name: string;
     }): string;
-    /** String operators → { pattern: (v) => regex, caseInsensitive } */
+    /** String operators -> { pattern: (v) => regex, caseInsensitive } */
     private static readonly REGEX_OP_MAP;
     /** MongoDB native operators - pass through as-is. */
     private static readonly NATIVE_OPS;
@@ -127,10 +129,26 @@ export declare class MongoDialect extends AbstractDialect {
      * per parent, and the `$set` that lifts the tally onto the document as the field the `$sort` then
      * orders by. A parent with no related row gets no lookup result at all, which is a zero.
      */
-    sortCountStages<E extends Document>(entity: Type<E>, sort: QuerySortMap<E> | undefined, opts?: QueryOptions): {
+    sortCountStages<E extends Document>(entity: Type<E>, sort: QuerySortMap<E> | undefined): {
         readonly stages: MongoAggregationPipelineEntry<Document>[];
         readonly fields: string[];
     };
+    /** The correlated lookup counting a relation's rows, which `where` narrows, into `temp`. */
+    private tallyLookup;
+    /** The tally a lookup left in `temp`, which holds no row at all where nothing matched: a zero. */
+    private tally;
+    /**
+     * The lookups reading each to-many a query populates, and the tally of each `$count`, onto the fields
+     * its rows answer under, and the fields they parked a junction's pairings or a tally on taken back out.
+     * [The design](../../../../architecture/relations-in-one-statement.md).
+     */
+    private relationReadStages;
+    /**
+     * A to-many's rows as a lookup running their own read, whose filters, ordering and page apply per
+     * parent inside it. A many-to-many reads its targets, each once, by the ids its junction pairs the
+     * parent with, parked in a temporary field of the parent's.
+     */
+    private toManyLookup;
     /** Whether a `$sort` reads a relation, which is what forces the lookups to run before it. */
     sortsRelations<E extends Document>(entity: Type<E>, sort: QuerySortMap<E> | undefined): boolean;
     /**
@@ -152,7 +170,7 @@ export declare class MongoDialect extends AbstractDialect {
      * Shared by the plain pipeline and the `$vectorSearch` one, which each used to spell the order out
      * for themselves and each got a different part of it wrong.
      */
-    readStages<E extends Document>(entity: Type<E>, q: Query<E>, opts?: QueryOptions, extra?: MongoReadStages): MongoAggregationPipelineEntry<Document>[];
+    readStages<E extends Document>(entity: Type<E>, q: Query<E>, extra?: MongoReadStages): MongoAggregationPipelineEntry<Document>[];
     /**
      * `$distinct` as a `$group` on the columns the query projects - the same set a SQL dialect puts
      * after `SELECT DISTINCT` - and the `$replaceRoot` that lifts the grouped key back to the top
@@ -162,16 +180,11 @@ export declare class MongoDialect extends AbstractDialect {
     private distinctStages;
     /**
      * The scalar projection a narrowing query asks for, widened by what the pipeline itself produced:
-     * the joined documents, and the `_id` a to-many fill groups children by. It goes last, after the
-     * lookups have read the join keys - projecting any earlier is what used to leave `$populate`
-     * empty, and is why the pipeline emitted no projection at all and returned every column.
+     * each populated relation and the tallies. It goes last, after the lookups have read the join keys -
+     * projecting any earlier is what used to leave `$populate` empty, and is why the pipeline emitted no
+     * projection at all and returned every column.
      */
     pipelineProjection<E extends Document>(entity: Type<E>, q: Query<E>): Record<string, 0 | 1> | undefined;
-    /**
-     * `$lookup`/`$unwind` stages for the joinable relations a query populates. Shared by the plain
-     * aggregation pipeline and the `$vectorSearch` one, so relations load the same way in both.
-     */
-    relationStages<E extends Document>(entity: Type<E>, q: Query<E>, opts?: QueryOptions): MongoAggregationPipelineEntry<E>[];
     /**
      * The `$lookup`/`$unwind` pair for each relation joined below `parent`, its own relations nested
      * inside its pipeline and resolved before the projection that reads them.
@@ -187,7 +200,7 @@ export declare class MongoDialect extends AbstractDialect {
     /** `[column, key]` for the fields whose stored name differs from their property name, memoized per entity. */
     private renamedColumns;
     private referenceKeys;
-    normalizeIds<E extends Document>(meta: EntityMeta<E>, docs: Document[] | undefined): E[] | undefined;
+    normalizeIds<E extends Document>(meta: EntityMeta<E>, docs: Document[]): E[];
     /** `doc` is the wire shape - `_id`, stored names, `ObjectId`s - and what comes back is the code's. */
     normalizeId<E extends Document>(meta: EntityMeta<E>, doc: Document | undefined): E | undefined;
     /**