@alexify/migronaut 1.0.0

package/index.js

@@ -0,0 +1 @@
+module.exports = require('./src/index.js');

package/migronaut.schema.json

@@ -0,0 +1,135 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://migronaut.vercel.app/migronaut.schema.json",
+  "title": "migronaut configuration",
+  "description": "Configuration for migronaut.config.json. Options that hold live instances (hooks, logger, mongoose, client) are only available in a .ts/.js config.",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "URL of this schema, for editor completion and validation"
+    },
+    "uri": {
+      "type": "string",
+      "minLength": 1,
+      "description": "MongoDB connection URI"
+    },
+    "dbName": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Database name"
+    },
+    "migrationsDir": {
+      "type": "string",
+      "minLength": 1,
+      "default": "./migrations",
+      "description": "Directory holding migration files"
+    },
+    "migrationsCollection": {
+      "type": "string",
+      "minLength": 1,
+      "default": "_migronaut_migrations",
+      "pattern": "^(?!system\\.)[^$\\u0000]+$",
+      "description": "Collection storing the changelog"
+    },
+    "lockCollection": {
+      "type": "string",
+      "minLength": 1,
+      "default": "_migronaut_locks",
+      "pattern": "^(?!system\\.)[^$\\u0000]+$",
+      "description": "Collection used for the concurrency lock"
+    },
+    "lockTTLSeconds": {
+      "type": "integer",
+      "minimum": 1,
+      "default": 60,
+      "description": "Seconds before a lock is considered stale and reclaimable"
+    },
+    "strict": {
+      "type": "boolean",
+      "default": false,
+      "description": "Abort (instead of warn) when an applied file's checksum no longer matches"
+    },
+    "useTransaction": {
+      "type": "boolean",
+      "default": false,
+      "description": "Wrap every migration in a transaction. Requires a replica set or sharded cluster"
+    },
+    "fileExtensions": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "default": [
+        ".ts",
+        ".js"
+      ],
+      "description": "Extensions scanned when discovering migrations"
+    },
+    "createExtension": {
+      "enum": [
+        "ts",
+        "js"
+      ],
+      "default": "js",
+      "description": "File type `migronaut create` generates by default"
+    },
+    "sequential": {
+      "type": "boolean",
+      "default": false,
+      "description": "Use 0001-style sequential numbering instead of timestamps"
+    },
+    "templatePath": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Path to a custom migration template file"
+    },
+    "environment": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Value stamped on changelog records. Defaults to NODE_ENV, then 'production'"
+    },
+    "onLockLost": {
+      "enum": [
+        "abort",
+        "warn"
+      ],
+      "default": "abort",
+      "description": "What to do when the lock is lost mid-run"
+    },
+    "envFile": {
+      "oneOf": [
+        {
+          "type": "string",
+          "minLength": 1
+        },
+        {
+          "const": false
+        }
+      ],
+      "default": ".env",
+      "description": "The .env file to load, or false to load none"
+    },
+    "ensureIndexes": {
+      "type": "boolean",
+      "default": true,
+      "description": "Create the changelog indexes on first connect"
+    },
+    "timeoutMs": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Abort the run when a single migration exceeds this many milliseconds"
+    },
+    "reloadMigrations": {
+      "type": "boolean",
+      "default": false,
+      "description": "Bypass the ESM module cache when loading migrations (long-lived processes)"
+    },
+    "clientOptions": {
+      "type": "object",
+      "description": "MongoDB driver options (MongoClientOptions): TLS, auth mechanisms, proxies, pool sizing. Passed to the driver as-is."
+    }
+  }
+}

package/package.json

@@ -0,0 +1,105 @@
+{
+  "name": "@alexify/migronaut",
+  "version": "1.0.0",
+  "description": "Elegant, fast, fully-typed, zero-dependency MongoDB migrations for Node.js",
+  "license": "MIT",
+  "author": "Alex Dolid <dolid.sasha@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Alexis-Technologies/migronaut.git"
+  },
+  "homepage": "https://migronaut.vercel.app/",
+  "bugs": {
+    "url": "https://github.com/Alexis-Technologies/migronaut/issues"
+  },
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "main": "index.js",
+  "types": "index.d.ts",
+  "bin": {
+    "migronaut": "./bin/migronaut.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    }
+  },
+  "directories": {
+    "test": "tests"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "migronaut.schema.json",
+    "bin",
+    "src",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "tsd": {
+    "directory": "tests/types"
+  },
+  "keywords": [
+    "mongodb",
+    "mongo",
+    "migration",
+    "migrations",
+    "mongodb-migration",
+    "mongodb-migrations",
+    "database-migration",
+    "schema-migration",
+    "migrate-mongo",
+    "mongoose",
+    "mongoose-migration",
+    "rollback",
+    "transactions",
+    "cli",
+    "typescript",
+    "nosql"
+  ],
+  "peerDependencies": {
+    "mongodb": ">=5.0.0",
+    "mongoose": ">=7.0.0"
+  },
+  "peerDependenciesMeta": {
+    "mongoose": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.19",
+    "c8": "^10.1.3",
+    "esbuild": "^0.28.1",
+    "mongodb": "^6.12.0",
+    "mongodb-memory-server": "10.4.3",
+    "mongoose": "^8.9.2",
+    "oxfmt": "^0.60.0",
+    "oxlint": "^1.75.0",
+    "pino": "^10.3.1",
+    "tsd": "^0.31.2",
+    "typescript": "^5.7.2",
+    "vitepress": "^1.6.4"
+  },
+  "scripts": {
+    "test": "pnpm run test:unit && pnpm run test:integration",
+    "test:unit": "node --test \"tests/unit/**/*.test.js\"",
+    "test:integration": "node scripts/node-test.js --test-concurrency=1 \"tests/integration/**/*.test.js\"",
+    "test:coverage": "c8 --all --include 'src/**' --check-coverage --lines 90 --branches 90 --functions 90 --reporter text --reporter lcov node scripts/node-test.js --test-concurrency=1 \"tests/unit/**/*.test.js\" \"tests/integration/**/*.test.js\"",
+    "test:types": "tsd",
+    "check:dts": "tsc --noEmit --strict --skipLibCheck false index.d.ts",
+    "lint": "oxlint src bin scripts tests bench",
+    "format": "oxfmt src bin scripts tests bench",
+    "format:check": "oxfmt --check src bin scripts tests bench",
+    "size": "node scripts/size.js",
+    "bench": "node bench/bench.js",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs",
+    "release": "pnpm publish"
+  }
+}

package/src/cli/args.js

@@ -0,0 +1,314 @@
+const OPTION_PATTERN = /^(?:-([A-Za-z]), )?--([a-z][a-z0-9-]*)(?: <([^>]+)>)?$/;
+
+/** Convert a kebab-case option name to its camelCase opts key */
+const camelize = (name) => name.replace(/-([a-z0-9])/g, (_, char) => char.toUpperCase());
+
+/** Pad `label` so descriptions in a help block line up */
+const padLabel = (label, width) => label + ' '.repeat(width - label.length);
+
+/** Render one aligned `label  description` section of a help screen */
+function renderSection(title, rows) {
+  if (rows.length === 0) return [];
+  let width = 0;
+  for (const row of rows) {
+    if (row[0].length > width) width = row[0].length;
+  }
+  const lines = [];
+  for (const row of rows) {
+    lines.push(`  ${padLabel(row[0], width)}  ${row[1]}`);
+  }
+  return ['', `${title}:`, ...lines];
+}
+
+/**
+ * Minimal commander-compatible CLI framework covering exactly the surface the
+ * migronaut commands use: one level of subcommands, boolean/value/negatable
+ * (`--no-x`) options with camelCase keys and optional short aliases, required
+ * `<x>` / optional `[x]` positional arguments, `optsWithGlobals()`, and
+ * generated `--help` / `--version`. Global (root) options are recognized both
+ * before and after the subcommand name. Parse errors are written to stderr
+ * and set `process.exitCode = 1` — `process.exit()` is never called.
+ *
+ * Deliberately unsupported (unused by migronaut): combined short flags
+ * (`-fy`), variadic arguments, option defaults other than negatable `true`.
+ */
+class Command {
+  #name = '';
+  #description = '';
+  #version = null;
+  #options = [];
+  #arguments = [];
+  #commands = [];
+  #actionFn = null;
+  #parent = null;
+  #values = {};
+  /** Lazily-built `--long`/`-s` → option lookup; reset whenever options change */
+  #optionIndex = null;
+
+  name(value) {
+    this.#name = value;
+    return this;
+  }
+
+  description(value) {
+    this.#description = value;
+    return this;
+  }
+
+  version(value) {
+    this.#version = value;
+    return this;
+  }
+
+  option(flags, description = '') {
+    const match = OPTION_PATTERN.exec(flags);
+    if (!match) throw new TypeError(`Unsupported option flags: '${flags}'`);
+    const short = match[1] ?? null;
+    const rawName = match[2];
+    const negated = rawName.startsWith('no-');
+    this.#options.push({
+      flags,
+      description,
+      short,
+      long: `--${rawName}`,
+      key: camelize(negated ? rawName.slice(3) : rawName),
+      negated,
+      takesValue: Boolean(match[3]),
+    });
+    this.#optionIndex = null;
+    return this;
+  }
+
+  argument(spec, description = '') {
+    this.#arguments.push({
+      name: spec.slice(1, -1),
+      required: spec.startsWith('<'),
+      description,
+    });
+    return this;
+  }
+
+  command(name) {
+    const sub = new Command();
+    sub.#name = name;
+    sub.#parent = this;
+    this.#commands.push(sub);
+    return sub;
+  }
+
+  action(fn) {
+    this.#actionFn = fn;
+    return this;
+  }
+
+  opts() {
+    return this.#values;
+  }
+
+  optsWithGlobals() {
+    const globals = this.#parent ? this.#parent.#values : {};
+    return { ...globals, ...this.#values };
+  }
+
+  /** Parse argv (including the node + script tokens) and run the matching action */
+  async parseAsync(argv) {
+    const tokens = argv.slice(2);
+    this.#values = {};
+    this.#seedNegatableDefaults();
+
+    let command = null;
+    const positionals = [];
+    // After a bare `--`, everything is a positional — the standard
+    // end-of-options terminator.
+    let optionsEnded = false;
+
+    for (let i = 0; i < tokens.length; i++) {
+      const token = tokens[i];
+      if (optionsEnded) {
+        positionals.push(token);
+        continue;
+      }
+      if (token === '--') {
+        optionsEnded = true;
+        continue;
+      }
+      if (token === '-h' || token === '--help') {
+        // Short-circuit, commander-style: the user asking for help must get
+        // it even when a later token would fail the parse — mistyping a flag
+        // and appending --help to find out what went wrong is the exact case.
+        process.stdout.write(`${this.#helpText(command ?? this)}\n`);
+        return;
+      }
+      if ((token === '-V' || token === '--version') && this.#version !== null) {
+        process.stdout.write(`${this.#version}\n`);
+        return;
+      }
+      if (token.startsWith('-') && token !== '-') {
+        let name = token;
+        let inlineValue;
+        const separator = token.indexOf('=');
+        if (token.startsWith('--') && separator !== -1) {
+          name = token.slice(0, separator);
+          inlineValue = token.slice(separator + 1);
+        }
+        const found = this.#findOption(command, name);
+        if (!found) return this.#fail(`unknown option '${name}'`);
+        const { owner, option } = found;
+        if (option.takesValue) {
+          let value = inlineValue;
+          if (value === undefined) {
+            const next = tokens[i + 1];
+            // A leading digit after `-` is a negative number, not a flag —
+            // `--steps -1` should reach the core validator (which rejects it
+            // with an actionable message), not die as "argument missing".
+            const negativeNumber = next !== undefined && /^-\d/.test(next);
+            if (next === undefined || (next.startsWith('-') && next !== '-' && !negativeNumber)) {
+              return this.#fail(
+                `option '${option.flags}' argument missing ` +
+                  `(use ${option.long}=<value> for values starting with '-')`,
+              );
+            }
+            value = next;
+            i++;
+          }
+          owner.#values[option.key] = value;
+        } else {
+          owner.#values[option.key] = !option.negated;
+        }
+        continue;
+      }
+      if (command === null) {
+        let sub = null;
+        for (const candidate of this.#commands) {
+          if (candidate.#name === token) {
+            sub = candidate;
+            break;
+          }
+        }
+        if (!sub) return this.#fail(`unknown command '${token}'`);
+        command = sub;
+        command.#values = {};
+        command.#seedNegatableDefaults();
+        continue;
+      }
+      positionals.push(token);
+    }
+
+    if (command === null) {
+      process.stderr.write(`${this.#helpText(this)}\n`);
+      process.exitCode = 1;
+      return;
+    }
+
+    const args = [];
+    for (let i = 0; i < command.#arguments.length; i++) {
+      const spec = command.#arguments[i];
+      const value = positionals[i];
+      if (value === undefined && spec.required) {
+        return this.#fail(`missing required argument '${spec.name}'`);
+      }
+      args.push(value);
+    }
+    // Extra positionals are almost always a mistake (`up a.js b.js` would
+    // silently run only a.js); commander errors here, and so do we.
+    if (positionals.length > command.#arguments.length) {
+      const extra = positionals.slice(command.#arguments.length);
+      return this.#fail(`too many arguments — unexpected: ${extra.join(', ')}`);
+    }
+
+    if (command.#actionFn) {
+      await command.#actionFn(...args, command.#values, command);
+    }
+  }
+
+  /** Seed negatable options: declaring `--no-x` makes `x` default to true */
+  #seedNegatableDefaults() {
+    for (const option of this.#options) {
+      if (option.negated) this.#values[option.key] = true;
+    }
+  }
+
+  /** The `--long`/`-s` → option map for this command, built once per option set */
+  #lookupIndex() {
+    if (this.#optionIndex === null) {
+      const index = new Map();
+      for (const option of this.#options) {
+        index.set(option.long, option);
+        if (option.short !== null) index.set(`-${option.short}`, option);
+      }
+      this.#optionIndex = index;
+    }
+    return this.#optionIndex;
+  }
+
+  /** Resolve an option token against the active command first, then the root */
+  #findOption(command, token) {
+    const lookup = (owner) => {
+      if (owner === null) return null;
+      const option = owner.#lookupIndex().get(token);
+      return option ? { owner, option } : null;
+    };
+    return lookup(command) ?? lookup(this);
+  }
+
+  #fail(message) {
+    process.stderr.write(`error: ${message}\n`);
+    process.exitCode = 1;
+  }
+
+  /** Usage suffix for a command's positional arguments, e.g. ` <direction> [file]` */
+  #argsUsage(command) {
+    let usage = '';
+    for (const spec of command.#arguments) {
+      usage += spec.required ? ` <${spec.name}>` : ` [${spec.name}]`;
+    }
+    return usage;
+  }
+
+  #helpText(target) {
+    const isRoot = target === this;
+    const usage = isRoot
+      ? `Usage: ${this.#name} [options] [command]`
+      : `Usage: ${this.#name} ${target.#name} [options]${this.#argsUsage(target)}`;
+    const lines = [usage];
+    if (target.#description) lines.push('', target.#description);
+
+    const argumentRows = [];
+    for (const spec of target.#arguments) {
+      argumentRows.push([spec.name, spec.description]);
+    }
+    lines.push(...renderSection('Arguments', argumentRows));
+
+    const optionRows = [];
+    for (const option of target.#options) {
+      optionRows.push([option.flags, option.description]);
+    }
+    if (isRoot && this.#version !== null) {
+      optionRows.push(['-V, --version', 'output the version number']);
+    }
+    optionRows.push(['-h, --help', 'display help for command']);
+    lines.push(...renderSection('Options', optionRows));
+
+    // Subcommand help also lists the root's flags: they are accepted after the
+    // command name, so hiding them here would misdocument the real surface.
+    if (!isRoot) {
+      const globalRows = [];
+      for (const option of this.#options) {
+        globalRows.push([option.flags, option.description]);
+      }
+      lines.push(...renderSection('Global Options', globalRows));
+    }
+
+    if (isRoot) {
+      const commandRows = [];
+      for (const sub of this.#commands) {
+        const options = sub.#options.length > 0 ? ' [options]' : '';
+        commandRows.push([`${sub.#name}${options}${this.#argsUsage(sub)}`, sub.#description]);
+      }
+      lines.push(...renderSection('Commands', commandRows));
+    }
+    return lines.join('\n');
+  }
+}
+
+module.exports = { Command };

package/src/cli/commands/audit.js

@@ -0,0 +1,40 @@
+const { createColors } = require('../../utils/colors.js');
+const { defineCommand, EXIT_CODES } = require('../shared.js');
+
+/** Symbol and color for each check outcome */
+function renderStatus(colors, status) {
+  if (status === 'pass') return colors.green('✔');
+  if (status === 'warn') return colors.yellow('!');
+  return colors.red('✖');
+}
+
+/** Register the `audit` command (read-only diagnostics) */
+function registerAudit(program) {
+  defineCommand(program, {
+    name: 'audit',
+    description: 'Check the migronaut setup: config, connectivity, transactions, indexes, lock',
+    // audit() connects on its own and reports the outcome as a check.
+    connect: false,
+    run: (migrator) => migrator.audit(),
+    render: (report, { logger }) => {
+      const colors = createColors(process.stdout);
+      for (const check of report.checks) {
+        logger.info(
+          `${renderStatus(colors, check.status)} ${check.name.padEnd(12)} ${check.detail}`,
+        );
+      }
+      logger.info(
+        report.ok
+          ? `\nNo problems found (${report.warnings} warning(s))`
+          : `\n${report.failed} check(s) failed, ${report.warnings} warning(s)`,
+      );
+    },
+    // A failed check is what CI should act on; warnings are advisory. The
+    // dedicated code separates "a check failed" from an unclassified crash.
+    after: (report) => {
+      if (!report.ok) process.exitCode = EXIT_CODES.AUDIT_FAILED;
+    },
+  });
+}
+
+module.exports = { registerAudit };

package/src/cli/commands/create.js

@@ -0,0 +1,29 @@
+const { defineCommand } = require('../shared.js');
+
+/** Register the `create` command */
+function registerCreate(program) {
+  defineCommand(program, {
+    name: 'create',
+    description: 'Create a new migration file',
+    args: [['<name>', 'Migration name (will be slugified)']],
+    options: [
+      ['--js', 'Force a .js file (overrides config createExtension)'],
+      ['--ts', 'Force a .ts file (overrides config createExtension)'],
+      ['--template <path>', 'Use a custom template file'],
+    ],
+    // Writing a file needs no database — no spinner, no pre-connect.
+    spinner: false,
+    run: async (migrator, opts, [name]) => {
+      // Tri-state: explicit flag wins; otherwise leave undefined so config decides.
+      const js = opts.ts ? false : opts.js ? true : undefined;
+      const path = await migrator.create(name, {
+        ...(js !== undefined ? { js } : {}),
+        ...(opts.template ? { template: opts.template } : {}),
+      });
+      return { path };
+    },
+    // No render: core already logs "✔ Created …" itself.
+  });
+}
+
+module.exports = { registerCreate };

package/src/cli/commands/down.js

@@ -0,0 +1,30 @@
+const { defineCommand } = require('../shared.js');
+
+/** Register the `down` command */
+function registerDown(program) {
+  defineCommand(program, {
+    name: 'down',
+    description:
+      'Rollback the last batch, a specific batch, the last N steps, or a single named file',
+    args: [['[file]', 'Specific migration file to revert']],
+    options: [
+      ['--batch <n>', 'Revert a specific batch number'],
+      ['--steps <n>', 'Revert the last N migrations, regardless of batch'],
+      ['--to <file>', 'Revert everything applied after this file (it stays applied)'],
+    ],
+    lockable: true,
+    mutating: true,
+    run: (migrator, opts, [file]) =>
+      migrator.down(file, {
+        noLock: opts.noLock,
+        // `!== undefined`, not truthiness: `--batch 0` is a mistake worth
+        // reporting, not one to silently drop. Core validates the value.
+        ...(opts.batch !== undefined ? { batch: Number(opts.batch) } : {}),
+        ...(opts.steps !== undefined ? { steps: Number(opts.steps) } : {}),
+        ...(opts.to ? { to: opts.to } : {}),
+      }),
+    // No render: core logs every ↩ Reverted line itself.
+  });
+}
+
+module.exports = { registerDown };

package/src/cli/commands/dry-run.js

@@ -0,0 +1,36 @@
+const { ConfigInvalidError } = require('../../errors/index.js');
+const { defineCommand } = require('../shared.js');
+const { renderStatusTable } = require('../table.js');
+
+/** Register the `dry-run` command */
+function registerDryRun(program) {
+  defineCommand(program, {
+    name: 'dry-run',
+    description: 'Preview what an up or down would do, without touching the database',
+    args: [
+      ['<direction>', "Either 'up' or 'down'"],
+      ['[file]', 'Specific migration file'],
+    ],
+    options: [
+      ['--steps <n>', 'Preview reverting the last N migrations (down only)'],
+      ['--batch <n>', 'Preview reverting a specific batch (down only)'],
+      ['--to <file>', 'Preview migrating to this file (up: inclusive; down: exclusive)'],
+    ],
+    preflight: (_opts, [direction]) => {
+      if (direction !== 'up' && direction !== 'down') {
+        throw new ConfigInvalidError("Direction must be 'up' or 'down'", { direction });
+      }
+    },
+    run: (migrator, opts, [direction, file]) =>
+      migrator.dryRun(direction, file, {
+        ...(opts.steps !== undefined ? { steps: Number(opts.steps) } : {}),
+        ...(opts.batch !== undefined ? { batch: Number(opts.batch) } : {}),
+        ...(opts.to ? { to: opts.to } : {}),
+      }),
+    render: (rows, { logger }) => {
+      if (rows.length > 0) logger.info(renderStatusTable(rows));
+    },
+  });
+}
+
+module.exports = { registerDryRun };