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

Install the package via yarn:

❯ yarn add koa-pagination

or via npm:

❯ npm install koa-pagination --save

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'
});

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);

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-*'

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.

❯ yarn test

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