{"id":26005328,"url":"https://github.com/alexmayol/localit","last_synced_at":"2025-03-05T20:53:34.909Z","repository":{"id":42044796,"uuid":"253084368","full_name":"AlexMayol/localit","owner":"AlexMayol","description":"Lightweight wrapper for localStorage and sessionStorage, with additional features on top of them like setting an expiration time for your data 🔥","archived":false,"fork":false,"pushed_at":"2025-02-12T14:32:25.000Z","size":760,"stargazers_count":16,"open_issues_count":4,"forks_count":2,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-02-26T15:01:44.535Z","etag":null,"topics":["hacktoberfest","javascript","library","localstorage","sessionstorage","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/AlexMayol.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":"2020-04-04T19:38:30.000Z","updated_at":"2025-02-12T14:32:27.000Z","dependencies_parsed_at":"2024-03-17T01:57:03.596Z","dependency_job_id":"2ec464ce-7fc2-4bff-bd1f-41f55b34a566","html_url":"https://github.com/AlexMayol/localit","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/AlexMayol%2Flocalit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexMayol%2Flocalit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexMayol%2Flocalit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexMayol%2Flocalit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AlexMayol","download_url":"https://codeload.github.com/AlexMayol/localit/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242103812,"owners_count":20072354,"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":["hacktoberfest","javascript","library","localstorage","sessionstorage","typescript"],"created_at":"2025-03-05T20:53:33.920Z","updated_at":"2025-03-05T20:53:34.902Z","avatar_url":"https://github.com/AlexMayol.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# localit\n\nManage the Storage API in a simpler and more efficient way.\n\nIt allows you to store and retrieve key-value pairs, set expiration times for values, and listen for changes on specific keys. The library supports configuration options, event handling, and domain management.\n\n## Install\n\nYou can install `localit` using your preferred package manager.\n\n`npm i localit`\n`yarn add localit`\n`pnpm add localit`\n\n## Usage\n\nTo use `localit` in your project, import the `localit` object from the library:\n\n```js\nimport { localit } from \"localit\";\n```\n\nThe localit object provides various methods for interacting with `Storage`:\n\n### Configuration\n\n`config({ domain, type })`\nSets the default configuration for storing data. The config method accepts a configuration object with the following optional properties:\n\n- `domain`: The name of the domain that will prefix all stored keys. If not provided, no domain prefix will be used.\n- `type`: The type of storage to use. It can be either `localStorage` or `sessionStorage`. The default value is `localStorage`.\n\n```js\nlocalit.config({\n  domain: \"mydomain\",\n  type: \"localStorage\",\n});\n```\n\n### Storing and Retrieving Values\n\n`localit`'s main goal is to wrap the native `Storage` API available in the browser. It provides a simpler and more efficient way to store and retrieve values, without the need to use `JSON.stringify` and `JSON.parse`.\n\n#### `set(key, value, expirationTime?)`\n\nStores the given key-value pair in the storage. Additionally, an **expiration time** can be set for the value.\n\n- `key`: the key to store in the storage.\n- `value`: the value to store.\n- `expirationTime` _(optional)_: the duration for which the value will remain stored. It can be specified in seconds (\"_Xs_\"), minutes (\"_Xm_\"), hours (\"_Xh_\"), or days (\"_Xd_\"), where _X_ represents any number.\n\nExample:\n\n```js\nlocalit.set(\"myKey\", \"myValue\", \"1h\");\nlocalit.set(\"otherKey\", { oh: 8 }, \"300s\");\n```\n\n#### `get(key)`\n\nRetrieves the value associated with the given key from the storage. It uses the current domain.\n\n- `key`: the key used to retrieve the value.\n\nIf the value has expired due to the expiration date that was set, it will be removed from the storage and `null` will be returned.\n\nExample:\n\n```js\nconst value = localit.get(\"myKey\"); // value = 'myValue'\n```\n\n### Removing values\n\nThe other side of the coin is removing values from `Storage`. `localit` provides two methods for removing values: `remove` and `getAndRemove`.\n\n#### `remove(key)`\n\nRemoves the given key and its associated value from `Storage`. It uses the current domain.\n\n- `key`: the key to remove from `Storage`.\n\nExample:\n\n```js\nlocalit.remove(\"myKey\");\n```\n\n#### `getAndRemove(key)`\n\nRetrieves the value associated with the given key from `Storage` and then removes it. It uses the current domain.\n\n- `key`: the key to get the value of and then remove from `Storage`.\n\nExample:\n\n```js\nconst value = localit.getAndRemove(\"myKey\");\n```\n\n### Domain management\n\nDomains let you store data in different namespaces. This is useful when working in an app where multiple, independent teams contribute, avoiding having key duplicates - and, thus, overwriting data. The domain name is prepended to the key when storing values, but you don't need to specify it again when using the `get()` method.\n\n#### `setDomain(domainName)`\n\n- `domain`: the name of the domain that will prefix all the keys until changed again.\n\nExample:\n\n```js\nlocalit.setDomain(\"myNewDomain\");\n```\n\n#### `clearDomain(domain?)`\n\nRemoves all the stored values for the specified domain. If no domain is provided, it clears the values for the current domain.\n\nExample:\n\n`localit.clearDomain('myDomain')`\n\n#### `bust()`\n\nRemoves all the stored values in `Storage`, regardless of the current domain.\n\n```js\nlocalit.bust();\n```\n\n### Event Handling\n\nA very interesting feature of `localit` is the ability to listen for changes on specific keys. This is useful when you want to update the UI when a value changes, for example. [Please, note that this is different from the `storage` event.](https://developer.mozilla.org/en-US/docs/Web/API/Window/storage_event)\n\n`on(key, callback)`\nAdds a new listener to track changes on a specific key.\n\n- `key`: the key to attach the callback.\n- `callback`: the callback function to be called when the key is emitted by `localit`.\n\nExample:\n\n```js\nlocalit.on(\"myKey\", (value) =\u003e {\n  console.log(`Value changed: ${value}`);\n});\n\nlocalit.set(\"myKey\", \"newValue\"); // console.log: Value changed: 'newValue'\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexmayol%2Flocalit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falexmayol%2Flocalit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexmayol%2Flocalit/lists"}