Feature Description

Currently migrate-mongo only tracks which migrations have been executed.
However, many migrations generate useful output (e.g., number of affected documents, logs, or aggregation results).
That output is not persisted, forcing developers to rely on console logs or external systems to understand what happened during a migration.

This feature would allow storing migration output inside the migration collection, along with the migration name and timestamp.

Use Case

• Improve traceability of data changes performed by migrations
• Help diagnose issues more easily by providing context for each executed migration
• Allow automated systems to inspect migration results programmatically
• Avoid losing relevant logs when migrations are executed inside a CI/CD pipeline

Proposed Solution

Extend the migration runner so that each migration function may return a JSON-serializable value.
migrate-mongo would store this value in the same document where executed migration metadata is saved.

This feature should:

• Store the return value only if present
• Ignore (or store null) when a migration returns nothing
• Provide a non-breaking API fallback if a migration does not return a value

Example Usage

// 20260108-add-field.js
module.exports.up = async (db) => {
  const result = await db.collection('users').updateMany({}, { $set: { active: true } });
  return {
    matchedCount: result.matchedCount,
    modifiedCount: result.modifiedCount
  };
};

module.exports.down = async (db) => {
  const result = await db.collection('users').updateMany({}, { $unset: { active: '' } });
  return {
    matchedCount: result.matchedCount,
    modifiedCount: result.modifiedCount
  };
};

Alternatives Considered

• Manual logging inside each migration (not persisted, inconvenient in CI)
• Writing to a separate custom audit collection (works, but duplicates tracking logic)
• Wrapping migrate-mongo programmatically to intercept results (adds boilerplate and complexity)

Breaking Changes

• This feature would require breaking changes
• This feature is backwards compatible

Additional Context

I can work on it and submit a PR