{"id":19529899,"url":"https://github.com/loopmode/persistence","last_synced_at":"2025-02-26T02:43:10.603Z","repository":{"id":140399800,"uuid":"141031208","full_name":"loopmode/persistence","owner":"loopmode","description":"A scoped and performant wrapper around localStorage/sessionStorage","archived":false,"fork":false,"pushed_at":"2018-07-17T10:06:31.000Z","size":440,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-08T17:18:06.706Z","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":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/loopmode.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2018-07-15T13:52:06.000Z","updated_at":"2018-07-17T10:06:32.000Z","dependencies_parsed_at":null,"dependency_job_id":"b50fef52-9198-4af1-b9ea-1e2721136816","html_url":"https://github.com/loopmode/persistence","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/loopmode%2Fpersistence","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loopmode%2Fpersistence/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loopmode%2Fpersistence/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loopmode%2Fpersistence/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/loopmode","download_url":"https://codeload.github.com/loopmode/persistence/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240783109,"owners_count":19856776,"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-11T01:28:04.140Z","updated_at":"2025-02-26T02:43:10.541Z","avatar_url":"https://github.com/loopmode.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @loopmode/persistence\n\nA scoped wrapper for web storage APIs.\n\n- Allows simplified and more performant usage of `window.localStorage` and `window.sessionStorage`.  \n- Instead of using complex keys to avoid naming collisions, create scoped persistence objects and use simple keys\n- Instead of serializing/deserializing object values on each access, do it only once and operate on a plain object in memory\n\n### Resources\n\n- Full documentation: [https://loopmode.github.io/persistence/](https://loopmode.github.io/persistence/)  \n- Github repository: [https://github.com/loopmode/persistence](https://github.com/loopmode/persistence)  \n- NPM package: [https://www.npmjs.com/package/@loopmode/persistence](https://www.npmjs.com/package/@loopmode/persistence)  \n\n## Installation\n\n```javascript\nyarn add @loopmode/persistence\n```\n\n## Usage\n\nSupports an API similar to the web storage API (`getItem`, `setItem`) with additional `get` and `set` aliases, but under the scope of a specific name. You can use logical and short/similar keys across scopes.\nAdditionally, you can store object values.\n\n```javascript\n// PageOne.js\nimport Persistence from '@loopmode/persistence';\nconst storage = new Persistence('PageOne');\n\nstorage.set('viewMode', 'list');\n\n// PageTwo.js\nimport Persistence from '@loopmode/persistence';\nconst storage = new Persistence('PageTwo');\n\nstorage.set('viewMode', 'grid');\nstorage.set('foo', {bar: {baz: 'boo'}});\nconsole.log(storage.get('foo')); // {bar: {baz: 'boo'}}\n\n// you can also pass objects to set all values at once\nstorage.set({foo: 'foo', bar: {baz: 'boo'}});\nconsole.log(storage.get('foo')); // 'foo'\nconsole.log(storage.get('bar')); // {baz: 'boo'}\n```\n\n## Serialization and performance\n\nWhen using the get/set methods, you are not operating on the actual web storage yet, because that would involve serialization/deserialization (e.g. `JSON.encode`, `JSON.stringify`).  \nInstead, you work on a simple in-memory object and no serialization is taking place until before the page is unloaded or you call `instance.save()` manually.\n\n_NOTE: Most mutating methods (`set`/`setItem`, `remove`/`removeItem`, `setItemValues`) support an optional `autoSave` flag. Passing `true` will cause the changes to be immediatly persisted to the web storage backend. The `clear` and `clearAll` methods are an exception to that rule as they are always immediatly persisted._\n\n```javascript\n// PageTwo.js\nstorage.set('foo', {bar: {baz: 'boo'}});\n// value is immediatly available for reading, even if it's not persisted to the web storage yet\nconsole.log(storage.get('foo').bar); // {baz: 'boo'}\nwindow.localStorage.getItem(\"PageTwo\"); // null\n\nstorage.save();\nwindow.localStorage.getItem(\"PageTwo\"); // \"{\\\"viewMode\\\": \\\"grid\\\", \\\"foo\\\": {\\\"bar\\\": {\\\"baz\\\": \\\"boo\\\"}}\"} \n```\n\nEffectively, you are free to set ridiculous amounts of data without worrying about performance impacts, for example you could set complex data object values from inside a `mousemove` event handler or set values from inside a `requestAnimationFrame` loop without the penalties of serialization.\n\n## Shared instances\n\nIn case you need to access values from different components, e.g. in a react application, when you don't know the order of instantiation, use the the static `connect` method instead of creating an instance.  \nThe first call will create and return an instance, all consecutive calls (e.g. in other parts of your code) will simply receive the existing instance.\n\n```javascript\nvar a = Persistence.connect('foo');\nvar b = Persistence.connect('foo');\nconsole.log(a === b); // true\n\n// also:\nvar a = new Persistence('foo');\nvar b = Persistence.connect('foo');\nvar c = Persistence.connect('foo');\nconsole.log(a === b === c); // true\n\n```\n\n## Storage: backend\n\nPass the `backend` option to specify where to actually persist the data. The value should be an object that supports the web storage API (`setItem`, `getItem`, `removeItem`).  \nThe default value is `window.localStorage`.\n\n\n```javascript\nconst storage = new Persistence('options', {backend: window.sessionStorage});\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Floopmode%2Fpersistence","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Floopmode%2Fpersistence","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Floopmode%2Fpersistence/lists"}