{"id":13708004,"url":"https://github.com/julienetie/db64","last_synced_at":"2025-05-16T06:07:43.034Z","repository":{"id":213406293,"uuid":"734045195","full_name":"julienetie/db64","owner":"julienetie","description":"A Practical IndexedDB API","archived":false,"fork":false,"pushed_at":"2024-12-05T13:26:14.000Z","size":289,"stargazers_count":204,"open_issues_count":7,"forks_count":12,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-04-08T18:18:52.959Z","etag":null,"topics":["indexeddb","localstorage","persistent-storage","promises","vanilla-js"],"latest_commit_sha":null,"homepage":"https://julienetie.github.io/db64/examples/input-data/","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/julienetie.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}},"created_at":"2023-12-20T18:21:12.000Z","updated_at":"2025-03-19T09:19:42.000Z","dependencies_parsed_at":"2024-04-12T08:26:10.141Z","dependency_job_id":"31fcd17e-b92f-4e1b-8ffd-ebf608781e0d","html_url":"https://github.com/julienetie/db64","commit_stats":null,"previous_names":["julienetie/db64"],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/julienetie%2Fdb64","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/julienetie%2Fdb64/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/julienetie%2Fdb64/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/julienetie%2Fdb64/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/julienetie","download_url":"https://codeload.github.com/julienetie/db64/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254478193,"owners_count":22077676,"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":["indexeddb","localstorage","persistent-storage","promises","vanilla-js"],"created_at":"2024-08-02T22:01:52.740Z","updated_at":"2025-05-16T06:07:38.026Z","avatar_url":"https://github.com/julienetie.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"\n\u003cimg src=\"https://github.com/julienetie/db64/assets/7676299/ba8b9109-0c3d-4495-a67e-048b166ea4a1\" width=\"150\"\u003e\n\n# DB64\n\n## A Practical IndexedDB API\n\n### [Example](https://julienetie.github.io/db64/examples/input-data/)\n\nA more practical alternative to [localStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage). db64 supports [all major browsers](https://caniuse.com/indexeddb).  \n\n\n### db64\n- Promise based API\n- Set and get single or multiple entries\n- Delete single, multiple or all entries\n- No versioning \n- 2.91KB minified | 938 bytes _(brotli)_\n\nE.g.\n```javascript\nimport db64 from './db64.js'\n\ntry {\n  // First create a database with stores\n  await db64.create('Games', ['Super Nintendo', 'Gameboy'])\n\n  // Assign a variable for modifying a store\n  const snes = db64.use('Games', 'Super Nintendo')\n\n  // Set multiple entries into Super Nintendo\n  await snes.setEntries({ adventure: 'Mario World', rpg: 'Zelda', fighting: 'Street Fighter II' })\n\n  // Get multiple entries from Super Nintendo\n  await snes.getEntries(['adventure', 'fighting']) // { adventure: 'Mario Wrold', fighting: 'Street Fighter II' }\n\n  // Delete an existing db \n  await db64.delete('Games')\n...\n```\n_Launch an example using `npm run d`, then navigate to `./examples`_\n\n### Why IndexedDB, why not localStorage?\n- Better performance\n- Asynchronous (localStorage is blocking)\n- Larger storage quota (localStorage is capped at 5MB)\n- Reliable (no type coercion)\n- Uses the [structuredClone](https://developer.mozilla.org/en-US/docs/Web/API/structuredClone) algorithm\n\n### Practical challenges when using IndexedDB\n- It's event driven, without promises\n- It was designed to encourage versioning, which is not necessary for the majority of projects\n- The API is considered _low level_ and can be challenging as a replacement for localStorage\n- Removing databases and stores is not straightforward nor necessary, and usually requires versioning\n\n\u003e **_Just give me the builds_**\n\u003e - `git clone git@github.com:julienetie/db64.git`\n\u003e - `cd db64 \u0026\u0026 npm i`\n\u003e - `npm run prepublishOnly`\n\n**Install**\n```\nnpm i db64\n```\n\n**Import**\n```javascript\nimport db64 from 'db64.js'    // ES (native)\n// or\nimport db64 from 'db64'       // ES\n// or\nconst db64 = require('db64')  // CommonJS\n```\n\n**Create a database with stores**  _(string, array, string)_\n```javascript \nawait db64.create('game-consoles', ['n64', 'ps5', 'dreamcast', 'xbox-360'])\n// or\nawait db64.create(..., ..., 'disable-delete')\n```\nBy default, if the database to create exists but dosn't have the expected stores, it will be deleted before being re-created.\nThis can be disabled by using the `'disable-delete'` string.\n\n**Check if a database has a store**  _(string, string | array)_\n```javascript \nconst hasN64 = await db64.has('game-consoles', 'n64')\n// or\nconst hasStores = await db64.has('game-consoles', ['n64', 'dreamcast', 'ps5'])\n```\n\n**Use a store**  _(string, string)_\n```javascript \nconst n64 = db64.use('game-consoles', 'n64')\n```\n\n**Set an entry** _(IDB type, IDB type)_ _See [structured clone algorithm](https://developer.mozilla.org/en/US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm) for supported types_\n```javascript\nawait n64.set(5, 'Super Mario 64')\n```\n**Set multiple entries** _(object | array)_\n```javascript\nawait n64.setEntries({fps: 'GoldenEye 007', space: 'Star Fox 64', adventure: 'Banjo-Kazooie'})\nawait n64.setEntries(['Wave Race 64', 'The Legend of Zelda'])\n```\n\n**Get an entry** _(IDB type)_\n```javascript\nconst fps = await n64.get('fps') // GoldenEye 007\n```\n\n**Get multiple entries** _(object | array)_\n```javascript\nconst rareware = await n64.getEntries(['fps', 'adventure', 5]) // {fps: 'GoldenEye 007', adventure: 'Banjo-Kazooie', 0: 'Super Mario 64'}\n```\n**Delete an entry** _(IDB type | array)_\n```javascript\nawait n64.delete(1)  // Deletes 'The Legend of Zelda'\n```\n\n**Delete multiple entries**\n```javascript\nawait n64.delete(['adventure', 0])  // Deletes 'Banjo-Kazooie' and 'Super Mario 64'\n```\n\n**Clear a store** _(string, string)_\n```javascript\nawait db64.clear('game-consoles', 'n64') // All data in n64 is deleted\n```\n\n**Delete a DB** _(string)_\n```javascript\nawait db64.delete('game-consoles') // game-consoles is deleted\n```\n\n### Why db64 opts out of deleting object stores\nWe are avoiding versioning to keep your life simple. Deleting an existing object stores in IndexedDB triggers a version change. _(Whilst compaction may optimise, it doesn't ensure the removal of unwanted data)_\n\nHere's the db64 workflow:\n\n1. Initialise by creating a DB with stores or multiple DBs with stores.\n    - _By design, you won't be able to add stores to an existing DB later, unless you delete the DB in question_\n\n2. Use a DB.\n    - _You can make multiple transactions concurrently for multiple DBs, or stores_\n\n3. Set, get and clear data.\n\n4. **Manage the lifecycle of DB deletion and re-creation**:\n    - _When data cannot be retrieved from the user's IndexedDB_\n    - _When there's an error, e.g.:_\n      - _Data corruption_\n      - _Quota exceeded_\n      - _General errors_\n    - _**When in the future you decide to add more stores at initialisation**_\n    - _When you want to remove stores, especially for data protection_\n\nIt's important to consider step 4, if not you may leave users stuck because everything will look fine on your computer.\nStep 4 isn't specific to IndexedDB, it mostly applies to _localStorage_. It's the same for all persistent storage on all platforms. Your application is at risk of breaking if you decide to change the persistent data structure or add to the structure in the future without preemptively managing common user cases.\n\n```javascript\n// An exhaustive list for handling errors in db64:\nswitch (e.name) {\n    case 'NotFoundError':\n    // The operation failed because the requested database object could not be found.\n    case 'Db64MissingStore':\n    /**\n      * An anticipated NotFoundError. Manage both cases together.\n      *\n      * You will likely need to re-create your database here with necessary stores \n      * and re-populate with existing data if necessary. \n      */ \n        break\n    case 'AbortError':\n        // A request was aborted.\n        break\n    case 'SecurityError':\n        // Handle security error \n        break\n    case 'DataError':\n        // Data provided to an operation does not meet requirements.\n        break\n    case 'TransactionInactiveError':\n        // A request was placed against a transaction which is currently not active or has been finished.\n        break\n    case 'InvalidStateError':\n        // The object is in an invalid state.\n        break\n    case 'ConstraintError':\n        // A mutation operation in the transaction failed because a constraint was not satisfied.\n        break\n    case 'SyntaxError':\n        // The keyPath argument contains an invalid key path.\n        break\n    case 'QuotaExceededError':\n        // The operation failed because there was not enough remaining storage space, or the storage quota was reached and the user declined to provide more space to the database.\n        break\n    case 'ReadOnlyError':\n        // The mutating operation was attempted in a read-only transaction.\n        break\n    case 'UnknownError':\n        // The operation failed for reasons unrelated to the database itself and not covered by any other errors.\n        break\n}\n```\n\nIf you do require versioning consider using [idb](https://github.com/jakearchibald/idb). **If you're not building a progressive web app (PWA) you probably don't need versioning**.\n\n### Contributors\nDon't hesitate just contribute, it's a tiny library we will figure it out.\n\nIf you want to edit `./README.md` edit `./src/_readme.md` which will update `./README.md` when `node create-distribution.js` is called.\nThis is to keep the minified size accurate.\n\n---\nMIT © Julien Etienne 2024\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjulienetie%2Fdb64","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjulienetie%2Fdb64","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjulienetie%2Fdb64/lists"}