{"id":20816313,"url":"https://github.com/riptano/urlito","last_synced_at":"2025-10-29T00:32:26.940Z","repository":{"id":43911124,"uuid":"223052660","full_name":"riptano/urlito","owner":"riptano","description":"Declarative API for persisting application state to URL","archived":false,"fork":false,"pushed_at":"2023-07-18T23:52:44.000Z","size":1906,"stargazers_count":1,"open_issues_count":20,"forks_count":2,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-01-18T15:52:29.551Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/riptano.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":"2019-11-21T00:20:13.000Z","updated_at":"2020-01-25T08:32:46.000Z","dependencies_parsed_at":"2024-11-17T21:29:58.674Z","dependency_job_id":"3e2f1fd2-1b7d-4f8d-ae25-7ddb66c7ce5a","html_url":"https://github.com/riptano/urlito","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riptano%2Furlito","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riptano%2Furlito/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riptano%2Furlito/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riptano%2Furlito/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/riptano","download_url":"https://codeload.github.com/riptano/urlito/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243164639,"owners_count":20246717,"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":[],"created_at":"2024-11-17T21:29:41.633Z","updated_at":"2025-10-29T00:32:21.901Z","avatar_url":"https://github.com/riptano.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Urlito\n\nDeclarative API for persisting application state to URL\n\n## Synopsis\n\n```javascript\nimport ViewModel from 'statium';\nimport stateToUri from 'urlito';\n\nconst defaultState = {\n    foo: 'bar',\n    qux: {\n        time: Date.now(),\n    },\n};\n\nconst [getStateFromUri, setStateToUri] = stateToUri(defaultState, [\n    'foo',\n    {\n        key: 'qux.time',\n        uriKey: 'time',\n        fromUri: time =\u003e parseInt(time, 10),\n        toUri: time =\u003e String(time),\n    },\n});\n\nconst Component = () =\u003e (\n    \u003cViewModel initialState={getStateFromUri}\n        observeStateChange={setStateToUri}\u003e\n        \n        {/* ... */}\n    \u003c/ViewModel\u003e\n);\n```\n\n## Introduction\n\nA helper library for [Statium](https://github.com/riptano/statium), Urlito makes it easier\nto persist application state to the `query` portion of its URL.\n\nThe default export is a function (`stateToUri`) that accepts two arguments. The first\nargument is an object with keys and values corresponding to the default state of the\nViewModel. The second argument is state key descriptors enumerating keys that should be\nretrieved from the URL by getter function, and persisted to the URL by the setter function.\nThe return value is a tuple of these functions: `[getStateFromUri, setStateToUri]`.\n\n## Retrieving state\n\nTo read state from URI, the `getStateFromUri` function should be called with no arguments.\nIt will iterate over the state keys defined in `stateToUri` call, and if the key is present\nin the `query` portion of the URL, its value will be used instead of default.\n\nThe return value is an object with initial state of the ViewModel.\n\n## Persisting state\n\nTo write state to the URI, the `setStateToUri` function should be called with one argument:\nan object containing actual ViewModel state. For each state key defined in the `stateToUri`\ncall, the actual value will be compared with default value; if the value in the actual state\nobject is defined and does not equal to default, it will be persisted to the `query` portion\nof the URL. If the value in the actual state object equals to default, this key will be\ndeleted from the `query` portion of the URL.\n\nThere is no return value for this function.\n\n## State key descriptors\n\nThe second argument to `stateToUri` function is a data structure that describes state keys\nwe are interested in. This can be an object describing keys and their properties, or\nan array of descriptors.\n\nAn array is the simplified form:\n\n```javascript\nconst stateKeys = [\n    // Read parameter 'foo' in the URL query, set the value to key 'foo' in the state object\n    'foo',\n    \n    // Read parameter 'bar.baz' in the URL query, set the value to key 'baz' contained\n    // in the object 'bar' of the state object. Selectors are in lodash get/set format.\n    'bar.baz',\n    \n    { ... }, // See object form below\n];\n```\n\nAn object has the following format:\n\n```javascript\nconst stateKeys = {\n    foo: {\n        // Define key selector in array format, ignored for object format\n        key: 'foo',\n        \n        // Name of the URL 'query' portion parameter to read from/write to\n        uriKey: 'foobaroo',\n        \n        // Function that parses the value when reading from the URL.\n        // Default is to return the value as is.\n        fromUri: value =\u003e value,\n        \n        // Function that stringifies the value when writing to the URL.\n        // Default is no conversion.\n        toUri: value =\u003e value,\n        \n        // Function to compare default value with actual value when reading from\n        // URL (after parsing) and writing to URL (before stringification).\n        // This function is passed two arguments and is expected to return true\n        // when they are equal, false otherwise.\n        // Default is lodash.isEqual()\n        equals: (a, b) =\u003e isEqual(a, b),\n    },\n};\n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Friptano%2Furlito","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Friptano%2Furlito","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Friptano%2Furlito/lists"}