express-pagination

Configurable ExpressJS pagination middleware.

The purpose of this package is to simplify handling of pagination for ExpressJS applications. It can be used as fast as possible as shown in the Basic Usage section, or it can be highly configured to perfectly reflect your application needs.

This middleware allows your application to read two parameters for pagination (the current page number and the number of desired results per page) and setup a configurable property in the request object that gets passed to your route handler.

installation

npm install --save @0xc14m1z/express-pagination

default behaviour

This middleware:

• looks for a page parameter as the current page number;
• looks for a perPage parameter as the desired number of results per page;
• sets a pagination property on the request object;
  • sets a page property to the given current page number or fallback to page 1;
  • sets a perPage property to the given desired number of results per page or fallback to 50;
  • sets a from property to the number of results to skip;

All of these properties can be configured as shown in the Advanced Usage section.

basic usage

This package exports two convenient methods to be used as ExpressJS middlewares on route or application basis.

If you don't have special needs, you can just import a middleware and use it like:

const pagination = require('@0xc14m1z/express-pagination')

app.get('/first-route', pagination.add, function (req, res) {
  // your handler here
})

Now your route can be called as: /first-route?page=3 or /first-route?page=3&perPage=30.

If no perPage parameter is given, the value 50 is used for it.

With this setup you'll have pagination information in req.pagination as:

{
  page: 3,
  perPage: 30, // or 50, if this parameter isn't given
  from: 60
}

If you want to change the default number of desired results per page, you can use a slightly different middleware:

const pagination = require('@0xc14m1z/express-pagination')

app.get('/second-route', pagination.addWith(25), function (req, res) {
  // your handler here
})

advanced usage

The default export of this package is a function that takes a configuration in input and returns a middleware generator.

This middleware generator can than be used in your application:

// customPagination.js
const pagination = require('@0xc14m1z/express-pagination')

module.exports = pagination(/* custom configuration here */)

// controller.js
const addPagination = require('./customPagination')

// here the number results per page is taken from the configuration
app.get('/first-route', addPagination(), function (req, res) {
  // your handler here
})

// here the given number results per page overrides the configuration value
app.get('/second-route', addPagination(100), function (req, res) {
  // your handler here
})

The default configuration is:

{
  input: {
    page: 'page',
    perPage: 'perPage'
  },
  output: {
    property: 'pagination',
    page: 'page',
    perPage: 'perPage',
    from: 'from',
    defaultPerPage: 50
  }
}

Let's say that we have an application that receives paging information in a shorter format, for instance: /paged-route?p=4&pp=30

Where p is the current page number and pp is the desired number of results per page, we can set the configuration as:

{
  input: {
    page: 'p',
    perPage: 'pp'
  }
}

Let's say that, for instance, we are using Sequelize ORM to perform our database queries. It allows to narrow query results using the standard SQL keywords: limit and offset.

We may set the configuration to:

{
  input: {
    page: 'p',
    perPage: 'pp'
  },
  output: {
    property: 'queryLimits'
    perPage: 'limit',
    from: 'offset'
  }
}

And use it like:

// controller.js
const addPagination = require('./customPagination')

app.get('/users', addPagination(), function (req, res) {
  const { limit, offset } = req.queryLimits

  User.findAll({ limit, offset })
  // or even User.findAll({ ...req.queryLimits })
})