uql-orm 0.58.0 → 0.60.0

package/dist/entity/metadata/definition.js

@@ -186,17 +186,10 @@ export function defineEntity(entity, opts = {}) {
         meta.derivedName = true;
     }
     meta.schema = opts.schema ?? meta.schema;
-    let proto = Object.getPrototypeOf(entity.prototype);
-    while (proto.constructor !== Object) {
-        const parent = proto.constructor;
-        // 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 reading through the
-        // metadata object's is what makes this work on every transformer: tsc and esbuild chain metadata
-        // across `extends`, SWC does not.
-        applyMembers(parent, ownRegistrations(parent));
-        extendMeta(meta, ensureMeta(parent));
-        proto = Object.getPrototypeOf(proto);
-    }
+    // The class's real chain first: where a class both extends a base and names one, the one it extends
+    // is the nearer, and nearer wins every merge.
+    inheritFrom(meta, parentOf(entity));
+    inheritFrom(meta, opts.extends);
     // Derive soft-delete from the (inheritance-merged) fields, so own and inherited markers are handled
     // uniformly. Exactly one field may be marked; it auto-registers the built-in `softDelete` read
     // filter (a reserved name - see defineFilter - so it never clobbers a user filter).
@@ -471,6 +464,24 @@ function junctionColumn(meta, idKey) {
 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.
+ */
+function inheritFrom(meta, ancestor) {
+    for (let parent = ancestor; parent && parent !== Object; parent = parentOf(parent)) {
+        const base = parent;
+        applyMembers(base, ownRegistrations(base));
+        extendMeta(meta, ensureMeta(base));
+    }
+}
+/** The class `entity` extends, `Object` where it extends nothing. */
+function parentOf(entity) {
+    return Object.getPrototypeOf(entity.prototype)?.constructor;
+}
 function extendMeta(target, source) {
     const sourceFields = { ...source.fields };
     // A subclass declaring its own primary key drops the parent's - every column of it, or a composite

package/dist/migrate/acquireQuerierForMigrations.d.ts

@@ -1,6 +1,6 @@
-import { type Querier, type QuerierPool, type SqlQuerier } from '../type/index.js';
+import { type MongoQuerier, type Querier, type QuerierPool, type SqlQuerier } from '../type/index.js';
 /**
- * Querier used for schema migrations and the migration journal (`DatabaseMigrationStorage`).
+ * Querier used for schema migrations and the migration journal.
  *
  * Pools may override {@link QuerierPool.getMigrationQuerier} so DDL runs on a different target than
  * app traffic (e.g. LibSQL embedded replica: local `file:` + remote `syncUrl`).
@@ -13,8 +13,7 @@ export declare function acquireQuerierForMigrations(pool: QuerierPool): Promise<
  * traffic, but the ownership rule is the same one: whoever acquires, releases.
  */
 export declare function withQuerierForMigrations<T>(pool: QuerierPool, task: (querier: Querier) => Promise<T>): Promise<T>;
-/**
- * Same, for the paths that only work against SQL. `requiredBy` names the caller in the error, which is
- * the only thing the five copies of this acquire-assert-release dance used to differ by.
- */
+/** Same, for the paths that only work against SQL. `requiredBy` names the caller in the error. */
 export declare function withSqlQuerierForMigrations<T>(pool: QuerierPool, requiredBy: string, task: (querier: SqlQuerier) => Promise<T>): Promise<T>;
+/** Same, for the paths that only work against MongoDB. */
+export declare function withMongoQuerierForMigrations<T>(pool: QuerierPool, requiredBy: string, task: (querier: MongoQuerier) => Promise<T>): Promise<T>;

package/dist/migrate/acquireQuerierForMigrations.js

@@ -1,6 +1,6 @@
-import { isSqlQuerier } from '../type/index.js';
+import { isMongoQuerier, isSqlQuerier, } from '../type/index.js';
 /**
- * Querier used for schema migrations and the migration journal (`DatabaseMigrationStorage`).
+ * Querier used for schema migrations and the migration journal.
  *
  * Pools may override {@link QuerierPool.getMigrationQuerier} so DDL runs on a different target than
  * app traffic (e.g. LibSQL embedded replica: local `file:` + remote `syncUrl`).
@@ -23,14 +23,18 @@ export async function withQuerierForMigrations(pool, task) {
         await querier.release();
     }
 }
-/**
- * Same, for the paths that only work against SQL. `requiredBy` names the caller in the error, which is
- * the only thing the five copies of this acquire-assert-release dance used to differ by.
- */
+/** Same, for the paths that only work against SQL. `requiredBy` names the caller in the error. */
 export function withSqlQuerierForMigrations(pool, requiredBy, task) {
+    return withQuerierOfKind(pool, isSqlQuerier, `${requiredBy} requires a SQL-based querier`, task);
+}
+/** Same, for the paths that only work against MongoDB. */
+export function withMongoQuerierForMigrations(pool, requiredBy, task) {
+    return withQuerierOfKind(pool, isMongoQuerier, `${requiredBy} requires a MongoDB querier`, task);
+}
+function withQuerierOfKind(pool, isKind, error, task) {
     return withQuerierForMigrations(pool, (querier) => {
-        if (!isSqlQuerier(querier)) {
-            throw new TypeError(`${requiredBy} requires a SQL-based querier`);
+        if (!isKind(querier)) {
+            throw new TypeError(error);
         }
         return task(querier);
     });

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

@@ -414,6 +414,4 @@ export interface IMigrationBuilder {
     dropForeignKey(tableName: string, constraintName: string): Promise<void>;
     /** Execute raw SQL */
     raw(sql: string): Promise<void>;
-    /** Get all recorded operations */
-    getOperations(): AnyMigrationOperation[];
 }

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

@@ -5,4 +5,4 @@
  */
 export { createEntityCodeGenerator, EntityCodeGenerator, type EntityCodeGeneratorOptions, type GeneratedEntity, } from './entityCodeGenerator.js';
 export { entityTypesSource } from './entityTypes.js';
-export { buildSqlQuerierMigrationModule, EMPTY_MANUAL_MIGRATION_DOWN_INNER, EMPTY_MANUAL_MIGRATION_UP_INNER, emitSqlRunCall, emitSqlRunCalls, type SqlMigrationModuleOptions, } from './migrationFile.js';
+export { buildMigrationModule, buildSqlQuerierMigrationModule, EMPTY_MANUAL_MIGRATION_DOWN_INNER, EMPTY_MANUAL_MIGRATION_UP_INNER, emitMongoCommandCalls, emitSqlRunCall, emitSqlRunCalls, type MigrationModuleOptions, type MigrationQuerierType, type SqlMigrationModuleOptions, } from './migrationFile.js';

package/dist/migrate/codegen/index.js

@@ -6,4 +6,4 @@
 // Entity code generator
 export { createEntityCodeGenerator, EntityCodeGenerator, } from './entityCodeGenerator.js';
 export { entityTypesSource } from './entityTypes.js';
-export { buildSqlQuerierMigrationModule, EMPTY_MANUAL_MIGRATION_DOWN_INNER, EMPTY_MANUAL_MIGRATION_UP_INNER, emitSqlRunCall, emitSqlRunCalls, } from './migrationFile.js';
+export { buildMigrationModule, buildSqlQuerierMigrationModule, EMPTY_MANUAL_MIGRATION_DOWN_INNER, EMPTY_MANUAL_MIGRATION_UP_INNER, emitMongoCommandCalls, emitSqlRunCall, emitSqlRunCalls, } from './migrationFile.js';

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

@@ -1,9 +1,13 @@
 /**
- * Source code generation for default-export SQL migrations (`SqlQuerier` / `uql-migrate`).
+ * Source code generation for default-export migrations (`uql-migrate`), on a `SqlQuerier` or a `MongoQuerier`.
  */
-export type SqlMigrationModuleOptions = {
+/** The querier a migration module is written against. */
+export type MigrationQuerierType = 'SqlQuerier' | 'MongoQuerier';
+export type MigrationModuleOptions = {
     migrationName: string;
     createdAt: Date;
+    /** Defaults to `SqlQuerier`. */
+    querier?: MigrationQuerierType;
     /** Extra lines in the file header comment (without leading ` * `). */
     docExtraLines?: string[];
     /** Indented body inside `async up` (including newlines). */
@@ -11,6 +15,8 @@ export type SqlMigrationModuleOptions = {
     /** Indented body inside `async down` (including newlines). */
     downInner: string;
 };
+/** @deprecated Use {@link MigrationModuleOptions}. */
+export type SqlMigrationModuleOptions = MigrationModuleOptions;
 /**
  * Emit one `await querier.run(...)` line for entity-generated migrations.
  * Uses `JSON.stringify` so SQL with backticks (SQLite/LibSQL), quotes, `${`, etc. stays valid TS source.
@@ -18,11 +24,28 @@ export type SqlMigrationModuleOptions = {
 export declare function emitSqlRunCall(sql: string): string;
 /** Indented `up`/`down` body: one `await querier.run(...)` per SQL string (entity-generated migrations, #87). */
 export declare function emitSqlRunCalls(statements: string[]): string;
+/** Indented `up`/`down` body: one awaited driver call on `querier.db` per MongoDB command. */
+export declare function emitMongoCommandCalls(statements: string[]): string;
 /** Body for `up` in a manual (empty) migration scaffold. */
 export declare const EMPTY_MANUAL_MIGRATION_UP_INNER = "    // Add your migration logic here.\n    // Use one await querier.run(\"...\") per SQL statement when possible (same style as generate:entities).\n    // Example (Postgres):\n    // await querier.run(\"CREATE TABLE \\\"users\\\" (\\\"id\\\" SERIAL PRIMARY KEY);\");\n";
 /** Body for `down` in a manual (empty) migration scaffold. */
 export declare const EMPTY_MANUAL_MIGRATION_DOWN_INNER = "    // Add your rollback logic here.\n    // await querier.run(\"DROP TABLE IF EXISTS \\\"users\\\";\");\n";
+/** How a migration on each querier is scaffolded empty, and how a generated statement is spelled in it. */
+export declare const migrationSource: {
+    SqlQuerier: {
+        emptyUp: string;
+        emptyDown: string;
+        emit: typeof emitSqlRunCalls;
+    };
+    MongoQuerier: {
+        emptyUp: string;
+        emptyDown: string;
+        emit: typeof emitMongoCommandCalls;
+    };
+};
 /**
  * Full contents of a `export default { async up/down(querier) { ... } }` migration module.
  */
-export declare function buildSqlQuerierMigrationModule(options: SqlMigrationModuleOptions): string;
+export declare function buildMigrationModule(options: MigrationModuleOptions): string;
+/** @deprecated Use {@link buildMigrationModule}. */
+export declare const buildSqlQuerierMigrationModule: typeof buildMigrationModule;

package/dist/migrate/codegen/migrationFile.js

@@ -1,6 +1,4 @@
-/**
- * Source code generation for default-export SQL migrations (`SqlQuerier` / `uql-migrate`).
- */
+import { mongoCommandSource } from '../generator/mongoCommand.js';
 /**
  * Emit one `await querier.run(...)` line for entity-generated migrations.
  * Uses `JSON.stringify` so SQL with backticks (SQLite/LibSQL), quotes, `${`, etc. stays valid TS source.
@@ -12,6 +10,10 @@ export function emitSqlRunCall(sql) {
 export function emitSqlRunCalls(statements) {
     return statements.map(emitSqlRunCall).join('\n');
 }
+/** Indented `up`/`down` body: one awaited driver call on `querier.db` per MongoDB command. */
+export function emitMongoCommandCalls(statements) {
+    return statements.map((statement) => /*ts*/ `    await ${mongoCommandSource(statement, 'querier.db')};`).join('\n');
+}
 /** Body for `up` in a manual (empty) migration scaffold. */
 export const EMPTY_MANUAL_MIGRATION_UP_INNER = `    // Add your migration logic here.
     // Use one await querier.run("...") per SQL statement when possible (same style as generate:entities).
@@ -22,26 +24,46 @@ export const EMPTY_MANUAL_MIGRATION_UP_INNER = `    // Add your migration logic
 export const EMPTY_MANUAL_MIGRATION_DOWN_INNER = `    // Add your rollback logic here.
     // await querier.run("DROP TABLE IF EXISTS \\"users\\";");
 `;
+/** How a migration on each querier is scaffolded empty, and how a generated statement is spelled in it. */
+export const migrationSource = {
+    SqlQuerier: {
+        emptyUp: EMPTY_MANUAL_MIGRATION_UP_INNER,
+        emptyDown: EMPTY_MANUAL_MIGRATION_DOWN_INNER,
+        emit: emitSqlRunCalls,
+    },
+    MongoQuerier: {
+        emptyUp: `    // Add your migration logic here, through the database handle.
+    // await querier.db.collection('users').updateMany({}, { $set: { active: true } });
+`,
+        emptyDown: `    // Add your rollback logic here.
+    // await querier.db.collection('users').updateMany({}, { $unset: { active: '' } });
+`,
+        emit: emitMongoCommandCalls,
+    },
+};
 /**
  * Full contents of a `export default { async up/down(querier) { ... } }` migration module.
  */
-export function buildSqlQuerierMigrationModule(options) {
+export function buildMigrationModule(options) {
+    const querier = options.querier ?? 'SqlQuerier';
     const iso = options.createdAt.toISOString();
     const extra = options.docExtraLines?.map((line) => `\n * ${line}`).join('') ?? '';
-    return /*ts*/ `import type { SqlQuerier } from 'uql-orm/migrate';
+    return /*ts*/ `import type { ${querier} } from 'uql-orm/migrate';
 
 /**
  * Migration: ${options.migrationName}
  * Created: ${iso}${extra}
  */
 export default {
-  async up(querier: SqlQuerier): Promise<void> {
+  async up(querier: ${querier}): Promise<void> {
 ${options.upInner}
   },
 
-  async down(querier: SqlQuerier): Promise<void> {
+  async down(querier: ${querier}): Promise<void> {
 ${options.downInner}
   },
 };
 `;
 }
+/** @deprecated Use {@link buildMigrationModule}. */
+export const buildSqlQuerierMigrationModule = buildMigrationModule;

package/dist/migrate/generator/mongoCommand.d.ts

@@ -50,8 +50,7 @@ export type MongoCommandTarget = {
         dropIndex(name: string): Promise<unknown>;
     };
 };
-/**
- * Execute one emitted command. The single cast lives here, where the union it casts to is defined
- * alongside the only code that writes these strings.
- */
+/** Execute one emitted command. */
 export declare function runMongoCommand(db: MongoCommandTarget, statement: string): Promise<unknown>;
+/** The driver call {@link runMongoCommand} makes, as source on the handle `db` names, for a generated migration. */
+export declare function mongoCommandSource(statement: string, db: string): string;

package/dist/migrate/generator/mongoCommand.js

@@ -2,11 +2,18 @@ export function serializeMongoCommand(command) {
     return JSON.stringify(command);
 }
 /**
- * Execute one emitted command. The single cast lives here, where the union it casts to is defined
+ * Read one emitted command back. The single cast lives here, where the union it casts to is defined
  * alongside the only code that writes these strings.
  */
+function parseMongoCommand(statement) {
+    return JSON.parse(statement);
+}
+function unsupportedMongoCommand(statement) {
+    return new TypeError(`unsupported MongoDB migration command: ${statement}`);
+}
+/** Execute one emitted command. */
 export function runMongoCommand(db, statement) {
-    const command = JSON.parse(statement);
+    const command = parseMongoCommand(statement);
     switch (command.action) {
         case 'createCollection':
             return db.createCollection(command.name);
@@ -21,6 +28,25 @@ export function runMongoCommand(db, statement) {
         default:
             // Unreachable for a command this module produced; a hand-written statement lands here rather
             // than being silently skipped, which is how `renameCollection` went unnoticed.
-            throw new TypeError(`unsupported MongoDB migration command: ${statement}`);
+            throw unsupportedMongoCommand(statement);
+    }
+}
+/** The driver call {@link runMongoCommand} makes, as source on the handle `db` names, for a generated migration. */
+export function mongoCommandSource(statement, db) {
+    const command = parseMongoCommand(statement);
+    const literal = JSON.stringify;
+    switch (command.action) {
+        case 'createCollection':
+            return `${db}.createCollection(${literal(command.name)})`;
+        case 'dropCollection':
+            return `${db}.collection(${literal(command.name)}).drop()`;
+        case 'renameCollection':
+            return `${db}.renameCollection(${literal(command.from)}, ${literal(command.to)})`;
+        case 'createIndex':
+            return `${db}.collection(${literal(command.collection)}).createIndex(${literal(command.key)}, ${literal(command.options)})`;
+        case 'dropIndex':
+            return `${db}.collection(${literal(command.collection)}).dropIndex(${literal(command.name)})`;
+        default:
+            throw unsupportedMongoCommand(statement);
     }
 }

package/dist/migrate/index.d.ts

@@ -13,3 +13,4 @@ export { createSchemaGenerator, SqlSchemaGenerator } from './schemaGenerator.js'
 export { createSchemaGeneratorAsync } from './schemaGeneratorAsync.js';
 export { DatabaseMigrationStorage } from './storage/databaseStorage.js';
 export { JsonMigrationStorage } from './storage/jsonStorage.js';
+export { MongoMigrationStorage } from './storage/mongoStorage.js';

package/dist/migrate/index.js

@@ -20,4 +20,5 @@ export { createSchemaGeneratorAsync } from './schemaGeneratorAsync.js';
 // Storage implementations
 export { DatabaseMigrationStorage } from './storage/databaseStorage.js';
 export { JsonMigrationStorage } from './storage/jsonStorage.js';
+export { MongoMigrationStorage } from './storage/mongoStorage.js';
 // Schema sync

package/dist/migrate/migrator.d.ts

@@ -1,4 +1,4 @@
-import type { DialectName, LoggingOptions, Migration, MigrationDefinition, MigrationResult, MigrationStorage, MigratorDialect, 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, SqlQuerier, SyncOptions, Type } from '../type/index.js';
 import { LoggerWrapper } from '../util/index.js';
 import type { IMigrationBuilder } from './builder/types.js';
 /**
@@ -34,11 +34,11 @@ export declare class Migrator {
     /**
      * Get all discovered migrations from the migrations directory
      */
-    getMigrations(): Promise<Migration[]>;
+    getMigrations(): Promise<Migration<Querier>[]>;
     /**
      * Get list of pending migrations (not yet executed)
      */
-    pending(): Promise<Migration[]>;
+    pending(): Promise<Migration<Querier>[]>;
     /**
      * Get list of executed migrations
      */
@@ -66,13 +66,23 @@ export declare class Migrator {
      */
     private runInOrder;
     /**
-     * Run a single migration within a transaction
+     * Run a single migration, within a transaction where the dialect has one for it
      */
-    runMigration(migration: Migration, direction: 'up' | 'down'): Promise<MigrationResult>;
+    runMigration(migration: Migration<Querier>, direction: 'up' | 'down'): Promise<MigrationResult>;
+    /**
+     * A migration querier, and how to run work in one transaction on it. MongoDB gets none: it creates
+     * collections and indexes outside any transaction. SQL asserts its querier before opening one, so a
+     * wrong querier reports which one the dialect needs rather than a missing `transaction`.
+     */
+    private withMigrationQuerier;
+    /** What this dialect's migration files are written against. */
+    private get migrationQuerier();
     /**
      * Generate a new migration file
      */
     generate(name: string): Promise<string>;
+    /** Writes a migration module on this dialect's querier to a new timestamped file, and returns its path. */
+    private writeMigration;
     /**
      * Generate a migration based on entity schema differences
      */
@@ -174,11 +184,11 @@ export declare class Migrator {
     /**
      * Load a migration from a file
      */
-    loadMigration(fileName: string): Promise<Migration | undefined>;
+    loadMigration(fileName: string): Promise<Migration<Querier> | undefined>;
     /**
      * Check if an object is a valid migration
      */
-    isMigration(obj: unknown): obj is MigrationDefinition;
+    isMigration(obj: unknown): obj is MigrationDefinition<Querier>;
     /**
      * Extract migration name from filename
      */
@@ -195,14 +205,15 @@ export declare class Migrator {
 /**
  * Helper function to define a migration with proper typing
  */
-export declare function defineMigration(migration: MigrationDefinition): MigrationDefinition;
+export declare function defineMigration<Q extends Querier = SqlQuerier>(migration: MigrationDefinition<Q>): MigrationDefinition<Q>;
 /**
- * Migration definition that uses the type-safe builder API.
+ * Migration definition that uses the type-safe builder API. The querier is the builder's own, so a
+ * data backfill it runs lands in the same transaction as the schema change.
  */
 export interface BuilderMigrationDefinition {
     readonly name?: string;
-    readonly up: (builder: IMigrationBuilder) => Promise<void>;
-    readonly down: (builder: IMigrationBuilder) => Promise<void>;
+    up(builder: IMigrationBuilder, querier: SqlQuerier): Promise<void>;
+    down(builder: IMigrationBuilder, querier: SqlQuerier): Promise<void>;
 }
 /**
  * Define a migration using the type-safe builder API.
@@ -223,4 +234,4 @@ export interface BuilderMigrationDefinition {
  * });
  * ```
  */
-export declare function defineBuilderMigration(migration: BuilderMigrationDefinition): BuilderMigrationDefinition;
+export declare function defineBuilderMigration(migration: BuilderMigrationDefinition): MigrationDefinition;

package/dist/migrate/migrator.js

@@ -3,14 +3,16 @@ import { basename, extname, join } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { getEntities, getMeta } from '../entity/index.js';
 import { introspectSchema, SchemaAST } from '../schema/index.js';
-import { isKnownMigratorDialect, isSqlQuerier } from '../type/index.js';
+import { isKnownMigratorDialect, isMongoQuerier, isSqlQuerier } from '../type/index.js';
 import { LoggerWrapper } from '../util/index.js';
-import { withQuerierForMigrations, withSqlQuerierForMigrations } from './acquireQuerierForMigrations.js';
-import { buildSqlQuerierMigrationModule, EMPTY_MANUAL_MIGRATION_DOWN_INNER, EMPTY_MANUAL_MIGRATION_UP_INNER, emitSqlRunCalls, } from './codegen/migrationFile.js';
+import { withMongoQuerierForMigrations, withSqlQuerierForMigrations } from './acquireQuerierForMigrations.js';
+import { MigrationBuilder } from './builder/migrationBuilder.js';
+import { buildMigrationModule, migrationSource, } from './codegen/migrationFile.js';
 import { runMongoCommand } from './generator/mongoCommand.js';
 import { introspectorFor } from './introspection/registry.js';
 import { createSchemaGenerator } from './schemaGenerator.js';
 import { DatabaseMigrationStorage } from './storage/databaseStorage.js';
+import { MongoMigrationStorage } from './storage/mongoStorage.js';
 /**
  * Main class for managing database migrations
  */
@@ -40,9 +42,9 @@ export class Migrator {
         this._defaultForeignKeyAction = options.defaultForeignKeyAction;
         this.storage =
             options.storage ??
-                new DatabaseMigrationStorage(pool, {
-                    tableName: options.tableName,
-                });
+                (this.dialectName === 'mongodb'
+                    ? new MongoMigrationStorage(pool, { tableName: options.tableName })
+                    : new DatabaseMigrationStorage(pool, { tableName: options.tableName }));
         this.migrationsPath = options.migrationsPath ?? './migrations';
         this._logger = new LoggerWrapper(options.logger, { logValues: options.logValues, slowQuery: options.slowQuery });
         this._entities = options.entities;
@@ -153,22 +155,20 @@ export class Migrator {
         return results;
     }
     /**
-     * Run a single migration within a transaction
+     * Run a single migration, within a transaction where the dialect has one for it
      */
     async runMigration(migration, direction) {
         const startTime = Date.now();
-        return withSqlQuerierForMigrations(this.pool, 'Migrator', async (querier) => {
+        return this.withMigrationQuerier(async (querier, inTransaction) => {
             try {
                 this.logger.logMigration(`${direction === 'up' ? 'Running' : 'Reverting'} migration: ${migration.name}`);
-                await querier.transaction(async () => {
+                await inTransaction(async () => {
                     if (direction === 'up') {
                         await migration.up(querier);
-                        // Log within the same transaction
                         await this.storage.logWithQuerier(querier, migration.name);
                     }
                     else {
                         await migration.down(querier);
-                        // Unlog within the same transaction
                         await this.storage.unlogWithQuerier(querier, migration.name);
                     }
                 });
@@ -194,22 +194,40 @@ export class Migrator {
             }
         });
     }
+    /**
+     * A migration querier, and how to run work in one transaction on it. MongoDB gets none: it creates
+     * collections and indexes outside any transaction. SQL asserts its querier before opening one, so a
+     * wrong querier reports which one the dialect needs rather than a missing `transaction`.
+     */
+    withMigrationQuerier(task) {
+        return this.dialectName === 'mongodb'
+            ? withMongoQuerierForMigrations(this.pool, 'Migrator', (querier) => task(querier, (work) => work()))
+            : withSqlQuerierForMigrations(this.pool, 'Migrator', (querier) => task(querier, (work) => querier.transaction(work)));
+    }
+    /** What this dialect's migration files are written against. */
+    get migrationQuerier() {
+        return this.dialectName === 'mongodb' ? 'MongoQuerier' : 'SqlQuerier';
+    }
     /**
      * Generate a new migration file
      */
     async generate(name) {
-        const timestamp = this.getTimestamp();
-        const fileName = `${timestamp}_${this.slugify(name)}.ts`;
-        const filePath = join(this.migrationsPath, fileName);
-        const content = buildSqlQuerierMigrationModule({
+        const { emptyUp, emptyDown } = migrationSource[this.migrationQuerier];
+        const filePath = await this.writeMigration(name, { upInner: emptyUp, downInner: emptyDown });
+        this.logger.logInfo(`Created migration: ${filePath}`);
+        return filePath;
+    }
+    /** Writes a migration module on this dialect's querier to a new timestamped file, and returns its path. */
+    async writeMigration(name, body) {
+        const filePath = join(this.migrationsPath, `${this.getTimestamp()}_${this.slugify(name)}.ts`);
+        const content = buildMigrationModule({
             migrationName: name,
             createdAt: new Date(),
-            upInner: EMPTY_MANUAL_MIGRATION_UP_INNER,
-            downInner: EMPTY_MANUAL_MIGRATION_DOWN_INNER,
+            querier: this.migrationQuerier,
+            ...body,
         });
         await mkdir(this.migrationsPath, { recursive: true });
         await writeFile(filePath, content, 'utf-8');
-        this.logger.logInfo(`Created migration: ${filePath}`);
         return filePath;
     }
     /**
@@ -236,19 +254,12 @@ export class Migrator {
             this.logger.logInfo('No schema changes detected.');
             return '';
         }
-        const timestamp = this.getTimestamp();
-        const fileName = `${timestamp}_${this.slugify(name)}.ts`;
-        const filePath = join(this.migrationsPath, fileName);
-        const down = [...downStatements].reverse();
-        const content = buildSqlQuerierMigrationModule({
-            migrationName: name,
-            createdAt: new Date(),
+        const { emit } = migrationSource[this.migrationQuerier];
+        const filePath = await this.writeMigration(name, {
             docExtraLines: ['Generated from entity definitions'],
-            upInner: emitSqlRunCalls(upStatements),
-            downInner: emitSqlRunCalls(down),
+            upInner: emit(upStatements),
+            downInner: emit([...downStatements].reverse()),
         });
-        await mkdir(this.migrationsPath, { recursive: true });
-        await writeFile(filePath, content, 'utf-8');
         this.logger.logInfo(`Created migration from entities: ${filePath}`);
         return filePath;
     }
@@ -474,15 +485,9 @@ export class Migrator {
         return filteredDiff;
     }
     async executeSyncStatements(statements, options) {
-        // Mongo creates collections and indexes outside any transaction, so only the SQL path opens one -
-        // and asks for a SQL querier before it opens it, since `transaction` is what a Mongo one lacks and
-        // reaching for it first reports that instead of which querier the dialect needs.
-        if (this.dialectName === 'mongodb') {
-            await withQuerierForMigrations(this.pool, (querier) => this.executeMongoSyncStatements(statements, options, querier));
-        }
-        else {
-            await withSqlQuerierForMigrations(this.pool, 'Migrator', (querier) => querier.transaction(() => this.executeSqlSyncStatements(statements, options, querier)));
-        }
+        await this.withMigrationQuerier((querier, inTransaction) => inTransaction(() => isMongoQuerier(querier)
+            ? this.executeMongoSyncStatements(statements, options, querier)
+            : this.executeSqlSyncStatements(statements, options, querier)));
         if (options.logging)
             this.logger.logSchema('Schema synchronization completed');
     }
@@ -618,5 +623,9 @@ export function defineMigration(migration) {
  * ```
  */
 export function defineBuilderMigration(migration) {
-    return migration;
+    return {
+        ...migration,
+        up: (querier) => migration.up(new MigrationBuilder(querier), querier),
+        down: (querier) => migration.down(new MigrationBuilder(querier), querier),
+    };
 }

package/dist/migrate/storage/jsonStorage.d.ts

@@ -1,4 +1,4 @@
-import type { MigrationStorage, SqlQuerier } from '../../type/index.js';
+import type { MigrationStorage, Querier } from '../../type/index.js';
 /**
  * Stores migration state in a JSON file.
  * Useful for development or environments without a database.
@@ -9,7 +9,7 @@ export declare class JsonMigrationStorage implements MigrationStorage {
     constructor(filePath?: string);
     ensureStorage(): Promise<void>;
     executed(): Promise<string[]>;
-    logWithQuerier(_querier: SqlQuerier, migrationName: string): Promise<void>;
-    unlogWithQuerier(_querier: SqlQuerier, migrationName: string): Promise<void>;
+    logWithQuerier(_querier: Querier, migrationName: string): Promise<void>;
+    unlogWithQuerier(_querier: Querier, migrationName: string): Promise<void>;
     private save;
 }

package/dist/migrate/storage/mongoStorage.d.ts

@@ -0,0 +1,17 @@
+import type { MigrationStorage, MongoQuerier, QuerierPool } from '../../type/index.js';
+/**
+ * Stores migration state in a MongoDB collection, named as the SQL table would be.
+ */
+export declare class MongoMigrationStorage implements MigrationStorage {
+    private readonly pool;
+    private readonly collectionName;
+    constructor(pool: QuerierPool, options?: {
+        tableName?: string;
+    });
+    /** Nothing to prepare: MongoDB creates the collection on its first insert. */
+    ensureStorage(): Promise<void>;
+    executed(): Promise<string[]>;
+    logWithQuerier(querier: MongoQuerier, migrationName: string): Promise<void>;
+    unlogWithQuerier(querier: MongoQuerier, migrationName: string): Promise<void>;
+    private collection;
+}

package/dist/migrate/storage/mongoStorage.js

@@ -0,0 +1,32 @@
+import { withMongoQuerierForMigrations } from '../acquireQuerierForMigrations.js';
+import { DEFAULT_MIGRATIONS_TABLE } from './databaseStorage.js';
+/**
+ * Stores migration state in a MongoDB collection, named as the SQL table would be.
+ */
+export class MongoMigrationStorage {
+    pool;
+    collectionName;
+    constructor(pool, options = {}) {
+        this.pool = pool;
+        this.collectionName = options.tableName ?? DEFAULT_MIGRATIONS_TABLE;
+    }
+    /** Nothing to prepare: MongoDB creates the collection on its first insert. */
+    async ensureStorage() { }
+    executed() {
+        return withMongoQuerierForMigrations(this.pool, 'MongoMigrationStorage', async (querier) => {
+            const documents = await this.collection(querier)
+                .find({}, { sort: { _id: 1 } })
+                .toArray();
+            return documents.map((document) => document._id);
+        });
+    }
+    async logWithQuerier(querier, migrationName) {
+        await this.collection(querier).insertOne({ _id: migrationName, executed_at: new Date() });
+    }
+    async unlogWithQuerier(querier, migrationName) {
+        await this.collection(querier).deleteOne({ _id: migrationName });
+    }
+    collection(querier) {
+        return querier.db.collection(this.collectionName);
+    }
+}

package/dist/type/entity.d.ts

@@ -878,6 +878,13 @@ type EntityRelationOptions<E> = {
  */
 export type EntityOptions<E = unknown> = {
     readonly name?: string;
+    /**
+     * The base to inherit fields, relations, hooks and filters from, for a class that cannot extend one
+     * (minted at runtime, or its base chosen from data): the merge `class Child extends Base` does, with
+     * the class's real base nearer, so it wins. Checked against whatever properties the entity declares,
+     * which a class behind an index signature has none of. See the Inheritance guide.
+     */
+    readonly extends?: string extends keyof E ? Type<object> : Type<Partial<E>>;
     /**
      * The schema (in MySQL terms, database) this table lives in, pinning it whichever pool reads it;
      * unset follows the pool's own. Not in `name`: a dotted `name` is rejected.

package/dist/type/migration.d.ts

@@ -3,19 +3,19 @@ import type { FullColumnDefinition, TableDefinition } from '../migrate/builder/t
 import type { IndexFacet } from '../schema/indexDifferences.js';
 import type { SchemaAST } from '../schema/schemaAST.js';
 import type { ColumnNode, ForeignKeyAction, IndexNode, IndexType, TableNode } from '../schema/types.js';
-import type { EntityMeta, FieldOptions, IndexColumnSchema, LoggingOptions, SqlQuerier, Type, VectorIndexOptions } from './index.js';
+import type { EntityMeta, FieldOptions, IndexColumnSchema, LoggingOptions, Querier, SqlQuerier, Type, VectorIndexOptions } from './index.js';
 /**
- * Defines a migration using a simple object literal
+ * Defines a migration using a simple object literal. `Q` is `MongoQuerier` for a MongoDB migration.
  */
-export interface MigrationDefinition {
+export interface MigrationDefinition<Q extends Querier = SqlQuerier> {
     readonly name?: string;
-    readonly up: (querier: SqlQuerier) => Promise<void>;
-    readonly down: (querier: SqlQuerier) => Promise<void>;
+    up(querier: Q): Promise<void>;
+    down(querier: Q): Promise<void>;
 }
 /**
  * Represents a single database migration
  */
-export interface Migration extends MigrationDefinition {
+export interface Migration<Q extends Querier = SqlQuerier> extends MigrationDefinition<Q> {
     /**
      * Unique name/identifier for this migration (typically timestamp + description)
      */
@@ -30,13 +30,13 @@ export interface MigrationStorage {
      */
     executed(): Promise<string[]>;
     /**
-     * Mark a migration as executed (called within migration transaction)
+     * Mark a migration as executed, on the querier that ran it (inside its transaction, where there is one)
      */
-    logWithQuerier(querier: SqlQuerier, migrationName: string): Promise<void>;
+    logWithQuerier(querier: Querier, migrationName: string): Promise<void>;
     /**
-     * Remove a migration from the executed list (called within migration transaction)
+     * Remove a migration from the executed list, on the querier that reverted it
      */
-    unlogWithQuerier(querier: SqlQuerier, migrationName: string): Promise<void>;
+    unlogWithQuerier(querier: Querier, migrationName: string): Promise<void>;
     /**
      * Ensure the storage is initialized (e.g., create migrations table)
      */
@@ -51,11 +51,11 @@ export interface MigratorOptions {
      */
     readonly migrationsPath?: string;
     /**
-     * Custom storage implementation. Defaults to DatabaseMigrationStorage.
+     * Custom storage implementation. Defaults to DatabaseMigrationStorage, or MongoMigrationStorage on MongoDB.
      */
     readonly storage?: MigrationStorage;
     /**
-     * Table name for storing migration state. Defaults to 'uql_migrations'.
+     * Table, or MongoDB collection, name for storing migration state. Defaults to 'uql_migrations'.
      */
     readonly tableName?: string;
     /**

package/dist/type/querier.d.ts

@@ -144,6 +144,11 @@ export interface MongoQuerier extends Querier {
      */
     readonly db: Db;
 }
+/**
+ * Type guard for a querier over a MongoDB database. A handle alone does not tell: the SQLite, D1 and
+ * Turso queriers carry a `db` of their own.
+ */
+export declare function isMongoQuerier(querier: Querier): querier is MongoQuerier;
 /**
  * Context passed to global querier listeners.
  */

package/dist/type/querier.js

@@ -8,3 +8,10 @@ export function isSqlQuerier(querier) {
         q.dialect !== undefined &&
         typeof q.dialect.escapeIdChar === 'string');
 }
+/**
+ * Type guard for a querier over a MongoDB database. A handle alone does not tell: the SQLite, D1 and
+ * Turso queriers carry a `db` of their own.
+ */
+export function isMongoQuerier(querier) {
+    return 'db' in querier && !isSqlQuerier(querier);
+}

package/package.json

@@ -3,7 +3,7 @@
   "homepage": "https://uql-orm.dev",
   "description": "The JSON-native TypeScript ORM for Bun, Browsers, Edge, Deno, Node, Workers. Supports PostgreSQL, PGlite, MySQL, MariaDB, SQLite, CockroachDB, SQL Server, Turso, Neon, Cloudflare D1 and MongoDB. Queries are plain JSON, typed to the leaf.",
   "license": "MIT",
-  "version": "0.58.0",
+  "version": "0.60.0",
   "type": "module",
   "engines": {
     "node": ">=24"