express-simple-pagination

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

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.