mongoose-aggregate-paginate-v2

A page based custom aggregate pagination library for Mongoose with customizable labels.

If you are looking for basic query pagination library without aggregate, use this one mongoose-paginate-v2

Installation

1npm install mongoose-aggregate-paginate-v2

Usage

Adding the plugin to a schema,

1var mongoose = require("mongoose");
2var aggregatePaginate = require("mongoose-aggregate-paginate-v2");
3
4var mySchema = new mongoose.Schema({
5  /* your schema definition */
6});
7
8mySchema.plugin(aggregatePaginate);
9
10var myModel = mongoose.model("SampleModel", mySchema);

and then use model aggregatePaginate method,

1// as Promise
2
3var myModel = require("/models/samplemodel");
4
5const options = {
6  page: 1,
7  limit: 10,
8};
9
10var myAggregate = myModel.aggregate();
11myModel
12  .aggregatePaginate(myAggregate, options)
13  .then(function (results) {
14    console.log(results);
15  })
16  .catch(function (err) {
17    console.log(err);
18  });

1// as Callback
2
3var myModel = require('/models/samplemodel');
4
5const options = {
6    page: 1,
7    limit: 10
8};
9
10var myAggregate = myModel.aggregate();
11myModel.aggregatePaginate(myAggregate, options, function(err, results) {
12	if(err) {
13		console.err(err);
14	else {
15    	console.log(results);
16	}
17})

1// Execute pagination from aggregate
2const myModel = require('/models/samplemodel');
3
4const options = {
5    page: 1,
6    limit: 10
7};
8
9const myAggregate = myModel.aggregate();
10myAggregate.paginateExec(options, function(err, results) {
11	if(err) {
12		console.err(err);
13	else {
14    	console.log(results);
15	}
16})

Model.aggregatePaginate([aggregateQuery], [options], [callback])

Returns promise

Parameters

• [aggregate-query] {Object} - Aggregate Query criteria. Documentation
• [options] {Object}
  • [sort] {Object | String} - Sort order. Documentation
  • [offset=0] {Number} - Use offset or page to set skip position
  • [page] {Number} - Current Page (Defaut: 1)
  • [limit] {Number} - Docs. per page (Default: 10).
  • [customLabels] {Object} - Developers can provide custom labels for manipulating the response data.
  • [pagination] {Boolean} - If pagination is set to false, it will return all docs without adding limit condition. (Default: True)
  • [allowDiskUse] {Bool} - To enable diskUse for bigger queries. (Default: False)
  • [countQuery] {Object} - Aggregate Query used to count the resultant documents. Can be used for bigger queries. (Default: aggregate-query)
  • [useFacet] {Bool} - To use facet operator instead of using two queries. This is the new default. (Default: true)
• [callback(err, result)] - (Optional) If specified the callback is called once pagination results are retrieved or when an error has occurred.

Return value

Promise fulfilled with object having properties:

• docs {Array} - Array of documents
• totalDocs {Number} - Total number of documents that match a query
• limit {Number} - Limit that was used
• page {Number} - Current page number
• totalPages {Number} - Total number of pages.
• offset {Number} - Only if specified or default page/offset values were used
• hasPrevPage {Bool} - Availability of prev page.
• hasNextPage {Bool} - Availability of next page.
• prevPage {Number} - Previous page number if available or NULL
• nextPage {Number} - Next page number if available or NULL
• pagingCounter {Number} - The starting sl. number of first document.
• meta {Object} - Object of pagination meta data (Default false).

Please note that the above properties can be renamed by setting customLabels attribute.

Sample Usage

Return first 10 documents from 100

1const options = {
2  page: 1,
3  limit: 10,
4};
5
6// Define your aggregate.
7var aggregate = Model.aggregate();
8
9Model.aggregatePaginate(aggregate, options)
10  .then(function (result) {
11    // result.docs
12    // result.totalDocs = 100
13    // result.limit = 10
14    // result.page = 1
15    // result.totalPages = 10
16    // result.hasNextPage = true
17    // result.nextPage = 2
18    // result.hasPrevPage = false
19    // result.prevPage = null
20  })
21  .catch(function (err) {
22    console.log(err);
23  });

With custom return labels

Now developers can specify the return field names if they want. Below are the list of attributes whose name can be changed.

• totalDocs
• docs
• limit
• page
• nextPage
• prevPage
• totalPages
• hasNextPage
• hasPrevPage
• pagingCounter
• meta

You should pass the names of the properties you wish to changes using customLabels object in options. Labels are optional, you can pass the labels of what ever keys are you changing, others will use the default labels.

If you want to return paginate properties as a separate object then define customLabels.meta.

Same query with custom labels

1
2const myCustomLabels = {
3  totalDocs: 'itemCount',
4  docs: 'itemsList',
5  limit: 'perPage',
6  page: 'currentPage',
7  nextPage: 'next',
8  prevPage: 'prev',
9  totalPages: 'pageCount',
10  hasPrevPage: 'hasPrev',
11  hasNextPage: 'hasNext',
12  pagingCounter: 'pageCounter',
13  meta: 'paginator'
14};
15
16const options = {
17    page: 1,
18    limit: 10,
19    customLabels: myCustomLabels
20};
21
22// Define your aggregate.
23var aggregate = Model.aggregate();
24
25Model.aggregatePaginate(aggregate, options, function(err, result) {
26if(!err) {
27  // result.itemsList [here docs become itemsList]
28  // result.itemCount = 100 [here totalDocs becomes itemCount]
29  // result.perPage = 10 [here limit becomes perPage]
30  // result.currentPage = 1 [here page becomes currentPage]
31  // result.pageCount = 10 [here totalPages becomes pageCount]
32  // result.next = 2 [here nextPage becomes next]
33  // result.prev = null [here prevPage becomes prev]
34
35  // result.hasNextPage = true [not changeable]
36  // result.hasPrevPage = false [not changeable]
37} else {
38  console.log(err);
39};

Using offset and limit

1Model.aggregatePaginate(
2  aggregate,
3  { offset: 30, limit: 10 },
4  function (err, result) {
5    // result
6  }
7);

Using countQuery

1// Define your aggregate query.
2var aggregate = Model.aggregate();
3
4// Define the count aggregate query. Can be different from `aggregate`
5var countAggregate = Model.aggregate();
6
7// Set the count aggregate query
8const options = {
9  countQuery: countAggregate,
10};
11
12Model.aggregatePaginate(aggregate, options)
13  .then(function (result) {
14    // result
15  })
16  .catch(function (err) {
17    console.log(err);
18  });

Using prepagination

This allows you to paginate the result at a given placeholder stage in a pipeline rather than at the end which is the default behavior. This can be useful when you have a large dataset and you want to paginate before carrying out expensive operations such as $lookup or $unwind.

1// Define your pipeline
2const pipeline = [
3  {
4    $match: {
5      status: "active",
6    },
7  },
8  {
9    $sort: {
10      date: -1,
11    },
12  },
13  "__PREPAGINATE__",
14  {
15    $lookup: {
16      from: "authors",
17      localField: "author",
18      foreignField: "_id",
19      as: "author",
20    },
21  },
22];
23Model.aggregatePaginate(pipeline, options)
24  .then(function (result) {
25    // result
26  })
27  .catch(function (err) {
28    console.log(err);
29  });

Global Options

If you want to set the pagination options globally across the model. Then you can do like below,

1let mongooseAggregatePaginate = require("mongoose-aggregate-paginate-v2");
2
3let BookSchema = new mongoose.Schema({
4  title: String,
5  date: Date,
6  author: {
7    type: mongoose.Schema.ObjectId,
8    ref: "Author",
9  },
10});
11
12BookSchema.plugin(mongooseAggregatePaginate);
13
14let Book = mongoose.model("Book", BookSchema);
15
16// Like this.
17Book.aggregatePaginate.options = {
18  limit: 20,
19};

Release Note

Moved to CHANGELOG.md

License

MIT