{"id":15570275,"url":"https://github.com/nfroidure/strict-qs","last_synced_at":"2025-07-12T16:04:36.652Z","repository":{"id":14374362,"uuid":"76167798","full_name":"nfroidure/strict-qs","owner":"nfroidure","description":"A stricter query string parser","archived":false,"fork":false,"pushed_at":"2025-01-29T15:47:02.000Z","size":1139,"stargazers_count":4,"open_issues_count":5,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-29T01:05:50.675Z","etag":null,"topics":["hacktoberfest","javascript","parser","querystrings","strict-types"],"latest_commit_sha":null,"homepage":"http://insertafter.com/en/blog/toward_stricter_query_string_parser.html","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nfroidure.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","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,"zenodo":null},"funding":{"github":["nfroidure"]}},"created_at":"2016-12-11T10:34:46.000Z","updated_at":"2025-01-29T15:47:06.000Z","dependencies_parsed_at":"2024-06-20T19:06:33.289Z","dependency_job_id":"f3e62853-9c5e-412a-bfab-eb6a8f3d7aaa","html_url":"https://github.com/nfroidure/strict-qs","commit_stats":{"total_commits":82,"total_committers":2,"mean_commits":41.0,"dds":"0.35365853658536583","last_synced_commit":"3d1c678d51f462e81136d9234a68376bd02d834f"},"previous_names":[],"tags_count":33,"template":false,"template_full_name":null,"purl":"pkg:github/nfroidure/strict-qs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nfroidure%2Fstrict-qs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nfroidure%2Fstrict-qs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nfroidure%2Fstrict-qs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nfroidure%2Fstrict-qs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nfroidure","download_url":"https://codeload.github.com/nfroidure/strict-qs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nfroidure%2Fstrict-qs/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262574127,"owners_count":23330778,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["hacktoberfest","javascript","parser","querystrings","strict-types"],"created_at":"2024-10-02T17:41:50.485Z","updated_at":"2025-07-12T16:04:36.630Z","avatar_url":"https://github.com/nfroidure.png","language":"TypeScript","funding_links":["https://github.com/sponsors/nfroidure"],"categories":[],"sub_categories":[],"readme":"[//]: # ( )\n[//]: # (This file is automatically generated by a `metapak`)\n[//]: # (module. Do not change it  except between the)\n[//]: # (`content:start/end` flags, your changes would)\n[//]: # (be overridden.)\n[//]: # ( )\n# strict-qs\n\u003e A stricter Query String parser\n\n[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/nfroidure/strict-qs/blob/main/LICENSE)\n[![Coverage Status](https://coveralls.io/repos/github/nfroidure/strict-qs/badge.svg?branch=main)](https://coveralls.io/github/nfroidure/strict-qs?branch=main)\n\n\n[//]: # (::contents:start)\n\nA stricter query string parser allows to ensure URIs uniqueness and better\n caching through your own cache but also public HTTP proxies for public\n endpoints.\n\nTo ensure URIs uniqueness, `strict-qs` checks:\n- the order in which query strings are set,\n- query parameters values aren't set to their default values,\n- values set are reentrant (ie: `1.10` will be refused, its\n canonical form `1.1` will be required),\n- query parameters used are existing and effective,\n- items collections are sorted (by value for number, alpha-numeric for strings).\n\nAs a side effect, it also cast values from strings to\n their target types.\n\nYou may wonder if it is not overkill to be that strict.\n On every projects I worked on, I never been sad to have\n built too strict systems. The inverse is not true ;).\n\nAlso, it may be less pain to handle such strictness if\n you generate client APIs that handle that strictness for\n you, which is recommended. You can see an example of such\n client [here](https://github.com/sencrop/sencrop-js-api-client).\n\n## Usage\n\n```js\nimport qs from 'strict-qs';\n\n// The definition formatting is swagger compatible\n// but only for the subset I use. PRs are welcome\n// for broader support\nconst qsDefinition = [{\n  name: 'lang',\n  in: 'query',\n  type: 'string',\n  required: true,\n  description: 'The language for the search'\n}, {\n  name: 'types',\n  in: 'query',\n  type: 'array',\n  items: {\n    type: 'string',\n    enum: ['open', 'closed', 'pending', 'idle', 'invalid'],\n  },\n  description: 'The types of the search'\n}, {\n  name: 'code',\n  in: 'query',\n  type: 'integer',\n  description: 'The code id'\n}];\n\nqs(\n  qsDefinition,\n  '?lang=fr\u0026types=open\u0026types=closed\u0026types=pending\u0026code=3'\n);\n// Returns\n{\n  lang: 'fr',\n  types: ['open', 'closed', 'pending'],\n  code: 3\n}\n\nqs(\n  qsDefinition,\n  '?code=3\u0026lang=fr\u0026types=open\u0026types=closed\u0026types=pending'\n);\n// throws an error since the order is bad\nnew Error('E_BAD_QUERY_PARAM', 'types')\n```\n\nThe returned query parameters should still be validated with\n any JSON Schema validator. You can see how it is done in\n [swagger-http-router](https://github.com/nfroidure/swagger-http-router)\n for instance.\n\n[//]: # (::contents:end)\n\n# API\n\u003ca name=\"qsStrict\"\u003e\u003c/a\u003e\n\n## qsStrict(options, definitions, search) ⇒ \u003ccode\u003eObject\u003c/code\u003e\nParse a queryString according to the provided definitions\n\n**Kind**: global function  \n**Returns**: \u003ccode\u003eObject\u003c/code\u003e - The parsed properties  \n\n| Param | Type | Description |\n| --- | --- | --- |\n| options | \u003ccode\u003eObject\u003c/code\u003e | Parser options |\n| options.allowEmptySearch | \u003ccode\u003eBoolean\u003c/code\u003e | Avoid throwing when the search is empty |\n| options.allowUnknownParams | \u003ccode\u003eBoolean\u003c/code\u003e | Avoid throwing when some params are unknown |\n| options.allowDefault | \u003ccode\u003eBoolean\u003c/code\u003e | Avoid throwing when some params is set to its default value |\n| options.allowUnorderedParams | \u003ccode\u003eBoolean\u003c/code\u003e | Avoid throwing when params are not set in the same order  than declarations |\n| definitions | \u003ccode\u003eArray\u003c/code\u003e | Swagger compatible list of defitions |\n| search | \u003ccode\u003estring\u003c/code\u003e | The actual query string to parse |\n\n**Example**  \n```js\nimport qs from 'strict-qs';\n\nconst qsOptions = { allowEmptySearch: true };\nconst qsDefinition = [{\n  name: 'pages',\n  in: 'query',\n  type: 'array',\n  items: {\n    type: 'number',\n  },\n  ordered: true,\n  description: 'The pages to print',\n}];\n\nqs(qsOptions, qsDefinition, '?pages=0\u0026pages=1\u0026pages=2');\n// Returns:\n// {\n//  pages: [0, 1, 2], // eslint-disable-line\n// }\n```\n\n# Authors\n- [Nicolas Froidure](http://insertafter.com/en/index.html)\n\n# License\n[MIT](https://github.com/nfroidure/strict-qs/blob/main/LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnfroidure%2Fstrict-qs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnfroidure%2Fstrict-qs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnfroidure%2Fstrict-qs/lists"}