uql-orm 0.66.0 → 0.67.0

package/dist/migrate/schemaGenerator.d.ts

@@ -28,35 +28,18 @@ export declare class SqlSchemaGenerator implements SchemaGenerator {
     /** Escape an identifier (table name, column name, etc.) */
     protected escapeId(identifier: string): string;
     /**
-     * How an auto-increment key of `type` is spelled: the type as any other column renders it, plus what
-     * the engine appends to make it generated.
-     *
-     * Derived rather than a fixed string per dialect, because a foreign key column takes its type from
-     * the key it points at, resolved through the same canonical type. A key whose spelling ignored that
-     * type could never be referenced: `@Id({ columnType: 'int' })` emitted `BIGINT` while the column
-     * pointing at it emitted `INT`, and every engine refuses that constraint.
+     * An auto-increment key's type: its canonical type rendered like any column's, plus the engine's generated
+     * suffix, so a foreign key taking its type from this key gets the same one.
      */
     protected serialType(type: CanonicalType): string;
-    /**
-     * The SQL type a column is spelled with: the engine's generated-key form for an auto-increment key,
-     * the canonical type otherwise.
-     *
-     * One method because both paths that spell a column need the same answer - written twice, with a
-     * comment asking the two to stay in sync, is how the generated key and the column referencing it
-     * came to disagree in the first place.
-     */
+    /** The SQL type a column is spelled with: the generated-key form for an auto-increment key, the canonical type otherwise. */
     protected columnSqlType(col: ColumnNode): string;
     protected canonicalTypeToSql(type: CanonicalType): string;
     /** The entity side as an AST, carrying this generator's default referential action. */
     buildAST(entities: readonly Type<object>[]): SchemaAST;
     /**
-     * Every `CREATE TABLE` for `entities`, then their foreign keys.
-     *
-     * Two phases rather than inline constraints, because a relation graph is routinely cyclic: any
-     * `createdBy`-style back-reference makes `A` reference `B` while `B` references `A`, and no create
-     * order satisfies that. TypeORM's schema builder splits for the same reason (`createNewTables()`
-     * then `createForeignKeys()`). SQLite is the exception and keeps them inline: it cannot `ALTER` a
-     * foreign key in, but it resolves targets lazily, so a forward reference is fine there.
+     * Every `CREATE TABLE` for `entities`, then their foreign keys, since a relation graph is routinely
+     * cyclic. SQLite keeps them inline: it cannot add one later, and resolves a forward reference lazily.
      */
     generateCreateSchema(entities: readonly Type<object>[], options?: CreateSchemaOptions): string[];
     /**
@@ -88,13 +71,8 @@ export declare class SqlSchemaGenerator implements SchemaGenerator {
      */
     generateDropIndex(tableName: string, indexName: string, schema?: string): string;
     /**
-     * A column definition from a {@link ColumnSchema}, whose type is already the engine's own spelling
-     * and may carry its own size.
-     *
-     * Kept apart from {@link generateColumnFromNode} rather than folded into it: a `ColumnSchema` has no
-     * `enum`, because introspection reads one back as a `CHECK` constraint and not as a property of the
-     * column, so only the node knows enough to emit that clause. Both spell the definition through
-     * {@link renderColumn}, which is the part that must not be written twice.
+     * A column definition from a {@link ColumnSchema}, whose type is already the engine's spelling. Apart from
+     * {@link generateColumnFromNode}, which alone knows an `enum`; both render through {@link renderColumn}.
      */
     generateColumnDefinitionFromSchema(column: ColumnSchema): string;
     /**
@@ -113,30 +91,16 @@ export declare class SqlSchemaGenerator implements SchemaGenerator {
     generateAlterColumnStatements(tableName: string, column: ColumnSchema, newDefinition: string): string[];
     /** The inline ` COMMENT '...'` a column declaration carries, where the engine takes one there. */
     generateColumnComment(comment: string): string;
-    /**
-     * The `COMMENT ON` statements a table and its columns need, on an engine that carries a comment
-     * that way. Empty on the others: MySQL writes them inline, SQLite has no comments at all.
-     *
-     * Emitted after the `CREATE TABLE` rather than folded into it, which is what `COMMENT ON` requires -
-     * and what makes a comment reach Postgres, where it was previously read as unsupported and dropped.
-     */
+    /** The `COMMENT ON` statements a table and its columns need, after the `CREATE TABLE`, where the engine uses them. */
     protected generateCommentStatements(table: TableNode): string[];
-    /**
-     * The `COMMENT ON COLUMN` one column needs, on an engine that carries a comment that way.
-     *
-     * Shared by `CREATE TABLE` and every path that adds a column: written only for the former, a column
-     * added later reached the database undocumented, the way its enum `CHECK` used to.
-     */
+    /** The `COMMENT ON COLUMN` a column needs where the engine uses one, for `CREATE TABLE` and every path adding a column. */
     protected generateColumnCommentStatement(tableName: string, column: {
         name: string;
         comment?: string;
     }, schema?: string): string[];
     /**
-     * How this entity differs from the table the database reported, as the migrator's `SchemaDiff`.
-     *
-     * The comparison itself is {@link diffTable}, the same one drift detection runs, so the two can no
-     * longer disagree about what has changed. Only two things are this side's own: the entity becomes a
-     * table node first, and types are compared as the *engine* would store them - see `normalizeType`.
+     * How the entity differs from the table the database reported, compared by {@link diffTable}, the one
+     * drift detection runs, with types normalized as the engine stores them.
      */
     diffSchema(entity: Type<object>, currentTable: TableNode | undefined, desiredAst?: SchemaAST): SchemaDiff | undefined;
     /**
@@ -175,13 +139,7 @@ export declare class SqlSchemaGenerator implements SchemaGenerator {
     generateRenameTableSql(oldName: string, newName: string): string;
     /** `raw` is split, being the one SQL no generator wrote. */
     generateOperation(operation: AnyMigrationOperation): string[];
-    /**
-     * `ADD COLUMN`, plus the constraint and index the column declares.
-     *
-     * `CREATE TABLE` lifts a column's `references` and `index` onto the table it is building; this had
-     * no lift, so a hand-written `addColumn(...).references(...).index()` emitted the column alone and
-     * dropped both without a word.
-     */
+    /** `ADD COLUMN`, plus the foreign key and index the column declares, as `CREATE TABLE` lifts them. */
     generateAddColumnSql(tableName: string, column: FullColumnDefinition): string[];
     generateAlterColumnSql(tableName: string, columnName: string, column: FullColumnDefinition): string[];
     generateDropColumnSql(tableName: string, columnName: string): string[];
@@ -202,12 +160,8 @@ export declare class SqlSchemaGenerator implements SchemaGenerator {
      */
     generateAddPrimaryKeySql(tableName: string, columns: readonly string[], name?: string): string;
     /**
-     * Drops whatever key the table has.
-     *
-     * `constraintName` has to be what the constraint is *actually* called: the name introspection
-     * reported for a key the database already had, or the derived one for a key this generator itself
-     * added, which is what reversing a migration drops. Guessing either way names nothing. MySQL takes
-     * no name at all - a table's key is always `PRIMARY` there.
+     * Drops the table's key, by the name the constraint really has: introspected, or derived where this
+     * generator added it. MySQL takes no name.
      */
     generateDropPrimaryKeySql(tableName: string, constraintName?: string): string;
     /**
@@ -218,11 +172,7 @@ export declare class SqlSchemaGenerator implements SchemaGenerator {
     private assertPrimaryKeyAlterable;
 }
 /**
- * The entities as an AST, named the way `generator` names things.
- *
- * Its resolvers rather than a naming strategy, because the two disagree: a strategy renames whatever
- * it is handed, while a generator leaves an explicit `@Entity({ name })` alone. Build the AST the
- * other way and the table is created under one name and compared under another, which reports every
- * table of a project using a naming strategy as both missing and unexpected.
+ * The entities as an AST, named by `generator`'s resolvers rather than a naming strategy, which would
+ * also rename an explicit `@Entity({ name })` and so compare each table under another name.
  */
 export declare function buildEntityAST(generator: Pick<SchemaGenerator, 'resolveTableAlias' | 'resolveSchema' | 'resolveColumnName' | 'compileDdl' | 'compileIndexPredicate'>, entities: readonly Type<object>[], defaultForeignKeyAction?: ForeignKeyAction): SchemaAST;

package/dist/migrate/schemaGenerator.js

@@ -59,25 +59,13 @@ export class SqlSchemaGenerator {
         return this.dialect.escapeId(identifier);
     }
     /**
-     * How an auto-increment key of `type` is spelled: the type as any other column renders it, plus what
-     * the engine appends to make it generated.
-     *
-     * Derived rather than a fixed string per dialect, because a foreign key column takes its type from
-     * the key it points at, resolved through the same canonical type. A key whose spelling ignored that
-     * type could never be referenced: `@Id({ columnType: 'int' })` emitted `BIGINT` while the column
-     * pointing at it emitted `INT`, and every engine refuses that constraint.
+     * An auto-increment key's type: its canonical type rendered like any column's, plus the engine's generated
+     * suffix, so a foreign key taking its type from this key gets the same one.
      */
     serialType(type) {
         return `${this.canonicalTypeToSql(type)} ${this.dialect.autoIncrementSuffix}`;
     }
-    /**
-     * The SQL type a column is spelled with: the engine's generated-key form for an auto-increment key,
-     * the canonical type otherwise.
-     *
-     * One method because both paths that spell a column need the same answer - written twice, with a
-     * comment asking the two to stay in sync, is how the generated key and the column referencing it
-     * came to disagree in the first place.
-     */
+    /** The SQL type a column is spelled with: the generated-key form for an auto-increment key, the canonical type otherwise. */
     columnSqlType(col) {
         return col.isPrimaryKey && col.isAutoIncrement ? this.serialType(col.type) : this.canonicalTypeToSql(col.type);
     }
@@ -89,13 +77,8 @@ export class SqlSchemaGenerator {
         return buildEntityAST(this, entities, this.defaultForeignKeyAction);
     }
     /**
-     * Every `CREATE TABLE` for `entities`, then their foreign keys.
-     *
-     * Two phases rather than inline constraints, because a relation graph is routinely cyclic: any
-     * `createdBy`-style back-reference makes `A` reference `B` while `B` references `A`, and no create
-     * order satisfies that. TypeORM's schema builder splits for the same reason (`createNewTables()`
-     * then `createForeignKeys()`). SQLite is the exception and keeps them inline: it cannot `ALTER` a
-     * foreign key in, but it resolves targets lazily, so a forward reference is fine there.
+     * Every `CREATE TABLE` for `entities`, then their foreign keys, since a relation graph is routinely
+     * cyclic. SQLite keeps them inline: it cannot add one later, and resolves a forward reference lazily.
      */
     generateCreateSchema(entities, options = {}) {
         const tables = this.orderedTables(entities, 'create', options.only);
@@ -271,13 +254,8 @@ export class SqlSchemaGenerator {
         return `DROP INDEX IF EXISTS ${this.dialect.escapeQualifiedId(indexName, schema)};`;
     }
     /**
-     * A column definition from a {@link ColumnSchema}, whose type is already the engine's own spelling
-     * and may carry its own size.
-     *
-     * Kept apart from {@link generateColumnFromNode} rather than folded into it: a `ColumnSchema` has no
-     * `enum`, because introspection reads one back as a `CHECK` constraint and not as a property of the
-     * column, so only the node knows enough to emit that clause. Both spell the definition through
-     * {@link renderColumn}, which is the part that must not be written twice.
+     * A column definition from a {@link ColumnSchema}, whose type is already the engine's spelling. Apart from
+     * {@link generateColumnFromNode}, which alone knows an `enum`; both render through {@link renderColumn}.
      */
     generateColumnDefinitionFromSchema(column) {
         return this.renderColumn({ ...column, type: sizedType(column) });
@@ -327,13 +305,7 @@ export class SqlSchemaGenerator {
     generateColumnComment(comment) {
         return this.features.commentSyntax === 'inline' ? ` COMMENT ${this.dialect.escape(comment)}` : '';
     }
-    /**
-     * The `COMMENT ON` statements a table and its columns need, on an engine that carries a comment
-     * that way. Empty on the others: MySQL writes them inline, SQLite has no comments at all.
-     *
-     * Emitted after the `CREATE TABLE` rather than folded into it, which is what `COMMENT ON` requires -
-     * and what makes a comment reach Postgres, where it was previously read as unsupported and dropped.
-     */
+    /** The `COMMENT ON` statements a table and its columns need, after the `CREATE TABLE`, where the engine uses them. */
     generateCommentStatements(table) {
         if (this.features.commentSyntax !== 'statement') {
             return [];
@@ -345,12 +317,7 @@ export class SqlSchemaGenerator {
         }
         return statements;
     }
-    /**
-     * The `COMMENT ON COLUMN` one column needs, on an engine that carries a comment that way.
-     *
-     * Shared by `CREATE TABLE` and every path that adds a column: written only for the former, a column
-     * added later reached the database undocumented, the way its enum `CHECK` used to.
-     */
+    /** The `COMMENT ON COLUMN` a column needs where the engine uses one, for `CREATE TABLE` and every path adding a column. */
     generateColumnCommentStatement(tableName, column, schema) {
         if (!column.comment || this.features.commentSyntax !== 'statement') {
             return [];
@@ -359,11 +326,8 @@ export class SqlSchemaGenerator {
         return [`COMMENT ON COLUMN ${tableRef}.${this.escapeId(column.name)} IS ${this.dialect.escape(column.comment)};`];
     }
     /**
-     * How this entity differs from the table the database reported, as the migrator's `SchemaDiff`.
-     *
-     * The comparison itself is {@link diffTable}, the same one drift detection runs, so the two can no
-     * longer disagree about what has changed. Only two things are this side's own: the entity becomes a
-     * table node first, and types are compared as the *engine* would store them - see `normalizeType`.
+     * How the entity differs from the table the database reported, compared by {@link diffTable}, the one
+     * drift detection runs, with types normalized as the engine stores them.
      */
     diffSchema(entity, currentTable, desiredAst) {
         const meta = getMeta(entity);
@@ -404,13 +368,8 @@ export class SqlSchemaGenerator {
             to: tableDiff.primaryKeyDiff.expected,
             fromName: tableDiff.primaryKeyDiff.actualName,
         };
-        // This table's own constraints, which is what `outgoingRelations` holds on both sides: the
-        // entity's as the AST derived them, the database's as the introspector read them back.
-        //
-        // None at all where the engine cannot alter one: SQLite resolves foreign keys lazily and keeps
-        // them inline at CREATE time, and its only way to change one afterwards is the twelve-step table
-        // rebuild, which a sync does not do. Reporting a difference nothing can apply would throw on
-        // every sync of an entity that has a relation. `drift:check` still names it.
+        // This table's own foreign keys. None where the engine cannot alter one (SQLite, short of rebuilding
+        // the table), since a difference nothing can apply would throw on every sync; `drift:check` names it.
         const relationDiffs = this.features.foreignKeyAlter
             ? diffRelationshipNodes(desired.outgoingRelations, currentTable.outgoingRelations, this.diffOptions())
             : [];
@@ -504,7 +463,9 @@ export class SqlSchemaGenerator {
         // later `DROP` has something to name. The exception is a dialect whose serial type states the key
         // itself (SQLite's `INTEGER PRIMARY KEY AUTOINCREMENT`, which cannot be split): there the column
         // has already declared it, and saying it again is a second primary key.
-        const declaredByColumn = this.dialect.serialDeclaresPrimaryKey && table.primaryKey.length === 1 && table.primaryKey[0].isAutoIncrement;
+        const declaredByColumn = this.dialect.features.serialDeclaresPrimaryKey &&
+            table.primaryKey.length === 1 &&
+            table.primaryKey[0].isAutoIncrement;
         if (table.primaryKey.length && !declaredByColumn) {
             const pkColumns = table.primaryKey.map((c) => c.name);
             const pkName = table.primaryKeyName ?? derivedPrimaryKeyName(table.name, pkColumns);
@@ -606,13 +567,7 @@ export class SqlSchemaGenerator {
                 return splitSqlStatements(operation.sql);
         }
     }
-    /**
-     * `ADD COLUMN`, plus the constraint and index the column declares.
-     *
-     * `CREATE TABLE` lifts a column's `references` and `index` onto the table it is building; this had
-     * no lift, so a hand-written `addColumn(...).references(...).index()` emitted the column alone and
-     * dropped both without a word.
-     */
+    /** `ADD COLUMN`, plus the foreign key and index the column declares, as `CREATE TABLE` lifts them. */
     generateAddColumnSql(tableName, column) {
         this.assertColumnAddable(tableName, column);
         const colSql = this.generateColumnFromNode(fullColumnDefinitionToNode(column, tableName));
@@ -674,12 +629,8 @@ export class SqlSchemaGenerator {
         return `ALTER TABLE ${this.escapeId(tableName)} ADD CONSTRAINT ${constraintName} PRIMARY KEY (${pkCols});`;
     }
     /**
-     * Drops whatever key the table has.
-     *
-     * `constraintName` has to be what the constraint is *actually* called: the name introspection
-     * reported for a key the database already had, or the derived one for a key this generator itself
-     * added, which is what reversing a migration drops. Guessing either way names nothing. MySQL takes
-     * no name at all - a table's key is always `PRIMARY` there.
+     * Drops the table's key, by the name the constraint really has: introspected, or derived where this
+     * generator added it. MySQL takes no name.
      */
     generateDropPrimaryKeySql(tableName, constraintName) {
         this.assertPrimaryKeyAlterable(tableName);
@@ -739,12 +690,8 @@ function foreignKeyOf(relation) {
     };
 }
 /**
- * The entities as an AST, named the way `generator` names things.
- *
- * Its resolvers rather than a naming strategy, because the two disagree: a strategy renames whatever
- * it is handed, while a generator leaves an explicit `@Entity({ name })` alone. Build the AST the
- * other way and the table is created under one name and compared under another, which reports every
- * table of a project using a naming strategy as both missing and unexpected.
+ * The entities as an AST, named by `generator`'s resolvers rather than a naming strategy, which would
+ * also rename an explicit `@Entity({ name })` and so compare each table under another name.
  */
 export function buildEntityAST(generator, entities, defaultForeignKeyAction) {
     return buildSchemaAST(entities, {

package/dist/mongo/mongoDialect.d.ts

@@ -1,6 +1,6 @@
 import { type Document, type Filter, type Sort, type UpdateFilter } from 'mongodb';
 import { AbstractDialect } from '../dialect/abstractDialect.js';
-import type { DialectFeatures, EntityData, EntityMeta, FieldValue, Query, QueryAggMap, QueryAggregate, QueryExclude, QueryGroupMap, QueryOptions, QueryPopulate, QuerySelectValue, QuerySortMap, QueryVectorSearch, QueryWhere, Type } from '../type/index.js';
+import type { DialectFeatures, EntityData, EntityMeta, Query, QueryAggMap, QueryAggregate, QueryExclude, QueryGroupMap, QueryOptions, QueryPager, QueryPopulate, QuerySelectValue, QuerySortMap, QueryVectorSearch, QueryWhere, Type } from '../type/index.js';
 import { type CallbackKey } from '../util/index.js';
 /** What a read pipeline contributes to {@link MongoDialect.readStages} beyond the query itself. */
 type MongoReadStages = {
@@ -19,7 +19,7 @@ type RelationLookups = {
 export declare const mongoDialectFeatures: DialectFeatures;
 export declare class MongoDialect extends AbstractDialect {
     #private;
-    protected readonly featureDefaults: DialectFeatures;
+    readonly features: DialectFeatures;
     readonly dialectName = "mongodb";
     readonly insertIdSource = "returning";
     private static readonly ID_KEY;
@@ -33,11 +33,8 @@ export declare class MongoDialect extends AbstractDialect {
     columnOf<E>(meta: EntityMeta<E>, key: string): string;
     where<E extends Document>(entity: Type<E>, where?: QueryWhere<E>, opts?: QueryOptions): Filter<E>;
     /**
-     * A `$where` that may constrain relations, split into the `$lookup` stages it needs and the `$match`
-     * filter that consumes them. Each relation condition becomes one correlated lookup into a temporary
-     * field plus an ordinary condition on that field, so the caller's boolean structure survives intact
-     * (a relation inside `$or` still means what it says) and nothing depends on materializing ids.
-     * `unset` names the temporary fields, which the caller drops once the match is done.
+     * A `$where` that may constrain relations, as the `$lookup` stages it needs and the `$match` reading
+     * them: each condition a lookup into a temporary field (`unset` names them), so `$or` keeps its meaning.
      */
     whereWithRelations<E extends Document>(entity: Type<E>, where?: QueryWhere<E>, opts?: QueryOptions): {
         readonly stages: MongoAggregationPipelineEntry<Document>[];
@@ -53,13 +50,8 @@ export declare class MongoDialect extends AbstractDialect {
      */
     protected renderFilter<E extends Document>(entity: Type<E>, where?: QueryWhere<E>, lookups?: RelationLookups): Filter<E>;
     /**
-     * Renders `$and`/`$or`/`$not`/`$nor` into `filter`. MongoDB has no root-level `$not`, so both
-     * negating operators become its `$nor`, which is exactly `NOT (a OR b)` - and by De Morgan that
-     * makes a `$nor` list its clauses directly while a `$not` wraps them in one `$and` first.
-     *
-     * Clauses that render to nothing are dropped and an empty operator emits no key at all: MongoDB
-     * rejects an empty `$and`/`$or`/`$nor` outright, where the SQL dialects contribute no term.
-     * Negations accumulate into the one `$nor`, since `NOT a AND NOT b` is `$nor: [a, b]`.
+     * Renders `$and`/`$or`/`$not`/`$nor` into `filter`, both negations as MongoDB's `$nor` (a `$not`'s clauses
+     * wrapped in one `$and`), dropping empty clauses, since MongoDB refuses an empty operator.
      */
     private appendLogicalOperator;
     /**
@@ -103,9 +95,6 @@ export declare class MongoDialect extends AbstractDialect {
      * apply to JSON paths.
      */
     private assertKnownPathRoot;
-    protected mapTableNameRow(row: {
-        table_name: string;
-    }): string;
     /** String operators -> { pattern: (v) => regex, caseInsensitive } */
     private static readonly REGEX_OP_MAP;
     /** MongoDB native operators - pass through as-is. */
@@ -167,13 +156,11 @@ export declare class MongoDialect extends AbstractDialect {
      */
     private pathOf;
     aggregationPipeline<E extends Document>(entity: Type<E>, q: Query<E>, opts?: QueryOptions): MongoAggregationPipelineEntry<E>[];
+    /** The `$skip`/`$limit` stages of a page, each checked: `/http` hands a page over untyped. */
+    pagerStages(q: QueryPager): MongoAggregationPipelineEntry<Document>[];
     /**
-     * What a read runs after its entry stage, in the one order that works: the lookups its relations
-     * need, the ordering and paging that may read them, and the projection last of all - it names the
-     * fields the lookups add, and no stage after it could read what it dropped.
-     *
-     * 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.
+     * What a read runs after its entry stage, in the one order that works: the lookups, then the sort and
+     * page that may read them, then the projection. Shared with the `$vectorSearch` pipeline.
      */
     readStages<E extends Document>(entity: Type<E>, q: Query<E>, extra?: MongoReadStages): MongoAggregationPipelineEntry<Document>[];
     /**
@@ -184,10 +171,8 @@ export declare class MongoDialect extends AbstractDialect {
      */
     private distinctStages;
     /**
-     * The scalar projection a narrowing query asks for, widened by what the pipeline itself produced:
-     * 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.
+     * The projection a narrowing query asks for, widened by what the pipeline produced (each populated
+     * relation and the tallies); last, once the lookups have read the join keys.
      */
     pipelineProjection<E extends Document>(entity: Type<E>, q: Query<E>): Record<string, 0 | 1> | undefined;
     /**
@@ -209,11 +194,8 @@ export declare class MongoDialect extends AbstractDialect {
     /** `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;
     /**
-     * The seam into the driver: a key, or a reference to one, as MongoDB stores it. A 24-hex string
-     * becomes an `ObjectId`, so a write agrees with the filter that will later look for it; anything
-     * else - a UUID, a number, an `ObjectId` already - is stored as given, which is how those keys keep
-     * their value. Strictly 24-hex: the driver also accepts any 12-byte string, and coercing one of
-     * those turned an ordinary short key into a foreign `ObjectId`. Arrays convert element-wise.
+     * A key as MongoDB stores it: a 24-hex string as an `ObjectId`, so a write matches the filter looking for
+     * it, and anything else as given. Only 24-hex, not any 12-byte string. Arrays convert element-wise.
      */
     toWireId(value: unknown): unknown;
     /** The seam out of the driver: an `ObjectId` becomes its hex string, the type the code declares. */
@@ -228,26 +210,11 @@ export declare class MongoDialect extends AbstractDialect {
      */
     getUpdateFilter<E extends Document>(persistable: Partial<E>): UpdateFilter<E> | Document[];
     /**
-     * MongoDB rejects two operators targeting one path in a single update document, so any path shared
-     * across operator groups is expressed as one aggregation-pipeline update instead.
-     *
-     * Each path's expression is composed in the same order stated on {@link JsonUpdateOp} (`$pull` ->
-     * `$set` -> `$push` -> `$unset`), so every combination yields the identical result: a `$pull`
-     * filters the stored array, a `$set` on the same path then replaces it outright, and a `$push`
-     * appends to whatever those produced. `$unset` is a later stage, so it wins over a `$set` on the
-     * same path - again matching SQL, where it is the outermost wrapper. Values are wrapped in
-     * `$literal` so a string starting with `$` stays data rather than becoming a field reference.
+     * A JSON update as one pipeline, since MongoDB refuses two operators on one path: each path composed as
+     * `$pull`, `$set`, `$push`, then `$unset`, as SQL does, with values as `$literal` so `$x` stays data.
      */
     private getUpdatePipeline;
-    /**
-     * Refuses a key the caller left to MongoDB that MongoDB cannot mint one of.
-     *
-     * The only key a server generates is an `ObjectId`, which {@link fromWireId} hands back as its hex
-     * string - so a key declared `String` is satisfiable and one declared `Number` is not. Answering a
-     * numeric declaration with a string is the lie this exists to refuse: the field says `number`, the
-     * value is not one, and every consumer that indexes or compares by it is quietly wrong. Prisma
-     * refuses the same shape at its schema, and this is the first moment uql can.
-     */
+    /** Refuses a key left to MongoDB that it cannot mint: only an `ObjectId`, read back as a string, so not a `Number`. */
     private assertMintableKey;
     getPersistables<E extends Document>(meta: EntityMeta<E>, payload: EntityData<E> | EntityData<E>[], callbackKey: CallbackKey): Partial<E>[];
     /**
@@ -273,7 +240,7 @@ export declare class MongoDialect extends AbstractDialect {
     buildVectorSearchStage<E extends Document>(entity: Type<E>, key: string, search: QueryVectorSearch, where: QueryWhere<E> | undefined, limit: number, opts?: QueryOptions, candidates?: number): Record<string, unknown>;
 }
 export type MongoAggregationPipelineEntry<E extends Document> = {
-    $lookup?: MongoAggregationLookup<E>;
+    $lookup?: MongoAggregationLookup;
     $match?: Filter<E> | Record<string, unknown>;
     $sort?: Sort;
     $unwind?: MongoAggregationUnwind;
@@ -289,11 +256,12 @@ export type MongoAggregationPipelineEntry<E extends Document> = {
     $skip?: number;
     $limit?: number;
 };
-type MongoAggregationLookup<E extends Document> = {
+/** A `$lookup`, whose pipeline runs over the collection it reads. */
+type MongoAggregationLookup = {
     readonly from?: string;
     readonly foreignField?: string;
     readonly localField?: string;
-    readonly pipeline?: MongoAggregationPipelineEntry<FieldValue<E>>[];
+    readonly pipeline?: MongoAggregationPipelineEntry<Document>[];
     /** A relation key when populating, a temporary field when a relation condition is being tested. */
     readonly as?: string;
 };