{"id":24429492,"url":"https://github.com/bjnstnkvc/js-local-storage","last_synced_at":"2026-04-16T22:31:13.944Z","repository":{"id":220200491,"uuid":"749991935","full_name":"BJNSTNKVC/js-local-storage","owner":"BJNSTNKVC","description":"Simple wrapper for JavaScript Local Storage API.","archived":false,"fork":false,"pushed_at":"2026-03-30T10:19:08.000Z","size":214,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-03-30T12:04:21.615Z","etag":null,"topics":["javascript","localstorage","storage","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/BJNSTNKVC.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-01-29T19:33:11.000Z","updated_at":"2026-03-30T10:17:51.000Z","dependencies_parsed_at":"2026-03-30T12:02:19.550Z","dependency_job_id":null,"html_url":"https://github.com/BJNSTNKVC/js-local-storage","commit_stats":null,"previous_names":["bjnstnkvc/js-local-storage"],"tags_count":23,"template":false,"template_full_name":null,"purl":"pkg:github/BJNSTNKVC/js-local-storage","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BJNSTNKVC%2Fjs-local-storage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BJNSTNKVC%2Fjs-local-storage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BJNSTNKVC%2Fjs-local-storage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BJNSTNKVC%2Fjs-local-storage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BJNSTNKVC","download_url":"https://codeload.github.com/BJNSTNKVC/js-local-storage/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BJNSTNKVC%2Fjs-local-storage/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31907424,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-16T18:22:33.417Z","status":"ssl_error","status_checked_at":"2026-04-16T18:21:47.142Z","response_time":69,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["javascript","localstorage","storage","typescript"],"created_at":"2025-01-20T13:38:52.098Z","updated_at":"2026-04-16T22:31:13.886Z","avatar_url":"https://github.com/BJNSTNKVC.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# LocalStorage\n\nA class that provides a set of methods for interacting with the browser's local storage.\n\n## Installation \u0026 setup\n\n### NPM\n\nYou can install the package via npm:\n\n```bash\nnpm install @bjnstnkvc/local-storage\n````\n\nand then import it into your project\n\n```javascript\nimport { LocalStorage } from '@bjnstnkvc/local-storage';\n```\n\n### CDN\n\nYou can install the package via jsDelivr CDN:\n\n```html\n\n\u003cscript src=\"https://cdn.jsdelivr.net/npm/@bjnstnkvc/local-storage/lib/main.min.js\"\u003e\u003c/script\u003e\n```\n\n## Usage\n\n### set\n\nSet the value for a given key in the Local Storage.\n\n#### Parameters\n\n- **key** - String containing the name of the key.\n- **value** - The value to be stored.\n- **ttl** *(optional)* - Time to live in seconds for the key. Defaults to `null` (no expiration) or equal\n  to [LocalStorage.ttl](#ttl) value.\n\n#### Example\n\n```javascript\nLocalStorage.set('key', 'value', 60); \n```\n\n### get\n\nRetrieve the value associated with the given key from the Local Storage.\n\n#### Parameters\n\n- **key** - String containing the name of the key.\n- **fallback** *(optional)* - The fallback value in case the key does not exist. Defaults to `null`.\n\n#### Example\n\n```javascript\nLocalStorage.get('key', 'default');\n````\n\nYou can also pass a closure as the default value. If the specified item is not found in the Local Storage, the closure\nwill be executed and its result returned.\nThis allows you to lazily load default values from other sources:\n\n```javascript\nLocalStorage.get('key', () =\u003e 'default');\n````\n\n\u003e **Note:** When you attempt to retrieve a value using the `get` method, it checks if the item has expired based on its\n\u003e TTL (Time-To-Live). If the item has indeed expired, it is automatically removed from the LocalStorage, ensuring that\n\u003e your application only works with valid, up-to-date data.\n\n### remember\n\nRetrieve the value associated with the given key, or execute the given callback and store the result in the Local\nStorage.\n\n#### Parameters\n\n- **key** - String containing the name of the key.\n- **fallback** - Function you want to execute.\n- **ttl** *(optional)* - Time to live in seconds for the key. Defaults to `null` (no expiration) or equal\n  to [LocalStorage.ttl](#ttl) value.\n\n#### Example\n\n```javascript\nLocalStorage.remember('key', () =\u003e 'default', 60);\n````\n\n### all\n\nRetrieve an array containing all keys and their associated values stored in the Local Storage.\n\n#### Example\n\n```javascript\nLocalStorage.all();\n```\n\n\u003e **Note:** The `all` method returns an array of objects with `key` and `value` properties (e.g.\n`[{ key: 'key', value: 'value' }]`)\n\n### remove\n\nRemove the key and its associated value from the Local Storage.\n\n#### Parameters\n\n- **key** - String containing the name of the key to be deleted.\n\n#### Example\n\n```javascript\nLocalStorage.remove('key');\n```\n\n### clear\n\nClear all keys and their associated values from the Local Storage.\n\n#### Example\n\n```javascript\nLocalStorage.clear();\n```\n\n### has\n\nCheck if a key exists in the Local Storage.\n\n#### Parameters\n\n- **key** - String containing the name of the key to be checked.\n\n#### Example\n\n```javascript\nLocalStorage.has('key');\n```\n\n### missing\n\nCheck if a key does not exist in the Local Storage.\n\n#### Parameters\n\n- **key** - String containing the name of the key to be checked.\n\n#### Example\n\n```javascript\nLocalStorage.missing('key');\n```\n\n### hasAny\n\nCheck if any of the provided keys exist in the Local Storage.\n\n#### Parameters\n\n- **keys** - String or an array of strings containing the names of the keys to be checked.\n\n#### Example\n\n```javascript\nLocalStorage.hasAny(['key1', 'key2']);\n```\n\n### isEmpty\n\nCheck if the Local Storage is empty.\n\n#### Example\n\n```javascript\nLocalStorage.isEmpty();\n```\n\n### isNotEmpty\n\nCheck if the Local Storage is not empty.\n\n#### Example\n\n```javascript\nLocalStorage.isNotEmpty();\n```\n\n### keys\n\nRetrieve an array containing all keys stored in the Local Storage.\n\n#### Example\n\n```javascript\nLocalStorage.keys();\n```\n\n### count\n\nRetrieve the total number of items stored in the Local Storage.\n\n#### Example\n\n```javascript\nLocalStorage.count();\n```\n\n### touch\n\nUpdate the expiration time of a key in the Local Storage.\n\n#### Parameters\n\n- **key** - String containing the name of the key.\n- **ttl** *(optional)* - Time to live in seconds for the key. Defaults to `null` (no expiration) or equal\n  to [LocalStorage.ttl](#ttl) value.\n\n#### Example\n\n```javascript\nLocalStorage.touch('key', 60);\n```\n\n### expiry\n\nRetrieve the expiration date for a given key.\n\n#### Parameters\n\n- **key** - String containing the name of the key you want to check against\n\n#### Example\n\n```javascript\nLocalStorage.expiry('key');\n```\n\nYou can also pass a boolean as the second parameter to return the expiration date as a Date object:\n\n```javascript\nLocalStorage.expiry('key', true);\n```\n\n### dump\n\nPrint the value associated with a key to the console.\n\n#### Parameters\n\n- **key** - String containing the name of the key.\n\n#### Example\n\n```javascript\nLocalStorage.dump('key');\n```\n\n### fake\n\nReplace the Local Storage instance with a fake implementation. This is particularly useful for testing purposes where\nyou want to avoid interacting with the actual browser's Local Storage.\n\n#### Example\n\n```javascript\nLocalStorage.fake();\n```\n\n### restore\n\nRestore the original Local Storage instance. This is typically used after [fake()](#fake) to return to using the real\nbrowser's Local Storage.\n\n#### Example\n\n```javascript\nLocalStorage.restore();\n```\n\n### isFake\n\nCheck if a fake Local Storage instance is currently being used.\n\n#### Example\n\n```javascript\nif (LocalStorage.isFake()) {\n    // ...\n}\n```\n\n### ttl\n\nDefine a global Time-To-Live (TTL) in seconds for all items saved using the [LocalStorage.set](#set)\nor [LocalStorage.touch](#touch) method, without specifying a TTL for each item. This can be particularly useful for\napplications needing a consistent expiry policy for most stored data.\n\n#### Example\n\n```javascript\nLocalStorage.ttl(7200);\n```\n\nIf a default TTL has been set using `LocalStorage.ttl`, it will be applied to all items set without a specified TTL.\n\n## Events\n\nIn case you would like to execute a callback on Local Storage operation, you may listen for various events dispatched by\nthe Local Storage.\n\n| Type            | Event           |\n|-----------------|-----------------|\n| `retrieving`    | RetrievingKey   |\n| `hit`           | KeyHit          |\n| `missed`        | KeyMissed       |\n| `writing`       | WritingKey      |\n| `written`       | KeyWritten      |\n| `write-failed`  | KeyWriteFailed  |\n| `forgot`        | KeyForgotten    |\n| `forgot-failed` | KeyForgotFailed |\n| `flushing`      | StorageFlushing |\n| `flushed`       | StorageFlushed  |\n\n### listen\n\nRegister an event listener for one or more storage events.\n\n#### Parameters\n\n- **events** - String or an object of strings containing the type and a callback function.\n- **callback** - Function to be executed when the event is dispatched in case an event is passed as a string.\n\n#### Example\n\n```javascript\nLocalStorage.listen('retrieving', (event) =\u003e {\n    console.log(event);\n});\n```\n\nIn case you would like to register multiple events, you can pass an object containing the type and a callback function:\n\n```javascript\nLocalStorage.listen({\n    'retrieving': (event) =\u003e {\n        // ...\n    },\n    'hit': (event) =\u003e {\n        // ...\n    },\n    'missed': (event) =\u003e {\n        // ...\n    },\n    'writing': (event) =\u003e {\n        // ...\n    },\n    'written': (event) =\u003e {\n        // ...\n    },\n    'write-failed': (event) =\u003e {\n        // ...\n    },\n    'forgot': (event) =\u003e {\n        // ...\n    },\n    'forgot-failed': (event) =\u003e {\n        // ...\n    },\n    'flushing': (event) =\u003e {\n        // ...\n    },\n    'flushed': (event) =\u003e {\n        // ...\n    },\n});\n```\n\nConveniently, you can also use the following methods to register event listeners for a specific event:\n\n### onRetrieving\n\nTriggered when a key is about to be retrieved from storage.\n\n```javascript\nLocalStorage.onRetrieving((event) =\u003e {\n  // ...\n});\n```\n\n### onHit\n\nTriggered when a requested key is found in the storage.\n\n```javascript\nLocalStorage.onHit((event) =\u003e {\n  // ...\n});\n```\n\n### onMissed\n\nTriggered when a requested key is not found in the storage.\n\n```javascript\nLocalStorage.onMissed((event) =\u003e {\n  // ...\n});\n```\n\n### onWriting\n\nTriggered when a key is about to be written to storage.\n\n```javascript\nLocalStorage.onWriting((event) =\u003e {\n  // ...\n});\n```\n\n### onWritten\n\nTriggered after a key has been successfully written to storage.\n\n```javascript\nLocalStorage.onWritten((event) =\u003e {\n  // ...\n});\n```\n\n### onWriteFailed\n\nTriggered when writing a key to storage fails.\n\n```javascript\nLocalStorage.onWriteFailed((event) =\u003e {\n  // ...\n});\n```\n\n### onForgot\n\nTriggered when a key is successfully removed from storage.\n\n```javascript\nLocalStorage.onForgot((event) =\u003e {\n  // ...\n});\n```\n\n### onForgotFailed\n\nTriggered when removing a key from storage fails.\n\n```javascript\nLocalStorage.onForgotFailed((event) =\u003e {\n  // ...\n});\n```\n\n### onFlushing\n\nTriggered when the storage is about to be cleared.\n\n```javascript\nLocalStorage.onFlushing((event) =\u003e {\n  // ...\n});\n```\n\n### onFlushed\n\nTriggered after the storage has been successfully cleared.\n\n```javascript\nLocalStorage.onFlushed((event) =\u003e {\n    // ...\n});\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbjnstnkvc%2Fjs-local-storage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbjnstnkvc%2Fjs-local-storage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbjnstnkvc%2Fjs-local-storage/lists"}