{"id":15388229,"url":"https://github.com/georapbox/web-storage","last_synced_at":"2025-04-15T18:30:41.969Z","repository":{"id":33861729,"uuid":"161748622","full_name":"georapbox/web-storage","owner":"georapbox","description":"WebStorage is a JavaScript library that improves the way you work with localStorage or sessionStorage","archived":false,"fork":false,"pushed_at":"2023-01-06T01:37:36.000Z","size":1147,"stargazers_count":10,"open_issues_count":1,"forks_count":4,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-29T00:33:56.672Z","etag":null,"topics":["dom-storage","localstorage","offline-storage","sessionstorage","storage","web-storage"],"latest_commit_sha":null,"homepage":"","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/georapbox.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2018-12-14T07:33:47.000Z","updated_at":"2023-07-13T07:27:02.000Z","dependencies_parsed_at":"2023-01-15T03:01:23.774Z","dependency_job_id":null,"html_url":"https://github.com/georapbox/web-storage","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/georapbox%2Fweb-storage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/georapbox%2Fweb-storage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/georapbox%2Fweb-storage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/georapbox%2Fweb-storage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/georapbox","download_url":"https://codeload.github.com/georapbox/web-storage/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249128881,"owners_count":21217236,"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":["dom-storage","localstorage","offline-storage","sessionstorage","storage","web-storage"],"created_at":"2024-10-01T14:56:02.709Z","updated_at":"2025-04-15T18:30:41.637Z","avatar_url":"https://github.com/georapbox.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![build](https://github.com/georapbox/web-storage/workflows/build/badge.svg)\n[![npm version](https://img.shields.io/npm/v/@georapbox/web-storage.svg)](https://www.npmjs.com/package/@georapbox/web-storage)\n[![Coverage Status](https://coveralls.io/repos/github/georapbox/web-storage/badge.svg?branch=master)](https://coveralls.io/github/georapbox/web-storage?branch=master)\n[![npm license](https://img.shields.io/npm/l/@georapbox/web-storage.svg)](https://www.npmjs.com/package/@georapbox/web-storage)\n\n# WebStorage\n\nWebStorage is a JavaScript library that improves the way you work with `localStorage` or `sessionStorage` by using a simple, `localStorage`-like API. It allows developers to store many types of data instead of just strings.\n\nThe purpose of this library is to allow the user to manipulate data to `localStorage` or `sessionStorage` accordingly using a namespace (default is `'web-storages/'`) as a prefix for each item's key. This is by design in order to avoid potential conflicts with other key/value pairs that are probably already saved to storage. For example, if the key prefix we provided is `'my-app/'`, calling `clear()` will remove only the items with key prefix `'my-app/'`. The same principle applies to all available API methods of the library.\n\n## Install\n\n```sh\n$ npm install --save @georapbox/web-storage\n```\n\n## Usage\n\nThe library is exported in UMD, CommonJS, and ESM formats. You can import it the following ways:\n\n### Using ESM import statement\n\n```js\nimport WebStorage from '@georapbox/web-storage';\n```\n\n### Using CommonJS require statement\n\n```js\nconst WebStorage = require('@georapbox/web-storage');\n\n// If you use a bundler like Webpack, you may need to import it the following way \n// as it might try to use the ESM module instead of the CommonJS.\nconst WebStorage = require('@georapbox/web-storage').default; \n```\n\n### Old school browser global\n```html\n\u003cscript src=\"https://unpkg.com/@georapbox/web-storage\"\u003e\u003c/script\u003e\n```\n\n## API\n## Static methods\n\n### WebStorage.createInstance(options = {})\n\nCreates a new instance of the WebStorage. The following options can be set:\n\n| Option | Type | Default | Description |\n| ------ | ---- | ------- | ----------- |\n| **driver** | `String` | \"localStorage\" | The preferred driver to use. Use one between \"localStorage\" or \"sessionStorage\". |\n| **keyPrefix\u003csup\u003e1\u003c/sup\u003e** | `String` | \"web-storage/\" | The prefix for all keys stored in the offline storage. The value provided is trimmed (both left and right) internally to avoid potential user mistakes. |\n\n**\u003csup\u003e1\u003c/sup\u003e** *`keyPrefix` needs to be declared only when creating an instance of `WebStorage`. Afterwards, when using any of the API methods that accept `key` as argument, we just use the key to refer to the item we want to manipulate.*\n\n**Example**\n\n```js\nconst myStore = WebStorage.createInstance({\n  driver: 'sessionStorage',\n  keyPrefix: 'my-storage/'\n});\n```\n\n### WebStorage.isAvailable(storageType)\n\nCheck if `storageType` is supported and is available.\nStorage might be unavailable due to no browser support or due to being full or due to browser privacy settings.\n\n**Kind**: static method of `WebStorage`  \n**Returns**: `Boolean` - Returns `true` if Storage available; otherwise `false`\n\n| Param | Type | Description |\n| ----- | ---- | ----------- |\n| storageType | `String` | The storage type; available values \"localStorage\" or \"sessionStorage\" |\n\n**Usage**\n\n```js\nWebStorage.isAvailable('localStorage');\n```\n\n## Instance methods\n\n### getItem(key [, onErrorCallback])\n\nGets a saved item from storage by its key.\n\n**Kind**: instance method of `WebStorage`  \n**Throws:** `TypeError` if `key` is not a string  \n**Returns:** `*` - Returns the retrieved value if found or `null` if value not found or operation has failed due to error\n\n| Param | Type | Default | Description |\n| ----- | ---- | ------- | ----------- |\n| key | `String` |  |The property name of the saved item |\n| [onErrorCallback] | `Function` | `() =\u003e {}` | Callback function to be executed if there were any errors |\n\n**Usage**\n\n```js\nmyStore.getItem('somekey', error =\u003e {\n  // This code runs if there were any errors\n  console.error(error);\n});\n```\n\n### setItem(key, value [, onErrorCallback])\n\nSaves an item to storage. You can store items of any of the following data types as long as data can be serialized to JSON.\n\n- String\n- Number\n- Array\n- Object\n\n**Kind**: instance method of `WebStorage`  \n**Throws:** `TypeError` if `key` is not a string  \n**Returns:** `undefined`\n\n| Param | Type | Default | Description |\n| ----- | ---- | ------- | ----------- |\n| key | `String` |  | The property name of the item to save |\n| value | `*` |  | The item to save to the selected storage. |\n| [onErrorCallback] | `Function` | `() =\u003e {}` | Callback function to be executed if there were any errors |\n\n**Usage**\n\n```js\nmyStore.setItem('somekey', { foo: 'bar' }, error =\u003e {\n  // This code runs if there were any errors\n  console.error(error);\n});\n```\n\n### removeItem(key [, onErrorCallback])\n\nRemoves the item for the specific key from the storage.\n\n**Kind**: instance method of `WebStorage`  \n**Throws:** `TypeError` if `key` is not a string  \n**Returns:** `undefined`\n\n| Param | Type | Default | Description |\n| ----- | ---- | ------- | ----------- |\n| key | `String` |  | The property name of the item to remove |\n| [onErrorCallback] | `Function` | `() =\u003e {}` | Callback function to be executed if there were any errors |\n\n**Usage**\n\n```js\nmyStore.removeItem('somekey', error =\u003e {\n  // This code runs if there were any errors\n  console.error(error);\n});\n```\n\n### clear([onErrorCallback])\n\nRemoves all saved items from storage.\n\n**Kind**: instance method of `WebStorage`  \n**Returns:** `undefined`\n\n| Param | Type | Default | Description |\n| ----- | ---- | ------- | ----------- |\n| [onErrorCallback] | `Function` | `() =\u003e {}` | Callback function to be executed if there were any errors |\n\n**Usage**\n\n```js\nmyStore.clear(error =\u003e {\n  // This code runs if there were any errors\n  console.error(error);\n});\n```\n\n### keys([onErrorCallback])\n\nGets the list of all keys in the storage for a specific datastore.\n\n**Kind**: instance method of `WebStorage`  \n**Returns:** `Array|undefined` - Returns an array of all the keys that belong to a specific datastore. If any error occurs, returns `undefined`.\n\n| Param | Type | Default | Description |\n| ----- | ---- | ------- | ----------- |\n| [onErrorCallback] | `Function` | `() =\u003e {}` | Callback function to be executed if there were any errors |\n\n**Usage**\n\n```js\nmyStore.keys(error =\u003e {\n  // This code runs if there were any errors\n  console.error(error);\n});\n```\n\n### length([onErrorCallback])\n\nGets the number of items saved in a specific datastore.\n\n**Kind**: instance method of `WebStorage`  \n**Returns:** `Number|undefined` - Returns the number of items for a specific datastore. If any error occurs, returns `undefined`.\n\n| Param | Type | Default | Description |\n| ----- | ---- | ------- | ----------- |\n| [onErrorCallback] | `Function` | `() =\u003e {}` | Callback function to be executed if there were any errors |\n\n**Usage**\n\n```js\nmyStore.length(error =\u003e {\n  // This code runs if there were any errors\n  console.error(error);\n});\n```\n\n### iterate(iteratorCallback [, onErrorCallback])\n\nIterate over all value/key pairs in datastore.\n\n**Kind**: instance method of `WebStorage`  \n**Throws:** `TypeError` if `iteratorCallback` is not a function  \n**Returns:** `undefined`\n\n| Param | Type | Default | Description |\n| ----- | ---- | ------- | ----------- |\n| iteratorCallback | `Function` |  | A callabck function to be executed for each iteration |\n| [onErrorCallback] | `Function` | `() =\u003e {}` | Callback function to be executed if there were any errors |\n\n`iteratorCallback` is called once for each pair, with the following arguments:\n\n| Param | Type | Description |\n| ----- | ---- | ----------- |\n| value | `*` | The value of the saved item. |\n| key | `String` | The key of the saved item. |\n\n**Usage**\n\n```js\nmyStore.iterate((value, key) =\u003e {\n  // Resulting key/value pair; this callback will be executed for every item in the datastore.\n  console.log(value, key);\n}, error =\u003e {\n  // This code runs if there were any errors\n  console.error(error);\n});\n```\n\n## Full usage example\n\n```js\n//\n// NOTE: The example below assumes that we begin with empty localStorage.\n//\n\n// Create a new instance of WebStorage using localStorage for driver (default) and 'my-store/' for prefixing keys\nconst webStorage = WebStorage.createInstance({\n  keyPrefix: 'my-store/'\n});\n\nconst onError = error =\u003e console.error(error);\n\nwebStorage.setItem('user1', { id: 1, name: 'John Doe' }, onError);\n\nwebStorage.setItem('user2', { id: 2, name: 'Tim Smith' }, onError);\n\nlocalStorage.setItem('user3', JSON.stringify({ id: 3, name: 'Alice Cooper' }));\n\nwebStorage.getItem('user1'); // -\u003e { id: 1, name: 'John Doe' }\n\nwebStorage.getItem('user2'); // -\u003e { id: 2, name: 'Tim Smith' }\n\nwebStorage.getItem('user3'); // -\u003e null\n\nwebStorage.keys();  // -\u003e ['user1', 'user2']\n\nwebStorage.length(); // -\u003e 2\n\nlocalStorage.length(); // -\u003e 3\n\nwebStorage.iterate((value, key) =\u003e {\n  console.log(value, '-', key);\n  // -\u003e { id: 1, name: 'John Doe' } - 'user1'\n  // -\u003e { id: 2, name: 'Tim Smith' } - 'user2'\n});\n\nwebStorage.removeItem('user1');\n\nwebStorage.getItem('user1'); // -\u003e null\n\nwebStorage.clear();\n\nwebStorage.keys(); // -\u003e []\n\nwebStorage.length(); // -\u003e 0\n\nlocalStorage.length(); // -\u003e 1\n```\n\n## For development\n\n### Build for development\n\n```sh\n$ npm run dev\n```\n\nBuilds the library for development and watches for any changes.\n\n### Build for production\n\n```sh\n$ npm run build\n```\n\nBuilds the library for production; creates library bundles (`UMD`, `ESM`, `CommonJS`) under the `dist/` directory.\n\n### Test\n\n```sh\n$ npm test\n```\n\n## Changelog\n\nFor API updates and breaking changes, check the [CHANGELOG](https://github.com/georapbox/web-storage/blob/master/CHANGELOG.md).\n\n## License\n\n[The MIT License (MIT)](https://georapbox.mit-license.org/@2018)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgeorapbox%2Fweb-storage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgeorapbox%2Fweb-storage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgeorapbox%2Fweb-storage/lists"}