query-strings-parser
    TypeScript icon, indicating that this package has built-in type declarations

    2.1.9 • Public • Published

    Query Strings Parser

    License NPM Version NPM Downloads Travis Coverage Dependencies DependenciesDev Vulnerabilities Releases Contributors Issues

    Middleware to transform query strings in a format that is recognized by the MongoDB, MySQL¹ and other databases.

    Prerequisites

    To ensure the smooth operation of the middleware, your web application must be built using the express.js or hapi.js frameworks.

    Installing

    Use the npm command to install this library into your project:

    npm i query-strings-parser --save  

    Usage Examples

    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))  
    })  
      
    /**  
     * 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: 1 }  
     *    filters: {},  
     *    pagination: {  
     *        skip: 10,  
     *        limit: 10  
     *    },  
     *    original: '?fields=name,age&skip=10&limit=10&sort=created_at'  
     * }  
     */  

    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: {  
          start_at: 'timestamp',  
          end_at: 'timestamp'  
      },  
      default: {  
          fields: {name: 1 , age: 1, number: 1, _id: 0},  
          sort: { created_at: -1 },  
          filters: {},  
          pagination: {  
              page: 1,  
              limit: 100  
          }  
      }  
    }))  
      
    /**  
     * Request: http://localhost:3000?fields=name,age&age=30  
     * Result (req.query):  
     * {  
     *    fields: { name: 1, age: 1},  
     *    sort: { created_at: -1 }  
     *    filters: {age: 30},  
     *    pagination: {  
     *        limit: 100,  
     *        page: 1  
     *    },  
     *    original: '?fields=name,age&age=30'  
     * }  
     */  

    The middleware uses the following defaults:

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

    If the options are not provided, the default values will be used for the treatment of queries strings.

    For more details, access the wiki page.

    Parsers Functions

    To use these functions, simply call them through the middleware instance and pass them the query string to be converted and its default values. If you pass the default values ​​a merge will be performed with the result of the query strings. Here are some examples of each analyzer:

    • parser()
    const qs = require('query-strings-parser')
    
    const query = '?fields=name,age&page=1&limit=10&sort=created_at'
    console.log(qs.parseFields(query, {}, { use_page: true }))
    
    /**
    * Result: 
    * {
    *   fields: { name: 1, age: 1 },
    *   sort: { created_at: 1 },
    *   filters: {},
    *   pagination: { limit: 10, page: 1 },
    *   original:  '?fields=name,age&page=1&limit=10&sort=created_at'
    * }
    */

    For more details >>

    • parseFields()
    const qs = require('query-strings-parser')
    
    const query = '?fields=name,age'
    console.log(qs.parseFields(query))
    
    /**
    * Result: 
    * { 
    *     name: 1,
    *     age: 1
    * }
    */

    For more details >>

    • parseSort()
    const qs = require('query-strings-parser')
    
    const query = '?sort=name,-age,created_at'
    console.log(qs.parseSort(query))
    
    /**
    * Result: 
    * { 
    *     name: 1,
    *     age: -1,
    *     created_at: 1
    * }
    */

    For more details >>

    • parsePagination()
    const qs = require('query-strings-parser')
    
    const query = '?limit=20&page=3'
    console.log(qs.parsePagination(query, {}, true))
    
    /**
    * Result: 
    * { 
    *     limit: 20,
    *     page: 3 
    * }
    */

    For more details >>

    • parseFilter()
     const qs = require('query-strings-parser')
     
     const query = '?name=elvis&age=80'
     console.log(qs.parseFilter(query))
     
     /**
     * Result: 
     * { 
     *     name: 'elvis',
     *     age: 80
     * }
     */

    For more details >>

    • parseDate()
    const qs = require('query-strings-parser')
    
    const query = '?start_at=2019-02-05T00:00:00&end_at=2019-02-05T23:59:59'
    console.log(qs.parseDate(query))
    
    /**
    * Result: 
    * { 
    *    $and: [
    *       { created_at: { lt: 2019-02-05T23:59:59 }},
    *       { created_at: { gte: 2019-02-05T00:00:00 }}
    *   ]}
    * }
    */

    For more details >>

    Supported Query Strings

    For informations and details about the supported query strings, access the wiki page.


    Future Features

    • ¹Support for relational databases such as MySQL, PostgreSQL and SQLite.

    Install

    npm i query-strings-parser

    DownloadsWeekly Downloads

    98

    Version

    2.1.9

    License

    MIT

    Unpacked Size

    82.1 kB

    Total Files

    20

    Last publish

    Collaborators

    • lucasrocha
    • douglas.rafael
    • nuepb