lai:collection-extensions

Meteor Collection Extensions

This package gives you utility functions to extend your Mongo.Collection instances in (hopefully) the safest, easiest and coolest way. If you want to create a package that monkey-patches the Mongo.Collection constructor, you'll need this package. I am striving for this package to be a third-party official way of monkey-patching Mongo.Collection until, well, Meteor decides to create a core functionality to properly extend it.

Breaking changes in 1.0.0, please keep reading!

Starting with v. 1.0.0, this package requires Meteor >= 3.0!
The module needs to be imported explicitly, it's not a global anymore!
All extensions will have to use collection as first param, instead of this:

1import { CollectionExtensions } from './collection-extensions'
2
3CollectionExtensions.addExtension(async (collection, name, options) => {
4  // ... your extension code
5})

This implies extensions have to be updated accordingly

Furthermore, extensions may not be applied immediately. This is, since extensions are applied during the call of the Mongo.Collection constructor. However, constructors cannot be async. We can't therefore be sure, when (async) extensions have been applied, without using a callback:

1const extensions = {
2  onComplete: () => {},
3  onError: e => console.error(e)
4}
5// exentsions options will not be passed to
6// the original collection constructor!
7const MyDocs = new Mongo.Collection('myDocs', { extensions })

This is unfortunate, but a tradeoff between determinism and compatibility.

addProperty now uses Object.definedProperty under the hood and allows to pass in property descriptors as third argument, while the function is always required

Background info

With the changes of Meteor 3.0 moving to full async, we now have to resolve the Promises, returned by Mongo.Collection methods (insertAsync etc.).

Installation

meteor add lai:collection-extensions

Why

Meteor gives you no easy way to extend the Mongo.Collection object, and therefore package publishers who want to extend its functionality resort to monkey-patching the Mongo.Collection constructor, and sometimes it's not done right. This package seeks to centralize one well-done monkey-patch with the ability to hook into the constructor as many times as possible. See my code.

I am hoping for all collection-extending package authors to to use this to end the package compatibility issues. In order for this to happen, I will fork major packages like matb33:collection-hooks, sewdn:collection-behaviours and refactor the code to use this utility package, and run their test suites. If you want to help, that would be awesome.

API

CollectionExtensions.addExtension(async fn ([collection, name, options]) {})

Pass in a (async or standard) function where the arguments are the same as that of when instantiating Mongo.Collection. In addition, you may access the collection instance by using this.

Very Important: You need to make sure your extensions are added before you instantiate your Mongo.Collections or your extensions will not work. Most likely you will only use this when building a custom package.

CollectionExtensions.addPrototype(name, fn (...) {})

Pass in the name of the prototype function as well as the function. Yes, I know you can simply just do Mongo.Collection.prototype.myPrototypeFunction = function (...) {}, which is fine. One of the things that this function does differently is to check whether you're in an older version of Meteor, in which Mongo.Collection doesn't exist but rather Meteor.Collection does. Note: If you are a package author that adds/modifies prototypes on the Mongo.Collection, this is not so critical for you to use unless you really want backwards-compatibility.

Examples

The following code recreates this section of code of the dburles:mongo-collection-instances using CollectionExtensions.addExtension(fn) thereby eliminating the need to monkey-patch the Mongo.Collection constructor:

1import {CollectionExtensions } from 'meteor/lai:collection-extensions'
2
3const instances = [];
4
5CollectionExtensions.addExtension((collection, name, options) => {
6  instances.push({
7    name: name,
8    instance: collection,
9    options: options
10  });
11});

The following code overrides ìnsert to use insertAsync under the hood.

1import {CollectionExtensions } from 'meteor/lai:collection-extensions'
2
3CollectionExtensions.addPrototype('insert', async function (doc) {
4  return this.insertAsync(doc)
5})

Todo

Integrate this package into the following packages and test them:

matb33:collection-hooks (Refactored and tested with 100% success)
dburles:mongo-collection-instances (Refactored and tested with 100% success) (Now merged into master!)
sewdn:collection-behaviours (He didn't write tests but here's the forked refactor anyway in case you wanted to test)

Create tests.

Contributing

If you are interested in using this package in your package, or if you want me to test (or if YOU want to test it yourself) integrating this into your package let me know and I will add it to the Todo list.

Feedback is welcome.

Future

Add control over the execution order of each collection extension somehow. Track collection instances that were prematurely instantiated and apply extensions on demand. Get Travis CI installed.

License

MIT, See license file