Extends Mongo.Collection with before
/after
hooks for insert
, update
, remove
, find
, and findOne
.
Works across client, server or a mix. Also works when a client initiates a collection method and the server runs the hook, all while respecting the collection validators (allow/deny).
Please refer to History.md for a summary of recent changes.
Installation:
meteor add matb33:collection-hooks
Fired before the doc is inserted.
Allows you to modify doc as needed, or run additional functionality
this.transform()
obtains transformed version of document, if a transform was defined.
import { Mongo } from 'meteor/mongo';
const test = new Mongo.Collection("test");
test.before.insert(function (userId, doc) {
doc.createdAt = Date.now();
});
Fired before the doc is updated.
Allows you to to change the modifier
as needed, or run additional
functionality.
this.transform()
obtains transformed version of document, if a transform was defined.
test.before.update(function (userId, doc, fieldNames, modifier, options) {
modifier.$set = modifier.$set || {};
modifier.$set.modifiedAt = Date.now();
});
Important:
-
Note that we are changing
modifier
, and notdoc
. Changingdoc
won't have any effect as the document is a copy and is not what ultimately gets sent down to the underlyingupdate
method. -
When triggering a single update targeting multiple documents using the option
multi: true
(see Meteor documentation), thebefore.update
hook is called once per document about to be updated, but the collection update called afterwards remains a single update (targetting multiple documents) with a single modifier. Hence it is not possible at the time to usebefore.update
to create a specific modifier for each targeted document.
Fired just before the doc is removed.
Allows you to to affect your system while the document is still in existence -- useful for maintaining system integrity, such as cascading deletes.
this.transform()
obtains transformed version of document, if a transform was defined.
test.before.remove(function (userId, doc) {
// ...
});
Fired before the doc is upserted.
Allows you to to change the modifier
as needed, or run additional
functionality.
test.before.upsert(function (userId, selector, modifier, options) {
modifier.$set = modifier.$set || {};
modifier.$set.modifiedAt = Date.now();
});
Note that calling upsert
will always fire .before.upsert
hooks, but will
call either .after.insert
or .after.update
hooks depending on the outcome of
the upsert
operation. There is no such thing as a .after.upsert
hook at this
time.
Fired after the doc was inserted.
Allows you to run post-insert tasks, such as sending notifications of new document insertions.
this.transform()
obtains transformed version of document, if a transform was defined;this._id
holds the newly inserted_id
if available.
test.after.insert(function (userId, doc) {
// ...
});
Fired after the doc was updated.
Allows you to to run post-update tasks, potentially comparing the previous and new documents to take further action.
this.previous
contains the document before it was updated.- The optional
fetchPrevious
option, when set to false, will not fetch documents before running the hooks.this.previous
will then not be available. The default behavior is to fetch the documents.
- The optional
this.transform()
obtains transformed version of document, if a transform was defined. Note that this function accepts an optional parameter to specify the document to transform โ useful to transform previous:this.transform(this.previous)
.
test.after.update(function (userId, doc, fieldNames, modifier, options) {
// ...
}, {fetchPrevious: true/false});
Important: If you have multiple hooks defined, and at least one of them does
not specify fetchPrevious: false
, then the documents will be fetched
and provided as this.previous
to all hook callbacks. All after-update hooks
for the same collection must have fetchPrevious: false
set in order to
effectively disable the pre-fetching of documents.
It is instead recommended to use the collection-wide options (e.g.
MyCollection.hookOptions.after.update = {fetchPrevious: false};
).
This hook will always be called with the new documents; even if the updated document gets modified in a way were it would normally not be able to be found because of before.find
hooks (see Meteor-Community-Packages#297).
Fired after the doc was removed.
doc
contains a copy of the document before it was removed.
Allows you to run post-removal tasks that don't necessarily depend on the document being found in the database (external service clean-up for instance).
this.transform()
obtains transformed version of document, if a transform was defined.
test.after.remove(function (userId, doc) {
// ...
});
Fired before a find query.
Allows you to adjust selector/options on-the-fly.
test.before.find(function (userId, selector, options) {
// ...
});
Important: This hook does not get called for after.update
hooks (see Meteor-Community-Packages#297).
Fired after a find query.
Allows you to act on a given find query. The cursor resulting from the query is provided as the last argument for convenience.
test.after.find(function (userId, selector, options, cursor) {
// ...
});
Fired before a findOne query.
Allows you to adjust selector/options on-the-fly.
test.before.findOne(function (userId, selector, options) {
// ...
});
Fired after a findOne query.
Allows you to act on a given findOne query. The document resulting from the query is provided as the last argument for convenience.
test.after.findOne(function (userId, selector, options, doc) {
// ...
});
All compatible methods have a direct
version that circumvent any defined hooks. For example:
collection.direct.insert({_id: "test", test: 1});
collection.direct.insertAsync({_id: "test", test: 1});
collection.direct.upsert({_id: "test", test: 1});
collection.direct.upsertAsync({_id: "test", test: 1});
collection.direct.update({_id: "test"}, {$set: {test: 1}});
collection.direct.updateAsync({_id: "test"}, {$set: {test: 1}});
collection.direct.find({test: 1});
collection.direct.findOne({test: 1});
collection.direct.findOneAsync({test: 1});
collection.direct.remove({_id: "test"});
collection.direct.removeAsync({_id: "test"});
As of version 0.7.0, options can be passed to hook definitions. Default options can be specified globally and on a per-collection basis for all or some hooks, with more specific ones having higher specificity.
Examples (in order of least specific to most specific):
import { CollectionHooks } from 'meteor/matb33:collection-hooks';
CollectionHooks.defaults.all.all = {exampleOption: 1};
CollectionHooks.defaults.before.all = {exampleOption: 2};
CollectionHooks.defaults.after.all = {exampleOption: 3};
CollectionHooks.defaults.all.update = {exampleOption: 4};
CollectionHooks.defaults.all.remove = {exampleOption: 5};
CollectionHooks.defaults.before.insert = {exampleOption: 6};
CollectionHooks.defaults.after.remove = {exampleOption: 7};
Similarly, collection-wide options can be defined (these have a higher specificity than the global defaults from above):
import { Mongo } from 'meteor/mongo';
const testCollection = new Mongo.Collection("test");
testCollection.hookOptions.all.all = {exampleOption: 1};
testCollection.hookOptions.before.all = {exampleOption: 2};
testCollection.hookOptions.after.all = {exampleOption: 3};
testCollection.hookOptions.all.update = {exampleOption: 4};
testCollection.hookOptions.all.remove = {exampleOption: 5};
testCollection.hookOptions.before.insert = {exampleOption: 6};
testCollection.hookOptions.after.remove = {exampleOption: 7};
Currently (as of 0.7.0), only fetchPrevious
is implemented as an option, and
is only relevant to after-update hooks.
-
Returning
false
in anybefore
hook will prevent the underlying method (and subsequentafter
hooks) from executing. Note that allbefore
hooks will still continue to run even if the first hook returnsfalse
. -
If you wish to makeuserId
available to afind
query in apublish
function, try the technique detailed in this commentuserId
is available tofind
andfindOne
queries that were invoked within apublish
function. -
All hook callbacks have
this._super
available to them (the underlying method) as well asthis.context
, the equivalent ofthis
to the underlying method. Additionally,this.args
contain the original arguments passed to the method and can be modified by reference (for example, modifying a selector in abefore
hook so that the underlying method uses this new selector). -
It is quite normal for
userId
to sometimes be unavailable to hook callbacks in some circumstances. For example, if anupdate
is fired from the server with no user context, the server certainly won't be able to provide any particular userId. -
You can define a
defaultUserId
in case you want to pass an userId to the hooks but there is no context. For instance if you are executing and API endpoint where theuserId
is derived from a token. Just assign the userId toCollectionHooks.defaultUserId
. It will be overriden by the userId of the context if it exists. -
If, like me, you transform
Meteor.users
through a round-about way involvingfind
andfindOne
, then you won't be able to usethis.transform()
. Instead, grab the transformed user withfindOne
. -
When adding a hook, a handler object is returned with these methods:
remove()
: will remove that particular hook;replace(callback, options)
: will replace the hook callback and options.
-
If your hook is defined in common code (both server and client), it will run twice: once on the server and once on the client. If your intention is for the hook to run only once, make sure the hook is defined somewhere where only either the client or the server reads it. When in doubt, define your hooks on the server.
-
Both
update
andremove
internally make use offind
, so be aware thatfind
/findOne
hooks can fire for those methods. -
find
hooks are also fired when fetching documents forupdate
,upsert
andremove
hooks. -
If using the
direct
version to bypass a hook, any mongo operations done within nested callbacks of thedirect
operation will also by default run asdirect
. You can use the following line in a nested callback before the operation to unset thedirect
setting:CollectionHooks.directEnv = new Meteor.EnvironmentVariable(false)
Maintained by Meteor Community Packages and in particular by:
- Mathieu Bouchard (matb33)
- Andrew Mao (mizzao)
- Simon Fridlund (zimme)
- Jan Dvorak (StorytellerCZ)
- Eric Dobbertin (aldeed)
- Kevin Kaland (wizonesolutions)
- Jonathan James (jonjamz)
- Dave Workman (davidworkman9)
- Tarang Patel (Tarangp)
- Nathan Strauser (nate-strauser)
- Hubert OG (subhog)
- Richard Lai (rclai)
- Sahebjot Singh (raunaqrox)
- Aram Kocharyan (aramk)
- Pierre Ozoux (pierreozoux)
- Tom Coleman (tmeasday)
- Eric Jackson (repjackson)
- Koen Lav (KoenLav)
- Chris Pravetz (cpravetz)
- Jan Kuster (jankapunkt)