https://github.com/vzhufk/bookshelf-collection-querystring-mutation
Bookshelf Plugin that allows easy querystring filtering and sorting of collection.
https://github.com/vzhufk/bookshelf-collection-querystring-mutation
bookshelf collection filter knex order plugin querystring
Last synced: about 2 months ago
JSON representation
Bookshelf Plugin that allows easy querystring filtering and sorting of collection.
- Host: GitHub
- URL: https://github.com/vzhufk/bookshelf-collection-querystring-mutation
- Owner: vzhufk
- Created: 2018-06-07T14:46:51.000Z (almost 8 years ago)
- Default Branch: master
- Last Pushed: 2018-12-11T09:12:32.000Z (over 7 years ago)
- Last Synced: 2025-07-07T01:52:13.033Z (8 months ago)
- Topics: bookshelf, collection, filter, knex, order, plugin, querystring
- Language: JavaScript
- Size: 60.5 KB
- Stars: 4
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Bookshelf Collection Querystring Mutation Plugin
[](https://travis-ci.com/vzhufk/bookshelf-collection-querystring-mutation)
This Bookshelf plugin allows you to filter and sort your bookshelf instances directly from URL query string parameters.
Using [jsep](https://www.npmjs.com/package/jsep) to parse query string logical expressions into QueryBuilder query.
Inspired by [Microsoft API Guideline Collections](https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#9-collectionsMS).
## Instalation
```sh
$ npm install bookshelf-collection-querystring-mutation
```
## Basic Usage
```javascript
const express = require("express");
const bookshelf = require("bookshelf");
const knex = require("knex");
const bcqm = reqire("bookshelf-collection-querystring-mutation");
const repository = bookshelf(
knex({
/*...*/
})
);
let app = express();
// Connect Plugin
repository.plugin(bcqm);
// Define Model
const List = repository.Model.extend({
tableName: "shopping_list",
allowed: ["name", "qty", "price"],
hidden: ["barcode"]
});
app.get("/list", function(req, res, next) {
let items = new List();
// Mutate from query
items.filter(req.query.filter).orderBy(req.query.orderBy);
items.fetchAll().then(r => {
/* Do stuff. */
});
});
```
## How to use
```http
GET /list?filter=price ge 10&orderBy=name
```
Will filter instances that have `price >= 10` and order them by `name`.
## Filter Operation
Allows you to filter collection.
Pattern: `field1 value [logical_opration] ...`
| Operator | Description | Example |
| -------------------- | --------------------- | ----------------------------------------------------- |
| Comparison Operators | |
| eq | Equal | city eq 'Redmond' |
| ne | Not equal | city ne 'London' |
| gt | Greater than | price gt 20 |
| ge | Greater than or equal | price ge 10 |
| lt | Less than | price lt 20 |
| le | Less than or equal | price le 100 |
| lk | Like | name lk '%gg%' |
| il | iLike | name il '%GG%' |
| in | in | name in ['GG', 'Salad'] |
| is | Is (null) | price is null |
| sn | Is Not (null) | price sn null |
| Logical Operators | |
| and | Logical and | price le 200 and price gt 3.5 |
| or | Logical or | price le 3.5 or price gt 200 |
| Grouping Operators | |
| ( ) | Precedence grouping | (priority eq 1 or city eq 'Redmond') and price gt 100 |
## Filter examples:
The following examples illustrate the use and semantics of each of the logical operators.
Example: all products with a name equal to 'Milk'
```http
GET /list?filter=name eq 'Milk'
```
Example: all products with a name not equal to 'Milk'
```http
GET /list?filter=name ne 'Milk'
```
Example: all products with the name 'Milk' that also has a price less than 2.55:
```http
GET /list?filter=name eq 'Milk' and price lt 2.55
```
Example: all products that either have the name 'Milk' or have a price less than 2.55:
```http
GET /list?filter=name eq 'Milk' or price lt 2.55
```
Example: all products that have the name 'Milk' or 'Eggs' and have a price less than 2.55:
```http
GET /list?filter=(name eq 'Milk' or name eq 'Eggs') and price lt 2.55
```
Example: all products that have the name matching '_gg_':
```http
GET /list?filter=name lk "%gg%"
```
Example: all products that have ids in array of [1, 2, 3]:
```http
GET /list?filter=id in [1, 2, 3]
```
Example: all products that have price is set to null:
```http
GET /list?filter=price is null
```
Example: all products that have price is not set to null:
```http
GET /list?filter=price sn null
```
## OrderBy
Allows you to sort collections.
Pattern: `field1 [dirrection(asc|desc)][, field2 [dirrection(asc|desc)], [...]]`
## OrderBy Examples
Example: will return all products sorted by name in ascending order.
```http
GET /list?orderBy=name
```
For example: will return all products sorted by name in descending order.
```http
GET /list?orderBy=name desc
```
Sub-sorts can be specified by a comma-separated list of property names with OPTIONAL direction qualifier.
Example: will return all people sorted by name in descending order and a secondary sort order of price in ascending order.
```http
GET /list?orderBy=name desc,price
```
## Plugin Configuration:
```js
repository.plugin(bcqm, {
filterName: "filter", //filter function name in BSModel
orderByName: "orderBy", //orderBy function name in BSModel
hiddenPropsName: "hidden", //name of Property that provides array of hidden fields
allowedPropsName: "allowed", //name of Property that provides array of allowed fields
ignoreErrors: false //throw errors or skip silently
});
```
Hidden and Allowed arrays provide fields visibility for a plugin.
If any filter or orderBy field is an array of private fields, it will throw an Error.
If any filter or orderBy field is not an array of allowed fields, it will throw an Error.
You can also not provide this props if you don't care.
Model example:
```js
const List = repository.Model.extend({
tableName: "shopping_list",
allowed: ["name", "qty", "price"], //filter and orderBy by this fields
hidden: ["barcode"] //DON'T by this
});
```
# TODO:
- `not` Logical operator