Merge pull request #4 from hiveteams/master

Set reactive callbacks based on whether or not cursor is ordered

Author: mitar

README.md

@@ -23,6 +23,60 @@ Installation
 meteor add peerlibrary:reactive-mongo
 ```
 
+Invalidating computations on Ordered vs. Unordered cursors
+------------
+In Meteor, there's a concept of `ordered` cursors. If a cursor is `ordered`, then when the order of the documents in the result set changes, the computation will be invalidated and the `autorun` will re-run.
+
+By default, this package will use an ordered cursor if a `sort` is present in the query. If no `sort` is specified, it will use an unordered cursor.
+
+To override the defualt functionality, you can explicitly force or un-force `ordered` by passing an `ordered` option to your `find`:
+
+```
+// Server code
+
+// Will use ordered since a sort is present
+Tracker.autorun(() => {
+  Posts.find({ topic: 'news' }, { sort: { name: 1 } }).fetch();
+});
+
+// Will use unordered since no sort is present
+Tracker.autorun(() => {
+  Posts.find({ topic: 'news' }).fetch();
+});
+
+// Will not use ordered since the option is forced to "false"
+Tracker.autorun(() => {
+  Posts.find({ topic: 'news' }, { sort: { name: 1 }, ordered: false }).fetch();
+});
+
+// Will use ordered since the option is forced to "true"
+Tracker.autorun(() => {
+  Posts.find({ topic: 'news' }, ordered: true }).fetch();
+});
+```
+
+Polling vs. Oplog inside autoruns
+------------
+A common use case for server autoruns is using a `findOne` to do a reactive join. Meteor's server-side `findOne` is a `find(selector, { limit: 1 }).fetch()[0]` [under the hood](https://github.com/meteor/meteor/blob/devel/packages/mongo/mongo_driver.js#L784). [Because Meteor Oplog does not support](https://galaxy-guide.meteor.com/apm-optimize-your-app-for-oplog.html#Limit-Without-Sort) `limit` without `sort`, calling `Collection.findOne(someId)` in a server autorun will default to using polling.
+
+
+If you'd like queries inside a server autorun to use Oplog, you'll need to specify a sort for your `findOne` **and** pass `ordered: false` to use unordered cursor:
+
+```
+// Server code
+
+// Will use oplog since it has sort, limit, and is unordered
+Tracker.autorun(() => {
+  Collection.findOne(someId, { sort: { _id: 1 }, ordered: false });
+});
+
+// Will use polling because a limit (from findOne) but no sort is specified
+Tracker.autorun(() => {
+  Collection.findOne(someId);
+});
+```
+
+
 Acknowledgments
 ---------------
 

server.coffee

@@ -40,16 +40,29 @@ MeteorCursor::observeChanges = (options) ->
       handle.stop()
   handle
 
+callbacksOrdered =
+  addedBefore: true
+  removed: true
+  changed: true
+  movedBefore: true
+
+callbacksUnordered =
+  added: true
+  changed: true
+  removed: true
+
 for method in ['forEach', 'map', 'fetch']
   do (method) ->
     originalMethod = MeteorCursor::[method]
     MeteorCursor::[method] = (args...) ->
       if @_isReactive()
-        @_depend
-          addedBefore: true
-          removed: true
-          changed: true
-          movedBefore: true
+        {sort, ordered} = @_cursorDescription.options
+        useOrderedOption = ordered != undefined
+        if useOrderedOption
+          callbacks = if ordered then callbacksOrdered else callbacksUnordered
+        else
+          callbacks = if !!sort then callbacksOrdered else callbacksUnordered
+        @_depend callbacks
 
       originalMethod.apply @, args