{"id":19272025,"url":"https://github.com/streaver/supercharged-storage","last_synced_at":"2025-07-26T18:10:49.681Z","repository":{"id":42292184,"uuid":"243094066","full_name":"streaver/supercharged-storage","owner":"streaver","description":"A supercharged storage that lets you do a lot of new things like expirations, default values and a lot of other things the regular web storages don't let you do","archived":false,"fork":false,"pushed_at":"2022-12-10T19:30:34.000Z","size":1896,"stargazers_count":5,"open_issues_count":15,"forks_count":0,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-10-07T07:56:36.754Z","etag":null,"topics":["deserializer","expiration","local-storage","namespace","serializer","session-storage","storage","web"],"latest_commit_sha":null,"homepage":null,"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/streaver.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-02-25T20:19:20.000Z","updated_at":"2024-05-08T15:14:11.000Z","dependencies_parsed_at":"2023-01-26T06:45:35.077Z","dependency_job_id":null,"html_url":"https://github.com/streaver/supercharged-storage","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/streaver%2Fsupercharged-storage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/streaver%2Fsupercharged-storage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/streaver%2Fsupercharged-storage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/streaver%2Fsupercharged-storage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/streaver","download_url":"https://codeload.github.com/streaver/supercharged-storage/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223881182,"owners_count":17219261,"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":["deserializer","expiration","local-storage","namespace","serializer","session-storage","storage","web"],"created_at":"2024-11-09T20:35:10.430Z","updated_at":"2024-11-09T20:35:11.175Z","avatar_url":"https://github.com/streaver.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Supercharged Storage\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://user-images.githubusercontent.com/7522836/75284215-19d0b880-57f3-11ea-8e15-6b5b187189f6.png\" height=\"100px\"\u003e\n  \u003cp align=\"center\"\u003eA supercharged storage that lets you do a lot of new things like expirations, default values and a lot of other things the regular web storages don't let you do.\u003cp\u003e\n\n  \u003cp align=\"center\"\u003e\n    \u003ca href=\"https://npmjs.org/package/supercharged-storage\"\u003e\n      \u003cimg src=\"https://img.shields.io/npm/v/supercharged-storage.svg\" /\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://circleci.com/gh/streaver/supercharged-storage/tree/master\"\u003e\n      \u003cimg src=\"https://circleci.com/gh/streaver/supercharged-storage/tree/master.svg?style=shield\" /\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://codeclimate.com/github/streaver/supercharged-storage/maintainability\"\u003e\n      \u003cimg src=\"https://api.codeclimate.com/v1/badges/e6725f51619a0c309f80/maintainability\" /\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://codeclimate.com/github/streaver/supercharged-storage/test_coverage\"\u003e\n      \u003cimg src=\"https://api.codeclimate.com/v1/badges/e6725f51619a0c309f80/test_coverage\" /\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://github.com/streaver/supercharged-storage/blob/master/LICENSE\"\u003e\n      \u003cimg src=\"https://img.shields.io/github/license/streaver/supercharged-storage.svg\" /\u003e\n    \u003c/a\u003e\n  \u003c/p\u003e\n\u003c/p\u003e\n\n## Motivation\n\nSometimes you just need a little bit more than the plain `localStorage` or `sessionStorage` but you don't want to build that feature or to load an external library with many Kilobytes. You might want to have data store with expiration times, of maybe some namespaces to keep the data separated, default values, and what not?\n\nIt happened to us as well, so we extracted this from [@streaver/vue-preferences](https://github.com/streaver/vue-preferences) so you can use in any type of javascript project.\n\n\n## Table of content\n\n* [Installation](#installation)\n* [Usage](#usage)\n* [Options](#options)\n* [Contributing](#contributing)\n* [Credits](#credits)\n\n## Installation\n\nIf you prefer `yarn`:\n\n```\n$ yarn add supercharged-storage --save\n```\n\nor with `npm`:\n\n```\n$ npm install supercharged-storage --save\n```\n\n## Usage\n\nFirst you need to tell the storage which features (plugins) you want to use, that is pretty easy to do and allows you to only import the things you need and tree-shake the hell out of your app so you keep your bundle size small!\n\n```javascript\n// Somewhere in your app, just before starting to use the storage\n// In this case we want to use the Defaultable and Namespaceable\n// storage features, keep reading to find out more features.\nimport SuperchargedStorage, {\n  DefaultableStorage,\n  NamespaceableStorage,\n} from 'supercharged-storage';\n\nSuperchargedStorage.use(DefaultableStorage);\nSuperchargedStorage.use(NamespaceableStorage);\n```\n\nThis only needs to be done once, in the `main.js` or `index.js` file of your app or wherever you want to initialize the storage capabilities. If you don't this you will have a proxy for the underlying storage doing basically nothing, not very fun at all!\n\nAfter doing that you have a configured storage which will know how to use the plugins you provided and use the options you use. In this case we need our storage to have a default value of `''` and a namespace of `user-details` since we are going to be saving some basic user details.\n\n```javascript\nconst storage = SuperchargedStorage.build({\n  defaultValue: '',\n  namespace: 'user-details',\n});\n\nstorage.setItem('firstName', 'Jane');\nstorage.setItem('lastName', 'Doe');\n\nconsole.log(`Mrs ${storage.getItem('firstName')} ${storage.getItem('nameName')}`)\n```\n\nUnder the hood this is using `localStorage` to persist the data (it is the default), but you can change that, you can use `sessionStorage`, or any storage implementation you want as long as it has the same API as `localStorage`, that means you need a `getItem`, `setItem`, `removeItem` and `clear` function.\n\nYou can have multiple storages that have different configurations. Simply initialize them with different options like this:\n\n```javascript\nconst storage1 = SuperchargedStorage.build({\n  defaultValue: '',\n  namespace: 'user-details',\n  storage: sessionStorage,\n});\n\nconst storage2 = SuperchargedStorage.build({\n  defaultValue: 0,\n  namespace: 'counters',\n  storage: localStorage,\n});\n```\n\n## Options\n\nThis are the available storages and the options and capabilities that each of them add to the storage you build:\n\n### BaseStorage\n\nThis is the most basic of the available storages and is always included as part of the initialization of `supercharged-storage`. It provides only one option, the `storage` option which allows you to define which is the underlying storage you want to use, the default value for this option is `window.localStorage`.\n\nIf you don't configure the storage, then the `BaseStorage` will behave as a proxy to the underlying storage.\n\n```javascript\nimport SuperchargedStorage from 'supercharged-storage';\n\nconst storage = SuperchargedStorage.build({\n  storage: sessionStorage,\n});\n```\n\n### DefaultableStorage\n\nAs the name suggests this storage allows your storage to have default values for when the data you are looking for is not there anymore. If you are using `localStorage` or `sessionStorage` the browser might need to delete the data for any number of reasons, also the users can delete the data.\n\nBy using this you have access to the `defaultValue` option which will be used as the default return value for any non-successfully `get` operation.\n\n```javascript\nimport SuperchargedStorage, { DefaultableStorage } from 'supercharged-storage';\n\nSuperchargedStorage.use(DefaultableStorage);\n\nconst storage = SuperchargedStorage.build({\n  defaultValue: 'None',\n});\n\nstorage.getItem('firstName') // \"None\"\nstorage.setItem('firstName', 'Jon')\nstorage.getItem('firstName') // \"Jon\"\n```\n\n### NamespaceableStorage\n\nThis storage allows you to setup a namespace for each storage this is very useful if you need to keep data separated between parts of the application. For example different views might have their own namespace so they can remember  options independently.\n\nThis storage enables the option `namespace` to be used as follows:\n\n```javascript\nimport SuperchargedStorage, { NamespaceableStorage } from 'supercharged-storage';\n\nSuperchargedStorage.use(NamespaceableStorage);\n\nconst player1 = SuperchargedStorage.build({\n  namespace: 'player1',\n});\n\nconst player2 = SuperchargedStorage.build({\n  namespace: 'player2',\n});\n\nplayer1.setItem('firstName', 'Jon1');\nplayer2.setItem('firstName', 'Jon2');\n\nplayer1.getItem('firstName'); // Jon1\nplayer2.getItem('firstName'); // Jon2\n```\n\n### ExpirableStorage\n\nWith this storage you enable two options `ttl` (time-to-live) and `expiration`, this options should not be used at the same time, but if used the `ttl` option will take precedence.\n\nThe `ttl` option is the *amount of seconds* after which a saved property will be considered expired. The `expiration` option can be an instance of `Date` or a function returning a `Date` which indicates the expiration date of the properties.\n\nIf this storage is combined with the `DefaultableStorage`, when a property is expired, then the `defaultValue` will be returned it not the underlying storage default value will be returned.\n\n```javascript\nimport SuperchargedStorage, { ExpirableStorage } from 'supercharged-storage';\n\nSuperchargedStorage.use(ExpirableStorage);\n\nconst shortLivedStorage = SuperchargedStorage.build({\n  ttl: 5,\n});\n\nconst predefinedExpirationDate = SuperchargedStorage.build({\n  expiration: new Date(2021, 1, 1), // Mon Feb 01 2021 00:00:00\n});\n\nconst dynamicExpirationDate = SuperchargedStorage.build({\n  expiration: () =\u003e {\n    return new Date(2021, 1, 1);\n  }\n});\n\nshortLivedStorage.setItem('lastName', 'Doe'); // Expires in 5 seconds\npredefinedExpirationDate.setItem('firstName', 'Jon'); // Expires on Mon Feb 01 2021 00:00:00\ndynamicExpirationDate.setItem('age', 23); // Expires on Mon Feb 01 2021\n```\n\n### SerializableStorage\n\nThis storage enables you to provide custom a serializer/deserializer when writing/reading properties to/from the storage. By default anything you provide will be serialized with `JSON.stringify` and deserialized with `JSON.parse`. But if you want to change this you can use the `serializer` and `deserializer` options of the storage enabled by this plugin for example:\n\n```javascript\nimport SuperchargedStorage, { SerializableStorage } from 'supercharged-storage';\n\nSuperchargedStorage.use(SerializableStorage);\n\nconst simpleCsvStorage = SuperchargedStorage.build({\n  serializer: (data) =\u003e data.join(','),\n  deserializer: (data) =\u003e data.split(',');\n});\n\nsimpleCsvStorage.setItem('data', [1,2,3,4]); // Will be saved as \"1,2,3,4\"\nsimpleCsvStorage.getItem('data'); // Will return [1,2,3,4]\n```\n\n🚀 In the future, we will be supporting other custom options that will add even more power to the storage. Stay tuned and support!\n\n## Contributing\n\nAll contributions or issue reporting are welcomed. If you are submitting a bug issue please include information to help us debug it!\n\nIf you plan to contribute, please make sure you test the code. Any new feature or bug fix should have its own test case.\n\n## Credits\n\nIcons made by \u003ca href=\"https://www.flaticon.com/authors/freepik\" title=\"Freepik\"\u003eFreepik\u003c/a\u003e from \u003ca href=\"https://www.flaticon.com/\" title=\"Flaticon\"\u003e www.flaticon.com\u003c/a\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstreaver%2Fsupercharged-storage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstreaver%2Fsupercharged-storage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstreaver%2Fsupercharged-storage/lists"}