Meteor.js 3.0 is an upcoming major release with lots of breaking changes. The platform is moving away from Fibers to use Node's native async await implementation.

In this article I'm going to show you a few techniques to detect code that requires changes in order to be ready for this upcoming Meteor.js 3.0 release. 🧙‍♂️

Photo bySusan Q Yin onUnsplash

Note, that this will not be a complete or perfect analysis, because you may end up with some false-positives or missing pieces. Consider it as a helping hand to aid the start for the transition. 🤝

Another primary goal is to be non-intrusive to your current application. This means, there should be no breaking effect to your current application by implementing the techniques, presented in this article.

This is important, because any breaking effect (server crashes etc.) creates frustration and decreases the chance of people finally starting to migrate now.

Background / why this is important? ☝

If you know all about Meteor.js 3.0 then you can safely skip this section.

Meteor.js is around forover 10 years now, and it's core API-structure did not change significantly. I previously showed this in anotherarticle on migrating an ancient Meteor.js project.

However, while Meteor.js pioneered the fullstack technologies until about 2016 it eventually lost its amazing momentum in about 2017 (read here on the why and how).

The JavaScript ecosystem evolved and like in the cambrian explosion we saw a multitude of tools, frameworks and libraries emerging.
A vast majority seemingly adopted theasync/await pattern,
while asynchronous code execution in Meteor.js was implemented usingcoroutines viaFibers.

Finally, the release of Node 16 became basically incompatible with fibers and thus, Meteor.js got stuck on Node 14. This implied amajor rewrite of a large potion of the platform's internals as it all depended onfibers. Further, it implied that all Meteor.js projects and packages required a major rewrite as well.

This is whereYOU come into play.

How do I know, if I need to migrate? 🤔

This answer is simple: you will have to! 🤓

This is, because all pre-3.0 projects run on a security-patched Node 14 (read here how to apply the patched version) and you will need Meteor 3.0 to be back on the safe side of the Node game by being able to use the latest Node LTS for your deployments.

How do I know what to migrate? 🤔

This is a rather complex situation with no simple answer. There are basically three big parts of your codebase to review:

• Mongo Collection and Cursor usage
• Meteor Methods + Publications
• Meteor Packages that depend on the "old" code style

There is also an official list of core functionality that
is to be migrated. It's part of the"How to migrate to Meteor Async in 2.x" guide.

Each of these come with a different approach, different complexity and constraints. Implementation also varies, whether a static analysis is desired or if runtime analysis is okay, too. Let's take a look at each of them, one by one.

Mongo Collection and Cursor usage 💽

Inclassic mode (using fibers) the Mongo collection calls to the MongoDB driver were executed within a Fiber and thus could be written in sync-style code, while being magically async under the hood:

constdocument=collection.findOne({foo:'bar'})

In the newasync mode (using async/await) we need to change this to an async counterpart:

constdocument=awaitcollection.findOneAsync({foo:'bar'})

This change targets the followingMongo.Collection methods:

Additional info

Note, thatCursor.count is deprecated and you should consider migrating toCollection.countDocuments orCollection.estimatedDocumentCount.

Static analysis 🔬

If you want to analyze their sync usage statically you would have to either write anisobuild plugin or ababel plugin.

The hardest challenge here is to get rid of the ambivalence due to the very common naming of the methods. For example:forEach andmap are typical Array methods and may create lots of false-positives. You will likely have to track, if the variable.

Additional Info

There seems to bea discussion in the Meteor forums about an ESLINT plugin for static analysis. I suggest you to keep watching the topic, if this is an alternative to you.

Runtime analysis 🔬

This approach is rather easy to implement and produces no false-positives. However, detection requires the code to run, which therefore requires a great test-coverage in order to really cover all possible calls. We can do that bymonkey patching the methods mentioned above.

Big plus: we can also detect usage in dependent Meteor packages, if we make sure the pathing occurs before the package code runs on startup. This is fortunately very easy as you just need to follow these steps:

1. Create a local package 📦

If your Meteor project does not contain apackages folder then you need to create one:

$cdyour-great-project$mkdir-p packages# needs to be on the same level as server, client, imports etc.$cdpackages

Then you create a new local package with a unique name:

$meteor create--package jkuester:migration-helper$cd ../# back to project root$meteor add jkuester:migration-helper

Let's change the following method inpackage.js in order toimmediately execute the code on startup (not to be confused withMeteor.startup, which runsafter all startup code):

Package.onUse(function(api){api.versionsFrom('2.3')api.use('ecmascript')api.use('mongo')api.addFiles('migration-helper.js','server')})

Finally, open the Meteor packages list atyour-great-project/.meteor/packages and move the entry for the packageat the very top of the file in order to apply the patches before any other package code runs.

2. Create a new patch function 🔨

Stay in the package and edit the main filemigration-helper.js which the following code (yes, you can copy/paste):

import{Meteor}from'meteor/meteor'import{Mongo}from'meteor/mongo'import{ValidatedMethod}from'meteor/mdg:validated-method'// some common patternconstnewLine=/\n/gconstwhiteSpace=/\s+/g// return the current location// of function execution, considering// multiple levels of wrappersconstgetLocation=()=>{conste=newError('')constlines=e.stack.split(newLine)returnlines[3].replace(whiteSpace,'').trim()}// monkey-patch a Collection/Cursor proto function// to inject some analysis code without altering// the original behaviorconstpatch=(proto,name)=>{constoriginal=proto[name]constclassName=proto.constructor.nameproto[name]=function(...args){constself=thisconstlocation=getLocation()constisWrappedAsync=location.includes(`as${name}Async`)if(!isWrappedAsync){console.warn(`Deprecated:${className}.${name} needs to be migrated to${name}Async in collection "${self._name}"!`)console.warn('=>',location)}returnoriginal.call(self,...args)}}// apply patching to Mongo.Collection functionsconstmNames=['insert','update','remove','findOne','createIndex']constmProto=Mongo.Collection.prototypemNames.forEach(name=>patch(mProto,name))// applying patches Mongo.Cursor functionsconstcNames=['count','forEach','map','fetch']constcProto=Mongo.Cursor.prototypecNames.forEach(name=>patch(cProto,name))

Start your Meteor project or run your tests and look for the deprecation messages. You can also replace theconsole.warn withthrow new Error to make the tests fail but that will also likely prevent your app from running - this is up to you how to handle things here.

Meteor Methods ☄️

Most of the time you will define Methods and Publications statically on startup. This allows us to create a neat little tool that provides a summary of all our methods and publications.

Consider the following example, which inserts a new document into a Mongo.Collection (similar to what happens in theMeteor tutorials):

// server/main.jsMeteor.methods({'createTodo'(text){constuserId=thisconstdocId=TodosCollection.insert({text,userId})returnTodosCollection.findOne(docId)}})

Building on top of the previous section, we continue to extend our migration helper package in order to detect the migration needs for this method. Let's start with Meteor Methods by patching theMeteor.methods function. You can continue inmigration-helper.js by simply adding the following code at the end of the file:

// ...continueing in migration-helper.jsconstasyncLine=/\s*return Promise.asyncApply\(\(\) => {\n/g// scans a function body for the above pattern// to detect async functionsconstanalyze=({name,fn,location,type})=>{constsource=fn.toString()constlines=source.split(byNewline)constisAsync=asyncLine.test(lines[1])if(!isAsync){console.warn(`Deprecated (${type}):${name} is not async, consider migrating now.`)}}

What is this actually good for?

Let me explain: In Meteor.js 2.x (using Fibers) any async declared function gets recompiled by theMeteor build tool, transforming async functions into thisPromise.asyncApply. It basically connects the given function to a Fiber that keeps track of the execution stack.

In turn - every Method or Publication that is not transformed into thisPromise.asyncApply will not contain this pattern on line 1.Thus, we can detect that this function is not async yet.

Let's apply this toMeteor.methods; you can simply continue at the end of the file:

// ...continueing in migration-helper.jsconstoriginalMethods=Meteor.methodsMeteor.methods=options=>{constlocation=getLocation()constentries=Object.entries(options)consttype='Method'entries.forEach(([name,fn])=>{analyze({name,fn,location,type})})returnoriginalMethods(options)}

Restarting the project yields to the following output:

W20231102-15:28:12.775(1)?(STDERR) Deprecated(Method): createTodo is not async, consider migrating now.W20231102-15:28:12.776(1)?(STDERR)=> at module(server/main.js:15:8)

And during tests or runtime we will see a message like this:

W20231102-15:32:31.550(1)?(STDERR)Deprecated:Collection.insertneedstobemigratedtoinsertAsyncincollection"todos"!W20231102-15:32:31.551(1)?(STDERR)=>atCollection.Mongo.Collection.<computed>[asinsertAsync](packages/mongo/collection.js:1004:46)W20231102-15:32:31.560(1)?(STDERR)Deprecated:Collection.findOneneedstobemigratedtofindOneAsyncincollection"todos"!W20231102-15:32:31.561(1)?(STDERR)=>atMethodInvocation.createTodo(server/main.js:26:28)

Both indicating thecreateTodo method needs some migration efforts. Let's do that:

Meteor.methods({'createTodo':asyncfunction(text){constuserId=thisconstdocId=awaitTodosCollection.insertAsync({text,userId})returnTodosCollection.findOneAsync(docId)}})

The warnings are gone and you have safely prepared this method for the major 3.0 update.

Meteor Publications ☄️

If you have already implemented the functions from the Meteor Methods section before then patching publications is as easy as it can get:

constoriginalPub=Meteor.publishMeteor.publish=(name,fn)=>{constlocation=getLocation()consttype='Publication'analyze({name,fn,location,type})returnoriginalPub(name,fn)}

Note, that publications return cursors using.find which does not need to be migrated to async. Therefore this may create some false-positives for functions that use no other Mongo.Collection or Mongo.Cursor functions that have to be async.

Validated Methods ☄️

A special case is, when usingValidatedMethod viamdg:validated-method. If you don't know the package, I highly suggest to check it out asit's the recommended way (add guide link) to create method with builtin argument validation.

We will not be able to detect non-async methods passed to theValidatedMethod constructor as with theMeteor.methods pattern, described above. This is, because we basically can't override/monkey-patch an ES6 constructor function the same way we do with any other function.

Fortunately we still have two alternative ways for detection.

Detect using a mixin 🔍

This works by creating a mixin function that detects theoptions.run function the same way we detect theMeteor.methods. However, there is one disadvantage - you have to assign the mixin to everyValidatedMethod construction options and at that point you'll likely check each method manually.

Therefore, this approach makes only sense if you use a factory-function to create your Methods, which acts as a single point of construction. In that case, it's rather easy to inject the mixin into your validated methods:

exportconstcreateMethod=options=>{options.mixins=options.mixins??[]options.mixins.push(checkAsyncMixin)returnnewValidatedMethod(options)}constcheckAsyncMixin=options=>{const{name,run}=optionsanalyze({name:name,location:getLocation(),type:'ValidatedMethod',fn:run})returnoptions}

Detect at runtime 🔬

If you don't use a pattern, similar to the above-mentioned factory-function, then you still have one more option here. However, this will only detect the methods at runtime, and you will either have to have a decent test-coverage or other ways to make sure that every of your methods are called.

It works by overriding the_execute prototype method, which will run on every method invocation for methods, declared usingValidatedMethod:

constoriginalExec=ValidatedMethod.prototype._executeValidatedMethod.prototype._execute=function(...args){constself=thisanalyze({name:self.name,location:getLocation(),type:'ValidatedMethod',fn:self.run})returnoriginalExec.call(self,...args)}

Summary and outlook 🔭

I showed in this article how to easily detect parts of your Meteor 2.x server environment that need change in order to be 3.0-ready. I purposefully leaved out the client side as this easily exceeds the scope of a short and simple article.

Since Meteor.js supports many client side libraries and frameworks this may be subject to specific articles for each of them, and I encourage everyone to step up and start writing on their experience
with them.

You can use this code and refactor / modify it to your needs or simply use the packagejkuester:migration-helper.
It's listed on Packosphere and available on GitHub, too:

Packosphere Link 📦

GitHub repository ⌨️

$ meteor add jkuester:migration-helper

import{checkAsyncMixin}from'meteor/jkuester:migration-helper'// ...

About me 👋

I regularly publish articles here on dev.to aboutMeteor.js andJavaScript. Recently I also co-host theweekly Meteor.js community podcast, which contains the newest from Meteor.js and the community.

You can also find (and contact) me onGitHub,Twitter/X andLinkedIn.

If you like what you are reading and want to support me, you cansponsor me on GitHub,send me a tip via PayPal or sponsor me a book formmy Amazon wishlist.