# loopback-paginator

> Pagination mixin for LoopBack.

Latest version **3.0.0** (published 2019-11-29) · MIT license · 0 weekly downloads

## Install

```sh
npm install loopback-paginator
pnpm add loopback-paginator
yarn add loopback-paginator
bun add loopback-paginator
```

## Health

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

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 3.0.0 |
| Published | 2019-11-29 |
| First published | 2018-08-14 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=8 |
| Dependencies | 1 |
| Unpacked size | 8.5 KB |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 13 |
| Author | Manuel Heidrich |
| Maintainers | prototype.berlin |
| Keywords | loopback, mixin, pagination |

## Links

- npm: https://www.npmjs.com/package/loopback-paginator
- Repository: https://github.com/prototype-berlin/loopback-paginator
- Homepage: https://github.com/prototype-berlin/loopback-paginator#readme
- Issues: https://github.com/prototype-berlin/loopback-paginator/issues
- npm.io page: https://npm.io/package/loopback-paginator

## Dependencies (1)

- [debug](https://npm.io/package/debug.md) 4.1.1

## Recent versions

- 3.0.0 (latest) — 2019-11-29
- 2.0.1-0 (beta) — 2019-11-29
- 2.0.0 — 2019-02-22
- 2.0.0-beta.2 — 2019-02-22
- 2.0.0-beta.1 — 2019-02-22
- 2.0.0-beta.0 — 2019-02-22
- 1.0.0 — 2018-10-18
- 0.9.7 — 2018-10-02
- 0.9.6 — 2018-08-19
- 0.9.5 — 2018-08-15
- 0.9.4 — 2018-08-15
- 0.9.3 — 2018-08-15
- 0.9.1 — 2018-08-14

## README

# Pagination mixin for LoopBack

Paginator adds an easy to use pagination to any of your models. See the [example](#usage) below.

## Installation

```
$ npm i loopback-paginator --save
```

## Config

### Server Config

With [loopback-boot@v2.8.0](https://github.com/strongloop/loopback-boot/) [mixinSources](https://github.com/strongloop/loopback-boot/pull/131) have been implemented in a way which allows for loading this mixin without changes to the server.js file previously required. Just add `"../node_modules/loopback-paginator"` to the `mixins` property of your `server/model-config.json`.

```javascript
{
  "_meta": {
    "mixins": [
      "loopback/common/mixins",
      "../node_modules/loopback-paginator",
      "../common/mixins"
    ]
  }
}
```
### Model Config

To use with your models just add `Paginator: true` to `mixins` in your model config and the default options will be used:

```javascript
{
  "name": "Model",
  "properties": {
    "name": {
      "type": "string",
    }
  },
  "mixins": {
    "Paginator": true
  }

  ...

  // you can also overide the default values:
  "mixins": {
    "Paginator": {
      "limit": 5,         // items per page, default: 10
      "maxLimit": 60,     // max items per page, default: 100
      "noMaxLimit": true  // only use this, if you know what you are doing!
    }
  }
}
```

#### limit and maxLimit

* `limit` is the default limit to be used for this model
* `maxLimit` is the default maximum number of items per page for this model. As you can override the default limit using the [LoopBack limit filter](https://loopback.io/doc/en/lb3/Limit-filter.html) it might come in handy to set a maxLimit to prevent your API from being abused. The default is `100`.
* `noMaxLimit` set to `true` will deactivate the `maxLimit`. Be careful!

### Global Config

It is also possible to configure the mixin globally in your `config.json`. Just add `paginator` and use the same options as with the model above:

```javascript
{
  "paginator": {
    "limit": 20,       // items per page, default: 10
    "maxLimit": 300,   // max items per page, default: 100
    "noMaxLimit": true // only use this, if you know what you are doing!
  }
}
```

#### limit and maxLimit

* `limit` is the default limit to be used globally
* `maxLimit` is the default maximum number of items per page globally. As you can override the default limit using the [LoopBack limit filter](https://loopback.io/doc/en/lb3/Limit-filter.html) it might come in handy to set a maxLimit to prevent your API from being abused. The global default is `100`.
* `noMaxLimit` set to `true` will deactivate the `maxLimit`. Be careful!

## Usage

When Paginator is added to a model and the `page` query parameter is present (e.g. `?page=1`), Model.find() will return an object with `data` and `meta`. `data` is an array with the queried items, limited to the number you defined in the mixin options (see [Model Config](#model-config)). `meta` contains information about the requested page (see example below). You can specify the page as a query parameter (e.g. `?page=3`). ~~If no page is specified it defaults to 1~~ (deprecated in versions >= 2.0.0).

`/GET https://example.com/api/items?page=3`

```javascript
{
  "data": [
    {
      "title": "Item 1",
      "description": "Cool first item.",
      "id": "c5075168-abe0-41c6-8052-e07745eade48"
    },
    {
      "title": "Item 2",
      "description": "Cool second item.",
      "id": "0cad55df-c59d-4195-bb4f-7a252bd4bbe8",
    }

    ...

  ],
  "meta": {
    "totalItemCount": 95, // total number of items
    "totalPageCount": 10, // total number of all pages
    "itemsPerPage": 10,   // numberof items per page
    "currentPage": 3,     // the current page
    "nextPage": 4,        // the next page, only present if there is another page
    "previousPage": 2     // the previous page, only present if currentPage != 1
  }
}
```

## ToDo

- [x] allow to override limit with an URL parameter

## License

[MIT](LICENSE)

## Changelog

### v3.0.0
- Breaking change: Add the mixin in `server/model-config.json` like this: `"../node_modules/loopback-paginator"`, without the former `/lib` at the end
- Remove Babel dependencies

### v2.0.0
- Breaking change: node >=8.0.0 is required!
- Breaking change: omitting the page parameter no longer defaults to page=1, it now returns unpaginated results

### v1.0.0
- Allow to override limit with the LoopBack limit filter
- Add `maxLimit` option
- Add `noMaxLimit` option

### v0.9.6
- Add global config

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