{"id":22432764,"url":"https://github.com/julesferreira/variant-web-storage","last_synced_at":"2025-03-27T07:42:58.972Z","repository":{"id":57390844,"uuid":"418345288","full_name":"julesferreira/variant-web-storage","owner":"julesferreira","description":"Web Storage with support for complex data types","archived":false,"fork":false,"pushed_at":"2022-02-23T18:53:38.000Z","size":485,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-18T15:49:30.869Z","etag":null,"topics":["localstorage","serialization","typescript"],"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/julesferreira.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}},"created_at":"2021-10-18T04:35:36.000Z","updated_at":"2021-11-16T19:09:39.000Z","dependencies_parsed_at":"2022-09-26T16:51:05.649Z","dependency_job_id":null,"html_url":"https://github.com/julesferreira/variant-web-storage","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/julesferreira%2Fvariant-web-storage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/julesferreira%2Fvariant-web-storage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/julesferreira%2Fvariant-web-storage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/julesferreira%2Fvariant-web-storage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/julesferreira","download_url":"https://codeload.github.com/julesferreira/variant-web-storage/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245806068,"owners_count":20675293,"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":["localstorage","serialization","typescript"],"created_at":"2024-12-05T22:12:51.197Z","updated_at":"2025-03-27T07:42:58.939Z","avatar_url":"https://github.com/julesferreira.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# [variant-web-storage]\n\nWeb Storage with support for complex data types.\n\nThe [Web Storage API] requires values to be stored as `string`s. You can use\n[variant-web-storage] to expand the set of supported data types. This thin\nwrapper handles conversions between developer-friendly types and web storage\nrequirements.\n\n## Install\n\n```sh\nnpm install variant-web-storage\n```\n\n## Usage\n\n### Minimal example\n\nStore and retrieve a `Set` from `localStorage`\n\n```ts\nimport { fromStorage } from 'variant-web-storage';\n\nconst variantStorage = fromStorage(localStorage);\nvariantStorage.set('foo', new Set(['bar', 'baz']));\nvariantStorage.get('foo'); // returns Set(2) { 'bar', 'baz' }\n```\n\n### Extended example\n\nRetrieve session state- if available. Otherwise, use and persist the default.\n\n```ts\nimport { fromStorage, KEY_NOT_FOUND } from 'variant-web-storage';\n\ntype Store = { mode: 'default' | 'light' | 'dark'; items: Set\u003cstring\u003e };\nconst DEFAULT: Store = {\n  mode: 'default',\n  items: new Set(),\n};\n\nconst variantStorage = fromStorage(sessionStorage);\n\n// get object shaped like `Store` from sessionStorage at key 'session-store'\nlet store = variantStorage.get\u003cStore\u003e('session-store');\n\nif (store === KEY_NOT_FOUND) {\n  // sessionStorage had no 'session-store' key. use and save the `DEFAULT`\n  variantStorage.set('session-store', (store = DEFAULT));\n}\n\nstore; // returns { mode: 'default', items: Set(0) {} }\n```\n\nFind additional examples in the [test/] directory.\n\n## Data types\n\nSupported types are formally defined as follows (and include circular,\nreferential, and deeply-nested values).\n\n```ts\ntype SupportedValue =\n  | Array\u003cSupportedValue\u003e\n  | BigInt\n  | Date\n  | Map\u003cSupportedValue, SupportedValue\u003e\n  | RegExp\n  | Set\u003cSupportedValue\u003e\n  | boolean\n  | null\n  | number\n  | string\n  | undefined\n  | { [k in string | number]: SupportedValue };\n```\n\nKnown limitations include:\n\n- functions\n- instances of custom classes\n- weak sets/maps\n\n## Internals\n\nValue /(en|de)coding/ is largely handled by the awesome _(read:\nschema-inferring + well-dense + TypeScript-centric)_ [Bunker] library _(note:\nGNU GPL 3)_. After a value is _bunkered_ into a compact byte sequence, it's\nthen converted to a base64-encoded string- achieving web storage compatibility.\nLastly, a sentinel value _(... OK OK, it's a magic string)_ is prefixed for\nquick package/versioning lookup.\n\n[bunker]: https://github.com/digital-loukoum/bunker\n[test/]: test/\n[variant-web-storage]: https://github.com/julesferreira/variant-web-storage\n[web storage api]: https://developer.mozilla.org/docs/Web/API/Web_Storage_API\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjulesferreira%2Fvariant-web-storage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjulesferreira%2Fvariant-web-storage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjulesferreira%2Fvariant-web-storage/lists"}