Repository: kadirahq/subs-manager Branch: master Commit: 305cf5c3b3bc Files: 13 Total size: 23.6 KB Directory structure: gitextract_6bzr4c0d/ ├── .gitignore ├── .travis.yml ├── CHANGELOG.md ├── LICENSE ├── README.md ├── lib/ │ └── sub_manager.js ├── package.js ├── smart.json ├── tests/ │ ├── core.js │ ├── error.js │ ├── init.js │ └── options.js └── versions.json ================================================ FILE CONTENTS ================================================ ================================================ FILE: .gitignore ================================================ .build* ================================================ FILE: .travis.yml ================================================ language: node_js node_js: - "0.10" before_install: - "curl -L http://git.io/ejPSng | /bin/sh" ================================================ FILE: CHANGELOG.md ================================================ # Change Log ### v1.6.4 2016-March-21 * Fix minor typo in the code related to cacheMap. ### v1.6.3 * Fix failing tests. * Update documentation. ### v1.6.2 * the feature of `subs.ready() === false` at initially causing SSR to not work properly. This version fix that. ### v1.6.1 * Add reactive changes related improvements - Make subs.ready() === false if there is no subs inside the subscription - Fire dep.changed() very carefully to avoid reactive loops ### v1.6.0 * Add gloabl `.ready()` api where we check the ready status of the whole subsManager at anytime. ### v1.4.0 IE8 Compatibility ================================================ FILE: LICENSE ================================================ The MIT License (MIT) Copyright (c) 2014 MeteorHacks Pvt Ltd. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ================================================ FILE: README.md ================================================ # SubsManager [![Build Status](https://travis-ci.org/kadirahq/subs-manager.svg?branch=master)](https://travis-ci.org/kadirahq/subs-manager) #### Subscriptions Manager for Meteor This is a general-purpose subscriptions manager for Meteor. You can use Subscription Manager to cache subscriptions in the client side. This will help you to reduce the CPU usage of your app and improve the client side experience. ## Why? Normally you invoke subscriptions inside the template level or in the router level(in the case of Iron Router). So, when you are switching routes or changing templates/components, subscriptions will run again. Normally, users go back and forth in your app in a single session. So, in each those route/page changes, app will re-subscribe data from the server. That's a [waste](https://kadira.io/academy/reduce-bandwidth-and-cpu-waste/) and slow down your app in the client side. ## Solution Subscriptions Manager caches your subscriptions in the client side. So, when the user switching between routes, he will no longer have to wait. Also, Meteor won't need to re-send data that's already in the client. In technical terms, Subscriptions Manager runs it's own `Tracker.autorun` computation internally. It does not interfere with Router or Templates. It works independently. > Subscriptions Manager does not cache your individual data. It tells Meteor to cache the whole subscription. So, your data will get updated in the background as usual. ## Usage Installation: ~~~ meteor add meteorhacks:subs-manager ~~~ Then create a new SubsManager instance: ~~~js PostSubs = new SubsManager(); ~~~ Then instead of subscribing to `Meteor.subscribe()`, use `PostSubs.subscribe()`. Check this example: ~~~js Template.blogPost.onCreated(function() { var self = this; self.ready = new ReactiveVar(); self.autorun(function() { var postId = FlowRouter.getQueryParam('postId'); var handle = PostSubs.subscribe('singlePost', postId); self.ready.set(handle.ready()); }); }); ~~~ Here's how this works: * Let's say you visit page `/posts?postId=abc`. * Then Meteor will subscribe to the `singlePost` publication with `abc` as the postId. * Then let's imagine you visit to `/posts?postId=bbc`. * Just like above, it'll subscribe to the `singlePost` publication with `bbc` as the postId. * Now, let's say we go back to `/posts?postId=abc`. Then, subsManager won't fetch data again from the server. Subscription is already exists inside the client. Check following links for more information: * [Related docs in the FlowRouter Guide](https://kadira.io/academy/meteor-routing-guide/content/subscriptions-and-data-management/using-subs-manager) * [BulletProof Meteor Lesson](https://bulletproofmeteor.com/basics/subscription-caching) ### Resetting Sometime, we need to re-run our subscriptions due to various reasons. > Eg:- After a user has update the plan. In those situations, you can try to reset Subscription Manager. ~~~js var subs = new SubsManager(); // later in some other place subs.reset(); ~~~ ### Clear Subscriptions In some cases, we need to clear the all the subscriptions we cache. So, this is how we can do it. ~~~js var subs = new SubsManager(); // later in some other place subs.clear(); ~~~ ## Cache Control Since now you are caching subscriptions, the Meteor server will also cache all your client data. But don't worry - that's not a huge issue. But, you can control the caching behavior. Here's how to do it. ~~~js var subs = new SubsManager({ // maximum number of cache subscriptions cacheLimit: 10, // any subscription will be expire after 5 minute, if it's not subscribed again expireIn: 5 }); ~~~ ## Patterns for using SubsManager ### Using a global Subscription Manager You can create a global subscription manager as shown in the above example. By doing that, all your subscriptions are cached as a whole. ### Using separate Subscription Managers If you need more control over caching, you can create separate Subscription Managers for each set of subscriptions and manage them differently. > If you are using SubsManager inside a ReactComponents, this is the suggested way. ### Using global ready checking You can also check the ready status of all the subscriptions at once like this: ~~~js var subs = new SubsManager(); subs.subscribe('postList'); subs.subscribe('singlePost', 'id1'); Tracker.autorun(function() { if(subs.ready()) { // all the subscriptions are ready to use. } }); ~~~ ### Cache subscriptions you only need With Subscription Manager you don't need to use it everywhere. Simply use it wherever you need without changing other subscriptions. ## Limitations Subscription Manager aims to be a drop-in replacement for [`Meteor.subscribe`](http://docs.meteor.com/#meteor_subscribe) (or `this.subscribe()` in Iron Router). At the moment, the following functionality doesn't work. * `onError` and `onReady` callbacks ([issue](https://github.com/meteorhacks/subs-manager/issues/7)) ================================================ FILE: lib/sub_manager.js ================================================ var FastRender = null; if(Package['meteorhacks:fast-render']) { FastRender = Package['meteorhacks:fast-render'].FastRender; } SubsManager = function (options) { var self = this; self.options = options || {}; // maxiumum number of subscriptions are cached self.options.cacheLimit = self.options.cacheLimit || 10; // maximum time, subscription stay in the cache self.options.expireIn = self.options.expireIn || 5; self._cacheMap = {}; self._cacheList = []; self._ready = false; self.dep = new Deps.Dependency(); self.computation = self._registerComputation(); }; SubsManager.prototype.subscribe = function() { var self = this; if(Meteor.isClient) { var args = _.toArray(arguments); this._addSub(args); return { ready: function() { self.dep.depend(); return self._ready; } }; } else { // to support fast-render if(Meteor.subscribe) { return Meteor.subscribe.apply(Meteor, arguments); } } }; SubsManager.prototype._addSub = function(args) { var self = this; var hash = EJSON.stringify(args); var subName = args[0]; var paramsKey = EJSON.stringify(args.slice(1)); if(!self._cacheMap[hash]) { var sub = { args: args, hash: hash }; this._handleError(sub); self._cacheMap[hash] = sub; self._cacheList.push(sub); // if fast-render comes with this subscription // we need to fake the ready message at first // This is because we are delaying the actual subscription evaluation // May be FastRender needs to send full list of subscription args to the client // But, for now this is something working if(FastRender && FastRender._subscriptions && FastRender._subscriptions[subName]) { self._ready = self._ready && FastRender._subscriptions[subName][paramsKey]; } else { self._ready = false; } // to notify the global ready() self._notifyChanged(); // no need to interfere with the current computation self._reRunSubs(); } // add the current sub to the top of the list var sub = self._cacheMap[hash]; sub.updated = (new Date).getTime(); var index = _.indexOf(self._cacheList, sub); self._cacheList.splice(index, 1); self._cacheList.push(sub); }; SubsManager.prototype._reRunSubs = function() { var self = this; if(Deps.currentComputation) { Deps.afterFlush(function() { self.computation.invalidate(); }); } else { self.computation.invalidate(); } }; SubsManager.prototype._notifyChanged = function() { var self = this; if(Deps.currentComputation) { setTimeout(function() { self.dep.changed(); }, 0); } else { self.dep.changed(); } }; SubsManager.prototype._applyCacheLimit = function () { var self = this; var overflow = self._cacheList.length - self.options.cacheLimit; if(overflow > 0) { var removedSubs = self._cacheList.splice(0, overflow); _.each(removedSubs, function(sub) { delete self._cacheMap[sub.hash]; }); } }; SubsManager.prototype._applyExpirations = function() { var self = this; var newCacheList = []; var expirationTime = (new Date).getTime() - self.options.expireIn * 60 * 1000; _.each(self._cacheList, function(sub) { if(sub.updated >= expirationTime) { newCacheList.push(sub); } else { delete self._cacheMap[sub.hash]; } }); self._cacheList = newCacheList; }; SubsManager.prototype._registerComputation = function() { var self = this; var computation = Deps.autorun(function() { self._applyExpirations(); self._applyCacheLimit(); var ready = true; _.each(self._cacheList, function(sub) { sub.ready = Meteor.subscribe.apply(Meteor, sub.args).ready(); ready = ready && sub.ready; }); if(ready) { self._ready = true; self._notifyChanged(); } }); return computation; }; SubsManager.prototype._createIdentifier = function(args) { var tmpArgs = _.map(args, function(value) { if(typeof value == "string") { return '"' + value + '"'; } else { return value; } }); return tmpArgs.join(', '); }; SubsManager.prototype._handleError = function(sub) { var args = sub.args; var lastElement = _.last(args); sub.identifier = this._createIdentifier(args); if(!lastElement) { args.push({onError: errorHandlingLogic}); } else if(typeof lastElement == "function") { args.pop(); args.push({onReady: lastElement, onError: errorHandlingLogic}); } else if(typeof lastElement.onError == "function") { var originalOnError = lastElement.onError; lastElement.onError = function(err) { errorHandlingLogic(err); originalOnError(err); }; } else if(typeof lastElement.onReady == "function") { lastElement.onError = errorHandlingLogic; } else { args.push({onError: errorHandlingLogic}); } function errorHandlingLogic (err) { console.log("Error invoking SubsManager.subscribe(%s): ", sub.identifier , err.reason); // expire this sub right away. // Then expiration machanism will take care of the sub removal sub.updated = new Date(1); } }; SubsManager.prototype.reset = function() { var self = this; var oldComputation = self.computation; self.computation = self._registerComputation(); // invalidate the new compuation and it will fire new subscriptions self.computation.invalidate(); // after above invalidation completed, fire stop the old computation // which then send unsub messages // mergeBox will correct send changed data and there'll be no flicker Deps.afterFlush(function() { oldComputation.stop(); }); }; SubsManager.prototype.clear = function() { this._cacheList = []; this._cacheMap = {}; this._reRunSubs(); }; SubsManager.prototype.ready = function() { this.dep.depend(); // if there are no items in the cacheList we are not ready yet. if(this._cacheList.length === 0) { return false; } return this._ready; }; ================================================ FILE: package.js ================================================ Package.describe({ "summary": "Subscriptions Manager for Meteor", "version": "1.6.4", "git": "https://github.com/meteorhacks/subs-manager.git", "name": "meteorhacks:subs-manager" }); Package.on_use(function(api) { configurePackage(api); api.export(['SubsManager']); }); Package.on_test(function(api) { configurePackage(api); api.use(['tinytest', 'mongo-livedata', 'session'], ['client', 'server']); api.add_files([ 'tests/init.js', ], ['server', 'client']); api.add_files([ 'tests/options.js', 'tests/core.js', 'tests/error.js' ], ['client']); }); function configurePackage(api) { if(api.versionsFrom) { api.versionsFrom('METEOR@0.9.0'); } api.use(['deps', 'underscore', 'ejson'], ['client', 'server']); api.use('meteorhacks:fast-render@2.7.0', 'client', {weak: true}); api.add_files([ 'lib/sub_manager.js', ], ['client', 'server']); } ================================================ FILE: smart.json ================================================ { "name": "subs-manager", "description": "Subscriptions Manager for Meteor", "homepage": "https://github.com/meteorhacks/subs-manager", "author": "MeteorHacks ", "version": "1.3.0", "git": "https://github.com/meteorhacks/subs-manager.git" } ================================================ FILE: tests/core.js ================================================ Tinytest.addAsync('core - init', function(test, done) { Meteor.call('init', done); }); Tinytest.addAsync('core - single subscribe', function(test, done) { var sm = new SubsManager(); Deps.autorun(function(c) { var status = sm.subscribe('posts'); if(status.ready()) { var posts = Posts.find().fetch(); test.equal(posts, [{_id: 'one'}]); sm.clear(); c.stop(); Meteor.defer(done); } }); }); Tinytest.addAsync('core - multi subscribe', function(test, done) { var sm = new SubsManager(); var subs = {}; Session.set('sub', 'posts'); Deps.autorun(function(c) { var sub = Session.get('sub'); subs[sub] = true; var handler = sm.subscribe(sub); if(_.keys(subs).length == 2) { if(handler.ready()) { test.equal(Posts.find().count(), 1); test.equal(Comments.find().count(), 1); sm.clear(); c.stop(); Meteor.defer(done); } } }); Meteor.call('wait', 200, function() { Session.set('sub', 'comments'); }); }); Tinytest.addAsync('core - global ready method - basic usage', function(test, done) { var sm = new SubsManager(); Deps.autorun(function(c) { sm.subscribe('posts'); if(sm.ready()) { var posts = Posts.find().fetch(); test.equal(posts, [{_id: 'one'}]); sm.clear(); c.stop(); Meteor.defer(done); } }); }); Tinytest.addAsync('core - global ready method - and change it - aa', function(test, done) { var sm = new SubsManager(); var readyCalledOnce = false; Deps.autorun(function(c) { sm.subscribe('posts'); var readyState = sm.ready(); if(readyState) { var posts = Posts.find().fetch(); test.equal(posts, [{_id: 'one'}]); readyCalledOnce = true; // with this, ready status became false sm.subscribe('not-existing-sub'); } else if(readyCalledOnce) { sm.clear(); c.stop(); Meteor.defer(done); } }); }); Tinytest.addAsync('core - global ready method - initial state', function(test, done) { var sm = new SubsManager(); test.equal(sm.ready(), false); done(); }); Tinytest.addAsync('core - multi subscribe but single collection', function(test, done) { var sm = new SubsManager(); var ids = {}; Session.set('id', 'one'); Deps.autorun(function(c) { var id = Session.get('id'); ids[id] = true; var handler = sm.subscribe('singlePoint', id); if(_.keys(ids).length == 2) { if(handler.ready()) { test.equal(Points.find().count(), 2); c.stop(); Meteor.defer(done); } } }); Meteor.call('wait', 200, function() { Session.set('id', 'two'); }); }); Tinytest.addAsync('core - resetting', function(test, done) { var sm = new SubsManager(); var allowed = false; Meteor.call('postsOnlyAllowed.allow', false, function() { Deps.autorun(function(c) { var status = sm.subscribe('postsOnlyAllowed'); var readyState = status.ready(); if(!allowed) { if(readyState) { var posts = PostsOnlyAllowed.find().fetch(); test.equal(posts, []); allowed = true; Meteor.call('postsOnlyAllowed.allow', true, function() { sm.reset(); }); } } else { var posts = PostsOnlyAllowed.find().fetch(); if(posts.length == 1) { test.equal(posts, [{_id: 'one'}]); sm.clear(); c.stop(); Meteor.defer(done); } } }); }); }); Tinytest.addAsync('core - clear subscriptions', function(test, done) { var sm = new SubsManager(); Deps.autorun(function(c) { var status = sm.subscribe('posts'); if(status.ready()) { var posts = Posts.find().fetch(); test.equal(posts, [{_id: 'one'}]); sm.clear(); c.stop(); setTimeout(checkPostsAgain, 200); } }); function checkPostsAgain() { var postCount = Posts.find({_id: "one"}).count(); test.equal(postCount, 0); done(); } }); ================================================ FILE: tests/error.js ================================================ Tinytest.addAsync('subs with error - mix of error and non error', function(test, done) { var sm = new SubsManager(); var subscribeToErrorOne = _.once(function() { return sm.subscribe('error-one'); }); Deps.autorun(function(c) { var status = subscribeToErrorOne(); status = sm.subscribe('posts'); if(status.ready()) { sm.clear(); c.stop(); Meteor.defer(done); } }); }); Tinytest.addAsync('subs with error - with existing ready callback', function(test, done) { var sm = new SubsManager(); var subscribeToErrorOne = _.once(function() { return sm.subscribe('error-one', function() {}); }); Deps.autorun(function(c) { var status = subscribeToErrorOne(); status = sm.subscribe('posts'); if(status.ready()) { sm.clear(); c.stop(); Meteor.defer(done); } }); }); Tinytest.addAsync('subs with error - with existing onReady', function(test, done) { var sm = new SubsManager(); var subscribeToErrorOne = _.once(function() { return sm.subscribe('error-one', {onReady: function() {}}); }); Deps.autorun(function(c) { var status = subscribeToErrorOne(); status = sm.subscribe('posts'); if(status.ready()) { sm.clear(); c.stop(); Meteor.defer(done); } }); }); Tinytest.addAsync('subs with error - with existing onError', function(test, done) { var sm = new SubsManager(); var called = false; var subscribeToErrorOne = _.once(function() { return sm.subscribe('error-one', {onError: function() {called = true;}}); }); Deps.autorun(function(c) { var status = subscribeToErrorOne(); status = sm.subscribe('posts'); if(status.ready()) { test.isTrue(called); sm.clear(); c.stop(); Meteor.defer(done); } }); }); Tinytest.addAsync('subs with error - with some args', function(test, done) { var sm = new SubsManager(); var subscribeToErrorOne = _.once(function() { return sm.subscribe('error-one', "args"); }); Deps.autorun(function(c) { var status = subscribeToErrorOne(); status = sm.subscribe('posts'); if(status.ready()) { sm.clear(); c.stop(); Meteor.defer(done); } }); }); Tinytest.addAsync('subs with error - just the error sub', function(test, done) { var sm = new SubsManager(); var subscribeToErrorOne = _.once(function() { return sm.subscribe('error-one'); }); var c = Deps.autorun(function() { var status = sm.subscribe('error-one') if(status.ready()) { test.fail("This should not pass!"); } }); Meteor.setTimeout(function() { sm.clear(); c.stop(); Meteor.defer(done); }, 100); }); ================================================ FILE: tests/init.js ================================================ Posts = new Meteor.Collection('posts'); PostsOnlyAllowed = new Meteor.Collection('posts-only-allowed'); Comments = new Meteor.Collection('comments'); Points = new Meteor.Collection('points'); if(Meteor.isServer) { Meteor.publish('posts', function() { return Posts.find(); }); Meteor.publish('postsOnlyAllowed', function() { if(PostsOnlyAllowed._allowed) { return PostsOnlyAllowed.find(); } else { this.ready(); } }); Meteor.publish('comments', function() { return Comments.find(); }); Meteor.publish('singlePoint', function(id) { return Points.find(id); }); Meteor.publish('error-one', function(id) { throw new Meteor.Error(400, "dddd"); }); // using this method since PhantomJS does have support setTimeout Meteor.methods({ "wait": function(millis) { Meteor.wrapAsync(function(done) { setTimeout(done, millis); })(); }, "init": function() { Posts.remove({}); Comments.remove({}); Points.remove({}); PostsOnlyAllowed.remove({}); Posts.insert({_id: "one"}); Comments.insert({_id: "one"}); Points.insert({_id: "one"}); Points.insert({_id: "two"}); PostsOnlyAllowed.insert({_id: "one"}); }, "postsOnlyAllowed.allow": function(allowed) { PostsOnlyAllowed._allowed = allowed; } }); } ================================================ FILE: tests/options.js ================================================ Tinytest.add('options cacheLimit - exceed', function(test) { var sm = new SubsManager({cacheLimit: 2}); sm._addSub(['posts']); sm._addSub(['comments']); sm._addSub(['singlePoint', 'one']); sm._applyCacheLimit(); test.equal(sm._cacheList.length, 2); var subsIds = sm._cacheList.map(function(sub) { return sub.args[0]; }); test.equal(subsIds, ['comments', 'singlePoint']); sm.clear(); }); Tinytest.add('options cacheLimit - not-exceed', function(test) { var sm = new SubsManager({cacheLimit: 10}); sm._addSub(['posts']); sm._addSub(['comments']); sm._addSub(['singlePoint', 'one']); sm._applyCacheLimit(); test.equal(sm._cacheList.length, 3); var subsIds = sm._cacheList.map(function(sub) { return sub.args[0]; }); test.equal(subsIds, ['posts', 'comments', 'singlePoint']); sm.clear(); }); Tinytest.addAsync('options expireIn - expired', function(test, done) { // expireIn 100 millis var sm = new SubsManager({cacheLimit: 20, expireIn: 1/60/10}); sm._addSub(['posts']); sm._addSub(['comments']); test.equal(sm._cacheList.length, 2); Meteor.call('wait', 200, function() { sm._applyExpirations(); test.equal(sm._cacheList.length, 0); sm.clear(); done(); }); }); Tinytest.addAsync('options expireIn - not expired', function(test, done) { // expireIn 2 minutes var sm = new SubsManager({cacheLimit: 20, expireIn: 2}); sm._addSub(['posts']); sm._addSub(['comments']); test.equal(sm._cacheList.length, 2); Meteor.call('wait', 200, function() { sm._applyExpirations(); test.equal(sm._cacheList.length, 2); sm.clear(); done(); }); }); ================================================ FILE: versions.json ================================================ { "dependencies": [ [ "base64", "1.0.1" ], [ "deps", "1.0.5" ], [ "ejson", "1.0.4" ], [ "json", "1.0.1" ], [ "meteor", "1.1.3" ], [ "tracker", "1.0.3" ], [ "underscore", "1.0.1" ] ], "pluginDependencies": [], "toolVersion": "meteor-tool@1.0.35", "format": "1.0" }