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"