# generic-query-parser > Parse request query object to conditions, projection, and options (sort, skip, limit) to use for DB queries Latest version **0.1.5** (published 2016-03-24) · MIT license · 0 weekly downloads ## Install ```sh npm install generic-query-parser pnpm add generic-query-parser yarn add generic-query-parser bun add generic-query-parser ``` ## Health **Score 15/100 (F)** — status: abandoned. Positive: no vulnerabilities. Warnings: low downloads; no types; no esm support; pre 1.0. Negative: abandoned; low maintenance score. ## Facts | | | |---|---| | Version | 0.1.5 | | Published | 2016-03-24 | | First published | 2016-03-24 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | none | | Module format | CommonJS | | Dependencies | 1 | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 1 | | Author | Mattia | | Maintainers | mguella | | Keywords | parse, rest, query, db-query, crm-map, rest-crm, rest-query | ## Links - npm: https://www.npmjs.com/package/generic-query-parser - Repository: https://github.com/mguella/generic-query-parser - Issues: https://github.com/mguella/generic-query-parser/issues - npm.io page: https://npm.io/package/generic-query-parser ## Dependencies (1) - [parse-value](https://npm.io/package/parse-value.md) ^0.1.0 ## Alternatives - [babylon](https://npm.io/package/babylon.md) — 5.1M weekly downloads - [csscolorparser](https://npm.io/package/csscolorparser.md) — 3.7M weekly downloads - [expr-eval-fork](https://npm.io/package/expr-eval-fork.md) — 1.5M weekly downloads - [@leeoniya/ufuzzy](https://npm.io/package/@leeoniya/ufuzzy.md) — 247.7K weekly downloads - [xml-parser](https://npm.io/package/xml-parser.md) — 78.4K weekly downloads ## Recent versions - 0.1.5 (latest) — 2016-03-24 - 0.1.4 — 2016-03-24 - 0.1.3 — 2016-03-24 - 0.1.2 — 2016-03-24 ## README # Generic Query Parser Convert a query string object to a generic db query. Generates conditions, projection, and options (sort, skip, limit). Works for generic usage or even better in combination with an ORM. You can map REST APIs to *mongodb driver*, *mongoose* or *sequelize* queries. *Express* and *Koa* middlewares are already provided. ## Installation ``` npm install --save generic-query-parser ``` ## Usage You can manually parse a query string or use one of the middlewares already provided to easily consume the parsed object in your server code. ### Manual parse ```javascript // define your query var query = ` filter[age]=32 &operator[age]=gte &type[age]=number &filter[name]=^A.* &type[name]=regexp &limit=3 &skip=0 `; // require query string module (nested structures support) var qs = require('qs'); // parse query to a nested object object var requestQuery = qs.parse(query); // require generic query parser var Parser = require('generic-query-parser'); // parse request query to a db query var dbQuery = Parser.parse(requestQuery) // use parsed object dbQuery.conditions; dbQuery.projection; dbQuery.options; ``` ### Middleware #### Express Simply use `expressMiddleware` provided with the module and `req.custom` in each subsequent middleware will be populated with conditions, projection and options. ```javascript // create new express app var express = require('express'), app = express(); // require generic query parser var Parser = require('generic-query-parser'); // use middleware app.use(Parser.expressMiddleware); // consume parsed results app.use(function(req,res,next){ var dbQuery = req.custom; dbQuery.conditions; dbQuery.projection; dbQuery.options; }) ``` #### Koa Simply use `koaMiddleware` provided with the module and `this.custom` in each subsequent middleware will be populated with conditions, projection and options. NOTE: Koa native query string module doesn't support nested structures. You need to use `koa-qs` module in order to use filter conditions. ```javascript // create new koa app var koa = require('koa'), app = koa(); // use koa-qs module to parse query string to nested object require('koa-qs')(app) // require generic query parser var Parser = require('generic-query-parser'); // use middleware app.use(Parser.koaMiddleware); // consume parsed results app.use(function*(next){ var dbQuery = this.custom; dbQuery.conditions; dbQuery.projection; dbQuery.options; }) ``` ### Documentation #### Methods **parse(queryObject)** *Parse a query string object to a db query* params - Object `queryObject`: *query string object* return - Object: *parsed query composed by: conditions, projection, options* **expressMiddleware(req, res, next)** *Use as a middleware for Express* **koaMiddleware(next)** *Use as a middleware for Koa* #### Syntax ##### Filters Convert filter, operator and type from query to conditions object Example: ```javascript // age greather than or equal to 32 (converted to a number) 'filter[age]=32&operation[age]=gte&type[age]=number' ``` ###### Filter values Filter attributes by given value. Adds a condition for each attribute name received. - Object `filter`: *filter values* - String `filter[attribute]`: *value to filter for given attribute* Example: ```javascript // age 32 'filter[age]=32' // color red 'filter[color]=red' // name starts with 'A' 'filter[name]=^A.*' ``` ###### Filter operators Apply an operator to a filter value. Adds the given operator to the conditions. - Object `operator`: *filter operators* - String `operator[attribute]`: *filter operator for the attribute, one of* `eq`, `gt`, `gte`, `lt`, `lte` *or* `ne` Example: ```javascript // age greather or equal than 'operation[age]=gte' ``` ###### Filter types Apply an type to a filter value. Converts the value to the given type. Some ORMs (or DBs) might do an implicit conversion and directly accept a string as parameter even if the db type is different. If this is not your case just use the `type` parameter. - Object `type`: *filter types* - String `type[attribute]`: *filter type for attribute, one of* `string`, `number`, `date`, `bool`, `regexp` *or* `null` Example: ```javascript // given age value is a number 'type[age]=number' // given name value is a regex 'type[name]=regex' ``` ##### Projection - String `fields`: *list of desired fields in the projection, comma or space separated* ##### Sort - String `sort`: *list of sorting attributes, comma or space separated* ##### Range - Number `limit`: *results amount, default `0`* - Number `skip`: *results offset, default `0`* Example: ```javascript // get the first 10 'skip=0&limit=10' // get the next 10 'skip=10&limit=10' ``` *LICENSE: MIT* --- _Source: https://npm.io/package/generic-query-parser · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._