uql-orm 0.56.0 → 0.57.0

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

@@ -1,16 +1,18 @@
-import type { PgLikeSqlDialect } from '../../dialect/pgLikeSqlDialect.js';
 import type { IndexColumnSchema, IndexSchema } from '../../type/index.js';
 import { IndexDdl } from './indexDdl.js';
 /** `CREATE INDEX ... USING hnsw ("embedding" vector_cosine_ops) WITH (m = ...)`, pgvector's form. */
-export declare class PgIndexDdl extends IndexDdl<PgLikeSqlDialect> {
+export declare class PgIndexDdl extends IndexDdl {
+    /** Postgres 18's `pg_am`, with pgvector's two. */
+    protected readonly indexTypes: Set<"brin" | "btree" | "fulltext" | "gin" | "gist" | "hash" | "hnsw" | "ivfflat" | "vector" | "vectorSearch">;
+    protected readonly indexTypeHints: ReadonlyMap<"brin" | "btree" | "fulltext" | "gin" | "gist" | "hash" | "hnsw" | "ivfflat" | "vector" | "vectorSearch", string>;
     protected readonly indexFeatures: Set<"expression" | "include" | "jsonArray" | "jsonPath" | "nullsOrder" | "opsClass" | "partial" | "prefixLength">;
+    /** The metrics its vector index takes, each naming the operator class it is built with. */
+    protected readonly vectorMetrics: ReadonlyMap<import("../../type/vector.js").VectorDistance, {
+        readonly op: string;
+        readonly opsSuffix: string;
+    }>;
     /** pgvector's own index types; CockroachDB's native one widens this. */
     protected isVectorIndex(index: IndexSchema): boolean;
-    /**
-     * ` USING <method>`. `fulltext` is refused rather than compiled into a ` USING fulltext` the server
-     * can only answer with a syntax error: `$text` computes its `TO_TSVECTOR` per row, which no index
-     * over the raw columns serves.
-     */
     protected indexAccessMethod(index: IndexSchema): string;
     /**
      * A vector index's operator class is named `{type}_{metric}_ops`: an index on a `halfvec` column
@@ -33,9 +35,17 @@ export declare class PgIndexDdl extends IndexDdl<PgLikeSqlDialect> {
  */
 export declare class CockroachIndexDdl extends PgIndexDdl {
     protected readonly indexFeatures: Set<"expression" | "include" | "jsonArray" | "jsonPath" | "nullsOrder" | "opsClass" | "partial" | "prefixLength">;
+    /** v26.3 answers `hash` and `brin` "unimplemented", `ivfflat` "unrecognized"; `hnsw` builds its vector index. */
+    protected readonly indexTypes: Set<"brin" | "btree" | "fulltext" | "gin" | "gist" | "hash" | "hnsw" | "ivfflat" | "vector" | "vectorSearch">;
+    protected readonly indexTypeHints: Map<"brin" | "btree" | "fulltext" | "gin" | "gist" | "hash" | "hnsw" | "ivfflat" | "vector" | "vectorSearch", string>;
+    protected readonly vectorMetrics: ReadonlyMap<import("../../type/vector.js").VectorDistance, {
+        readonly op: string;
+        readonly opsSuffix: string;
+    }>;
     private isNativeVectorIndex;
     protected isVectorIndex(index: IndexSchema): boolean;
     protected indexKeyword(index: IndexSchema): string;
     protected indexAccessMethod(index: IndexSchema): string;
-    protected indexTuning(index: IndexSchema): string;
+    /** None of pgvector's knobs: `WITH (m = 16)` answers "invalid storage parameter", `hnsw` included. */
+    protected indexTuning(): string;
 }

package/dist/migrate/ddl/pgIndexDdl.js

@@ -1,7 +1,23 @@
+import { COCKROACH_VECTOR_METRICS, PG_VECTOR_METRICS } from '../../dialect/pgVectorMetrics.js';
 import { unsupportedVectorMetric } from '../../type/vector.js';
 import { IndexDdl } from './indexDdl.js';
+/** `$text` computes its `TO_TSVECTOR` per row, which no index over the raw columns serves. */
+const PG_INDEX_TYPE_HINTS = new Map([
+    ['fulltext', '. $text needs none there; name the columns it searches with $fields.'],
+]);
 /** `CREATE INDEX ... USING hnsw ("embedding" vector_cosine_ops) WITH (m = ...)`, pgvector's form. */
 export class PgIndexDdl extends IndexDdl {
+    /** Postgres 18's `pg_am`, with pgvector's two. */
+    indexTypes = new Set([
+        'btree',
+        'hash',
+        'gin',
+        'gist',
+        'brin',
+        'hnsw',
+        'ivfflat',
+    ]);
+    indexTypeHints = PG_INDEX_TYPE_HINTS;
     indexFeatures = new Set([
         'expression',
         'partial',
@@ -10,20 +26,13 @@ export class PgIndexDdl extends IndexDdl {
         'include',
         'jsonPath',
     ]);
+    /** The metrics its vector index takes, each naming the operator class it is built with. */
+    vectorMetrics = PG_VECTOR_METRICS;
     /** pgvector's own index types; CockroachDB's native one widens this. */
     isVectorIndex(index) {
         return index.type === 'hnsw' || index.type === 'ivfflat';
     }
-    /**
-     * ` USING <method>`. `fulltext` is refused rather than compiled into a ` USING fulltext` the server
-     * can only answer with a syntax error: `$text` computes its `TO_TSVECTOR` per row, which no index
-     * over the raw columns serves.
-     */
     indexAccessMethod(index) {
-        if (index.type === 'fulltext') {
-            throw new TypeError(`${this.dialect.dialectName} has no fulltext index (index "${index.name}"). $text needs none there; ` +
-                'name the columns it searches with $fields.');
-        }
         return index.type ? ` USING ${index.type}` : '';
     }
     /**
@@ -37,7 +46,7 @@ export class PgIndexDdl extends IndexDdl {
         if (!this.isVectorIndex(index) || !index.distance) {
             return entry.opsClass ? ` ${entry.opsClass}` : '';
         }
-        const metric = this.dialect.vectorMetrics.get(index.distance);
+        const metric = this.vectorMetrics.get(index.distance);
         if (!metric) {
             throw unsupportedVectorMetric(this.dialect.dialectName, index.distance, index.name);
         }
@@ -78,6 +87,13 @@ export class PgIndexDdl extends IndexDdl {
  */
 export class CockroachIndexDdl extends PgIndexDdl {
     indexFeatures = new Set(['expression', 'partial', 'include', 'jsonPath']);
+    /** v26.3 answers `hash` and `brin` "unimplemented", `ivfflat` "unrecognized"; `hnsw` builds its vector index. */
+    indexTypes = new Set(['btree', 'gin', 'gist', 'hnsw', 'vector']);
+    indexTypeHints = new Map([
+        ...PG_INDEX_TYPE_HINTS,
+        ['ivfflat', "; declare type: 'vector' instead"],
+    ]);
+    vectorMetrics = COCKROACH_VECTOR_METRICS;
     isNativeVectorIndex(index) {
         return index.type === 'vector';
     }
@@ -90,7 +106,8 @@ export class CockroachIndexDdl extends PgIndexDdl {
     indexAccessMethod(index) {
         return this.isNativeVectorIndex(index) ? '' : super.indexAccessMethod(index);
     }
-    indexTuning(index) {
-        return this.isNativeVectorIndex(index) ? '' : super.indexTuning(index);
+    /** None of pgvector's knobs: `WITH (m = 16)` answers "invalid storage parameter", `hnsw` included. */
+    indexTuning() {
+        return '';
     }
 }

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,7 +18,7 @@ export declare class Migrator {
     schemaIntrospector?: SchemaIntrospector;
     private readonly _defaultForeignKeyAction?;
     private _mongoSchemaLoadPromise?;
-    constructor(pool: QuerierPool, options?: MigratorOptions);
+    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}).

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';
@@ -543,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;
     }
@@ -726,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.