koa-pagination

koa-pagination is a middleware to handle Range Pagination Headers using Range & Content-Range entity-headers.

Status

Installation

Install the package via yarn:

❯ yarn add koa-pagination

or via npm:

❯ npm install koa-pagination --save

Configuration

The middleware can be configured with the following parameters:

• allowAll: Whether to accept * as range-specifier.
• maximum: Maximum number of items allowed per page (50 by default).
• unit: Accepted range unit (items by default).

You can change the defaults by doing:

middleware({
  allowAll: true,
  maximum: 100,
  unit: 'bytes'
});

Usage

const { middleware } = require('koa-pagination');
const Koa = require('koa');

const app = new Koa();

app.get('/', middleware(), async ctx => {
  // `paginate` middleware will inject a `pagination` object in the `koa` context,
  // which will allow you to use the `pagination.offset` and `pagination.limit`
  // in your data retrieval methods.
  ctx.body = await foobar.getData({
    limit: ctx.pagination.limit,
    offset: ctx.pagination.offset
  });

  // This is needed in order to expose the length in `Content-Range` header.
  ctx.pagination.length = foobar.count();
});

app.listen(3000);

Request

You can provide the Range header specifying the items you want to retrieve. For instance to retrieve the first 5 elements:

'Range: items=0-4'

You can also provide * at the end of the range in order to retrieve the all of the available items:

'Range: items=0-*'

Response

The first example will generate a response with the following headers:

'Accepted-Ranges': 'items'
'Content-Range: items 0-4/*'

The * in the Content-Range header will be replaced with the total number of items provided in the length variable.

Codes

Code | Reason ---- | ------------------------------------------------------------------------- 200 | Range header has not been provided. 206 | Range header is valid. 412 | Range header is malformed. 416 | Range header is invalid. 500 | Incorrect middleware configuration or unexpected value inside middleware.

Tests

❯ yarn test

Release

❯ npm version [<new version> | major | minor | patch] -m "Release %s"