About

Express middleware for simple pagination. Easy way to handle limit and offset.

The pagination middleware will add an object pagination to request.

By default it includes:

• The default values for pagination.
• The current pagination request.
• If the pagination is active.
• Default values, Range validation, wrong values validation and sanitization.
• By default the offset will be 0 and the limit range between (20-500)
• Full customizable
• Easy to use and 100% test coverage

req.pagination = {
    isEnable: Boolean(),               // This indicates if the pagination was requested in the url
    default: { limit: 20, offset: 0 }, // default values
    current: { limit: 20, offset: 0 } // In case that the pagination was requested, this estimates the real pagination using ranges and default values.
}

This middelware will be triggered by query params offset and/or limit, like:

• /route?limit=10
• /route?limit=100&offset=500
• /route?offset=350

Usage

Install

npm install express-simple-pagination

Simple Usage (Enable All Pagination Requests)

const express = require('express')
const pagination = require('express-simple-pagination')
const app = express()
const port = 3000

app.use(pagination())

app.get('/products', (req, res, next) => {
  res.json({msg: req.pagination})
})

app.listen(port, () => {
  console.log(`web server listening on ${port}`)
})

output:

/products
└──> msg: {req.isEnable: false, default: { limit: 20, offset: 0 }}
/products?limit=200
└──> msg: {req.isEnable: false, current: { limit: 200, offset: 0 }, default: { limit: 20, offset: 0 }}
/products?limit=200&offset=600
└──> msg: {req.isEnable: false, current: { limit: 200, offset: 600 }, default: { limit: 20, offset: 0 }}
/products?limit=4000
└──> msg: {req.isEnable: false, current: { limit: 200, offset: 0 }, default: { limit: 20, offset: 0 }}
/products?limit=-10
└──> msg: {req.isEnable: false, current: { limit: 20, offset: 0 }, default: { limit: 20, offset: 0 }}
/products?offset=-10
└──> msg: {req.isEnable: false, current: { limit: 20, offset: 0 }, default: { limit: 20, offset: 0 }}

Enable pagination for a Single Route

const express = require('express')
const pagination = require('express-simple-pagination')
const app = express()
const port = 3000
  
app.get('/products', pagination(), (req, res, next) => {
  res.json({msg: req.pagination})
})

app.get('/clients', (req, res, next) => {
  res.json({msg: req.pagination})
})

app.listen(port, () => {
  console.log(`web server listening on ${port}`)
})

output:

/products
└──> msg: {req.isEnable: false, default: { limit: 20, offset: 0 }}

/clients
└──> msg: undefined

Configuring Pagination (items per page)

const express = require('express')
const pagination = require('express-simple-pagination')
const app = express()
const port = 3000

const paginationOptions = {
  min: 5,
  max: 1000
}

app.get('/products', pagination(paginationOptions), (req, res, next) => {
  res.json({msg: req.pagination})
})

app.listen(port, () => {
  console.log(`web server listening on ${port}`)
})

output:

/products
└──> msg: {req.isEnable: false, default: { limit: 5, offset: 0 }}
/products?limit=1
└──> msg: {req.isEnable: false, current: { limit: 5, offset: 0 }, default: { limit: 5, offset: 0 }}
/products?limit=2400000&offset=600
└──> msg: {req.isEnable: false, current: { limit: 1000, offset: 600 }, default: { limit: 5, offset: 0 }}
/products?limit=4000
└──> msg: {req.isEnable: false, current: { limit: 4000, offset: 0 }, default: { limit: 5, offset: 0 }}

Page vs Offset

It is possible to use page argument like ?page=1 in state of offset

Test

You can run them:

npm run test:coverage

Contributing

Please check CONTRIBUTING for guidelines on contributing to this project.

Author

express-simple-pagination © Ulises Gascón, Released under the MIT License.