{"id":13906086,"url":"https://github.com/anvaka/query-state","last_synced_at":"2025-09-11T08:38:07.438Z","repository":{"id":65482166,"uuid":"74183402","full_name":"anvaka/query-state","owner":"anvaka","description":"Application state in query string","archived":false,"fork":false,"pushed_at":"2025-02-03T10:26:40.000Z","size":1420,"stargazers_count":98,"open_issues_count":3,"forks_count":5,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-05-07T21:09:37.534Z","etag":null,"topics":["binding","querystring","state"],"latest_commit_sha":null,"homepage":"https://anvaka.github.io/query-state/","language":"JavaScript","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/anvaka.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}},"created_at":"2016-11-19T03:02:49.000Z","updated_at":"2025-02-03T10:26:43.000Z","dependencies_parsed_at":"2024-03-08T05:31:51.741Z","dependency_job_id":"c302fada-2c9e-40a2-be5a-3f759c8d45c5","html_url":"https://github.com/anvaka/query-state","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anvaka%2Fquery-state","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anvaka%2Fquery-state/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anvaka%2Fquery-state/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anvaka%2Fquery-state/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/anvaka","download_url":"https://codeload.github.com/anvaka/query-state/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252954410,"owners_count":21830905,"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":["binding","querystring","state"],"created_at":"2024-08-06T23:01:29.091Z","updated_at":"2025-05-07T21:09:43.054Z","avatar_url":"https://github.com/anvaka.png","language":"JavaScript","readme":"# query-state [![build status](https://github.com/anvaka/query-state/actions/workflows/tests.yaml/badge.svg)](https://github.com/anvaka/query-state/actions/workflows/tests.yaml)\n\nApplication state in query string.\n\n![demo](https://raw.githubusercontent.com/anvaka/query-state/master/docs/demo.gif)\n\nhttps://anvaka.github.io/query-state/#?name=world\n\n# usage\n\nGrab it from npm and use with your favorite bundler:\n\n```\nnpm install query-state --save\n```\n\nOr download from CDN:\n\n``` html\n\u003cscript src='https://cdn.rawgit.com/anvaka/query-state/v4.0.0/dist/query-state.min.js'\u003e\u003c/script\u003e\n```\n\nIf you downloaded from CDN the library will be available under `queryState` global name.\n\n``` js\n// create a new query state instance\nvar qs = queryState();\n\n// get current application state from the hash string:\nvar appState = qs.get();\n\n// you can also monitor for changes in the query string:\nqs.onChange(function(appState) {\n  // prints new application state on each hash update\n  console.log('app state changed!', appState);\n});\n\n// If you want to set a new value in the app state:\nqs.set('answer', 42);\n\n// Now the query string will have `answer=42` part in it.\nconsole.log(window.location.hash.indexOf('answer=42')) // prints value \u003e 0.\n\n// You can also set multiple values at once:\nqs.set({\n  name: 'Haddaway',\n  song: 'What is love?'\n});\n\n// NOTE: The call above merges new properties. It appends two new properties to \n// the current query string\n```\n\n## defaults\n\nIf you want to initialize app state with default values, you can pass them into\nquery state function:\n\n``` js\n// this will set query string to `answer=42`, unless it already has key called\n// \"answer\". In which case query string's value will take precedence.\nvar qs = queryState({\n  answer: 42\n});\n```\n\n## type limitations\n\nThis is a very simple module that currently does not support nested objects.\nI.e. you cannot set application state to `{foo: {bar: 42}}`. If you need this\nbehavior, most likely this module is not for you.\n\nWe do support primitive types serialization/deserialization:\n\n* Numbers\n* Dates\n* Strings\n\n## Sharing between modules (singleton)\n\nIf you are using a bundler (e.g. browserify or webpack), its often desirable\nto have just one instance of the application state, shared between files. Normally\nthis is accomplished via singleton pattern. The library exposes singleton\ninstance for your convenience:\n\n\n``` js\n// fileA.js\nvar stateInFileA = queryState.instance();\n\n// fileB.js\nvar stateInFileB = queryState.instance();\n\n// Both `stateInFileA` and `stateInFileB` are the same:\n// assert(stateInFileA === stateInFileB); // this is true!\n```\n\nNOTE: This is \"lazy\" implementation of the singleton: The instance is not created\nuntil you call `queryState.instance()`. After initial call the return value is\nalways the same.\n\n## Defaults in singleton scenario\n\nEach of your module may desire to pass its own defaults. You can do it by passing\noptional `defaults` object:\n\n``` js\n// fileA.js\nvar stateInFileA = queryState.instance({name: 'John'});\n// The query string now has `name=John` part.\n\n// fileB.js\nvar stateInFileB = queryState.instance({age: 42});\n// Now query string has both parts: `name=John\u0026age=42`\n\n// fileC.js\n// Note: singleton instance never overwrites query string values. So if someone\n// sets argument that already exists, the library will ignore it:\nvar stateInFileC = queryState.instance({age: 100, height: 180})\n\n// The query string still has age 42, not 100:\n// name=John\u0026age=42\u0026height=180\n```\n\n## search instead of hash\n\nBy default `query-state` saves state in the `hash` part of the url. But what if\nwe want to store state in the `search` part instead?\n\nInstead of awesome-site.com/**#?answer=42** we want awesome-site.com/**?answer=42**.\n\nPass an optional argument to tell query-state use the search part:\n\n``` js\nvar qs = queryState({\n  answer: 42\n}, {\n  useSearch: true\n});\n```\n\nThis can be especially useful if you are planning to share links on social media,\nas hash part of the query string is not visible to the servers, and they often\nconsider two different links to be the same.\n\n## clean up\n\nNormally your app state will live as long as your application. However if you\ndo need to clean up resources (e.g. unloading your app) you can call `qs.dispose()`\n\n``` js\nvar qs = queryState();\n\n// use it...\n\n// and clean up when you need it:\nqs.dispose();\n```\n\n# license\n\nMIT\n","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanvaka%2Fquery-state","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fanvaka%2Fquery-state","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanvaka%2Fquery-state/lists"}