diff --git a/guide/source/2.7.4-migration.md b/guide/source/2.7.4-migration.md new file mode 100644 index 0000000000..058a16cdfb --- /dev/null +++ b/guide/source/2.7.4-migration.md @@ -0,0 +1,89 @@ +--- +title: Migrating to Meteor 2.7.4 +description: How to migrate your application to Meteor 2.7.4. +--- + +Meteor `2.7.4` introduce the new MongoDB Package Async API. For a complete breakdown of the changes, please refer to the [changelog](http://docs.meteor.com/changelog.html). + +For this new async API, we have new methods like `findOneAsync`, which behaves exactly like the `findOne` method, but it now returns a promise that needs to be solved to get the data. + +

Why this is important?

+ +You may know that on Meteor we use a package called [Fibers](https://github.com/laverdet/node-fibers). This package is what makes possible to call async function, like `db.findOne()`, inside Meteor in a sync way (without having to wait for the promise to resolve). + +But starting from Node 16, Fibers will stop working, so Meteor needs to move away from Fibers, otherwise, we'll be stuck on Node 14. + +If you want to know more about the plan, you can check this [discussion](https://github.com/meteor/meteor/discussions/11505). + +

Why doing this now?

+ +This will be a considerable change for older Meteor applications, and some parts of the code of any Meteor app will have to be adjusted eventually. + +But we're going to do this in a way that has the most negligible impact possible on the applications and over time. + +With this version, you'll be able to start preparing your app for the future by replacing your current MongoDB methods with the new async ones. + +

What's new?

+ +Here are the newly added methods (you can see this description and the code [here](https://github.com/meteor/meteor/pull/12028)): + +**Added async methods on collections.** + - All async methods have an Async suffix to their names. These are: `createCappedCollectionAsync`, `createIndexAsync`, `dropCollectionAsync`, `dropIndexAsync`, `findOneAsync`, `insertAsync`, `removeAsync`, `updateAsync`, and `upsertAsync`. + +**Added async methods on cursors.** + - All async methods have an Async suffix to their names. These are: `countAsync`, `fetchAsync`, `forEachAsync`, and `mapAsync`. + - There's also `[Symbol.asyncIterator]`, so this code should work: + ```js + for await (const document of collection.find(query, options)) /* ... */ + ``` +**A few internal methods are now async.** + + - These are: `MongoConnection` (constructor), `MongoInternals.RemoteCollectionDriver` (constructor), `MongoInternals.defaultRemoteCollectionDriver`, `OplogHandle` (constructor). + +Adding these async counterparts allows gradual migration, as both versions will coexist for the time being. At the moment, all async methods are calling sync one directly, so all hooks and wrappers should work as expected. + +

Can I update to this version without changing my app?

+ +Yes and no. + +If you're not using any constructor, like `MongoInternals.RemoteCollectionDriver`, then yes. Your app will run normally. + +But if you're using a construction like that one, then an error be thrown because these are async now. In this case, you have two options: + - You can wrap the call in an async function, like so: + ```js + async function Connection() { + return await MongoInternals.RemoteCollectionDriver(/.../) + } + ``` + - Use `.await()`, like so: + ```js + const Connection = new MongoInternals.RemoteCollectionDriver(/.../).await(); + ``` + +The last option is easier for a quick fix. Just bear in mind that the function `.await()` in working with Fibers, meaning that it'll be deprecated in the future. + +

Migrating from a version older than 2.7.4?

+ +If you're migrating from a version of Meteor older than Meteor 2.7.4, there may be important considerations not listed in this guide. Please review the older migration guides for details: + +* [Migrating to Meteor 2.7](2.7-migration.html) (from 2.6) +* [Migrating to Meteor 2.6](2.6-migration.html) (from 2.5) +* [Migrating to Meteor 2.5](2.5-migration.html) (from 2.4) +* [Migrating to Meteor 2.4](2.4-migration.html) (from 2.3) +* [Migrating to Meteor 2.3](2.3-migration.html) (from 2.2) +* [Migrating to Meteor 2.2](2.2-migration.html) (from 2.0) +* [Migrating to Meteor 2.0](2.0-migration.html) (from 1.12) +* [Migrating to Meteor 1.12](1.12-migration.html) (from 1.11) +* [Migrating to Meteor 1.11](1.11-migration.html) (from 1.10.2) +* [Migrating to Meteor 1.10.2](1.10.2-migration.html) (from 1.10) +* [Migrating to Meteor 1.10](1.10-migration.html) (from 1.9.3) +* [Migrating to Meteor 1.9.3](1.9.3-migration.html) (from 1.9) +* [Migrating to Meteor 1.9](1.9-migration.html) (from 1.8.3) +* [Migrating to Meteor 1.8.3](1.8.3-migration.html) (from 1.8.2) +* [Migrating to Meteor 1.8.2](1.8.2-migration.html) (from 1.8) +* [Migrating to Meteor 1.8](1.8-migration.html) (from 1.7) +* [Migrating to Meteor 1.7](1.7-migration.html) (from 1.6) +* [Migrating to Meteor 1.6](1.6-migration.html) (from 1.5) +* [Migrating to Meteor 1.5](1.5-migration.html) (from 1.4) +* [Migrating to Meteor 1.4](1.4-migration.html) (from 1.3) +* [Migrating to Meteor 1.3](1.3-migration.html) (from 1.2)