@alexify/migronaut 2.2.0 → 2.3.0

package/src/core/options.js

@@ -152,6 +152,20 @@ function assertConvergeAfterUpValid(converge, filename, to) {
   }
 }
 
+/**
+ * `onBackgroundPending`: what a run does at a migration that `requires` a
+ * background migration not completed yet — `'error'` (throw
+ * BackgroundPendingError) or `'stop'` (end the run there, cleanly).
+ */
+function assertBackgroundPendingValid(onBackgroundPending) {
+  if (onBackgroundPending === undefined) return;
+  if (onBackgroundPending !== 'error' && onBackgroundPending !== 'stop') {
+    throw new ConfigInvalidError("onBackgroundPending must be 'error' or 'stop'", {
+      onBackgroundPending,
+    });
+  }
+}
+
 /** `up(filename, options)` */
 function assertUpOptions(filename, options) {
   assertFilename(filename);
@@ -167,6 +181,7 @@ function assertUpOptions(filename, options) {
   assertOrderedValid(options.ordered, filename);
   assertConvergeAfterUpValid(options.converge, filename, options.to);
   assertChecksumValid(options.checksum, filename);
+  assertBackgroundPendingValid(options.onBackgroundPending);
   assertActorValid(options);
 }
 
@@ -254,6 +269,7 @@ function assertImportOptions(options) {
 }
 
 module.exports = {
+  assertActorValid,
   assertConvergeOptions,
   assertDownOptions,
   assertDryRunOptions,

package/src/core/run.js

@@ -41,6 +41,7 @@ const { MigratorKit, RECORD_LOCK_WAIT } = require('./migrator.js');
 async function runMigrations(config = {}, options = {}) {
   const {
     noLock,
+    onBackgroundPending,
     onLockHeld = 'throw',
     // Left undefined unless given: the default then follows the holder's TTL.
     lockWaitTimeoutMs,
@@ -71,6 +72,11 @@ async function runMigrations(config = {}, options = {}) {
   kit.on('converge:end', (event) => {
     if (event.trigger === 'up' && event.success) converge = event.result;
   });
+  // With onBackgroundPending: 'stop', where the run stopped and what for.
+  const waiting = [];
+  kit.on('background:waiting', (event) => {
+    waiting.push({ migration: event.migration, waitsFor: event.waitsFor });
+  });
 
   // An abort reaches the run wherever it is: the wait loop sees the signal
   // between polls, and kit.stop() stops a run that is setting up or between
@@ -90,20 +96,28 @@ async function runMigrations(config = {}, options = {}) {
       waited,
       waitedMs,
       attempts,
-    } = await withLockWait(() => kit.up(undefined, noLock ? { noLock: true } : {}), {
-      onLockHeld,
-      ...(lockWaitTimeoutMs !== undefined ? { lockWaitTimeoutMs } : {}),
-      ...(lockPollIntervalMs !== undefined ? { lockPollIntervalMs } : {}),
-      // Resolved AFTER connect, from the kit's own merged config: a `logger:
-      // null` in the config file must silence the wait lines too, not only
-      // the kit's own.
-      logger: kit.logger,
-      ...(signal ? { signal } : {}),
-      onSettle: (wait) => kit[RECORD_LOCK_WAIT](wait),
-    });
+    } = await withLockWait(
+      () =>
+        kit.up(undefined, {
+          ...(noLock ? { noLock: true } : {}),
+          ...(onBackgroundPending !== undefined ? { onBackgroundPending } : {}),
+        }),
+      {
+        onLockHeld,
+        ...(lockWaitTimeoutMs !== undefined ? { lockWaitTimeoutMs } : {}),
+        ...(lockPollIntervalMs !== undefined ? { lockPollIntervalMs } : {}),
+        // Resolved AFTER connect, from the kit's own merged config: a `logger:
+        // null` in the config file must silence the wait lines too, not only
+        // the kit's own.
+        logger: kit.logger,
+        ...(signal ? { signal } : {}),
+        onSettle: (wait) => kit[RECORD_LOCK_WAIT](wait),
+      },
+    );
     return {
       applied,
-      upToDate: applied.length === 0,
+      upToDate: applied.length === 0 && waiting.length === 0,
+      ...(waiting.length > 0 ? { waiting } : {}),
       waited,
       waitedMs,
       attempts,

package/src/core/runner.js

@@ -197,4 +197,4 @@ async function runMigration(params) {
   }
 }
 
-module.exports = { runMigration };
+module.exports = { isTransactionsUnsupported, runMigration };

package/src/core/server-info.js

@@ -25,16 +25,23 @@ const READ_CONCURRENCY = 8;
 
 /**
  * What the server is: a mongos in front of shards (its shard keys matter to
- * prune), and its version (what it can change in place). Best-effort — a
+ * prune), its topology (`replicaSet`, `sharded`, `standalone` — transactions
+ * need one of the first two), and its version (what it can change in place). Best-effort — a
  * server that refuses to say gets the conservative answer: no in-place
  * extras, no shard-key handling.
  */
 async function readServer(db) {
-  const server = { mongos: false, version: undefined };
+  const server = { mongos: false, version: undefined, topology: undefined };
   if (typeof db.admin !== 'function') return server;
   try {
     const hello = await db.admin().command({ hello: 1 });
     server.mongos = hello?.msg === 'isdbgrid';
+    // What transactions need: a replica set member or a mongos.
+    server.topology = server.mongos
+      ? 'sharded'
+      : typeof hello?.setName === 'string'
+        ? 'replicaSet'
+        : 'standalone';
   } catch {
     // Unknown — treated as a replica set or standalone.
   }

package/src/core/shard-info.js

@@ -0,0 +1,76 @@
+const { READ_OPTIONS } = require('./server-info.js');
+
+/**
+ * What the cluster says about a collection's sharding — read from the
+ * `config` database through a mongos. Every read here needs `clusterMonitor`
+ * (or more): a user without it gets `undefined` ("unknown"), never an error,
+ * and the caller falls back to what works without it.
+ *
+ * - `readShardKey` — the shard key, or `null` for a collection that is not
+ *   sharded (an 8.0 `unsplittable` one included: tracked, but on one shard
+ *   under `{ _id: 1 }`, which is no key to partition or target by);
+ * - `readChunks` — the chunks of a sharded collection, in key order.
+ */
+
+/** The server's "not authorized" — the one refusal that means "unknown", not "broken" */
+const UNAUTHORIZED = 13;
+
+const isUnauthorized = (error) => error?.code === UNAUTHORIZED;
+
+/**
+ * `{ key, uuid, timestamp, unsplittable }` of a sharded collection, `null` when
+ * it is not sharded, `undefined` when `config.collections` may not be read.
+ */
+async function readShardKey(client, dbName, collection) {
+  let entry;
+  try {
+    entry = await client
+      .db('config')
+      .collection('collections')
+      .findOne(
+        { _id: `${dbName}.${collection}` },
+        { projection: { key: 1, uuid: 1, timestamp: 1, unsplittable: 1 }, ...READ_OPTIONS },
+      );
+  } catch (error) {
+    if (isUnauthorized(error)) return undefined;
+    throw error;
+  }
+  if (entry === null || entry.unsplittable === true || entry.key === undefined) return null;
+  return {
+    key: entry.key,
+    uuid: entry.uuid,
+    ...(entry.timestamp !== undefined ? { timestamp: entry.timestamp } : {}),
+  };
+}
+
+/**
+ * The chunks of a sharded collection (`readShardKey`'s result), in key order:
+ * `[{ min, max, shard }]` — or `undefined` when `config.chunks` may not be
+ * read. By `uuid` (5.0+), then by namespace (a cluster upgraded from 4.4 that
+ * never refreshed its chunks).
+ */
+async function readChunks(client, dbName, collection, sharding) {
+  const chunks = client.db('config').collection('chunks');
+  // Hashed bounds are NumberLongs: promoted to numbers, they lose precision
+  // past 2^53 (ARCHITECTURE §6.8).
+  const options = {
+    projection: { min: 1, max: 1, shard: 1 },
+    ...READ_OPTIONS,
+    promoteLongs: false,
+  };
+  try {
+    let rows = await chunks.find({ uuid: sharding.uuid }, options).sort({ min: 1 }).toArray();
+    if (rows.length === 0) {
+      rows = await chunks
+        .find({ ns: `${dbName}.${collection}` }, options)
+        .sort({ min: 1 })
+        .toArray();
+    }
+    return rows;
+  } catch (error) {
+    if (isUnauthorized(error)) return undefined;
+    throw error;
+  }
+}
+
+module.exports = { isUnauthorized, readChunks, readShardKey };

package/src/core/versioning-spec.js

@@ -0,0 +1,181 @@
+const { isPlainObject } = require('../utils/canonical.js');
+const { versionIndexKey } = require('../versioning/document.js');
+const { toCount } = require('../versioning/internal.js');
+
+/**
+ * What a collection's `versioning` block asks of the database: the validator
+ * rules for the version and revision fields, merged into whatever validator
+ * the definition declares, and the index every version-filtered scan uses.
+ * Pure — collections.js folds the result into the normalized definition, so
+ * the planner sees an ordinary validator and an ordinary index.
+ *
+ * The version rule has a `minimum` but never a `maximum`: during a rolling
+ * deploy (or after a rollback) a newer release writes a higher version than
+ * the declaration knows, and refusing that write would turn a deploy into an
+ * outage. A revision outgrows `int` after 2³¹ writes — `$inc` turns it into a
+ * `long` — so both are accepted.
+ */
+
+/** `{ required, properties }` for the managed fields, in a fixed order */
+function versioningRules(versioning) {
+  const { field, min, revisionField } = versioning;
+  const properties = { [field]: { bsonType: 'int', minimum: min } };
+  const required = [field];
+  if (revisionField !== null) {
+    properties[revisionField] = { bsonType: ['int', 'long'], minimum: 0 };
+    required.push(revisionField);
+  }
+  // `min: 0` adapts a collection whose documents predate versioning: the
+  // fields are typed when present, but nothing requires them yet.
+  return min === 0 ? { properties } : { required, properties };
+}
+
+/** The managed field names a validator already constrains itself */
+function managedFieldsIn(validator, versioning) {
+  const managed = [versioning.field];
+  if (versioning.revisionField !== null) managed.push(versioning.revisionField);
+  const found = new Set();
+  const schema = validator.$jsonSchema;
+  const properties = isPlainObject(schema) ? schema.properties : undefined;
+  const required = new Set(
+    isPlainObject(schema) && Array.isArray(schema.required) ? schema.required : [],
+  );
+  for (const name of managed) {
+    if (Object.hasOwn(validator, name)) found.add(name);
+    if (isPlainObject(properties) && Object.hasOwn(properties, name)) found.add(name);
+    if (required.has(name)) found.add(name);
+  }
+  return [...found];
+}
+
+/**
+ * Why a declared validator cannot carry the versioning rules — it constrains
+ * a managed field itself, or its `$jsonSchema` is not a schema object. Empty
+ * when the merge can go ahead.
+ */
+function validatorVersioningIssues(validator, versioning) {
+  if (validator === undefined) return [];
+  if (validator === null || !isPlainObject(validator)) {
+    return ['is null, which would remove the versioning rules — drop the validator key instead'];
+  }
+  const issues = [];
+  if (validator.$jsonSchema !== undefined && !isPlainObject(validator.$jsonSchema)) {
+    issues.push('$jsonSchema must be an object to take the versioning rules');
+  } else if (
+    isPlainObject(validator.$jsonSchema) &&
+    validator.$jsonSchema.required !== undefined &&
+    !Array.isArray(validator.$jsonSchema.required)
+  ) {
+    issues.push('$jsonSchema.required must be an array to take the versioning rules');
+  }
+  for (const name of managedFieldsIn(validator, versioning)) {
+    issues.push(`constrains "${name}", which is managed by versioning — remove that rule`);
+  }
+  return issues;
+}
+
+/**
+ * The validator to declare: the versioning rules alone (no validator
+ * declared), merged into the declared `$jsonSchema` (the declared `required`
+ * and `properties` first, ours after), or — next to query operators — added
+ * as a top-level `$jsonSchema`, which the server combines with them.
+ */
+function mergeVersioningValidator(validator, versioning) {
+  const rules = versioningRules(versioning);
+  if (validator === undefined || Object.keys(validator).length === 0) {
+    return { $jsonSchema: rules };
+  }
+  const schema = validator.$jsonSchema;
+  if (!isPlainObject(schema)) return { ...validator, $jsonSchema: rules };
+  const merged = { ...schema };
+  if (rules.required) merged.required = [...(schema.required ?? []), ...rules.required];
+  merged.properties = { ...schema.properties, ...rules.properties };
+  return { ...validator, $jsonSchema: merged };
+}
+
+/** The declared version index — `{ [field]: 1, _id: 1 }`, named by its key */
+const versioningIndex = (versioning) => ({ key: versionIndexKey(versioning) });
+
+/**
+ * The version index of a sharded collection: the shard key between the
+ * version field and `_id` — `{ __v: 1, region: 1, _id: 1 }` — so a batch
+ * over one chunk's range is an index range, not a filter over every old
+ * document of the shard. A hashed field stays hashed; `_id` is not repeated
+ * when the key holds it. On `{ _id: 1 }` it is the ordinary version index.
+ */
+function shardedVersionIndexKey(versioning, shardKey) {
+  const key = { [versioning.field]: 1 };
+  for (const [field, value] of Object.entries(shardKey)) {
+    if (field !== versioning.field) key[field] = value;
+  }
+  if (!('_id' in key)) key._id = 1;
+  return key;
+}
+
+/** Whether an index key is the version index's (same fields, same order, ascending) */
+function isVersioningIndexKey(key, versioning) {
+  if (!isPlainObject(key)) return false;
+  const entries = Object.entries(key);
+  const expected = Object.entries(versionIndexKey(versioning));
+  if (entries.length !== expected.length) return false;
+  for (let i = 0; i < entries.length; i++) {
+    if (entries[i][0] !== expected[i][0] || Number(entries[i][1]) !== expected[i][1]) return false;
+  }
+  return true;
+}
+
+/**
+ * The version floor the live validator enforces — the `minimum` of the version
+ * field's `$jsonSchema` rule — or `null` when it enforces none.
+ */
+function liveVersionFloor(options, versioning) {
+  const schema = options?.validator?.$jsonSchema;
+  const rule = isPlainObject(schema?.properties) ? schema.properties[versioning.field] : undefined;
+  return isPlainObject(rule) ? toCount(rule.minimum) : null;
+}
+
+/**
+ * The `min` converge must check the data against before it raises the floor,
+ * or `null` when there is nothing to check: no versioning, `min: 0`, a
+ * collection that does not exist yet (no documents), or a floor already that
+ * high. Only a rising floor costs a read — the steady state costs nothing.
+ */
+function versionFloorToCheck(definition, live) {
+  const versioning = definition.versioning;
+  if (!versioning || versioning.min === 0 || !live.exists) return null;
+  if (live.type !== undefined && live.type !== 'collection') return null;
+  const floor = liveVersionFloor(live.options, versioning);
+  return floor !== null && floor >= versioning.min ? null : versioning.min;
+}
+
+/**
+ * Why the version floor cannot be raised — `live.versionFloor` is what
+ * converge read: `{ min, below: true | false | 'unknown', error? }` — or
+ * `undefined` when it can. The document ids are never named: they may be PII.
+ */
+function versionFloorConflict(floor) {
+  if (!floor || floor.below === false) return undefined;
+  if (floor.below === true) {
+    return (
+      `documents below version ${floor.min} remain — raising versioning.min would leave them ` +
+      'invalid; let the background migration that upgrades them finish (migronaut background ' +
+      'status), then converge again'
+    );
+  }
+  return (
+    `could not check for documents below version ${floor.min} (${floor.error}) — converge ` +
+    'with the old min first so the version index exists, then raise it'
+  );
+}
+
+module.exports = {
+  isVersioningIndexKey,
+  shardedVersionIndexKey,
+  liveVersionFloor,
+  versionFloorConflict,
+  versionFloorToCheck,
+  mergeVersioningValidator,
+  validatorVersioningIssues,
+  versioningIndex,
+  versioningRules,
+};

package/src/errors/index.js

@@ -260,6 +260,88 @@ class ConvergeFailedError extends MigronautError {
   }
 }
 
+/**
+ * Thrown by the optimistic-concurrency helpers (`@alexify/migronaut/versioning`)
+ * when a revision-guarded write matched nothing. `context.reason` says why:
+ * `'conflict'` (the document exists at another revision — `context.actual`),
+ * `'not-found'` (no document matches the filter at all) or `'unknown'` (the
+ * follow-up read was skipped or could not tell). `context.expected` is the
+ * revision the caller held. The filter is never copied in — it may carry PII.
+ */
+class RevisionConflictError extends MigronautError {
+  constructor(message, context, options) {
+    super('REVISION_CONFLICT', message, context, options);
+    this.name = 'RevisionConflictError';
+  }
+}
+
+/**
+ * Thrown by an upcaster that cannot bring a document to the current shape:
+ * `context.reason` is `'newer'` (written by a newer release), `'below-min'`
+ * (older than the oldest shape still supported) or `'invalid'` (the version
+ * field is not a non-negative integer, or a step returned something that is
+ * not a document).
+ */
+class ShapeVersionError extends MigronautError {
+  constructor(message, context, options) {
+    super('SHAPE_VERSION_UNSUPPORTED', message, context, options);
+    this.name = 'ShapeVersionError';
+  }
+}
+
+/**
+ * Thrown when a migration `requires` a background migration that has not
+ * completed yet — or whose collection still holds documents of the old shape.
+ * Nothing was run: `context.waitsFor` names the background migrations it
+ * waits for, with their status.
+ */
+class BackgroundPendingError extends MigronautError {
+  constructor(message, context, options) {
+    super('BACKGROUND_PENDING', message, context, options);
+    this.name = 'BackgroundPendingError';
+  }
+}
+
+/**
+ * Thrown when a background migration ended `failed` — a partition used up its
+ * slice failures, the document error budget ran out, or old-shape documents
+ * kept appearing for `maxPasses` passes. `context.migration` names it and
+ * `context.lastError` says what happened last.
+ */
+class BackgroundFailedError extends MigronautError {
+  constructor(message, context, options) {
+    super('BACKGROUND_FAILED', message, context, options);
+    this.name = 'BackgroundFailedError';
+  }
+}
+
+/**
+ * Thrown when a control action does not fit the background migration's state
+ * — pausing a completed one, resuming one that is not paused, retrying one
+ * that is still running. `context.status` is the state it found and
+ * `context.action` what was asked.
+ */
+class BackgroundConflictError extends MigronautError {
+  constructor(message, context, options) {
+    super('BACKGROUND_CONFLICT', message, context, options);
+    this.name = 'BackgroundConflictError';
+  }
+}
+
+/**
+ * Thrown by the dry-run sandbox when a step reaches for something it cannot
+ * run inside an always-aborted transaction — DDL, an admin command, another
+ * session, `$out`/`$merge`, a migronaut-internal collection. `context.method`
+ * names the call and `context.reason` the rule it broke. A dry run reports
+ * every refusal even when the step caught the error itself.
+ */
+class SandboxRefusedError extends MigronautError {
+  constructor(message, context, options) {
+    super('SANDBOX_REFUSED', message, context, options);
+    this.name = 'SandboxRefusedError';
+  }
+}
+
 module.exports = {
   MigronautError,
   LockAlreadyHeldError,
@@ -286,4 +368,10 @@ module.exports = {
   QueueJobInvalidError,
   QueueJobFailedError,
   ConvergeFailedError,
+  RevisionConflictError,
+  ShapeVersionError,
+  BackgroundPendingError,
+  BackgroundFailedError,
+  BackgroundConflictError,
+  SandboxRefusedError,
 };

package/src/index.js

@@ -1,8 +1,12 @@
 const { EXIT_CODES } = require('./cli/exit-codes.js');
+const { startBackgroundRunner } = require('./core/background-runner.js');
 const { MigratorKit } = require('./core/migrator.js');
 const { pendingMigrations, runMigrations } = require('./core/run.js');
 const { createLogger } = require('./utils/logger.js');
 const {
+  BackgroundConflictError,
+  BackgroundFailedError,
+  BackgroundPendingError,
   ChecksumMismatchError,
   ConfigFileExistsError,
   ConfigInvalidError,
@@ -27,7 +31,10 @@ const {
   OutOfOrderMigrationError,
   QueueJobFailedError,
   QueueJobInvalidError,
+  RevisionConflictError,
   RunAbortedError,
+  SandboxRefusedError,
+  ShapeVersionError,
 } = require('./errors/index.js');
 
 module.exports = {
@@ -46,7 +53,13 @@ module.exports = {
   // The CLI's exit-code map, for wrappers that mirror its semantics
   EXIT_CODES,
 
+  // Background migrations driven from inside the application (experimental)
+  startBackgroundRunner,
+
   // Error classes
+  BackgroundConflictError,
+  BackgroundFailedError,
+  BackgroundPendingError,
   ChecksumMismatchError,
   ConfigFileExistsError,
   ConfigInvalidError,
@@ -71,5 +84,8 @@ module.exports = {
   OutOfOrderMigrationError,
   QueueJobFailedError,
   QueueJobInvalidError,
+  RevisionConflictError,
   RunAbortedError,
+  SandboxRefusedError,
+  ShapeVersionError,
 };

package/src/utils/error.js

@@ -1,5 +1,5 @@
 const { MigronautError } = require('../errors/index.js');
-const { redactUris } = require('./redact.js');
+const { redactOutbound, redactUris } = require('./redact.js');
 
 /**
  * Human-readable message from any thrown value, with URI credentials masked.
@@ -25,4 +25,13 @@ function errorWithCause(error) {
   return cause ? `${message} — ${cause}` : message;
 }
 
-module.exports = { errorText, errorWithCause };
+/**
+ * {@link errorText} for an error about the application's data — a background
+ * migration's document errors and failed slices, kept in its state and
+ * logged: the values a server error quotes (an E11000's duplicate key — an
+ * email, a phone number) are masked too. Migronaut never logs a document's
+ * contents; the index name still says which constraint was violated.
+ */
+const documentErrorText = (error) => redactOutbound(errorText(error));
+
+module.exports = { documentErrorText, errorText, errorWithCause };

package/src/utils/loader.js

@@ -3,6 +3,7 @@ const path = require('node:path');
 const { pathToFileURL } = require('node:url');
 const { MigrationFileNotFoundError, MigrationInvalidExportError } = require('../errors/index.js');
 const { errorText } = require('./error.js');
+const { requiresIssues } = require('./migration-name.js');
 
 /** TypeScript source extensions that require a TS-capable runtime to import */
 const TS_EXTENSIONS = new Set(['.ts', '.mts', '.cts']);
@@ -96,16 +97,13 @@ function importUserFile(filepath, options = {}) {
 }
 
 /**
- * Dynamically load a migration file and validate its exports.
- *
- * Handles all three supported formats:
- * - TypeScript / JavaScript ESM named exports (`export async function up/down`)
- * - CommonJS default export (`module.exports = { up, down }`)
+ * Import a migration file: its module, resolved — the default export of a
+ * CommonJS file, the namespace of an ES module with named exports.
  *
  * @throws {MigrationFileNotFoundError} when the file does not exist
- * @throws {MigrationInvalidExportError} when up/down are not both functions
+ * @throws {MigrationInvalidExportError} when TypeScript cannot be loaded
  */
-async function loadMigrationFile(filepath, options = {}) {
+async function importMigrationModule(filepath, options = {}) {
   try {
     await fs.access(filepath);
   } catch {
@@ -123,7 +121,48 @@ async function loadMigrationFile(filepath, options = {}) {
     throw error;
   }
   // `mod.default ?? mod` handles the CommonJS default-export case
-  const resolved = imported.default ?? imported;
+  return imported.default ?? imported;
+}
+
+/** The `requires` export, validated against the file's own name */
+function readRequires(resolved, filepath) {
+  if (resolved.requires === undefined) return {};
+  const issues = requiresIssues(resolved.requires, path.basename(filepath));
+  if (issues.length > 0) {
+    throw new MigrationInvalidExportError(`Invalid ${issues[0].path}: ${issues[0].message}`, {
+      filepath,
+      issues,
+    });
+  }
+  return { requires: [...resolved.requires] };
+}
+
+/**
+ * What a migration module exports, validated: a regular migration
+ * (`{ up, down, useTransaction?, timeoutMs?, description?, requires? }`) or a
+ * background one (`{ kind: 'background', background, description?,
+ * requires? }` — its spec is validated where the collection's versioning is
+ * known). A file with both `background` and `up`/`down` is refused: the
+ * expand steps belong in a migration of their own.
+ *
+ * @throws {MigrationInvalidExportError}
+ */
+function resolveMigrationExports(resolved, filepath) {
+  if (resolved.background !== undefined) {
+    if (resolved.up !== undefined || resolved.down !== undefined) {
+      throw new MigrationInvalidExportError(
+        'A background migration exports no up() or down() — put the expand steps in a ' +
+          'migration of their own',
+        { filepath },
+      );
+    }
+    return {
+      kind: 'background',
+      background: resolved.background,
+      ...(typeof resolved.description === 'string' ? { description: resolved.description } : {}),
+      ...readRequires(resolved, filepath),
+    };
+  }
 
   if (!isFunction(resolved.up) || !isFunction(resolved.down)) {
     throw new MigrationInvalidExportError('Migration must export async up() and down() functions', {
@@ -142,8 +181,37 @@ async function loadMigrationFile(filepath, options = {}) {
   if (typeof resolved.description === 'string') {
     migration.description = resolved.description;
   }
+  Object.assign(migration, readRequires(resolved, filepath));
 
   return migration;
 }
 
-module.exports = { importUserFile, loadMigrationFile, tsLoadErrorOrNull, tsLoadMessageOrNull };
+/**
+ * Dynamically load a migration file and validate its exports.
+ *
+ * Handles all three supported formats:
+ * - TypeScript / JavaScript ESM named exports (`export async function up/down`)
+ * - CommonJS default export (`module.exports = { up, down }`)
+ *
+ * A background migration (`kind: 'background'`) is returned like any other:
+ * the caller tells it apart by its kind.
+ *
+ * @throws {MigrationFileNotFoundError} when the file does not exist
+ * @throws {MigrationInvalidExportError} when up/down are not both functions
+ */
+async function loadMigrationFile(filepath, options = {}) {
+  const migration = resolveMigrationExports(
+    await importMigrationModule(filepath, options),
+    filepath,
+  );
+  return migration;
+}
+
+module.exports = {
+  importMigrationModule,
+  importUserFile,
+  loadMigrationFile,
+  resolveMigrationExports,
+  tsLoadErrorOrNull,
+  tsLoadMessageOrNull,
+};