{"id":20589967,"url":"https://github.com/doist/idbstorage","last_synced_at":"2025-10-05T02:23:41.570Z","repository":{"id":33784467,"uuid":"116388910","full_name":"Doist/IDBStorage","owner":"Doist","description":"IndexedDB as key-value storage","archived":false,"fork":false,"pushed_at":"2023-03-02T14:42:48.000Z","size":2568,"stargazers_count":8,"open_issues_count":14,"forks_count":2,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-04-13T00:20:03.244Z","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/Doist.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-01-05T13:40:10.000Z","updated_at":"2023-08-14T18:37:21.000Z","dependencies_parsed_at":"2024-11-16T07:33:19.875Z","dependency_job_id":"7b489a97-3d67-4102-9a02-884778fc59d1","html_url":"https://github.com/Doist/IDBStorage","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/Doist%2FIDBStorage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Doist%2FIDBStorage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Doist%2FIDBStorage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Doist%2FIDBStorage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Doist","download_url":"https://codeload.github.com/Doist/IDBStorage/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248969954,"owners_count":21191354,"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-16T07:33:11.279Z","updated_at":"2025-10-05T02:23:36.509Z","avatar_url":"https://github.com/Doist.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# IDBStorage\n\n[![Build Status](https://travis-ci.org/stkao05/IDBStorage.svg?branch=master)](https://travis-ci.org/stkao05/IDBStorage)\n\nIDBStorage is a key-value asynchronous storage that uses indexedDB as underlaying storage.\n\n[Why another key-val IndexedDB library?](https://github.com/Doist/IDBStorage#motivations)\n\n## Usage\n\n```js\nimport IDBStorage from 'idbstorage'\n\nconst storage = new IDBStorage()\n\nstorage.setItem('foo', 1).then((value) =\u003e {\n    console.log(value + ' has succesfully been stored')\n})\n```\n\n## Installation\n\n```\n$ npm install --save idbstorage\n```\n\n## API\n\n##### Constructor `new IDBStorage(config)`\n\nEach `IDBStorage` instance represents an individual database connection to a database (`IDBDatabase`).\nIn most scenarios, your app should only need to create one instance of `IDBStorage` and use it across the app.\n\n##### `setItem(key, value)`\n\n-   key: A key has an associated type which is one of: number, date, string, binary, or array ([ref](https://www.w3.org/TR/IndexedDB/#key-construct)).\n-   value: Any serializable object ([ref](https://www.w3.org/TR/2018/REC-IndexedDB-2-20180130/#value-construct)).\n\nReturn a Promise that resolves with `value` if data has successfully persisted; rejects with error otherwise.\n\n##### `getItem(key)`\n\nReturn a Promise that resolves with value associated with the key. If no value has been set with the `key`, the resolving value will be `undefined`; the returned Promise will be rejected with error when in case of indexedDB failure.\n\n##### `removeItem(key)`\n\nReturn a Promise that resolves (with nothing) when the item has been successfully removed; reject with error otherwise\n\n##### `clear()`\n\nRemove all key/value datas from the database.\n\nReturn a Promise that resolves (with no value) when operation succeeded and rejected with error otherwise.\n\n##### `deleteDatabase()`\n\nDelete the whole database; just like `clear()` but it would also remove the underlying indexedDB instance from the browser storage.\nReturn a Promise that resolves (with no value) when operation succeeded and rejected with error otherwise.\n\n## Motivations\n\nIDBStorage is created to address the following issues\n\n### Preserve Transaction Ordering\n\nIDBStorage makes sure the end result is consistent with the ordering of the operation calls.\n\nFor instance\n\n```js\nconst db = new IDBStorage()\nconst r1 = db.setItem('foo', 1)\nconst r2 = db.setItem('foo', 2)\nconst r3 = db.setItem('foo', 3)\n\nPromise.all([r1, r2, r3]).then(() =\u003e db.getItem('foo')) // should give you 3, always\n```\n\nSome libraries, such as [localForage](https://github.com/localForage/localForage), failed to provide such a guarantee due to the way it creates IndexedDB transaction. The library might give you correct result majority of the time, but there could be time where inconsistency could occur.\n\nFrom [W3C spec](https://www.w3.org/TR/2018/REC-IndexedDB-2-20180130/#transaction-construct):\n\n\u003e If multiple read/write transactions are attempting to access the same object store (i.e. if they have overlapping scope), the transaction that was created first must be the transaction which gets access to the object store first.\n\nOne common mistakes with IndexedDB library implementation is forget to preserve the same transactions creation ordering as library function calls.\n\n### Error Recovery\n\nUnlike other browser storage such as localStorage, IndexedDB has been observed to be less stable and is more likely to have errors. While most client libraries do provide basic handling of error (which usually just return the error back to the caller), most of them fail to provide error recovery mechanism, which is crucial in production setting.\n\nOne error scenarios that have been commonly observed but not usually been dealt with properly is handing of broken IndexedDB connections. IndexedDB connections could sometime be in an abnormal state (which is expected for any database system), and any operations will result in failure.\n\nIDBStorage provides a recovery mechanism that dealt with connection failure. When noticing an abnormality in the database connection, it will close the dysfunctional one and try to re-establish a new connection.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdoist%2Fidbstorage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdoist%2Fidbstorage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdoist%2Fidbstorage/lists"}