{ "manifest": { "name": "idb", "version": "7.1.1", "description": "A small wrapper that makes IndexedDB usable", "main": "./build/index.cjs", "module": "./build/index.js", "types": "./build/index.d.ts", "exports": { ".": { "types": "./build/index.d.ts", "module": "./build/index.js", "import": "./build/index.js", "default": "./build/index.cjs" }, "./with-async-ittr": { "types": "./with-async-ittr.d.ts", "module": "./with-async-ittr.js", "import": "./with-async-ittr.js", "default": "./with-async-ittr.cjs" }, "./build/*": "./build/*", "./package.json": "./package.json" }, "files": [ "build/**", "with-*", "CHANGELOG.md" ], "type": "module", "scripts": { "build": "PRODUCTION=1 rollup -c && node --experimental-modules lib/size-report.mjs", "dev": "rollup -c --watch", "prepack": "npm run build" }, "repository": { "type": "git", "url": "git://github.com/jakearchibald/idb.git" }, "author": { "name": "Jake Archibald" }, "license": "ISC", "devDependencies": { "@rollup/plugin-commonjs": "^22.0.2", "@rollup/plugin-node-resolve": "^14.1.0", "@types/chai": "^4.3.3", "@types/estree": "^1.0.0", "@types/mocha": "^9.1.1", "chai": "^4.3.6", "conditional-type-checks": "^1.0.6", "del": "^7.0.0", "filesize": "^9.0.11", "glob": "^8.0.3", "mocha": "^10.0.0", "prettier": "^2.7.1", "rollup": "^2.79.0", "rollup-plugin-terser": "^7.0.2", "typescript": "^4.8.3" }, "_registry": "npm", "_loc": "/homez.1033/heliovt/.cache/yarn/v6/npm-idb-7.1.1-d910ded866d32c7ced9befc5bfdf36f572ced72b-integrity/node_modules/idb/package.json", "readmeFilename": "README.md", "readme": "# IndexedDB with usability.\n\nThis is a tiny (~1.06kB brotli'd) library that mostly mirrors the IndexedDB API, but with small improvements that make a big difference to usability.\n\n1. [Installation](#installation)\n1. [Changes](#changes)\n1. [Browser support](#browser-support)\n1. [API](#api)\n 1. [`openDB`](#opendb)\n 1. [`deleteDB`](#deletedb)\n 1. [`unwrap`](#unwrap)\n 1. [`wrap`](#wrap)\n 1. [General enhancements](#general-enhancements)\n 1. [`IDBDatabase` enhancements](#idbdatabase-enhancements)\n 1. [`IDBTransaction` enhancements](#idbtransaction-enhancements)\n 1. [`IDBCursor` enhancements](#idbcursor-enhancements)\n 1. [Async iterators](#async-iterators)\n1. [Examples](#examples)\n1. [TypeScript](#typescript)\n\n# Installation\n\n## Using npm\n\n```sh\nnpm install idb\n```\n\nThen, assuming you're using a module-compatible system (like webpack, Rollup etc):\n\n```js\nimport { openDB, deleteDB, wrap, unwrap } from 'idb';\n\nasync function doDatabaseStuff() {\n const db = await openDB(…);\n}\n```\n\n## Directly in a browser\n\n### Using the modules method directly via jsdelivr:\n\n```html\n\n```\n\n### Using external script reference\n\n```html\n\n\n```\n\nA global, `idb`, will be created, containing all exports of the module version.\n\n# Changes\n\n[See details of (potentially) breaking changes](CHANGELOG.md).\n\n# Browser support\n\nThis library targets modern browsers, as in Chrome, Firefox, Safari, and other browsers that use those engines, such as Edge. IE is not supported.\n\nIf you want to target much older versions of those browsers, you can transpile the library using something like [Babel](https://babeljs.io/). You can't transpile the library for IE, as it relies on a proper implementation of [JavaScript proxies](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy).\n\n# API\n\n## `openDB`\n\nThis method opens a database, and returns a promise for an enhanced [`IDBDatabase`](https://w3c.github.io/IndexedDB/#database-interface).\n\n```js\nconst db = await openDB(name, version, {\n upgrade(db, oldVersion, newVersion, transaction, event) {\n // …\n },\n blocked(currentVersion, blockedVersion, event) {\n // …\n },\n blocking(currentVersion, blockedVersion, event) {\n // …\n },\n terminated() {\n // …\n },\n});\n```\n\n- `name`: Name of the database.\n- `version` (optional): Schema version, or `undefined` to open the current version.\n- `upgrade` (optional): Called if this version of the database has never been opened before. Use it to specify the schema for the database. This is similar to the [`upgradeneeded` event](https://developer.mozilla.org/en-US/docs/Web/API/IDBOpenDBRequest/upgradeneeded_event) in plain IndexedDB.\n - `db`: An enhanced `IDBDatabase`.\n - `oldVersion`: Last version of the database opened by the user.\n - `newVersion`: Whatever new version you provided.\n - `transaction`: An enhanced transaction for this upgrade. This is useful if you need to get data from other stores as part of a migration.\n - `event`: The event object for the associated `upgradeneeded` event.\n- `blocked` (optional): Called if there are older versions of the database open on the origin, so this version cannot open. This is similar to the [`blocked` event](https://developer.mozilla.org/en-US/docs/Web/API/IDBOpenDBRequest/blocked_event) in plain IndexedDB.\n - `currentVersion`: Version of the database that's blocking this one.\n - `blockedVersion`: The version of the database being blocked (whatever version you provided to `openDB`).\n - `event`: The event object for the associated `blocked` event.\n- `blocking` (optional): Called if this connection is blocking a future version of the database from opening. This is similar to the [`versionchange` event](https://developer.mozilla.org/en-US/docs/Web/API/IDBDatabase/versionchange_event) in plain IndexedDB.\n - `currentVersion`: Version of the open database (whatever version you provided to `openDB`).\n - `blockedVersion`: The version of the database that's being blocked.\n - `event`: The event object for the associated `versionchange` event.\n- `terminated` (optional): Called if the browser abnormally terminates the connection, but not on regular closures like calling `db.close()`. This is similar to the [`close` event](https://developer.mozilla.org/en-US/docs/Web/API/IDBDatabase/close_event) in plain IndexedDB.\n\n## `deleteDB`\n\nDeletes a database.\n\n```js\nawait deleteDB(name, {\n blocked() {\n // …\n },\n});\n```\n\n- `name`: Name of the database.\n- `blocked` (optional): Called if the database already exists and there are open connections that don’t close in response to a versionchange event, the request will be blocked until they all close.\n - `currentVersion`: Version of the database that's blocking the delete operation.\n - `event`: The event object for the associated 'versionchange' event.\n\n## `unwrap`\n\nTakes an enhanced IndexedDB object and returns the plain unmodified one.\n\n```js\nconst unwrapped = unwrap(wrapped);\n```\n\nThis is useful if, for some reason, you want to drop back into plain IndexedDB. Promises will also be converted back into `IDBRequest` objects.\n\n## `wrap`\n\nTakes an IDB object and returns a version enhanced by this library.\n\n```js\nconst wrapped = wrap(unwrapped);\n```\n\nThis is useful if some third party code gives you an `IDBDatabase` object and you want it to have the features of this library.\n\nThis doesn't work with `IDBCursor`, [due to missing primitives](https://github.com/w3c/IndexedDB/issues/255). Also, if you wrap an `IDBTransaction`, `tx.store` and `tx.objectStoreNames` won't work in Edge. To avoid these issues, wrap the `IDBDatabase` object, and use the wrapped object to create a new transaction.\n\n## General enhancements\n\nOnce you've opened the database the API is the same as IndexedDB, except for a few changes to make things easier.\n\nFirstly, any method that usually returns an `IDBRequest` object will now return a promise for the result.\n\n```js\nconst store = db.transaction(storeName).objectStore(storeName);\nconst value = await store.get(key);\n```\n\n### Promises & throwing\n\nThe library turns all `IDBRequest` objects into promises, but it doesn't know in advance which methods may return promises.\n\nAs a result, methods such as `store.put` may throw instead of returning a promise.\n\nIf you're using async functions, there's no observable difference.\n\n### Transaction lifetime\n\nTL;DR: **Do not `await` other things between the start and end of your transaction**, otherwise the transaction will close before you're done.\n\nAn IDB transaction auto-closes if it doesn't have anything left do once microtasks have been processed. As a result, this works fine:\n\n```js\nconst tx = db.transaction('keyval', 'readwrite');\nconst store = tx.objectStore('keyval');\nconst val = (await store.get('counter')) || 0;\nawait store.put(val + 1, 'counter');\nawait tx.done;\n```\n\nBut this doesn't:\n\n```js\nconst tx = db.transaction('keyval', 'readwrite');\nconst store = tx.objectStore('keyval');\nconst val = (await store.get('counter')) || 0;\n// This is where things go wrong:\nconst newVal = await fetch('/increment?val=' + val);\n// And this throws an error:\nawait store.put(newVal, 'counter');\nawait tx.done;\n```\n\nIn this case, the transaction closes while the browser is fetching, so `store.put` fails.\n\n## `IDBDatabase` enhancements\n\n### Shortcuts to get/set from an object store\n\nIt's common to create a transaction for a single action, so helper methods are included for this:\n\n```js\n// Get a value from a store:\nconst value = await db.get(storeName, key);\n// Set a value in a store:\nawait db.put(storeName, value, key);\n```\n\nThe shortcuts are: `get`, `getKey`, `getAll`, `getAllKeys`, `count`, `put`, `add`, `delete`, and `clear`. Each method takes a `storeName` argument, the name of the object store, and the rest of the arguments are the same as the equivalent `IDBObjectStore` method.\n\n### Shortcuts to get from an index\n\nThe shortcuts are: `getFromIndex`, `getKeyFromIndex`, `getAllFromIndex`, `getAllKeysFromIndex`, and `countFromIndex`.\n\n```js\n// Get a value from an index:\nconst value = await db.getFromIndex(storeName, indexName, key);\n```\n\nEach method takes `storeName` and `indexName` arguments, followed by the rest of the arguments from the equivalent `IDBIndex` method.\n\n## `IDBTransaction` enhancements\n\n### `tx.store`\n\nIf a transaction involves a single store, the `store` property will reference that store.\n\n```js\nconst tx = db.transaction('whatever');\nconst store = tx.store;\n```\n\nIf a transaction involves multiple stores, `tx.store` is undefined, you need to use `tx.objectStore(storeName)` to get the stores.\n\n### `tx.done`\n\nTransactions have a `.done` promise which resolves when the transaction completes successfully, and otherwise rejects with the [transaction error](https://developer.mozilla.org/en-US/docs/Web/API/IDBTransaction/error).\n\n```js\nconst tx = db.transaction(storeName, 'readwrite');\nawait Promise.all([\n tx.store.put('bar', 'foo'),\n tx.store.put('world', 'hello'),\n tx.done,\n]);\n```\n\nIf you're writing to the database, `tx.done` is the signal that everything was successfully committed to the database. However, it's still beneficial to await the individual operations, as you'll see the error that caused the transaction to fail.\n\n## `IDBCursor` enhancements\n\nCursor advance methods (`advance`, `continue`, `continuePrimaryKey`) return a promise for the cursor, or null if there are no further values to provide.\n\n```js\nlet cursor = await db.transaction(storeName).store.openCursor();\n\nwhile (cursor) {\n console.log(cursor.key, cursor.value);\n cursor = await cursor.continue();\n}\n```\n\n## Async iterators\n\nAsync iterator support isn't included by default (Edge doesn't support them). To include them, import `idb/with-async-ittr` instead of `idb` (this increases the library size to ~1.29kB brotli'd):\n\n```js\nimport { openDB } from 'idb/with-async-ittr';\n```\n\nOr `https://cdn.jsdelivr.net/npm/idb@7/build/umd-with-async-ittr.js` if you're using the non-module version.\n\nNow you can iterate over stores, indexes, and cursors:\n\n```js\nconst tx = db.transaction(storeName);\n\nfor await (const cursor of tx.store) {\n // …\n}\n```\n\nEach yielded object is an `IDBCursor`. You can optionally use the advance methods to skip items (within an async iterator they return void):\n\n```js\nconst tx = db.transaction(storeName);\n\nfor await (const cursor of tx.store) {\n console.log(cursor.value);\n // Skip the next item\n cursor.advance(2);\n}\n```\n\nIf you don't manually advance the cursor, `cursor.continue()` is called for you.\n\nStores and indexes also have an `iterate` method which has the same signature as `openCursor`, but returns an async iterator:\n\n```js\nconst index = db.transaction('books').store.index('author');\n\nfor await (const cursor of index.iterate('Douglas Adams')) {\n console.log(cursor.value);\n}\n```\n\n# Examples\n\n## Keyval store\n\nThis is very similar to `localStorage`, but async. If this is _all_ you need, you may be interested in [idb-keyval](https://www.npmjs.com/package/idb-keyval). You can always upgrade to this library later.\n\n```js\nimport { openDB } from 'idb';\n\nconst dbPromise = openDB('keyval-store', 1, {\n upgrade(db) {\n db.createObjectStore('keyval');\n },\n});\n\nexport async function get(key) {\n return (await dbPromise).get('keyval', key);\n}\nexport async function set(key, val) {\n return (await dbPromise).put('keyval', val, key);\n}\nexport async function del(key) {\n return (await dbPromise).delete('keyval', key);\n}\nexport async function clear() {\n return (await dbPromise).clear('keyval');\n}\nexport async function keys() {\n return (await dbPromise).getAllKeys('keyval');\n}\n```\n\n## Article store\n\n```js\nimport { openDB } from 'idb/with-async-ittr.js';\n\nasync function demo() {\n const db = await openDB('Articles', 1, {\n upgrade(db) {\n // Create a store of objects\n const store = db.createObjectStore('articles', {\n // The 'id' property of the object will be the key.\n keyPath: 'id',\n // If it isn't explicitly set, create a value by auto incrementing.\n autoIncrement: true,\n });\n // Create an index on the 'date' property of the objects.\n store.createIndex('date', 'date');\n },\n });\n\n // Add an article:\n await db.add('articles', {\n title: 'Article 1',\n date: new Date('2019-01-01'),\n body: '…',\n });\n\n // Add multiple articles in one transaction:\n {\n const tx = db.transaction('articles', 'readwrite');\n await Promise.all([\n tx.store.add({\n title: 'Article 2',\n date: new Date('2019-01-01'),\n body: '…',\n }),\n tx.store.add({\n title: 'Article 3',\n date: new Date('2019-01-02'),\n body: '…',\n }),\n tx.done,\n ]);\n }\n\n // Get all the articles in date order:\n console.log(await db.getAllFromIndex('articles', 'date'));\n\n // Add 'And, happy new year!' to all articles on 2019-01-01:\n {\n const tx = db.transaction('articles', 'readwrite');\n const index = tx.store.index('date');\n\n for await (const cursor of index.iterate(new Date('2019-01-01'))) {\n const article = { ...cursor.value };\n article.body += ' And, happy new year!';\n cursor.update(article);\n }\n\n await tx.done;\n }\n}\n```\n\n# TypeScript\n\nThis library is fully typed, and you can improve things by providing types for your database:\n\n```ts\nimport { openDB, DBSchema } from 'idb';\n\ninterface MyDB extends DBSchema {\n 'favourite-number': {\n key: string;\n value: number;\n };\n products: {\n value: {\n name: string;\n price: number;\n productCode: string;\n };\n key: string;\n indexes: { 'by-price': number };\n };\n}\n\nasync function demo() {\n const db = await openDB('my-db', 1, {\n upgrade(db) {\n db.createObjectStore('favourite-number');\n\n const productStore = db.createObjectStore('products', {\n keyPath: 'productCode',\n });\n productStore.createIndex('by-price', 'price');\n },\n });\n\n // This works\n await db.put('favourite-number', 7, 'Jen');\n // This fails at compile time, as the 'favourite-number' store expects a number.\n await db.put('favourite-number', 'Twelve', 'Jake');\n}\n```\n\nTo define types for your database, extend `DBSchema` with an interface where the keys are the names of your object stores.\n\nFor each value, provide an object where `value` is the type of values within the store, and `key` is the type of keys within the store.\n\nOptionally, `indexes` can contain a map of index names, to the type of key within that index.\n\nProvide this interface when calling `openDB`, and from then on your database will be strongly typed. This also allows your IDE to autocomplete the names of stores and indexes.\n\n## Opting out of types\n\nIf you call `openDB` without providing types, your database will use basic types. However, sometimes you'll need to interact with stores that aren't in your schema, perhaps during upgrades. In that case you can cast.\n\nLet's say we were renaming the 'favourite-number' store to 'fave-nums':\n\n```ts\nimport { openDB, DBSchema, IDBPDatabase } from 'idb';\n\ninterface MyDBV1 extends DBSchema {\n 'favourite-number': { key: string; value: number };\n}\n\ninterface MyDBV2 extends DBSchema {\n 'fave-num': { key: string; value: number };\n}\n\nconst db = await openDB('my-db', 2, {\n async upgrade(db, oldVersion) {\n // Cast a reference of the database to the old schema.\n const v1Db = db as unknown as IDBPDatabase;\n\n if (oldVersion < 1) {\n v1Db.createObjectStore('favourite-number');\n }\n if (oldVersion < 2) {\n const store = v1Db.createObjectStore('favourite-number');\n store.name = 'fave-num';\n }\n },\n});\n```\n\nYou can also cast to a typeless database by omitting the type, eg `db as IDBPDatabase`.\n\nNote: Types like `IDBPDatabase` are used by TypeScript only. The implementation uses proxies under the hood.\n\n# Developing\n\n```sh\nnpm run dev\n```\n\nThis will also perform type testing.\n\nTo test, navigate to `build/test/` in a browser. You'll need to set up a [basic web server](https://www.npmjs.com/package/serve) for this.\n", "licenseText": "ISC License (ISC)\nCopyright (c) 2016, Jake Archibald \n\nPermission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.\n" }, "artifacts": [], "remote": { "resolved": "https://registry.yarnpkg.com/idb/-/idb-7.1.1.tgz#d910ded866d32c7ced9befc5bfdf36f572ced72b", "type": "tarball", "reference": "https://registry.yarnpkg.com/idb/-/idb-7.1.1.tgz", "hash": "d910ded866d32c7ced9befc5bfdf36f572ced72b", "integrity": "sha512-gchesWBzyvGHRO9W8tzUWFDycow5gwjvFKfyV9FF32Y7F50yZMp7mP+T2mJIWFx49zicqyC4uefHM17o6xKIVQ==", "registry": "npm", "packageName": "idb", "cacheIntegrity": "sha512-gchesWBzyvGHRO9W8tzUWFDycow5gwjvFKfyV9FF32Y7F50yZMp7mP+T2mJIWFx49zicqyC4uefHM17o6xKIVQ== sha1-2RDe2GbTLHztm+/Fv9829XLO1ys=" }, "registry": "npm", "hash": "d910ded866d32c7ced9befc5bfdf36f572ced72b" }