# mongoose-paginate

> Pagination plugin for Mongoose

Latest version **5.0.3** (published 2016-10-03) · MIT license · 0 weekly downloads

## Install

```sh
npm install mongoose-paginate
pnpm add mongoose-paginate
yarn add mongoose-paginate
bun add mongoose-paginate
```

## Health

**Score 23/100 (F)** — status: abandoned.

Positive: has types package; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 5.0.3 |
| Published | 2016-10-03 |
| First published | 2011-12-16 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/mongoose-paginate) |
| Module format | CommonJS |
| Node | >=4.0.0 |
| Dependencies | 1 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 974 |
| Author | Edward Hotchkiss |
| Maintainers | edwardhotchkiss, jokero, niftylettuce |
| Keywords | mongoose, paginate, pagination, paging, page |

## Links

- npm: https://www.npmjs.com/package/mongoose-paginate
- Repository: https://github.com/edwardhotchkiss/mongoose-paginate
- Homepage: https://github.com/edwardhotchkiss/mongoose-paginate#readme
- Issues: https://github.com/edwardhotchkiss/mongoose-paginate/issues
- npm.io page: https://npm.io/package/mongoose-paginate

## Dependencies (1)

- [bluebird](https://npm.io/package/bluebird.md) 3.0.5

## Alternatives

- [angular-pipes](https://npm.io/package/angular-pipes.md) — 5.6K weekly downloads
- [@ng-web-apis/midi](https://npm.io/package/@ng-web-apis/midi.md) — 2.6K weekly downloads
- [happn-3](https://npm.io/package/happn-3.md) — 1.6K weekly downloads
- [@opensip-cli/lang-go](https://npm.io/package/@opensip-cli/lang-go.md) — 1.2K weekly downloads
- [mongoose-typescript](https://npm.io/package/mongoose-typescript.md) — 85 weekly downloads

## Recent versions

- 5.0.3 (latest) — 2016-10-03
- 5.0.2 — 2016-10-01
- 5.0.1 — 2016-09-29
- 5.0.0 — 2015-12-07
- 4.2.0 — 2015-09-12
- 4.0.1 — 2015-08-05
- 4.0.0 — 2015-07-06
- 3.1.6 — 2015-07-05
- 3.1.5 — 2015-06-26
- 3.1.3 — 2014-10-18
- 3.1.2 — 2014-10-16
- 3.1.1 — 2014-09-05
- 3.1.0 — 2014-06-13
- 3.0.0 — 2014-06-12
- 2.3.0 — 2014-06-12
- … 14 more at https://npm.io/package/mongoose-paginate/versions

## README

# mongoose-paginate

Pagination plugin for [Mongoose](http://mongoosejs.com)

[![NPM version](https://img.shields.io/npm/v/mongoose-paginate.svg)](https://npmjs.org/package/mongoose-paginate)
[![Build status](https://img.shields.io/travis/edwardhotchkiss/mongoose-paginate.svg)](https://travis-ci.org/edwardhotchkiss/mongoose-paginate)

**Note:** This plugin will only work with Node.js >= 4.0 and Mongoose >= 4.0.

## Installation

```sh
npm install mongoose-paginate
```

## Usage

Add plugin to a schema and then use model `paginate` method:

```js
var mongoose         = require('mongoose');
var mongoosePaginate = require('mongoose-paginate');

var schema = new mongoose.Schema({ /* schema definition */ });
schema.plugin(mongoosePaginate);

var Model = mongoose.model('Model',  schema); // Model.paginate()
```

### Model.paginate([query], [options], [callback])

Returns promise

**Parameters**

* `[query]` {Object} - Query criteria. [Documentation](https://docs.mongodb.org/manual/tutorial/query-documents)
* `[options]` {Object}
  - `[select]` {Object | String} - Fields to return (by default returns all fields). [Documentation](http://mongoosejs.com/docs/api.html#query_Query-select) 
  - `[sort]` {Object | String} - Sort order. [Documentation](http://mongoosejs.com/docs/api.html#query_Query-sort) 
  - `[populate]` {Array | Object | String} - Paths which should be populated with other documents. [Documentation](http://mongoosejs.com/docs/api.html#query_Query-populate)
  - `[lean=false]` {Boolean} - Should return plain javascript objects instead of Mongoose documents?  [Documentation](http://mongoosejs.com/docs/api.html#query_Query-lean)
  - `[leanWithId=true]` {Boolean} - If `lean` and `leanWithId` are `true`, adds `id` field with string representation of `_id` to every document
  - `[offset=0]` {Number} - Use `offset` or `page` to set skip position
  - `[page=1]` {Number}
  - `[limit=10]` {Number}
* `[callback(err, result)]` - 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
* `total` {Number} - Total number of documents in collection that match a query
* `limit` {Number} - Limit that was used
* `[page]` {Number} - Only if specified or default `page`/`offset` values were used 
* `[pages]` {Number} - Only if `page` specified or default `page`/`offset` values were used 
* `[offset]` {Number} - Only if specified or default `page`/`offset` values were used

### Examples

#### Skip 20 documents and return 10 documents

```js
Model.paginate({}, { page: 3, limit: 10 }, function(err, result) {
    // result.docs
    // result.total
    // result.limit - 10
    // result.page - 3
    // result.pages
});
```

Or you can do the same with `offset` and `limit`:
```js
Model.paginate({}, { offset: 20, limit: 10 }, function(err, result) {
    // result.docs
    // result.total
    // result.limit - 10
    // result.offset - 20
});
```

With promise:
```js
Model.paginate({}, { offset: 20, limit: 10 }).then(function(result) {
    // ...
});
```

#### More advanced example

```js
var query   = {};
var options = {
    select:   'title date author',
    sort:     { date: -1 },
    populate: 'author',
    lean:     true,
    offset:   20, 
    limit:    10
};

Book.paginate(query, options).then(function(result) {
    // ...
});
```

#### Zero limit

You can use `limit=0` to get only metadata:

```js
Model.paginate({}, { offset: 100, limit: 0 }).then(function(result) {
    // result.docs - empty array
    // result.total
    // result.limit - 0
    // result.offset - 100
});
```

#### Set custom default options for all queries

config.js:
```js
var mongoosePaginate = require('mongoose-paginate');

mongoosePaginate.paginate.options = { 
    lean:  true,
    limit: 20
};
```

controller.js:
```js
Model.paginate().then(function(result) {
    // result.docs - array of plain javascript objects
    // result.limit - 20
});
```

## Tests

```sh
npm install
npm test
```

## License

[MIT](LICENSE)

---
_Source: https://npm.io/package/mongoose-paginate · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._