@alexify/migronaut 1.0.0

package/src/core/run.js

@@ -0,0 +1,144 @@
+const { setTimeout: delay } = require('node:timers/promises');
+const { ConfigInvalidError, LockAlreadyHeldError } = require('../errors/index.js');
+const { MigratorKit } = require('./migrator.js');
+
+/**
+ * Longer than the default 60s lock TTL on purpose: with a shorter budget, a peer
+ * migration that outlives it makes every waiting instance fail to boot, even
+ * though the peer is healthy and still holding a valid lock.
+ */
+const DEFAULT_LOCK_WAIT_TIMEOUT_MS = 90_000;
+const DEFAULT_LOCK_POLL_INTERVAL_MS = 500;
+/** ±25% jitter so N instances booting together stop polling in lockstep */
+const POLL_JITTER_RATIO = 0.25;
+
+function jitteredDelay(baseMs) {
+  const spread = baseMs * POLL_JITTER_RATIO;
+  return Math.max(1, Math.round(baseMs - spread + Math.random() * spread * 2));
+}
+
+/**
+ * Run all pending migrations and return a summary — the blessed one-call entry
+ * point for application startup, deploy hooks, serverless cold starts, and test
+ * setup.
+ *
+ * Unlike driving MigratorKit by hand, this opens its own connection,
+ * runs pending `up` migrations, and **always disconnects in a `finally`** so a
+ * failure never leaks a MongoDB connection. Migration errors propagate
+ * unchanged (as MigronautError subclasses with a typed `code`) so a broken
+ * migration aborts your boot sequence instead of starting the app against a
+ * half-migrated database.
+ *
+ * For multi-instance deploys, set `onLockHeld: 'wait'` so instances that lose
+ * the race to acquire the lock block until the migrating peer finishes, then
+ * confirm there is nothing left to apply.
+ *
+ * @example
+ * ```js
+ * const { runMigrations } = require('@alexify/migronaut');
+ *
+ * const { applied, upToDate } = await runMigrations(
+ *   { uri: process.env.MIGRONAUT_URI, dbName: 'my_app' },
+ *   { onLockHeld: 'wait' },
+ * );
+ * if (!upToDate) console.log(`Applied ${applied.length} migration(s)`);
+ * ```
+ */
+async function runMigrations(config = {}, options = {}) {
+  const {
+    noLock,
+    onLockHeld = 'throw',
+    lockWaitTimeoutMs = DEFAULT_LOCK_WAIT_TIMEOUT_MS,
+    lockPollIntervalMs = DEFAULT_LOCK_POLL_INTERVAL_MS,
+    ...kitOptions
+  } = options;
+
+  // Validated before anything connects. A NaN here (or any non-positive value)
+  // disables every deadline comparison below — `NaN > deadline` is always
+  // false — turning the wait loop into an unbounded retry storm against the
+  // lock collection that never returns and never surfaces the real error.
+  if (!Number.isFinite(lockWaitTimeoutMs) || lockWaitTimeoutMs <= 0) {
+    throw new ConfigInvalidError('lockWaitTimeoutMs must be a positive finite number', {
+      lockWaitTimeoutMs,
+    });
+  }
+  if (!Number.isFinite(lockPollIntervalMs) || lockPollIntervalMs <= 0) {
+    throw new ConfigInvalidError('lockPollIntervalMs must be a positive finite number', {
+      lockPollIntervalMs,
+    });
+  }
+
+  const kit = new MigratorKit(config, kitOptions);
+  let waited = false;
+  let waitedMs = 0;
+  let attempts = 0;
+
+  try {
+    await kit.connect();
+    // Resolved AFTER connect, from the kit's own merged config: a `logger:
+    // null` in the config file must silence this module's lines too, not only
+    // the kit's own.
+    const logger = kit.logger;
+    // The clock starts at the first contention, not before the first attempt —
+    // otherwise a slow initial attempt eats the whole waiting budget.
+    let deadline;
+
+    for (;;) {
+      try {
+        attempts += 1;
+        const applied = await kit.up(undefined, noLock ? { noLock: true } : {});
+        return { applied, upToDate: applied.length === 0, waited, waitedMs, attempts };
+      } catch (error) {
+        if (onLockHeld !== 'wait' || !(error instanceof LockAlreadyHeldError)) {
+          throw error;
+        }
+        deadline ??= Date.now() + lockWaitTimeoutMs;
+        const nextDelay = jitteredDelay(lockPollIntervalMs);
+        if (Date.now() + nextDelay > deadline) {
+          throw error;
+        }
+        if (!waited) {
+          logger.info('Migration lock held by another process — waiting for it to release…');
+        }
+        waited = true;
+        logger.debug('Migration lock still held — retrying', {
+          attempts,
+          waitedMs,
+          nextDelayMs: nextDelay,
+        });
+        waitedMs += nextDelay;
+        await delay(nextDelay);
+      }
+    }
+  } finally {
+    await kit.disconnect().catch(() => undefined);
+  }
+}
+
+/**
+ * Return the migrations that have not yet been applied — a connection-managed
+ * readiness probe. Opens its own connection and always disconnects in a
+ * `finally`. Use it to fail a deploy/health check when the database is behind
+ * (`(await pendingMigrations(config)).length === 0`) without running anything.
+ *
+ * @example
+ * ```js
+ * const { pendingMigrations } = require('@alexify/migronaut');
+ *
+ * const pending = await pendingMigrations({ uri, dbName: 'my_app' });
+ * if (pending.length > 0) {
+ *   throw new Error(`Database is behind by ${pending.length} migration(s)`);
+ * }
+ * ```
+ */
+async function pendingMigrations(config = {}, options = {}) {
+  const kit = new MigratorKit(config, options);
+  try {
+    await kit.connect();
+    return await kit.list('pending');
+  } finally {
+    await kit.disconnect().catch(() => undefined);
+  }
+}
+
+module.exports = { runMigrations, pendingMigrations };

package/src/core/runner.js

@@ -0,0 +1,150 @@
+const {
+  MigrationExecutionFailedError,
+  MigrationTimeoutError,
+  TransactionsUnsupportedError,
+} = require('../errors/index.js');
+const { errorText } = require('../utils/error.js');
+
+/**
+ * True when the driver refused to start a transaction because the deployment
+ * cannot run one (standalone server; code 20 = IllegalOperation). Matched on
+ * the message too, since older servers phrase it without the code.
+ */
+function isTransactionsUnsupported(error) {
+  if (typeof error !== 'object' || error === null) return false;
+  return (
+    error.code === 20 ||
+    (typeof error.message === 'string' &&
+      error.message.includes('Transaction numbers are only allowed'))
+  );
+}
+
+/**
+ * Race a migration against its timeout.
+ *
+ * Best-effort by design: JavaScript cannot cancel a running function, so the
+ * migration keeps executing in the background after this rejects. What the
+ * timeout buys is the *run* stopping instead of hanging forever — which also
+ * lets the lock's TTL expire, so a wedged migration no longer blocks every
+ * other instance indefinitely. Migrations that need real cancellation should
+ * watch `ctx.signal`.
+ */
+async function withTimeout(promise, timeoutMs, name, direction) {
+  if (!timeoutMs) return promise;
+  let timer;
+  try {
+    return await Promise.race([
+      promise,
+      new Promise((_resolve, reject) => {
+        timer = setTimeout(() => {
+          // The body keeps running after this rejects (see docblock), and its
+          // eventual rejection — e.g. MongoExpiredSessionError once the caller
+          // ends the session — would otherwise surface as an
+          // unhandledRejection long after the run already reported the
+          // timeout. Swallow it: the timeout is the reported failure.
+          Promise.resolve(promise).catch(() => {});
+          reject(
+            new MigrationTimeoutError(
+              `Migration ${direction} timed out after ${timeoutMs}ms: ${name}`,
+              {
+                name,
+                direction,
+                timeoutMs,
+              },
+            ),
+          );
+        }, timeoutMs);
+        timer.unref?.();
+      }),
+    ]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Execute a single migration's `up` or `down` safely.
+ *
+ * When `useTransaction` is true the call runs inside `session.withTransaction()`,
+ * which commits on success, aborts on failure, and — unlike a hand-rolled
+ * start/commit pair — retries `TransientTransactionError` and
+ * `UnknownTransactionCommitResult` per the driver's documented commit protocol.
+ *
+ * `onSuccess(duration, session)` runs inside the same transaction, right after
+ * the migration body. That is what makes the changelog write atomic with the
+ * migration itself: a crash between the two can no longer leave a migration
+ * applied but unrecorded (which would silently re-run it on the next `up`).
+ *
+ * On any error the `onError` hook is invoked before a
+ * MigrationExecutionFailedError is thrown — the error is never swallowed, and a
+ * throwing hook cannot mask the original failure.
+ */
+async function runMigration(params) {
+  const { name, migration, direction, context, useTransaction, hooks, onSuccess, logger } = params;
+  const fn = direction === 'up' ? migration.up : migration.down;
+  // A per-file `export const timeoutMs` overrides the global setting.
+  const timeoutMs = migration.timeoutMs ?? params.timeoutMs;
+
+  const start = Date.now();
+  let session;
+  let runtimeContext = context;
+  let duration = 0;
+
+  try {
+    if (useTransaction) {
+      session = context.client.startSession();
+      runtimeContext = { ...context, session };
+      // withTransaction may run the body more than once when the driver retries
+      // a transient failure, so duration is re-measured on each attempt.
+      await session.withTransaction(async () => {
+        const attemptStart = Date.now();
+        await withTimeout(fn(runtimeContext), timeoutMs, name, direction);
+        duration = Date.now() - attemptStart;
+        await onSuccess?.(duration, session);
+      });
+    } else {
+      await withTimeout(fn(runtimeContext), timeoutMs, name, direction);
+      duration = Date.now() - start;
+      await onSuccess?.(duration, undefined);
+    }
+
+    return { duration };
+  } catch (error) {
+    const err = error instanceof Error ? error : new Error(String(error));
+
+    if (hooks?.onError) {
+      // A throwing onError hook must not replace the real cause.
+      try {
+        await hooks.onError(name, err, runtimeContext);
+      } catch (hookError) {
+        const message = errorText(hookError);
+        logger?.warn(`⚠ onError hook failed for ${name}: ${message}`);
+      }
+    }
+
+    if (err instanceof MigrationTimeoutError) throw err;
+    // A standalone deployment refusing the transaction is a topology problem,
+    // not a bug in the migration — say so instead of blaming the file.
+    if (useTransaction && isTransactionsUnsupported(err)) {
+      throw new TransactionsUnsupportedError(
+        `Cannot run ${name} in a transaction — this deployment is standalone. ` +
+          'Set useTransaction: false, or run against a replica set / mongos.',
+        { name, direction, cause: err.message },
+        { cause: err },
+      );
+    }
+    throw new MigrationExecutionFailedError(
+      `Migration ${direction} failed: ${name}`,
+      // The message is duplicated into context because that is what survives
+      // JSON serialization; `cause` keeps the real Error (and its stack).
+      { name, direction, cause: err.message },
+      { cause: err },
+    );
+  } finally {
+    if (session) {
+      await session.endSession();
+    }
+  }
+}
+
+module.exports = { runMigration };

package/src/errors/index.js

@@ -0,0 +1,215 @@
+/**
+ * Base error for all migronaut failures. Carries a typed `code`, an optional
+ * `context`, and — when the failure wraps another error — that error as
+ * `cause`.
+ *
+ * The cause is a real Error, not a string, so `err.cause.stack` still points
+ * into the user's own migration. Wrap sites additionally keep the *message* in
+ * `context.cause`, because that is what survives JSON serialization for
+ * `--json` consumers.
+ */
+class MigronautError extends Error {
+  constructor(code, message, context, options) {
+    super(message, options?.cause !== undefined ? { cause: options.cause } : undefined);
+    this.name = 'MigronautError';
+    this.code = code;
+    if (context !== undefined) {
+      this.context = context;
+    }
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+
+/** Thrown when a lock is already held by another process within its TTL */
+class LockAlreadyHeldError extends MigronautError {
+  constructor(message, context, options) {
+    super('LOCK_ALREADY_HELD', message, context, options);
+    this.name = 'LockAlreadyHeldError';
+  }
+}
+
+/** Thrown when releasing a lock fails */
+class LockReleaseFailedError extends MigronautError {
+  constructor(message, context, options) {
+    super('LOCK_RELEASE_FAILED', message, context, options);
+    this.name = 'LockReleaseFailedError';
+  }
+}
+
+/**
+ * Thrown when the lock is lost while migrations are still running — another
+ * process reclaimed it, or the heartbeat could not reach the database. The run
+ * stops rather than risk two processes migrating the same database at once.
+ */
+class LockLostError extends MigronautError {
+  constructor(message, context, options) {
+    super('LOCK_LOST', message, context, options);
+    this.name = 'LockLostError';
+  }
+}
+
+/**
+ * Thrown when a run is stopped before finishing — via `MigratorKit.stop()` or a
+ * SIGINT/SIGTERM. Migrations already applied are listed in `context.results`.
+ */
+class RunAbortedError extends MigronautError {
+  constructor(message, context, options) {
+    super('RUN_ABORTED', message, context, options);
+    this.name = 'RunAbortedError';
+  }
+}
+
+/** Thrown when a user-supplied lifecycle hook throws */
+class HookFailedError extends MigronautError {
+  constructor(message, context, options) {
+    super('HOOK_FAILED', message, context, options);
+    this.name = 'HookFailedError';
+  }
+}
+
+/** Thrown when `migronaut create` would overwrite an existing migration file */
+class MigrationFileExistsError extends MigronautError {
+  constructor(message, context, options) {
+    super('MIGRATION_FILE_EXISTS', message, context, options);
+    this.name = 'MigrationFileExistsError';
+  }
+}
+
+/** Thrown when a file's checksum differs from the one recorded at apply time */
+class ChecksumMismatchError extends MigronautError {
+  constructor(message, context, options) {
+    super('CHECKSUM_MISMATCH', message, context, options);
+    this.name = 'ChecksumMismatchError';
+  }
+}
+
+/** Thrown when a referenced migration file does not exist on disk */
+class MigrationFileNotFoundError extends MigronautError {
+  constructor(message, context, options) {
+    super('MIGRATION_FILE_NOT_FOUND', message, context, options);
+    this.name = 'MigrationFileNotFoundError';
+  }
+}
+
+/**
+ * Thrown when a migration name is not a plain filename — e.g. it contains a
+ * path separator or `..`, which would let a target escape the migrations
+ * directory (path traversal) when joined into a filesystem path.
+ */
+class MigrationInvalidNameError extends MigronautError {
+  constructor(message, context, options) {
+    super('MIGRATION_INVALID_NAME', message, context, options);
+    this.name = 'MigrationInvalidNameError';
+  }
+}
+
+/** Thrown when a migration file does not export valid up()/down() functions */
+class MigrationInvalidExportError extends MigronautError {
+  constructor(message, context, options) {
+    super('MIGRATION_INVALID_EXPORT', message, context, options);
+    this.name = 'MigrationInvalidExportError';
+  }
+}
+
+/** Thrown when a migration's up() or down() throws during execution */
+class MigrationExecutionFailedError extends MigronautError {
+  constructor(message, context, options) {
+    super('MIGRATION_EXECUTION_FAILED', message, context, options);
+    this.name = 'MigrationExecutionFailedError';
+  }
+}
+
+/**
+ * Thrown when a migration exceeds its `timeoutMs`. Best-effort: the migration's
+ * own work cannot be cancelled, but the run stops instead of hanging, letting
+ * the lock's TTL expire so other instances are not blocked forever.
+ */
+class MigrationTimeoutError extends MigronautError {
+  constructor(message, context, options) {
+    super('MIGRATION_TIMEOUT', message, context, options);
+    this.name = 'MigrationTimeoutError';
+  }
+}
+
+/**
+ * Thrown when `useTransaction` is on but the deployment cannot run
+ * transactions (a standalone server — they need a replica set or mongos).
+ * A dedicated code, because the driver's own error blames the migration.
+ */
+class TransactionsUnsupportedError extends MigronautError {
+  constructor(message, context, options) {
+    super('TRANSACTIONS_UNSUPPORTED', message, context, options);
+    this.name = 'TransactionsUnsupportedError';
+  }
+}
+
+/** Thrown when the merged configuration fails validation */
+class ConfigInvalidError extends MigronautError {
+  constructor(message, context, options) {
+    super('CONFIG_INVALID', message, context, options);
+    this.name = 'ConfigInvalidError';
+  }
+}
+
+/** Thrown when creating a config file that already exists without `--force` */
+class ConfigFileExistsError extends MigronautError {
+  constructor(message, context, options) {
+    super('CONFIG_FILE_EXISTS', message, context, options);
+    this.name = 'ConfigFileExistsError';
+  }
+}
+
+/** Thrown when connecting to MongoDB fails */
+class ConnectionFailedError extends MigronautError {
+  constructor(message, context, options) {
+    super('CONNECTION_FAILED', message, context, options);
+    this.name = 'ConnectionFailedError';
+  }
+}
+
+/** Thrown when attempting to revert a migration that was never applied */
+class NotAppliedError extends MigronautError {
+  constructor(message, context, options) {
+    super('NOT_APPLIED', message, context, options);
+    this.name = 'NotAppliedError';
+  }
+}
+
+/** Thrown when `migronaut import` targets a non-empty changelog without `--force` */
+class ImportTargetNotEmptyError extends MigronautError {
+  constructor(message, context, options) {
+    super('IMPORT_TARGET_NOT_EMPTY', message, context, options);
+    this.name = 'ImportTargetNotEmptyError';
+  }
+}
+
+/** Thrown when attempting to roll back a migrate-mongo-imported (forward-only) migration */
+class IrreversibleMigrationError extends MigronautError {
+  constructor(message, context, options) {
+    super('MIGRATION_IRREVERSIBLE', message, context, options);
+    this.name = 'IrreversibleMigrationError';
+  }
+}
+
+module.exports = {
+  MigronautError,
+  LockAlreadyHeldError,
+  LockReleaseFailedError,
+  LockLostError,
+  RunAbortedError,
+  HookFailedError,
+  ChecksumMismatchError,
+  MigrationFileNotFoundError,
+  MigrationFileExistsError,
+  MigrationInvalidNameError,
+  MigrationInvalidExportError,
+  MigrationExecutionFailedError,
+  MigrationTimeoutError,
+  TransactionsUnsupportedError,
+  ConfigInvalidError,
+  ConfigFileExistsError,
+  ConnectionFailedError,
+  NotAppliedError,
+  ImportTargetNotEmptyError,
+  IrreversibleMigrationError,
+};

package/src/index.js

@@ -0,0 +1,59 @@
+const { EXIT_CODES } = require('./cli/exit-codes.js');
+const { MigratorKit } = require('./core/migrator.js');
+const { pendingMigrations, runMigrations } = require('./core/run.js');
+const {
+  ChecksumMismatchError,
+  ConfigFileExistsError,
+  ConfigInvalidError,
+  ConnectionFailedError,
+  HookFailedError,
+  ImportTargetNotEmptyError,
+  IrreversibleMigrationError,
+  LockAlreadyHeldError,
+  LockLostError,
+  LockReleaseFailedError,
+  MigrationExecutionFailedError,
+  MigrationFileExistsError,
+  MigrationFileNotFoundError,
+  MigrationInvalidExportError,
+  MigrationInvalidNameError,
+  MigrationTimeoutError,
+  TransactionsUnsupportedError,
+  MigronautError,
+  NotAppliedError,
+  RunAbortedError,
+} = require('./errors/index.js');
+
+module.exports = {
+  // Main class
+  MigratorKit,
+
+  // Programmatic entry points (app startup / serverless / test setup)
+  pendingMigrations,
+  runMigrations,
+
+  // The CLI's exit-code map, for wrappers that mirror its semantics
+  EXIT_CODES,
+
+  // Error classes
+  ChecksumMismatchError,
+  ConfigFileExistsError,
+  ConfigInvalidError,
+  ConnectionFailedError,
+  HookFailedError,
+  ImportTargetNotEmptyError,
+  IrreversibleMigrationError,
+  LockAlreadyHeldError,
+  LockLostError,
+  LockReleaseFailedError,
+  MigrationExecutionFailedError,
+  MigrationFileExistsError,
+  MigrationFileNotFoundError,
+  MigrationInvalidExportError,
+  MigrationInvalidNameError,
+  MigrationTimeoutError,
+  TransactionsUnsupportedError,
+  MigronautError,
+  NotAppliedError,
+  RunAbortedError,
+};

package/src/utils/checksum.js

@@ -0,0 +1,23 @@
+const crypto = require('node:crypto');
+const fs = require('node:fs/promises');
+
+const UTF8_BOM = 0xfeff;
+
+/**
+ * SHA-256 hex digest of a migration file, normalized so the same logical file
+ * hashes the same everywhere.
+ *
+ * Line endings are normalized to LF and a leading UTF-8 BOM is stripped:
+ * without that, a Windows checkout (or a `.gitattributes` `text=auto`) produces
+ * a different digest for byte-identical content and every applied migration
+ * reports a spurious checksum mismatch.
+ */
+async function computeChecksum(filepath) {
+  const buffer = await fs.readFile(filepath);
+  let contents = buffer.toString('utf8');
+  if (contents.charCodeAt(0) === UTF8_BOM) contents = contents.slice(1);
+  contents = contents.replace(/\r\n/g, '\n');
+  return crypto.createHash('sha256').update(contents, 'utf8').digest('hex');
+}
+
+module.exports = { computeChecksum };

package/src/utils/colors.js

@@ -0,0 +1,68 @@
+/**
+ * Decide whether ANSI colors should be emitted to `stream`.
+ *
+ * Precedence, most specific signal first:
+ *   MIGRONAUT_FORCE_COLOR > MIGRONAUT_NO_COLOR > FORCE_COLOR > NO_COLOR >
+ *   TERM=dumb > the stream being an interactive TTY.
+ *
+ * The MIGRONAUT_* pair exists so a project can pin migronaut's own output
+ * without disturbing every other tool in the same shell; the unprefixed pair
+ * stays honored underneath, because NO_COLOR/FORCE_COLOR are ecosystem-wide
+ * conventions (no-color.org) that a CLI is expected to obey. Same value
+ * semantics in both tiers: a *FORCE_COLOR that is set and non-empty decides
+ * ('0' off, anything else on); a *NO_COLOR that is set and non-empty forces off.
+ *
+ * There is deliberately no MIGRONAUT_TERM — TERM describes what the terminal
+ * can render, not what migronaut should do, and MIGRONAUT_NO_COLOR already
+ * covers the override case.
+ */
+function supportsColor(stream, env = process.env) {
+  const ownForce = env.MIGRONAUT_FORCE_COLOR;
+  if (ownForce !== undefined && ownForce !== '') return ownForce !== '0';
+  if (env.MIGRONAUT_NO_COLOR !== undefined && env.MIGRONAUT_NO_COLOR !== '') return false;
+  const force = env.FORCE_COLOR;
+  if (force !== undefined && force !== '') return force !== '0';
+  if (env.NO_COLOR !== undefined && env.NO_COLOR !== '') return false;
+  if (env.TERM === 'dumb') return false;
+  return Boolean(stream && stream.isTTY);
+}
+
+const paint = (open, close) => (text) => `\x1b[${open}m${text}\x1b[${close}m`;
+const identity = (text) => text;
+
+const ESC = String.fromCharCode(27);
+const ANSI_PATTERN = new RegExp(`${ESC}\\[[0-9;]*m`, 'g');
+
+/** Remove ANSI SGR color codes from a string */
+function stripAnsi(text) {
+  return text.replace(ANSI_PATTERN, '');
+}
+
+/**
+ * Create the color palette for writing to `stream`: green/yellow/red/cyan/dim
+ * wrapper functions plus an `enabled` flag. When colors are unsupported every
+ * wrapper is the identity function, so call sites never need to branch.
+ */
+function createColors(stream, env = process.env) {
+  const enabled = supportsColor(stream, env);
+  if (!enabled) {
+    return {
+      enabled,
+      green: identity,
+      yellow: identity,
+      red: identity,
+      cyan: identity,
+      dim: identity,
+    };
+  }
+  return {
+    enabled,
+    green: paint(32, 39),
+    yellow: paint(33, 39),
+    red: paint(31, 39),
+    cyan: paint(36, 39),
+    dim: paint(2, 22),
+  };
+}
+
+module.exports = { supportsColor, createColors, stripAnsi };

package/src/utils/concurrency.js

@@ -0,0 +1,32 @@
+/**
+ * Map `items` through `fn` with at most `limit` calls in flight, preserving
+ * input order in the result.
+ *
+ * `Promise.all` over a whole list starts everything at once. For per-file
+ * reads that means thousands of simultaneous open descriptors (EMFILE) once a
+ * project has thousands of migrations; for writes it means an unbounded fan-out
+ * at one connection pool. Failures still reject on the first error, matching
+ * `Promise.all` — the point here is pacing, not error handling.
+ */
+async function mapLimit(items, limit, fn) {
+  const results = new Array(items.length);
+  if (items.length === 0) return results;
+
+  const width = Math.max(1, Math.min(limit, items.length));
+  let next = 0;
+
+  const worker = async () => {
+    for (;;) {
+      const index = next++;
+      if (index >= items.length) return;
+      results[index] = await fn(items[index], index);
+    }
+  };
+
+  const workers = [];
+  for (let i = 0; i < width; i++) workers.push(worker());
+  await Promise.all(workers);
+  return results;
+}
+
+module.exports = { mapLimit };