2. Usage Examples

You can use the default middleware settings or customize them according to the needs of your application.

1. The middleware configuration

The middleware uses the following defaults:

options = {
    default: {
        pagination: {
            limit: Number.MAX_SAFE_INTEGER,
            skip: 0,
            page: 1
        },
        fields: {},
        sort: {},
        filters: {}
    },
    use_page: false,
    client_db: 'mongodb',
    date_fields: {
        'start_at': 'created_at',
        'end_at': 'created_at'
    }
}

These settings can be customized by the user, as long as they follow the standard defined in the middleware. Below we have the description of each of the parameters, as well as the definition of their default values.

default:

pagination:

Paging works in conjunction with two query strings: limit, skip/page.

• limit Determines the maximum number of items that the query should return, limit=30 returns a maximum of 30 items.
  • Default value: limit: MAX_SAFE_INTEGER (constant value for 9007199254740991)

Pagination with skip

• skip Determines the number of items you want to skip in the query, skip=20 ignore the first 20 items.
  • Default value: skip: 0

Pagination with page

• page Determines the page number to return with the requested resource. The number of available pages is dynamic according to the number of records on the server and the limit per page set.
  • Default value: page: 1

fields:

Allows you to retrieve only the information you want. To do this, simply provide the attribute/property names separated by commas. By default, there is no field selection defined.

sort:

Allows to apply sorting rules. To do this, simply provide the attribute/property names that will be used to sort the query result separated by comma. By default, there is no pre-defined sort parameter.

filters:

It consists of limiting the number of resources requested by specify some attributes and their expected values. It's possible to filter a collection by multiple attributes at the same time and allow to filter multiple values for an attribute. By default, there is no pre-defined filter parameter.

use_page:

Defines whether query pagination will be done using page if the value is true, or skip if this value is false. By default, this parameter is set to false.

client_db:

Defines which database is being used. Based on this parameter, the queries are treated in different ways. By default, this parameter is set to 'mongodb'.

date_fields:

Defines the name of the parameter that will be used in Date filters.

start_at: Defines the name of the parameter set with start date of the filter. By default, this parameter is set to 'created_at'.

end_at: Defines the name of the parameter set with end date of the filter. By default, this parameter is set to 'created_at'.

2. Using default configurations

To use the default settings, just do as described in the example below:

const express = require('express')
const qs = require('query-strings-parser')
const app = express()

app.use(qs()) // middleware query-strings-parser

app.listen(3000, (req, res) => {
    console.log('app listening on port 3000')
})

app.get('/', (req, res) => {
    res.send('the query is:' + JSON.stringify(req.query))
})

When a query with query strings is performed, the request query parameter is updated, and transformed into a JSON object containing the following information:

/**
 * Request: http://localhost:3000?fields=name,age&skip=10&limit=10&sort=created_at
 * Result (req.query):
 * {
 *    fields: { name: 1, age: 1 },
 *    sort: { created_at: 'asc' }
 *    filters: {},
 *    pagination: {
 *        skip: 10,
 *        limit: 10
 *    }
 * }
 */

2. Using custom configurations:

const express = require('express')
const qs = require('query-strings-parser')
const app = express()

app.use(qs({
  use_page: true,
  client_db: 'mongodb',
  date_field: 'created_at'
  default: {
      fields: {_id: 0},
      sort: { created_at: 'desc' },
      filters: {},
      pagination: {
          page: 1,
          limit: 100
      }
  }
}))

/**
 * Request: http://localhost:3000?fields=name,age&age=30
 * Result (req.query):
 * {
 *    fields: {_id: 0, name: 1, age: 1},
 *    sort: { created_at: 'desc' }
 *    filters: {age: 30},
 *    pagination: {
 *        limit: 100,
 *        page: 1
 *    }
 * }
 */

Note: The custom queries settings must follow the standard defined in the middleware to ensure the correct operation of queries:

• For fields select in the search, the custom setting must be attribute: 1 if the parameter should come, and attribute: 0, otherwise.
• For ordering in the search, the custom setting must be attribute: 'asc' for ascending sort and 'attribute': 'desc' for descending sort.
• For pagination in search, the value of parameters limit, skip and page should be positive integers.