@alexify/migronaut 2.0.0 → 2.1.0

package/migronaut.schema.json

@@ -2,7 +2,7 @@
   "$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.",
+  "description": "Configuration for migronaut.config.json. Options that hold live instances or functions (hooks, logger, mongoose, client, generateId, telemetry) are only available in a .ts/.js config.",
   "type": "object",
   "properties": {
     "$schema": {
@@ -39,6 +39,13 @@
       "pattern": "^(?!system\\.)[^$\\u0000]+$",
       "description": "Collection used for the concurrency lock"
     },
+    "convergeLogCollection": {
+      "type": "string",
+      "minLength": 1,
+      "default": "_migronaut_converge",
+      "pattern": "^(?!system\\.)[^$\\u0000]+$",
+      "description": "Collection holding the converge history (written on the first converge that changes something)"
+    },
     "lockTTLSeconds": {
       "type": "integer",
       "minimum": 1,
@@ -139,6 +146,180 @@
     "clientOptions": {
       "type": "object",
       "description": "MongoDB driver options (MongoClientOptions): TLS, auth mechanisms, proxies, pool sizing. Passed to the driver as-is."
+    },
+    "collections": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/collection"
+      },
+      "description": "Declared collections: `migronaut converge` keeps their indexes and validator in the declared state, with no migration file per change"
+    },
+    "collectionsDir": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Directory of collection definition files, one collection per file. Opt-in: nothing is read unless this is set"
+    },
+    "convergeAfterUp": {
+      "type": "boolean",
+      "default": false,
+      "description": "End every bulk `up` (no file, no --to) by converging the declared collections under the same lock"
+    }
+  },
+  "definitions": {
+    "collection": {
+      "type": "object",
+      "required": [
+        "name"
+      ],
+      "additionalProperties": false,
+      "anyOf": [
+        {
+          "required": [
+            "indexes"
+          ]
+        },
+        {
+          "required": [
+            "validator"
+          ]
+        }
+      ],
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^(?!system\\.)[^$\\u0000]+$",
+          "description": "Collection name"
+        },
+        "indexes": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/index"
+          },
+          "description": "Every index besides _id. Omit to leave the collection's indexes unmanaged"
+        },
+        "validator": {
+          "oneOf": [
+            {
+              "type": "object"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "A query or { $jsonSchema } document; null or {} for no validator. Omit to leave the validator unmanaged"
+        },
+        "validationLevel": {
+          "enum": [
+            "off",
+            "strict",
+            "moderate"
+          ],
+          "description": "How the validator applies to updates. Defaults to 'strict'"
+        },
+        "validationAction": {
+          "enum": [
+            "error",
+            "warn",
+            "errorAndLog"
+          ],
+          "description": "What an invalid write does. Defaults to 'error'"
+        },
+        "prune": {
+          "type": "boolean",
+          "description": "Drop indexes this definition does not declare (otherwise they are kept and reported)"
+        }
+      }
+    },
+    "index": {
+      "type": "object",
+      "required": [
+        "key"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "key": {
+          "type": "object",
+          "minProperties": 1,
+          "additionalProperties": {
+            "enum": [
+              1,
+              -1,
+              "text",
+              "hashed",
+              "2d",
+              "2dsphere"
+            ]
+          },
+          "description": "Field → direction, in index order"
+        },
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Defaults to the name MongoDB generates (email_1)"
+        },
+        "unique": {
+          "type": "boolean"
+        },
+        "sparse": {
+          "type": "boolean"
+        },
+        "hidden": {
+          "type": "boolean"
+        },
+        "expireAfterSeconds": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "partialFilterExpression": {
+          "type": "object"
+        },
+        "collation": {
+          "type": "object",
+          "required": [
+            "locale"
+          ]
+        },
+        "wildcardProjection": {
+          "type": "object"
+        },
+        "weights": {
+          "type": "object"
+        },
+        "default_language": {
+          "type": "string",
+          "minLength": 1
+        },
+        "language_override": {
+          "type": "string",
+          "minLength": 1
+        },
+        "textIndexVersion": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "2dsphereIndexVersion": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "bits": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "min": {
+          "type": "number"
+        },
+        "max": {
+          "type": "number"
+        },
+        "storageEngine": {
+          "type": "object"
+        },
+        "background": {
+          "type": "boolean",
+          "description": "Accepted and ignored — a no-op since MongoDB 4.2"
+        }
+      }
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexify/migronaut",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Elegant, fast, fully-typed, zero-dependency MongoDB migrations for Node.js — adopts an existing migrate-mongo changelog in one command",
   "license": "MIT",
   "author": "Alex Dolid <dolid.sasha@gmail.com>",
@@ -24,6 +24,10 @@
     ".": {
       "types": "./index.d.ts",
       "default": "./index.js"
+    },
+    "./bullmq": {
+      "types": "./bullmq.d.ts",
+      "default": "./bullmq.js"
     }
   },
   "directories": {
@@ -32,6 +36,8 @@
   "files": [
     "index.js",
     "index.d.ts",
+    "bullmq.js",
+    "bullmq.d.ts",
     "migronaut.schema.json",
     "bin",
     "src",
@@ -58,6 +64,9 @@
     "migrate-mongo-alternative",
     "mongoose",
     "mongoose-migration",
+    "bullmq",
+    "job-queue",
+    "migration-service",
     "rollback",
     "transactions",
     "zero-dependency",
@@ -75,11 +84,18 @@
     }
   },
   "devDependencies": {
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/instrumentation-mongodb": "^0.75.0",
+    "@opentelemetry/sdk-metrics": "^2.11.0",
+    "@opentelemetry/sdk-trace-node": "^2.11.0",
     "@types/node": "^22.19.19",
     "@vercel/analytics": "^2.0.1",
     "@vercel/speed-insights": "^2.0.0",
+    "bullmq": "^6.3.11",
+    "bullmq-otel": "^2.0.1",
     "c8": "^10.1.3",
     "esbuild": "^0.28.1",
+    "ioredis": "^5.11.1",
     "mongodb": "^6.12.0",
     "mongodb-memory-server": "10.4.3",
     "mongoose": "^8.9.2",
@@ -96,10 +112,10 @@
     "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",
+    "check:dts": "tsc --noEmit --strict --skipLibCheck false index.d.ts bullmq.d.ts",
+    "lint": "oxlint src bin scripts tests bench examples",
+    "format": "oxfmt src bin scripts tests bench examples",
+    "format:check": "oxfmt --check src bin scripts tests bench examples",
     "size": "node scripts/size.js",
     "bench": "node bench/bench.js",
     "docs:dev": "vitepress dev docs",

package/src/bullmq/index.js

@@ -0,0 +1,55 @@
+const {
+  DEFAULT_CONVERGE_SCHEDULER_ID,
+  DEFAULT_QUEUE_NAME,
+  DEFAULT_SCHEDULER_ID,
+  JOB_DATA_VERSION,
+  JOB_NAMES,
+  MIN_JOB_DATA_VERSION,
+  dedupId,
+  parseJobData,
+} = require('./jobs.js');
+const { RETRYABLE_CODES, createMigrationProcessor, isRetryableError } = require('./processor.js');
+const {
+  enqueueConverge,
+  enqueueDown,
+  enqueueUp,
+  planDownJobs,
+  planUpJobs,
+} = require('./producer.js');
+const { MigrationQueue, createMigrationQueue } = require('./service.js');
+const { waitForGroup } = require('./wait.js');
+
+/**
+ * `@alexify/migronaut/bullmq` — migrations as a queue, one migration per job.
+ *
+ * BullMQ is never required from here: the classes are injected by the caller
+ * (`createMigrationQueue({ bullmq: { Queue, Worker } })`), so this entry point
+ * costs nothing to anyone who does not use it and pins no BullMQ version.
+ */
+module.exports = {
+  // The service facade — queue, worker, scheduling and status in one object
+  createMigrationQueue,
+  MigrationQueue,
+
+  // Building blocks, for a Queue/Worker the application already owns
+  // (NestJS processors, BullMQ Pro, a shared worker process)
+  createMigrationProcessor,
+  enqueueUp,
+  enqueueDown,
+  enqueueConverge,
+  planUpJobs,
+  planDownJobs,
+  waitForGroup,
+
+  // The job contract
+  JOB_NAMES,
+  JOB_DATA_VERSION,
+  MIN_JOB_DATA_VERSION,
+  DEFAULT_QUEUE_NAME,
+  DEFAULT_SCHEDULER_ID,
+  DEFAULT_CONVERGE_SCHEDULER_ID,
+  RETRYABLE_CODES,
+  dedupId,
+  isRetryableError,
+  parseJobData,
+};