{"id":41864914,"url":"https://github.com/vzhufk/bookshelf-collection-querystring-mutation","last_synced_at":"2026-01-25T11:37:48.434Z","repository":{"id":104830670,"uuid":"136491487","full_name":"vzhufk/bookshelf-collection-querystring-mutation","owner":"vzhufk","description":"Bookshelf Plugin that allows easy querystring filtering and sorting of collection.","archived":false,"fork":false,"pushed_at":"2018-12-11T09:12:32.000Z","size":62,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-07-07T01:52:13.033Z","etag":null,"topics":["bookshelf","collection","filter","knex","order","plugin","querystring"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vzhufk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-06-07T14:46:51.000Z","updated_at":"2018-12-11T09:12:34.000Z","dependencies_parsed_at":null,"dependency_job_id":"b1028597-8120-457d-ad69-36b8a00d7cf3","html_url":"https://github.com/vzhufk/bookshelf-collection-querystring-mutation","commit_stats":{"total_commits":25,"total_committers":3,"mean_commits":8.333333333333334,"dds":0.07999999999999996,"last_synced_commit":"3573d75f444c155dbd5eec264a4545ccebf09168"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/vzhufk/bookshelf-collection-querystring-mutation","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vzhufk%2Fbookshelf-collection-querystring-mutation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vzhufk%2Fbookshelf-collection-querystring-mutation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vzhufk%2Fbookshelf-collection-querystring-mutation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vzhufk%2Fbookshelf-collection-querystring-mutation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vzhufk","download_url":"https://codeload.github.com/vzhufk/bookshelf-collection-querystring-mutation/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vzhufk%2Fbookshelf-collection-querystring-mutation/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28752668,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-25T10:25:12.305Z","status":"ssl_error","status_checked_at":"2026-01-25T10:25:11.933Z","response_time":113,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bookshelf","collection","filter","knex","order","plugin","querystring"],"created_at":"2026-01-25T11:37:47.700Z","updated_at":"2026-01-25T11:37:48.422Z","avatar_url":"https://github.com/vzhufk.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Bookshelf Collection Querystring Mutation Plugin\n\n[![Build Status](https://travis-ci.com/vzhufk/bookshelf-collection-querystring-mutation.svg?branch=master)](https://travis-ci.com/vzhufk/bookshelf-collection-querystring-mutation)\n\nThis Bookshelf plugin allows you to filter and sort your bookshelf instances directly from URL query string parameters.\nUsing [jsep](https://www.npmjs.com/package/jsep) to parse query string logical expressions into QueryBuilder query.\n\nInspired by [Microsoft API Guideline Collections](https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#9-collectionsMS).\n\n## Instalation\n\n```sh\n$ npm install bookshelf-collection-querystring-mutation\n```\n\n## Basic Usage\n\n```javascript\nconst express = require(\"express\");\nconst bookshelf = require(\"bookshelf\");\nconst knex = require(\"knex\");\n\nconst bcqm = reqire(\"bookshelf-collection-querystring-mutation\");\n\nconst repository = bookshelf(\n  knex({\n    /*...*/\n  })\n);\n\nlet app = express();\n\n// Connect Plugin\nrepository.plugin(bcqm);\n\n// Define Model\nconst List = repository.Model.extend({\n  tableName: \"shopping_list\",\n  allowed: [\"name\", \"qty\", \"price\"],\n  hidden: [\"barcode\"]\n});\n\napp.get(\"/list\", function(req, res, next) {\n  let items = new List();\n\n  // Mutate from query\n  items.filter(req.query.filter).orderBy(req.query.orderBy);\n\n  items.fetchAll().then(r =\u003e {\n    /* Do stuff. */\n  });\n});\n```\n\n## How to use\n\n```http\nGET /list?filter=price ge 10\u0026orderBy=name\n```\n\nWill filter instances that have `price \u003e= 10` and order them by `name`.\n\n## Filter Operation\n\nAllows you to filter collection.\n\nPattern: `field1 \u003coperation\u003e value [logical_opration] ...`\n\n| Operator             | Description           | Example                                               |\n| -------------------- | --------------------- | ----------------------------------------------------- |\n| Comparison Operators |                       |\n| eq                   | Equal                 | city eq 'Redmond'                                     |\n| ne                   | Not equal             | city ne 'London'                                      |\n| gt                   | Greater than          | price gt 20                                           |\n| ge                   | Greater than or equal | price ge 10                                           |\n| lt                   | Less than             | price lt 20                                           |\n| le                   | Less than or equal    | price le 100                                          |\n| lk                   | Like                  | name lk '%gg%'                                        |\n| il                   | iLike                 | name il '%GG%'                                        |\n| in                   | in                    | name in ['GG', 'Salad']                               |\n| is                   | Is (null)             | price is null                                         |\n| sn                   | Is Not (null)         | price sn null                                         |\n| Logical Operators    |                       |\n| and                  | Logical and           | price le 200 and price gt 3.5                         |\n| or                   | Logical or            | price le 3.5 or price gt 200                          |\n| Grouping Operators   |                       |\n| ( )                  | Precedence grouping   | (priority eq 1 or city eq 'Redmond') and price gt 100 |\n\n## Filter examples:\n\nThe following examples illustrate the use and semantics of each of the logical operators.\n\nExample: all products with a name equal to 'Milk'\n\n```http\nGET /list?filter=name eq 'Milk'\n```\n\nExample: all products with a name not equal to 'Milk'\n\n```http\nGET /list?filter=name ne 'Milk'\n```\n\nExample: all products with the name 'Milk' that also has a price less than 2.55:\n\n```http\nGET /list?filter=name eq 'Milk' and price lt 2.55\n```\n\nExample: all products that either have the name 'Milk' or have a price less than 2.55:\n\n```http\nGET /list?filter=name eq 'Milk' or price lt 2.55\n```\n\nExample: all products that have the name 'Milk' or 'Eggs' and have a price less than 2.55:\n\n```http\nGET /list?filter=(name eq 'Milk' or name eq 'Eggs') and price lt 2.55\n```\n\nExample: all products that have the name matching '_gg_':\n\n```http\nGET /list?filter=name lk \"%gg%\"\n```\n\nExample: all products that have ids in array of [1, 2, 3]:\n\n```http\nGET /list?filter=id in [1, 2, 3]\n```\n\nExample: all products that have price is set to null:\n\n```http\nGET /list?filter=price is null\n```\n\nExample: all products that have price is not set to null:\n\n```http\nGET /list?filter=price sn null\n```\n\n## OrderBy\n\nAllows you to sort collections.\n\nPattern: `field1 [dirrection(asc|desc)][, field2 [dirrection(asc|desc)], [...]]`\n\n## OrderBy Examples\n\nExample: will return all products sorted by name in ascending order.\n\n```http\nGET /list?orderBy=name\n```\n\nFor example: will return all products sorted by name in descending order.\n\n```http\nGET /list?orderBy=name desc\n```\n\nSub-sorts can be specified by a comma-separated list of property names with OPTIONAL direction qualifier.\n\nExample: will return all people sorted by name in descending order and a secondary sort order of price in ascending order.\n\n```http\nGET /list?orderBy=name desc,price\n```\n\n## Plugin Configuration:\n\n```js\nrepository.plugin(bcqm, {\n  filterName: \"filter\", //filter function name in BSModel\n  orderByName: \"orderBy\", //orderBy function name in BSModel\n  hiddenPropsName: \"hidden\", //name of Property that provides array of hidden fields\n  allowedPropsName: \"allowed\", //name of Property that provides array of allowed fields\n  ignoreErrors: false //throw errors or skip silently\n});\n```\n\nHidden and Allowed arrays provide fields visibility for a plugin.\nIf any filter or orderBy field is an array of private fields, it will throw an Error.\nIf any filter or orderBy field is not an array of allowed fields, it will throw an Error.\n\nYou can also not provide this props if you don't care.\n\nModel example:\n\n```js\nconst List = repository.Model.extend({\n  tableName: \"shopping_list\",\n  allowed: [\"name\", \"qty\", \"price\"], //filter and orderBy by this fields\n  hidden: [\"barcode\"] //DON'T by this\n});\n```\n\n# TODO:\n\n- `not` Logical operator\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvzhufk%2Fbookshelf-collection-querystring-mutation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvzhufk%2Fbookshelf-collection-querystring-mutation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvzhufk%2Fbookshelf-collection-querystring-mutation/lists"}