README and improved tests

Author: vkarpov15

README.md

@@ -1,2 +1,44 @@
 # migrations
 Mongoose Migration Framework
+
+### Getting Started
+
+```javascript
+// Import the migration framework. Put this import **before** any other imports,
+// except dotenv or other environment configuration
+const migrations = require('@mongoosejs/migrations');
+
+const Character = require('./models/character');
+const mongoose = require('mongoose');
+
+run().catch(err => { console.error(err); process.exit(-1); });
+
+async function run() {
+  await mongoose.connect('mongodb://localhost:27017/migrations_examples');
+  // Tell the migration framework that a migration is starting.
+  // Set `restart` option if you want to restart a previously failed migration.
+  await migrations.startMigration({ restart: process.env.RESTART });
+
+  try {
+    // Put any migration logic here - update, save, eachAsync, etc.
+    await Character.updateMany({}, { $set: { ship: 'USS Enterprise' } });
+  } finally {
+    // Make sure to always call `endMigration()`, even if errors occur
+    await migrations.endMigration();
+    await mongoose.disconnect();
+  }
+}
+```
+
+### UI Setup
+
+You can run the Migration Framework UI as an executable using the provided `migration-ui` command:
+
+```
+env PORT=3001 env MONGO_URI="mongodb://localhost:27017/mydb" ./node_modules/.bin/migration-ui
+```
+
+You can also import the Migration Framework UI to your Express app:
+
+**Note:** you are responsible for securing the Migration Framework UI. There is currently no restrictions on the UI or API: anyone that can access the Migration Framework UI's URL can read migration data.
+**Note:** do **not** run the Migration Framework UI in the same process that runs migrations.

bin/ui.js renamed to bin/migration-ui.js

@@ -6,14 +6,16 @@ const ui = require('../src/ui');
 
 const app = express();
 
+const port = process.env.PORT || 3001;
+
 mongoose.connect(process.env.MONGO_URL || 'mongodb://localhost:27017/migrationstest');
 
 app.use('/', ui(mongoose, express));
 
-const server = app.listen(3001, err => {
+const server = app.listen(port, err => {
   if (err != null) {
     console.error(err);
     process.exit(-1);
   }
-  console.log('Listening on 3001');
+  console.log('Listening on ' + port);
 });

bin/migrations.js

@@ -48,11 +48,14 @@ exports.initMigrationModels = function initMigrationModels(conn) {
 exports.initMigrationFramework = function initMigrationFramework(conn) {
   conn = conn || mongoose.connection;
   didInit = true;
+  if (didInit) {
+    return;
+  }
 
   exports.initMigrationModels(conn);
 
   mongoose.plugin(function(schema) {
-    schema.pre(writeOps, { query: true, document: false }, async function(next) {
+    schema.pre(writeOps, { query: true, document: false }, async function migrationPreWriteOp(next) {
       if (migration == null) {
         return;
       }
@@ -61,16 +64,17 @@ exports.initMigrationFramework = function initMigrationFramework(conn) {
       Object.assign(opFilter, {
         migrationId: migration._id,
         modelName: this.model.modelName,
-        opName: this.op
+        opName: this.op,
+        parameters: {
+          filter: this.getFilter(),
+          update: this.getUpdate()
+        }
       });
       const res = await Operation.findOneAndUpdate(
         opFilter,
         {
           $setOnInsert: {
-            parameters: {
-              filter: this.getFilter(),
-              update: this.getUpdate()
-            }
+            status: 'in_progress'
           }
         },
         { new: true, upsert: true, rawResult: true }
@@ -90,7 +94,7 @@ exports.initMigrationFramework = function initMigrationFramework(conn) {
       }
     });
 
-    schema.post(writeOps, { query: true, document: false }, async function(res) {
+    schema.post(writeOps, { query: true, document: false }, async function migrationPostWriteOp(res) {
       if (migration == null) {
         return;
       }
@@ -111,6 +115,68 @@ exports.initMigrationFramework = function initMigrationFramework(conn) {
 
       await op.save();
     });
+
+    schema.pre('save', async function migrationPreSave(next) {
+      if (migration == null) {
+        return;
+      }
+
+      const opFilter = migration.lastOperationId ? { _id: { $gt: migration.lastOperationId } } : {};
+      Object.assign(opFilter, {
+        migrationId: migration._id,
+        modelName: this.constructor.modelName,
+        opName: 'save',
+        parameters: {
+          where: this.isNew ? null : this.$__delta()[0],
+          isNew: this.isNew,
+          changes: this.getChanges()
+        }
+      });
+
+      const res = await Operation.findOneAndUpdate(
+        opFilter,
+        {
+          $setOnInsert: {
+            status: 'in_progress'
+          }
+        },
+        { new: true, upsert: true, rawResult: true }
+      );
+
+      const op = res.value;
+
+      migration.lastOperationId = op._id;
+      await migration.save();
+
+      debug(`${this.constructor.modelName}.save`);
+
+      mongooseObjToOp.set(this, op);
+
+      if (res.lastErrorObject.updatedExisting) {
+        next(mongoose.skipMiddlewareFunction(op.result));
+      }
+    });
+
+    schema.post('save', async function migrationPostSave() {
+      if (migration == null) {
+        return;
+      }
+
+      const op = mongooseObjToOp.get(this);
+
+      if (op == null) {
+        return;
+      }
+
+      if (op.status !== 'complete') {
+        op.endedAt = new Date();
+        op.status = 'complete';
+      }
+
+      debug(`${this.constructor.modelName}.save`);
+
+      await op.save();
+    });
   });
 };
 
@@ -263,6 +329,7 @@ exports.eachAsync = async function eachAsync(model, options, fn) {
     opName: 'eachAsync',
     userFunctionName: options?.name || fn.name
   });
+
   const op = await Operation.findOneAndUpdate(
     opFilter,
     {

index.js

@@ -5,6 +5,9 @@
     "lint": "eslint .",
     "test": "mocha test/*.test.js"
   },
+  "bin": {
+    "migration-ui": "./bin/migration-ui.js"
+  },
   "dependencies": {
     "debug": "4.x"
   },

package.json

@@ -79,10 +79,14 @@ describe('eachAsync', function() {
 
     migration = await migrations.restartMigration({ name: 'test' });
     count = 0;
+    let eachAsyncId = null;
     await migrations.eachAsync(TestModel, async function addShip(doc) {
+      if (eachAsyncId == null) {
+        eachAsyncId = migration.lastOperationId;
+      }
       ++count;
 
-      const op = await mongoose.model('_Operation').findById(migration.lastOperationId);
+      const op = await mongoose.model('_Operation').findById(eachAsyncId);
       assert.equal(op.state.current, count + 2);
       doc.ship = 'USS Enterprise';
       await doc.save();

test/eachAsync.test.js

@@ -0,0 +1,65 @@
+'use strict';
+
+const assert = require('assert');
+const { before, describe, it, afterEach, beforeEach } = require('mocha');
+const mongoose = require('mongoose');
+const migrations = require('../');
+
+describe('save', function() {
+  let TestModel;
+  let migration;
+
+  before(function() {
+    mongoose.deleteModel(/Test/);
+
+    TestModel = mongoose.model('Test', mongoose.Schema({
+      name: String,
+      email: String
+    }));
+  });
+
+  beforeEach(async function() {
+    await TestModel.collection.deleteMany({});
+
+    migration = await migrations.startMigration({ name: 'test' });
+  });
+
+  afterEach(() => migrations.endMigration());
+  afterEach(() => migrations.models.Migration.deleteMany({ name: 'test' }));
+
+  it('stores the result', async function() {
+    const doc = new TestModel({ name: 'John Smith' });
+    await doc.save();
+
+    const operations = await mongoose.model('_Operation').find({ migrationId: migration._id });
+    assert.equal(operations.length, 1);
+    assert.equal(operations[0].status, 'complete');
+    assert.deepEqual(operations[0].parameters.changes, { $set: { name: 'John Smith' } });
+  });
+
+  it('skips if same op already exists', async function() {
+    await mongoose.model('_Operation').create({
+      migrationId: migration._id,
+      modelName: 'Test',
+      opName: 'save',
+      status: 'complete',
+      parameters: {
+        where: null,
+        isNew: true,
+        changes: { $set: { name: 'John Smith' } }
+      }
+    });
+
+    const doc = new TestModel({
+      name: 'John Smith'
+    });
+    await doc.save();
+
+    const operations = await mongoose.model('_Operation').find({ migrationId: migration._id });
+    assert.equal(operations.length, 1);
+    assert.equal(operations[0].status, 'complete');
+
+    const count = await TestModel.countDocuments({});
+    assert.equal(count, 0);
+  });
+});

test/save.test.js

@@ -62,6 +62,10 @@ describe('updates', function() {
       modelName: 'Test',
       opName: 'updateOne',
       status: 'complete',
+      parameters: {
+        filter: { name: 'John Smith' },
+        update: { name: 'John Smythe' }
+      },
       result: {
         matchedCount: 1,
         modifiedCount: 1,

test/updates.test.js

@@ -0,0 +1,3 @@
+'use strict';
+
+module.exports = require('./src/ui');