uapi-paginate-nodejs

Simple pagination tool for a the University API implementation.

Installation

npm i @byu-oit/uapi-paginate-nodejs

Usage

Calculates all pagination starting locations for first, last, prev, and next page.

Parameters:

• @param { number | string | any[] } collection - a collection or a collection size
• @param { number | string } offset - start location (start index is 0)
• @param { number | string } limit - quantity of items in the subset
• @param { Object } [options] - options to replace the global defaults (See section on the return values to see the defaults)
• @param { number } [options.start]
• @param { number } [options.size]
• @param { number } [options.max]

Returns:

An Object with the following properties:

• start: { ?number } - the location of the first item in the current page.
• end: { ?number } - the location of the last item in the current page.
• size: { ?number } - number of elements returned in the current selection.
• next: { ?number } - the location of the next page's starting element.
• prev: { ?number } - the location of the previous page's starting element.
• last: { ?number } - the location of the starting element in the last page of the collection.
• collectionSize: { ?number } - the number of items in the collection.
• defaults: { Object }
  • start: { ?number } - default start location (defaults to 0)
  • size: { ?number } - default page size (defaults to 50).
  • max: { ?number } - default max page size (defaults to 100).
• result: { any[] } - an array of the current page's items.
• input: { Object } - your inputs
  • collection: { number | string | any[] }
  • offset: { number | string }
  • limit: { number | string }
  • options: { Object } [options]

Usage examples:

let paginate = require('byu-paginate')

const months = [ 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sept', 'Oct', 'Nov', 'Dec' ]

let page = paginate(months, 0, 3)

return {
  links: {
    info: {
      rel: 'self',
      href: `https://my-domain/my-path?page_start=${page.start}&page_size=${page.input.limit}`,
      method: 'GET'
    },
    ...page.prev && { prev: {
      rel: 'prev',
      href: `https://my-domain/my-path?page_start=${page.prev}&page_size=${page.input.limit}`,
      method: 'GET'
    } },
    ...page.next && { next: {
      rel: 'next',
      href: `https://my-domain/my-path?page_start=${page.next}&page_size={page.input.limit}`,
      method: 'GET'
    } }
  },
  metadata: {
    collection_size: page.collectionSize,
    page_start: page.start,
    page_end: page.end,
    page_size: page.size,
    default_page_size: page.defaults.size,
    max_page_size: page.defaults.maxSize
  },
  values: page.results
}

The above return value would look like:

{
  links: {
    info: {
      rel: 'self',
      href: `https://my-domain/my-path?page_start=0&page_size=3`,
      method: 'GET'
    },
    next: {
      rel: 'next',
      href: `https://my-domain/my-path?page_start=3&page_size=3`,
      method: 'GET'
    }
  },
  metadata: {
    collection_size: 12,
    page_start: 0,
    page_end: 2,
    page_size: 3,
    default_page_size: 50,
    max_page_size: 100
  },
  values: [
    'Jan',
    'Feb',
    'Mar'
  ]
}