{"id":40310058,"url":"https://github.com/phetsims/query-string-machine","last_synced_at":"2026-01-20T06:31:47.132Z","repository":{"id":47477132,"uuid":"67671121","full_name":"phetsims/query-string-machine","owner":"phetsims","description":" Query String Machine is a query string parser that supports type coercion, default values \u0026 validation. No dependencies.","archived":false,"fork":false,"pushed_at":"2025-10-07T18:51:31.000Z","size":424,"stargazers_count":3,"open_issues_count":7,"forks_count":3,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-10-07T20:42:39.112Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","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/phetsims.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2016-09-08T05:24:01.000Z","updated_at":"2025-10-07T18:51:35.000Z","dependencies_parsed_at":"2023-12-22T02:22:06.593Z","dependency_job_id":"370972a3-ab5d-402a-a0fd-a404eef488f2","html_url":"https://github.com/phetsims/query-string-machine","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/phetsims/query-string-machine","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phetsims%2Fquery-string-machine","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phetsims%2Fquery-string-machine/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phetsims%2Fquery-string-machine/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phetsims%2Fquery-string-machine/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/phetsims","download_url":"https://codeload.github.com/phetsims/query-string-machine/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phetsims%2Fquery-string-machine/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28597628,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-20T02:08:49.799Z","status":"ssl_error","status_checked_at":"2026-01-20T02:08:44.148Z","response_time":117,"last_error":"SSL_read: 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":[],"created_at":"2026-01-20T06:31:46.927Z","updated_at":"2026-01-20T06:31:47.115Z","avatar_url":"https://github.com/phetsims.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Query String Machine\n\nQuery String Machine is a query string parser that supports type coercion, default values \u0026 validation. No dependencies.\n\n## Installation\n\nDownload [QueryStringMachine.js](blob/main/LICENSE) and include it with a script tag, like:\n\n```html\n\u003cscript src=\"QueryStringMachine.js\"\u003e\u003c/script\u003e\n```\n\n## Usage\n\nAfter downloading and including QueryStringMachine, you can use it to obtain values from the query string. Query String\nMachine values can be obtained by calling `QueryStringMachine.get`, which supports the following types:\n\n### boolean\n\nType: 'boolean' returns a primitive boolean value. Note this of type boolean, not string.\n\n```js\n\nvar audio = QueryStringMachine.get( 'audio', { type: 'boolean' } );\n\n// http://localhost/test.html?audio=false   =\u003e audio===false\n// http://localhost/test.html?audio=true    =\u003e audio===true\n```\n\n### flag\n\nType: 'flag' takes the boolean value true if and only if it is provided\n\n```js\n\nvar audio = QueryStringMachine.get( 'audio', { type: 'flag' } );\n\n// http://localhost/test.html            =\u003e audio===false\n// http://localhost/test.html?audio      =\u003e audio===true\n```\n\n### number\n\nType: 'number' provides numeric values. Note that for each type, a `defaultValue` can be provided. If `defaultValue` is\nnot provided, then that query parameter is required, or QueryStringMachine will error.\n\n```js\nvar delay = QueryStringMachine.get( 'delay', { type: 'number', defaultValue: 1000 }};\n\n// http://localhost/test.html            =\u003e delay===1000\n// http://localhost/test.html?delay=123  =\u003e delay===123\n```\n\n### string\n\nType: 'string' provides values as strings:\n\n```js\nvar name = QueryStringMachine.get( 'name', { type: 'string', defaultValue: 'Alice' }};\n\n// http://localhost/test.html            =\u003e name==='Alice'\n// http://localhost/test.html?name=Bob   =\u003e name==='Bob'\n```\n\n### array\n\nType: 'array' provides values as strings, using a nested element schema\n\n```js\nvar words = QueryStringMachine.get( 'heights', { type: 'array', elementSchema: { type: 'string' } } };\n\n// http://localhost/test.html?words=hello,there  =\u003e words===['hello', 'there']\n// http://localhost/test.html?words=hi           =\u003e words===['hi']\n```\n\n### custom\n\nBy providing a `parse` function, you can support arbitrary types:\n\n```js\nvar lower = QueryStringMachine.get( 'name', {\n  parse: function( string ) {\n    return string.toLowerCase();\n  }\n};\n\n// http://localhost/test.html?name=Edward       =\u003e name==='edward'\n```\n\n## Allowed Values\n\nEach type supports allowed values, which specifies an array of valid values, which are checked with `===`.\n\n```js\nvar height = QueryStringMachine.get( 'height', {\n  type: 'number',\n  allowedValues: [ 4, 5, 6, 7, 8 ]\n};\n\n// http://localhost/test.html?height=123 =\u003e throws an Error\n```\n\n## Multiple Values\n\nIn addition to `QueryStringMachine.get`, you can use `QueryStringMachine.getAll` which provides multiple values at the\nsame time:\n\n```js\nQueryStringMachine.getAll( {\n    height: {\n      type: 'number',\n      defaultValue: 6,\n      allowedValues: [ 4, 5, 6, 7, 8 ]\n    },\n    name: {\n      type: 'string',\n      defaultValue: 'Larry',\n      validate: function( str ) {\n        assert \u0026\u0026 assert( str.indexOf( 'Z' ) !== 0, 'Name cannot start with Z: ' + str );\n      }\n    },\n    custom: {\n      parse: function( string ) {\n        return string.toLowerCase();\n      },\n      allowedValues: [ 'abc', 'def', 'ghi' ],\n      defaultValue: 'abc'\n    },\n    isWebGL: {\n      type: 'flag'\n    },\n    screens: {\n      type: 'array',\n      elementType: 'number',\n      defaultValue: [],\n      // separator can be overridden, defaults to ','\n    }\n  } )\n```\n\nreturns the following results:\n\n```js\n// http://localhost/query-string-machine/test-query-string-machine.html\n{\n  \"height\": 6,\n  \"name\": \"Larry\",\n  \"custom\": \"abc\",\n  \"isWebGL\": false,\n  \"screens\": []\n}\n\n// http://localhost/query-string-machine/test-query-string-machine.html?height=7\u0026isWebGL\u0026wisdom=123\n{\n  \"height\": 7,\n  \"name\": \"Larry\",\n  \"custom\": \"abc\",\n  \"isWebGL\": true,\n  \"screens\": []\n}\n\n// http://localhost/query-string-machine/test-query-string-machine.html?height=7\u0026isWebGL\u0026wisdom=123\u0026custom=DEF\n{\n  \"height\": 7,\n  \"name\": \"Larry\",\n  \"custom\": \"def\",\n  \"isWebGL\": true,\n  \"screens\": []\n}\n\n// http://localhost/query-string-machine/test-query-string-machine.html?height=0\nError( 'value not allowed: 0, allowedValues = 4,5,6,7,8' )\n\n// http://localhost/query-string-machine/test-query-string-machine.html?isWebGL\u0026screens=1,2,3,5\n{\n  \"height\": 6,\n  \"name\": \"Larry\",\n  \"custom\": \"abc\",\n  \"isWebGL\": true,\n  \"screens\": [\n    1,\n    2,\n    3,\n    5\n  ]\n}\n```\n\n## Additional Features\n\nMost use cases are covered by the preceding examples, but in some cases you will want to parse arbitrary strings or\ncheck for the existence of a key.\n\n### Parsing arbitrary strings\n\nBy default, Query String Machine parses the browser query string `window.location.search`. It can also parse values from\nprovided strings like so:\n\n```js\nvar text = QueryStringMachine.getForString( 'text', { type: 'string' }, '?text=hello' );\nvar queryParameters = QueryStringMachine.getAllForString( {\n  name: {\n    type: 'string'\n  },\n  age: {\n    type: 'number',\n    defaultValue: '0',\n  }, '?name=Shirley\u0026age=100' );\n```\n\n### Checking for the existence of a key\n\nIn some cases, it is only important to check for the existence of a key. This can be done using Query String Machine\nlike so:\n\n```js\nvar containsAudioKey = QueryStringMachine.containsKey( 'audio' );\nvar queryParameters = QueryStringMachine.containsKeyForString( 'audio', '?mute' );\n```\n\nLaunch test-query-string-machine.html for automated tests\n\n## Copyright and License\n\nQueryStringMachine is Copyright 2016-2018, University of Colorado Boulder and licensed under MIT","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphetsims%2Fquery-string-machine","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fphetsims%2Fquery-string-machine","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphetsims%2Fquery-string-machine/lists"}