@alexify/migronaut 2.1.0 → 2.3.0

package/src/core/server-info.js

@@ -0,0 +1,70 @@
+/**
+ * What converge and audit read about the server, and how: the read options
+ * forced onto every read, the pace of reading many collections, the server's
+ * version and topology, and the error codes for a namespace or an index that
+ * is not there. Mechanism only — no logger, no decisions.
+ */
+
+/**
+ * Read options forced onto both reads: the primary (a secondary may not have
+ * an index build yet), and BSON values as plain JavaScript — an injected
+ * client configured with `promoteValues: false` or `useBigInt64: true` would
+ * otherwise hand back `Int32` objects or `1n`, and everything would compare as
+ * changed.
+ */
+const READ_OPTIONS = Object.freeze({
+  readPreference: 'primary',
+  promoteLongs: true,
+  promoteValues: true,
+  useBigInt64: false,
+  bsonRegExp: false,
+});
+
+/** listIndexes calls in flight while reading many collections — a pace, not a pool */
+const READ_CONCURRENCY = 8;
+
+/**
+ * What the server is: a mongos in front of shards (its shard keys matter to
+ * 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, 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.
+  }
+  try {
+    const info = await db.admin().command({ buildInfo: 1 });
+    const [major, minor, patch] = Array.isArray(info?.versionArray) ? info.versionArray : [];
+    if (Number.isInteger(major) && Number.isInteger(minor)) {
+      server.version = { major, minor, ...(Number.isInteger(patch) ? { patch } : {}) };
+    }
+  } catch {
+    // Unknown version: only the always-available in-place changes.
+  }
+  return server;
+}
+
+const NAMESPACE_NOT_FOUND = 26;
+
+const INDEX_NOT_FOUND = 27;
+
+module.exports = {
+  INDEX_NOT_FOUND,
+  NAMESPACE_NOT_FOUND,
+  READ_CONCURRENCY,
+  READ_OPTIONS,
+  readServer,
+};

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

@@ -243,11 +243,15 @@ class QueueJobFailedError extends MigronautError {
 
 /**
  * Thrown by `converge` when the database cannot be brought to the declared
- * state: the plan has a conflict (refused before any write — `context.phase`
- * is `'plan'`), or a step failed (`'apply'`). `context.converge` is the
- * converge result so far — which steps were applied, which failed, which were
- * never reached — and `context.hint`, when present, says what usually fixes
- * the server error behind it.
+ * state. `context.phase` says where it stopped: `'plan'` (a conflict refused
+ * the run before any write), `'replan'` (a collection changed while the run
+ * was under way), `'apply'` (a step failed) or `'wait'` (the search index
+ * builds did not finish — `context.reason`: `'failed'`, `'timeout'` or
+ * `'unreadable'`). A search index list that could not be read is reported in
+ * the phase that read it. `context.converge` is the converge result so far —
+ * which steps were applied, which failed, which were never reached — and
+ * `context.hint`, when present, says what usually fixes the server error
+ * behind it.
  */
 class ConvergeFailedError extends MigronautError {
   constructor(message, context, options) {
@@ -256,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,
@@ -282,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/canonical.js

@@ -100,6 +100,31 @@ function regExpIssue(value, seen = new Set()) {
   return null;
 }
 
+/**
+ * Why `value` cannot be sent as declared — a function, a symbol, a cycle, or a
+ * RegExp the driver would change (see {@link regExpIssue}) — or null. Walks
+ * plain objects and arrays, the shapes a declaration is written in.
+ */
+function unsendable(value, seen = new Set()) {
+  if (seen.size === 0) {
+    const issue = regExpIssue(value);
+    if (issue) return issue;
+  }
+  const type = typeof value;
+  if (type === 'function') return 'must not contain functions';
+  if (type === 'symbol') return 'must not contain symbols';
+  if (value === null || type !== 'object') return null;
+  if (seen.has(value)) return 'must not contain circular references';
+  seen.add(value);
+  const items = Array.isArray(value) ? value : isPlainObject(value) ? Object.values(value) : [];
+  for (const item of items) {
+    const reason = unsendable(item, seen);
+    if (reason) return reason;
+  }
+  seen.delete(value);
+  return null;
+}
+
 /**
  * Assign without invoking setters: a key named `__proto__` (JSON.parse makes
  * one an own property) must stay a key, not replace the object's prototype —
@@ -176,4 +201,12 @@ function toWire(value) {
   return out;
 }
 
-module.exports = { canonical, deepEqual, isPlainObject, regExpIssue, toWire };
+module.exports = {
+  assign,
+  canonical,
+  deepEqual,
+  isPlainObject,
+  regExpIssue,
+  toWire,
+  unsendable,
+};

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,
+};