├── test ├── mocha.opts ├── anchor.js └── skip.js ├── .gitignore ├── Makefile ├── lib ├── index.js ├── anchor.js └── skip.js ├── package.json └── README.md /test/mocha.opts: -------------------------------------------------------------------------------- 1 | --reporter spec 2 | --ui bdd -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | node_modules/ 2 | *.DS_Store 3 | try.js 4 | npm-debug.log -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | test: 2 | ./node_modules/.bin/mocha 3 | 4 | .PHONY: test -------------------------------------------------------------------------------- /lib/index.js: -------------------------------------------------------------------------------- 1 | 2 | exports.anchor = function (schema) { 3 | schema.statics.findPaginated = require('./anchor.js'); 4 | } 5 | 6 | exports.skip = function (schema) { 7 | schema.statics.findPaginated = require('./skip.js'); 8 | } 9 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "mongoose-pages", 3 | "version": "0.0.3", 4 | "description": "Developer-friendly pagination plugin for Mongoose ODM", 5 | "main": "lib/index.js", 6 | "scripts": { 7 | "test": "mocha test" 8 | }, 9 | "repository": { 10 | "type": "git", 11 | "url": "git://github.com/hacksparrow/mongoose-pages.git" 12 | }, 13 | "keywords": [ 14 | "mongoose", 15 | "pagination", 16 | "mongodb", 17 | "database", 18 | "paginate" 19 | ], 20 | "author": "Hage Yaapa", 21 | "license": "ISC", 22 | "bugs": { 23 | "url": "https://github.com/hacksparrow/mongoose-pages/issues" 24 | }, 25 | "homepage": "https://github.com/hacksparrow/mongoose-pages", 26 | "devDependencies": { 27 | "mocha": "^1.20.1", 28 | "mongoose": "^3.8.13" 29 | } 30 | } 31 | -------------------------------------------------------------------------------- /lib/anchor.js: -------------------------------------------------------------------------------- 1 | module.exports = function (conditions, fields, options, callback, limit, anchorId) { 2 | 3 | var model = this; 4 | 5 | // re-assign params 6 | if ('function' == typeof conditions) { 7 | //console.log('A'); 8 | limit = fields; 9 | anchorId = options; 10 | callback = conditions; 11 | conditions = {}; 12 | fields = null; 13 | options = {}; 14 | 15 | } else if ('function' == typeof fields) { 16 | //console.log('B'); 17 | limit = options; 18 | anchorId = callback; 19 | callback = fields; 20 | fields = null; 21 | options = {}; 22 | 23 | } else if ('function' == typeof options) { 24 | //console.log('C'); 25 | anchorId = limit; 26 | limit = callback; 27 | callback = options; 28 | options = {}; 29 | 30 | } 31 | 32 | // set pagination filters 33 | if (anchorId) conditions._id = { $gt: anchorId } 34 | if (limit) options.limit = limit; 35 | 36 | return model.find(conditions, fields, options, function (err, docs) { 37 | 38 | if (err) { 39 | return callback(err); 40 | } 41 | else { 42 | 43 | var result = {} 44 | if (docs.length) { 45 | 46 | result.documents = docs; 47 | 48 | model.count(conditions, function (err, count) { 49 | 50 | var totalPages = count; 51 | 52 | if (limit) result.totalPages = Math.ceil(totalPages / limit); 53 | else result.totalPages = 1; 54 | 55 | if (result.totalPages > 1) { 56 | result.prevAnchorId = anchorId; 57 | result.nextAnchorId = docs[ docs.length - 1 ]._id.toString(); 58 | } 59 | 60 | callback(err, result); 61 | 62 | }) 63 | 64 | } 65 | else { 66 | result.documents = []; 67 | result.totalPages = 0; 68 | callback(err, result); 69 | } 70 | 71 | } 72 | 73 | }) 74 | 75 | 76 | } 77 | -------------------------------------------------------------------------------- /lib/skip.js: -------------------------------------------------------------------------------- 1 | module.exports = function (conditions, fields, options, callback, limit, pageNumber) { 2 | 3 | 4 | var model = this; 5 | 6 | // re-assign params 7 | if ('function' == typeof conditions) { 8 | //console.log('A'); 9 | limit = fields; 10 | pageNumber = options; 11 | callback = conditions; 12 | conditions = {}; 13 | fields = null; 14 | options = {}; 15 | 16 | } else if ('function' == typeof fields) { 17 | //console.log('B'); 18 | limit = options; 19 | pageNumber = callback; 20 | callback = fields; 21 | fields = null; 22 | options = {}; 23 | 24 | } else if ('function' == typeof options) { 25 | //console.log('C'); 26 | pageNumber = limit; 27 | limit = callback; 28 | callback = options; 29 | options = {}; 30 | 31 | } 32 | 33 | if (pageNumber < 1) { 34 | callback(new Error('Invalid Page Number')); 35 | } 36 | else if (!(typeof pageNumber == 'undefined') && isNaN(pageNumber)) { 37 | callback(new Error('Invalid Page Number')); 38 | } 39 | else { 40 | 41 | pageNumber = +pageNumber || 1; 42 | 43 | // set pagination filters 44 | if (pageNumber) options.skip = limit * (pageNumber - 1); 45 | if (limit) options.limit = limit; 46 | 47 | return model.find(conditions, fields, options, function (err, docs) { 48 | 49 | var result = {} 50 | 51 | if (docs && docs.length) { 52 | 53 | result.documents = docs; 54 | 55 | model.count(conditions, function (err, count) { 56 | 57 | var totalDocs = count; 58 | 59 | if (limit) result.totalPages = Math.ceil(totalDocs / limit); 60 | else result.totalPages = 1; 61 | 62 | if (result.totalPages > 1) { 63 | if (pageNumber > 1) result.prevPage = pageNumber - 1; 64 | if (pageNumber < result.totalPages) result.nextPage = pageNumber + 1; 65 | } 66 | 67 | callback(err, result); 68 | 69 | }) 70 | 71 | } else { 72 | 73 | result.documents = []; 74 | result.totalPages = 0; 75 | callback(err, result); 76 | 77 | } 78 | 79 | }) 80 | 81 | } 82 | 83 | } 84 | -------------------------------------------------------------------------------- /test/anchor.js: -------------------------------------------------------------------------------- 1 | var assert = require('assert'); 2 | var mongoose = require('mongoose'); 3 | var mongoosePages = require('../'); 4 | 5 | var limit, anchorId; 6 | var connection = mongoose.createConnection('mongodb://localhost/mongoose-pages'); 7 | 8 | var UserSchema = new mongoose.Schema({ 9 | username: String, 10 | points: Number, 11 | email: String 12 | }) 13 | mongoosePages.anchor(UserSchema); 14 | var User = connection.model('User', UserSchema); 15 | 16 | describe('mongoosePages.anchor', function() { 17 | 18 | 19 | // # make entries in the db, before testing 20 | var numberOfEntries = 27; 21 | 22 | before(function(done) { 23 | 24 | var populate = function populate(i, total, cb) { 25 | 26 | if (i > total) return cb(); 27 | 28 | var now = Date.now(); 29 | var username = 'dancer' + now + Math.floor(Math.random() * 100000000); 30 | var points = Math.floor(now * Math.random()/ 100000000); 31 | var email = now + '@disco.org'; 32 | 33 | new User({ 'username': username, 'points': points, 'email': email }) 34 | .save(function(err) { 35 | if (err) { return cb(err); } 36 | populate(++i, total, cb); 37 | } 38 | ) 39 | } 40 | 41 | return User.remove({}, function(err) { 42 | if (err) done(err); 43 | populate(1, numberOfEntries, done); 44 | }) 45 | 46 | }) 47 | 48 | // # after testing, close the db connection 49 | after(function() { connection.close(); }) 50 | 51 | 52 | //# test cases 53 | 54 | it('should get all ' + numberOfEntries + ' users', function(done) { 55 | User.findPaginated({}, function(err, result) { 56 | assert.equal(err, null); 57 | assert.equal(result.documents.length, numberOfEntries); 58 | done(err); 59 | }) 60 | }) 61 | 62 | it('should support conditions', function(done) { 63 | User.findPaginated({ points: { $gt: 5000 } }, function(err, result) { 64 | assert.equal(err, null); 65 | assert.ok(result.documents.length == 5); 66 | done(err); 67 | }, 5) 68 | }) 69 | 70 | it('should support fields', function(done) { 71 | User.findPaginated({}, 'username', function(err, result) { 72 | assert.equal(err, null); 73 | assert.ok(!result.documents[0].__v); 74 | assert.ok(result.documents[0].username.length); 75 | done(err); 76 | }, 10) 77 | }) 78 | 79 | it('should support options', function(done) { 80 | User.findPaginated({}, 'username', { limit: 2 }, function(err, result) { 81 | assert.equal(err, null); 82 | assert.ok(result.documents.length == 2); 83 | done(err); 84 | }) 85 | }) 86 | 87 | it('should set `nextAnchorId` and `prevAnchorId` as `undefined` if there is only one page', function(done) { 88 | User.findPaginated({}, function(err, result) { 89 | assert.equal(err, null); 90 | assert.ok(result.nextAnchorId == undefined); 91 | assert.ok(result.prevAnchorId == undefined); 92 | done(err); 93 | }) 94 | }) 95 | 96 | it('should set `nextAnchorId` to a doc id, and `prevAnchorId` to `undefined` on the first page', function(done) { 97 | 98 | User.findPaginated({}, function(err, result) { 99 | assert.equal(err, null); 100 | assert.ok(result.prevAnchorId == undefined); 101 | assert.ok(result.nextAnchorId.length == 24); 102 | done(err); 103 | }, 10) 104 | }) 105 | 106 | it('should get the next 10 users', function(done) { 107 | 108 | User.findPaginated({}, function(err, result) { 109 | User.findPaginated({}, function(err, result) { 110 | assert.equal(err, null); 111 | assert.ok(result.prevAnchorId.length == 24); 112 | assert.ok(result.nextAnchorId.length == 24); 113 | assert.equal(result.documents.length, 10); 114 | done(err); 115 | }, 10, result.nextAnchorId) 116 | 117 | }, 10) 118 | 119 | }) 120 | 121 | it('should return an empty error for a non-existent id', function(done) { 122 | User.findPaginated({}, function(err, result) { 123 | assert.equal(err, null); 124 | assert.equal(result.documents.length, 0); 125 | done(); 126 | }, 10, '999997a2047db76f2c670000') 127 | }) 128 | 129 | it('should return an error for an invalid id', function(done) { 130 | User.findPaginated({}, function(err, result) { 131 | assert.ok(err); 132 | assert.equal(result, undefined); 133 | done(); 134 | }, 10, 'x') 135 | }) 136 | 137 | describe('page count tests', function () { 138 | 139 | it('should have 27 pages', function(done) { 140 | User.findPaginated({}, function(err, result) { 141 | assert.equal(err, null); 142 | assert.equal(result.totalPages, 27); 143 | done(err); 144 | }, 1) 145 | }) 146 | 147 | it('should have 4 pages', function(done) { 148 | User.findPaginated({}, function(err, result) { 149 | assert.equal(err, null); 150 | assert.equal(result.totalPages, 6); 151 | done(err); 152 | }, 5) 153 | }) 154 | 155 | it('should have 3 pages', function(done) { 156 | User.findPaginated({}, function(err, result) { 157 | assert.equal(err, null); 158 | assert.equal(result.totalPages, 3); 159 | done(err); 160 | }, 10) 161 | }) 162 | 163 | }) 164 | 165 | }) 166 | 167 | 168 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | Mongoose Pages [![NPM version](https://badge.fury.io/js/mongoose-pages.svg)](https://badge.fury.io/js/mongoose-pages) 2 | ============== 3 | 4 | Developer-friendly pagination plugin for Mongoose ODM. 5 | 6 | ## Installation 7 | 8 | ``` 9 | $ npm install mongoose-pages 10 | ``` 11 | 12 | ## Usage 13 | 14 | Mongoose Pages offers pagination via two different implementations - **skip** and **anchor**. Both the implementations add a new method named `findPaginated()` to the model, which works like the regular `find()` method, except it accepts optional pagination options. 15 | 16 | Chose whichever works for your application, their details and differences are explained below. 17 | 18 | ###skip 19 | 20 | When you work with skip, you will get to work with the familiar `docsPerPage` and `pageNumber` objects. 21 | 22 | The result object will have the following structure. 23 | 24 | ``` 25 | { 26 | documents: Array; list of documents 27 | totalPages: Number; total number of pages, as per the `docsPerPage` value 28 | prevPage: Number; the previous page number 29 | nextPage: Number; the next page number 30 | } 31 | ``` 32 | 33 | `prevPage` will be undefined for the first page. `nextPage` will be undefined for the last page. 34 | 35 | Here is an example of using the the skip method for implementing pagination. 36 | 37 | ``` 38 | var mongoose = require('mongoose'); 39 | var Schema = mongoose.Schema; 40 | var mongoosePages = require('mongoose-pages'); 41 | 42 | var UserSchema = new Schema({ 43 | username: String, 44 | points: Number, 45 | email: String 46 | }) 47 | 48 | mongoosePages.skip(UserSchema); // makes the findPaginated() method available 49 | 50 | var docsPerPage = 10; 51 | var pageNumber = 1; 52 | 53 | var User = mongoose.model('User', UserSchema); 54 | User.findPaginated({}, function (err, result) { 55 | if (err) throw err; 56 | console.log(result); 57 | }, docsPerPage, pageNumber); // pagination options go here 58 | 59 | ``` 60 | 61 | **Pros** 62 | 63 | 1. Familiar concept of `docsPerPage` and `pageNumber`. 64 | 2. Can implement a paged navigation system. 65 | 3. Can jump to any page. 66 | 67 | **Cons** 68 | 69 | 1. Performance will degrade as the number of documents increase. This is a limitation is [MongoDB's skip](http://docs.mongodb.org/manual/reference/method/cursor.skip/). 70 | 2. Not recommended for high traffic websites with large number of documents in collection. 71 | 72 | ###anchor 73 | 74 | With anchoring, you get to work with `docsPerPage`, but lose the concept of `pageNumber`; instead you work with an `anchorId`. 75 | 76 | An anchor id is the document id which is used as a marker for making the query to MongoDB. Basically you tell Mongo, "Give me `docsPerPage` items from `anchorId` onwards". 77 | 78 | If the anchor id is not passed, it is assumed to be making a request for the first page. You get the `nextAnchorId` value from the result of the first page, to request for the second page etc. The document with the `anchorId` is not included in the result. 79 | 80 | **NOTE**: For pagination via anchoring, you will need to use an autoincrementing `_id` value; the default implementation of `_id` works just fine. If you don't like the default implementation of `_id`, you will need to implement `_id` of your own, which numerically autoincrements. 81 | 82 | The result object will have the following structure. 83 | 84 | ``` 85 | { 86 | documents: Array; list of documents 87 | totalPages: Number; total page count 88 | prevAnchorId: String; ObjectId which was used as the anchor id in the last request 89 | nextAnchorId: String; ObjectId which should be used as the anchor id in the next request 90 | } 91 | ``` 92 | 93 | `prevAnchorId` will be undefined for the first page. `nextAnchorId` will be undefined for the last page. 94 | 95 | Here is an example of using the the anchor method for implementing pagination. 96 | 97 | ``` 98 | var mongoose = require('mongoose'); 99 | var Schema = mongoose.Schema; 100 | var mongoosePages = require('mongoose-pages'); 101 | 102 | var UserSchema = new Schema({ 103 | username: String, 104 | points: Number, 105 | email: String 106 | }) 107 | 108 | mongoosePages.anchor(UserSchema); // makes the findPaginated() method available 109 | 110 | var docsPerPage = 10; 111 | var anchorId = '53c797a2043db36f2b673cd1'; 112 | 113 | var User = mongoose.model('User', UserSchema); 114 | User.findPaginated({}, function (err, result) { 115 | if (err) throw err; 116 | console.log(result); 117 | }, docsPerPage, anchorId); // pagination options go here 118 | ``` 119 | 120 | If you want to request the first page, just omit the `anchorId` parameter. 121 | 122 | ``` 123 | User.findPaginated({}, function (err, result) { 124 | if (err) throw err; 125 | console.log(result); 126 | }, docsPerPage); 127 | ``` 128 | 129 | **Pros** 130 | 131 | 1. Performance is not affected with increasing number of documents in the collection. 132 | 2. Recommended for high traffic websites. 133 | 3. Navigation is previou-next based. 134 | 135 | **Cons** 136 | 137 | 1. Page navigation is sequential. 138 | 2. Pages cannot be referenced via page numbers. 139 | 3. Cannot jump to pages. However, it can jump to anchor points, once you have the reference. 140 | 141 | 142 | ## License 143 | 144 | Copyright (c) 2014 Hage Yaapa <captain@hacksparrow.com> 145 | 146 | Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies. 147 | 148 | THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 149 | -------------------------------------------------------------------------------- /test/skip.js: -------------------------------------------------------------------------------- 1 | var assert = require('assert'); 2 | var mongoose = require('mongoose'); 3 | var mongoosePages = require('../'); 4 | 5 | var limit, anchorId; 6 | var connection = mongoose.createConnection('mongodb://localhost/mongoose-pages'); 7 | 8 | var UserSchema = new mongoose.Schema({ 9 | username: String, 10 | points: Number, 11 | email: String 12 | }) 13 | mongoosePages.skip(UserSchema); 14 | var User = connection.model('User', UserSchema); 15 | 16 | describe('mongoosePages.skip', function() { 17 | 18 | 19 | // # make entries in the db, before testing 20 | var numberOfEntries = 27; 21 | 22 | before(function(done) { 23 | 24 | var populate = function populate(i, total, cb) { 25 | 26 | if (i > total) return cb(); 27 | 28 | var now = Date.now(); 29 | var username = 'dancer' + now + Math.floor(Math.random() * 100000000); 30 | var points = Math.floor(now * Math.random()/ 100000000); 31 | var email = now + '@disco.org'; 32 | 33 | new User({ 'username': username, 'points': points, 'email': email }) 34 | .save(function(err) { 35 | if (err) { return cb(err); } 36 | populate(++i, total, cb); 37 | } 38 | ) 39 | } 40 | 41 | return User.remove({}, function(err) { 42 | if (err) done(err); 43 | populate(1, numberOfEntries, done); 44 | }) 45 | 46 | }) 47 | 48 | // # after testing, close the db connection 49 | after(function() { connection.close(); }) 50 | 51 | 52 | //# test cases 53 | 54 | it('should get all ' + numberOfEntries + ' users', function(done) { 55 | User.findPaginated({}, function(err, result) { 56 | assert.equal(err, null); 57 | assert.equal(result.documents.length, numberOfEntries); 58 | done(err); 59 | }) 60 | }) 61 | 62 | it('should support conditions', function(done) { 63 | User.findPaginated({ points: { $gt: 5000 } }, function(err, result) { 64 | assert.equal(err, null); 65 | assert.ok(result.documents.length == 5); 66 | done(err); 67 | }, 5) 68 | }) 69 | 70 | it('should support fields', function(done) { 71 | User.findPaginated({}, 'username', function(err, result) { 72 | assert.equal(err, null); 73 | assert.ok(!result.documents[0].__v); 74 | assert.ok(result.documents[0].username.length); 75 | done(err); 76 | }, 10) 77 | }) 78 | 79 | it('should support options', function(done) { 80 | User.findPaginated({}, 'username', { limit: 2 }, function(err, result) { 81 | assert.equal(err, null); 82 | assert.ok(result.documents.length == 2); 83 | done(err); 84 | }) 85 | }) 86 | 87 | it('should set `nextPage` and `prevPage` as `undefined` if there is only one page', function(done) { 88 | User.findPaginated({}, function(err, result) { 89 | assert.equal(err, null); 90 | assert.ok(undefined == result.prevPag); 91 | assert.ok(undefined == result.nextPage); 92 | done(err); 93 | }) 94 | }) 95 | 96 | it('should set `nextPage` to a page number, and `prevPage` should be `undefined` on the first page', function(done) { 97 | 98 | User.findPaginated({}, function(err, result) { 99 | assert.equal(err, null); 100 | assert.ok(undefined == result.prevPag); 101 | assert.ok('number' == typeof result.nextPage); 102 | done(err); 103 | }, 10) 104 | }) 105 | 106 | it('should get the next 10 users', function(done) { 107 | User.findPaginated({}, function(err, result) { 108 | assert.equal(err, null); 109 | assert.ok('number' == typeof result.prevPage); 110 | assert.ok('number' == typeof result.nextPage); 111 | assert.equal(result.prevPage, 1); 112 | assert.equal(result.nextPage, 3); 113 | assert.equal(result.documents.length, 10); 114 | done(err); 115 | }, 10, 2) 116 | }) 117 | 118 | it('should get the last 7 users', function(done) { 119 | User.findPaginated({}, function(err, result) { 120 | assert.equal(err, null); 121 | assert.equal(result.documents.length, 7); 122 | done(err); 123 | }, 10, 3) 124 | }) 125 | 126 | it('should set `prevPage` to a number on the last page, and `nextPage` should be `undefined`', function(done) { 127 | User.findPaginated({}, function(err, result) { 128 | assert.equal(err, null); 129 | assert.ok('number' == typeof result.prevPage); 130 | assert.ok(undefined == result.nextPage); 131 | done(err); 132 | }, 10, 3) 133 | }) 134 | 135 | it('should return an error for a negative page number', function(done) { 136 | User.findPaginated({}, function(err, result) { 137 | assert.ok(err); 138 | done(); 139 | }, 10, -1) 140 | }) 141 | 142 | it('should return an error for an invalid page number', function(done) { 143 | User.findPaginated({}, function(err, result) { 144 | assert.ok(err); 145 | done(); 146 | }, 10, 'x') 147 | }) 148 | 149 | it('should return an empty array a non-existent positive page number', function(done) { 150 | User.findPaginated({}, function(err, result) { 151 | assert.equal(err, null); 152 | assert.equal(result.documents.length, 0); 153 | done(err); 154 | }, 10, 1000) 155 | }) 156 | 157 | describe('page count tests', function () { 158 | 159 | it('should have 27 pages', function(done) { 160 | User.findPaginated({}, function(err, result) { 161 | assert.equal(err, null); 162 | assert.equal(result.totalPages, 27); 163 | done(err); 164 | }, 1) 165 | }) 166 | 167 | it('should have 4 pages', function(done) { 168 | User.findPaginated({}, function(err, result) { 169 | assert.equal(err, null); 170 | assert.equal(result.totalPages, 6); 171 | done(err); 172 | }, 5) 173 | }) 174 | 175 | it('should have 3 pages', function(done) { 176 | User.findPaginated({}, function(err, result) { 177 | assert.equal(err, null); 178 | assert.equal(result.totalPages, 3); 179 | done(err); 180 | }, 10) 181 | }) 182 | 183 | }) 184 | }) 185 | 186 | 187 | 188 | 189 | --------------------------------------------------------------------------------