Repository: jakearchibald/idb
Branch: main
Commit: 77dd8bebf366
Files: 27
Total size: 151.4 KB
Directory structure:
gitextract_epojnbq1/
├── .github/
│ └── ISSUE_TEMPLATE/
│ ├── bug_report.md
│ └── feature_request.md
├── .gitignore
├── .prettierrc.json
├── CHANGELOG.md
├── LICENSE
├── README.md
├── generic-tsconfig.json
├── lib/
│ └── size-report.mjs
├── package.json
├── rollup.config.mjs
├── size-tests/
│ └── main.js
├── src/
│ ├── async-iterators.ts
│ ├── database-extras.ts
│ ├── entry.ts
│ ├── index.ts
│ ├── tsconfig.json
│ ├── util.ts
│ └── wrap-idb-value.ts
└── test/
├── index.html
├── index.ts
├── iterate.ts
├── main.ts
├── missing-types.d.ts
├── open.ts
├── tsconfig.json
└── utils.ts
================================================
FILE CONTENTS
================================================
================================================
FILE: .github/ISSUE_TEMPLATE/bug_report.md
================================================
---
name: Bug report
about: Create a report to help us improve
title: ''
labels: ''
assignees: ''
---
<!-- Bug reports without a minimal reproducible example will be closed (https://stackoverflow.com/help/minimal-reproducible-example). Ideally, the example should be accessible somewhere public, like jsbin, Glitch, jsfiddle, codepen etc etc -->
================================================
FILE: .github/ISSUE_TEMPLATE/feature_request.md
================================================
---
name: Feature request
about: Suggest an idea for this project
title: ''
labels: ''
assignees: ''
---
**Is your feature request related to a problem? Please describe.**
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
**Describe the solution you'd like**
A clear and concise description of what you want to happen.
================================================
FILE: .gitignore
================================================
node_modules
.ts-tmp
build
tmp
.idea
.vscode
================================================
FILE: .prettierrc.json
================================================
{
"singleQuote": true,
"trailingComma": "all"
}
================================================
FILE: CHANGELOG.md
================================================
# Breaking changes in 8.x
- Finally dropped support for old EdgeHTML engine.
- Dropped support for browsers that don't support [`cursor.request`](https://caniuse.com/mdn-api_idbcursor_request).
- Removed separate async iterators build. It's now one build with async iterator support.
# Breaking changes in 7.x
- No longer committing `build` to GitHub.
- Renamed files in dist.
- Added conditional exports.
- iife build is now a umd.
# Breaking changes in 6.x
Some TypeScript definitions changed so write-methods are missing from 'readonly' transactions. This might be backwards-incompatible with code that performs a lot of type wrangling.
# Breaking changes in 5.x
I moved some files around, so I bumped the major version for safety.
# Changes in 4.x
## Breaking changes
### Opening a database
```js
// Old 3.x way
import { openDb } from 'idb';
openDb('db-name', 1, (upgradeDb) => {
console.log(upgradeDb.oldVersion);
console.log(upgradeDb.transaction);
});
```
```js
// New 4.x way
import { openDB } from 'idb';
openDB('db-name', 1, {
upgrade(db, oldVersion, newVersion, transaction) {
console.log(oldVersion);
console.log(transaction);
},
});
```
- `openDb` and `deleteDb` were renamed `openDB` and `deleteDB` to be more consistent with DOM naming.
- The signature of `openDB` changed. The third parameter used to be the upgrade callback, it's now an option object which can include an `upgrade` method.
- There's no `UpgradeDB` anymore. You get the same database `openDB` resolves with. Versions numbers and the upgrade transaction are included as additional parameters.
### Promises & throwing
The library turns all `IDBRequest` objects into promises, but it doesn't know in advance which methods may return promises.
As a result, methods such as `store.put` may throw instead of returning a promise.
If you're using async functions, there isn't a difference.
### Other breaking changes
- `iterateCursor` and `iterateKeyCursor` have been removed. These existed to work around browsers microtask issues which have since been fixed. Async iterators provide similar functionality.
- All pseudo-private properties (those beginning with an underscore) are gone. Use `unwrap()` to get access to bare IDB objects.
- `transaction.complete` was renamed to `transaction.done` to be shorter and more consistent with the DOM.
- `getAll` is no longer polyfilled on indexes and stores.
- The library no longer officially supports IE11.
## New stuff
- The library now uses proxies, so objects will include everything from their plain-IDB equivalents.
- TypeScript support has massively improved, including the ability to provide types for your database.
- Optional support for async iterators, which makes handling cursors much easier.
- Database objects now have shortcuts for single actions (like `get`, `put`, `add`, `getAll` etc etc).
- For transactions that cover a single store `transaction.store` is a reference to that store.
- `openDB` lets you add callbacks for when your database is blocking another connection, or when you're blocked by another connection.
# Changes in 3.x
The library became a module.
```js
// Old 2.x way:
import idb from 'idb';
idb.open(…);
idb.delete(…);
// 3.x way:
import { openDb, deleteDb } from 'idb';
openDb(…);
deleteDb(…);
```
================================================
FILE: LICENSE
================================================
ISC License (ISC)
Copyright (c) 2016, Jake Archibald <jaffathecake@gmail.com>
Permission 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.
THE 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.
================================================
FILE: README.md
================================================
# IndexedDB with usability.
This is a tiny (~1.19kB brotli'd) library that mostly mirrors the IndexedDB API, but with small improvements that make a big difference to usability.
1. [Installation](#installation)
1. [Changes](#changes)
1. [Browser support](#browser-support)
1. [API](#api)
1. [`openDB`](#opendb)
1. [`deleteDB`](#deletedb)
1. [`unwrap`](#unwrap)
1. [`wrap`](#wrap)
1. [General enhancements](#general-enhancements)
1. [`IDBDatabase` enhancements](#idbdatabase-enhancements)
1. [`IDBTransaction` enhancements](#idbtransaction-enhancements)
1. [`IDBCursor` enhancements](#idbcursor-enhancements)
1. [Async iterators](#async-iterators)
1. [Examples](#examples)
1. [TypeScript](#typescript)
# Installation
## Using npm
```sh
npm install idb
```
Then, assuming you're using a module-compatible system (like webpack, Rollup etc):
```js
import { openDB, deleteDB, wrap, unwrap } from 'idb';
async function doDatabaseStuff() {
const db = await openDB(…);
}
```
## Directly in a browser
### Using the modules method directly via jsdelivr:
```html
<script type="module">
import { openDB, deleteDB, wrap, unwrap } from 'https://cdn.jsdelivr.net/npm/idb@8/+esm';
async function doDatabaseStuff() {
const db = await openDB(…);
}
</script>
```
### Using external script reference
```html
<script src="https://cdn.jsdelivr.net/npm/idb@8/build/umd.js"></script>
<script>
async function doDatabaseStuff() {
const db = await idb.openDB(…);
}
</script>
```
A global, `idb`, will be created, containing all exports of the module version.
# Changes
[See details of (potentially) breaking changes](CHANGELOG.md).
# Browser support
This library targets modern browsers, as in Chrome, Firefox, Safari, and other browsers that use those engines, such as Edge. IE is not supported.
# API
## `openDB`
This method opens a database, and returns a promise for an enhanced [`IDBDatabase`](https://w3c.github.io/IndexedDB/#database-interface).
```js
const db = await openDB(name, version, {
upgrade(db, oldVersion, newVersion, transaction, event) {
// …
},
blocked(currentVersion, blockedVersion, event) {
// …
},
blocking(currentVersion, blockedVersion, event) {
// …
},
terminated() {
// …
},
});
```
- `name`: Name of the database.
- `version` (optional): Schema version, or `undefined` to open the current version.
- `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.
- `db`: An enhanced `IDBDatabase`.
- `oldVersion`: Last version of the database opened by the user.
- `newVersion`: Whatever new version you provided.
- `transaction`: An enhanced transaction for this upgrade. This is useful if you need to get data from other stores as part of a migration.
- `event`: The event object for the associated `upgradeneeded` event.
- `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.
- `currentVersion`: Version of the database that's blocking this one.
- `blockedVersion`: The version of the database being blocked (whatever version you provided to `openDB`).
- `event`: The event object for the associated `blocked` event.
- `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.
- `currentVersion`: Version of the open database (whatever version you provided to `openDB`).
- `blockedVersion`: The version of the database that's being blocked.
- `event`: The event object for the associated `versionchange` event.
- `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.
## `deleteDB`
Deletes a database.
```js
await deleteDB(name, {
blocked() {
// …
},
});
```
- `name`: Name of the database.
- `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.
- `currentVersion`: Version of the database that's blocking the delete operation.
- `event`: The event object for the associated 'versionchange' event.
## `unwrap`
Takes an enhanced IndexedDB object and returns the plain unmodified one.
```js
const unwrapped = unwrap(wrapped);
```
This is useful if, for some reason, you want to drop back into plain IndexedDB. Promises will also be converted back into `IDBRequest` objects.
## `wrap`
Takes an IDB object and returns a version enhanced by this library.
```js
const wrapped = wrap(unwrapped);
```
This is useful if some third party code gives you an `IDBDatabase` object and you want it to have the features of this library.
## General enhancements
Once you've opened the database the API is the same as IndexedDB, except for a few changes to make things easier.
Firstly, any method that usually returns an `IDBRequest` object will now return a promise for the result.
```js
const store = db.transaction(storeName).objectStore(storeName);
const value = await store.get(key);
```
### Promises & throwing
The library turns all `IDBRequest` objects into promises, but it doesn't know in advance which methods may return promises.
As a result, methods such as `store.put` may throw instead of returning a promise.
If you're using async functions, there's no observable difference.
### Transaction lifetime
TL;DR: **Do not `await` other things between the start and end of your transaction**, otherwise the transaction will close before you're done.
An IDB transaction auto-closes if it doesn't have anything left do once microtasks have been processed. As a result, this works fine:
```js
const tx = db.transaction('keyval', 'readwrite');
const store = tx.objectStore('keyval');
const val = (await store.get('counter')) || 0;
await store.put(val + 1, 'counter');
await tx.done;
```
But this doesn't:
```js
const tx = db.transaction('keyval', 'readwrite');
const store = tx.objectStore('keyval');
const val = (await store.get('counter')) || 0;
// This is where things go wrong:
const newVal = await fetch('/increment?val=' + val);
// And this throws an error:
await store.put(newVal, 'counter');
await tx.done;
```
In this case, the transaction closes while the browser is fetching, so `store.put` fails.
## `IDBDatabase` enhancements
### Shortcuts to get/set from an object store
It's common to create a transaction for a single action, so helper methods are included for this:
```js
// Get a value from a store:
const value = await db.get(storeName, key);
// Set a value in a store:
await db.put(storeName, value, key);
```
The 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.
### Shortcuts to get from an index
The shortcuts are: `getFromIndex`, `getKeyFromIndex`, `getAllFromIndex`, `getAllKeysFromIndex`, and `countFromIndex`.
```js
// Get a value from an index:
const value = await db.getFromIndex(storeName, indexName, key);
```
Each method takes `storeName` and `indexName` arguments, followed by the rest of the arguments from the equivalent `IDBIndex` method.
## `IDBTransaction` enhancements
### `tx.store`
If a transaction involves a single store, the `store` property will reference that store.
```js
const tx = db.transaction('whatever');
const store = tx.store;
```
If a transaction involves multiple stores, `tx.store` is undefined, you need to use `tx.objectStore(storeName)` to get the stores.
### `tx.done`
Transactions 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).
```js
const tx = db.transaction(storeName, 'readwrite');
await Promise.all([
tx.store.put('bar', 'foo'),
tx.store.put('world', 'hello'),
tx.done,
]);
```
If 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.
## `IDBCursor` enhancements
Cursor advance methods (`advance`, `continue`, `continuePrimaryKey`) return a promise for the cursor, or null if there are no further values to provide.
```js
let cursor = await db.transaction(storeName).store.openCursor();
while (cursor) {
console.log(cursor.key, cursor.value);
cursor = await cursor.continue();
}
```
## Async iterators
You can iterate over stores, indexes, and cursors:
```js
const tx = db.transaction(storeName);
for await (const cursor of tx.store) {
// …
}
```
Each yielded object is an `IDBCursor`. You can optionally use the advance methods to skip items (within an async iterator they return void):
```js
const tx = db.transaction(storeName);
for await (const cursor of tx.store) {
console.log(cursor.value);
// Skip the next item
cursor.advance(2);
}
```
If you don't manually advance the cursor, `cursor.continue()` is called for you.
Stores and indexes also have an `iterate` method which has the same signature as `openCursor`, but returns an async iterator:
```js
const index = db.transaction('books').store.index('author');
for await (const cursor of index.iterate('Douglas Adams')) {
console.log(cursor.value);
}
```
# Examples
## Keyval store
This 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.
```js
import { openDB } from 'idb';
const dbPromise = openDB('keyval-store', 1, {
upgrade(db) {
db.createObjectStore('keyval');
},
});
export async function get(key) {
return (await dbPromise).get('keyval', key);
}
export async function set(key, val) {
return (await dbPromise).put('keyval', val, key);
}
export async function del(key) {
return (await dbPromise).delete('keyval', key);
}
export async function clear() {
return (await dbPromise).clear('keyval');
}
export async function keys() {
return (await dbPromise).getAllKeys('keyval');
}
```
## Article store
```js
import { openDB } from 'idb/with-async-ittr.js';
async function demo() {
const db = await openDB('Articles', 1, {
upgrade(db) {
// Create a store of objects
const store = db.createObjectStore('articles', {
// The 'id' property of the object will be the key.
keyPath: 'id',
// If it isn't explicitly set, create a value by auto incrementing.
autoIncrement: true,
});
// Create an index on the 'date' property of the objects.
store.createIndex('date', 'date');
},
});
// Add an article:
await db.add('articles', {
title: 'Article 1',
date: new Date('2019-01-01'),
body: '…',
});
// Add multiple articles in one transaction:
{
const tx = db.transaction('articles', 'readwrite');
await Promise.all([
tx.store.add({
title: 'Article 2',
date: new Date('2019-01-01'),
body: '…',
}),
tx.store.add({
title: 'Article 3',
date: new Date('2019-01-02'),
body: '…',
}),
tx.done,
]);
}
// Get all the articles in date order:
console.log(await db.getAllFromIndex('articles', 'date'));
// Add 'And, happy new year!' to all articles on 2019-01-01:
{
const tx = db.transaction('articles', 'readwrite');
const index = tx.store.index('date');
for await (const cursor of index.iterate(new Date('2019-01-01'))) {
const article = { ...cursor.value };
article.body += ' And, happy new year!';
cursor.update(article);
}
await tx.done;
}
}
```
# TypeScript
This library is fully typed, and you can improve things by providing types for your database:
```ts
import { openDB, DBSchema } from 'idb';
interface MyDB extends DBSchema {
'favourite-number': {
key: string;
value: number;
};
products: {
value: {
name: string;
price: number;
productCode: string;
};
key: string;
indexes: { 'by-price': number };
};
}
async function demo() {
const db = await openDB<MyDB>('my-db', 1, {
upgrade(db) {
db.createObjectStore('favourite-number');
const productStore = db.createObjectStore('products', {
keyPath: 'productCode',
});
productStore.createIndex('by-price', 'price');
},
});
// This works
await db.put('favourite-number', 7, 'Jen');
// This fails at compile time, as the 'favourite-number' store expects a number.
await db.put('favourite-number', 'Twelve', 'Jake');
}
```
To define types for your database, extend `DBSchema` with an interface where the keys are the names of your object stores.
For 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.
Optionally, `indexes` can contain a map of index names, to the type of key within that index.
Provide 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.
## Opting out of types
If 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.
Let's say we were renaming the 'favourite-number' store to 'fave-nums':
```ts
import { openDB, DBSchema, IDBPDatabase } from 'idb';
interface MyDBV1 extends DBSchema {
'favourite-number': { key: string; value: number };
}
interface MyDBV2 extends DBSchema {
'fave-num': { key: string; value: number };
}
const db = await openDB<MyDBV2>('my-db', 2, {
async upgrade(db, oldVersion) {
// Cast a reference of the database to the old schema.
const v1Db = db as unknown as IDBPDatabase<MyDBV1>;
if (oldVersion < 1) {
v1Db.createObjectStore('favourite-number');
}
if (oldVersion < 2) {
const store = v1Db.createObjectStore('favourite-number');
store.name = 'fave-num';
}
},
});
```
You can also cast to a typeless database by omitting the type, eg `db as IDBPDatabase`.
Note: Types like `IDBPDatabase` are used by TypeScript only. The implementation uses proxies under the hood.
# Developing
```sh
pnpm run dev
```
This will also perform type testing.
To 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.
================================================
FILE: generic-tsconfig.json
================================================
{
"compilerOptions": {
"target": "ES2019",
"downlevelIteration": true,
"module": "esnext",
"strict": true,
"moduleResolution": "node",
"composite": true,
"declaration": true,
"allowSyntheticDefaultImports": true,
"noUnusedLocals": true,
"sourceMap": false
}
}
================================================
FILE: lib/size-report.mjs
================================================
/**
* Copyright 2019 Google Inc. All Rights Reserved.
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
* http://www.apache.org/licenses/LICENSE-2.0
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import { promisify } from 'util';
import { brotliCompress } from 'zlib';
import { promises as fsp } from 'fs';
import { glob } from 'glob';
import { filesize } from 'filesize';
const brCompress = promisify(brotliCompress);
(async function () {
const paths = await glob('tmp/size-tests/*.js');
const entryPromises = paths.map(async (path) => {
const br = await brCompress(await fsp.readFile(path));
return [path, filesize(br.length), br.length];
});
for await (const entry of entryPromises) console.log(...entry);
})();
================================================
FILE: package.json
================================================
{
"name": "idb",
"version": "8.0.3",
"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"
},
"./build/*": "./build/*",
"./package.json": "./package.json"
},
"files": [
"build/**",
"with-*",
"CHANGELOG.md"
],
"type": "module",
"scripts": {
"build": "cross-env 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": "Jake Archibald",
"license": "ISC",
"devDependencies": {
"@rollup/plugin-commonjs": "^28.0.3",
"@rollup/plugin-node-resolve": "^16.0.1",
"@rollup/plugin-terser": "^0.4.4",
"@rollup/plugin-typescript": "^12.1.2",
"@types/chai": "^5.2.2",
"@types/estree": "^1.0.7",
"@types/mocha": "^10.0.10",
"@types/node": "^22.15.14",
"chai": "^5.2.0",
"conditional-type-checks": "^1.0.6",
"cross-env": "^7.0.3",
"del": "^8.0.0",
"filesize": "^10.1.6",
"glob": "^11.0.2",
"mocha": "^11.2.2",
"prettier": "^3.5.3",
"rollup": "^4.40.2",
"tslib": "^2.8.1",
"typescript": "^5.8.3"
}
}
================================================
FILE: rollup.config.mjs
================================================
import { promises as fsp } from 'fs';
import { basename } from 'path';
import terser from '@rollup/plugin-terser';
import resolve from '@rollup/plugin-node-resolve';
import commonjs from '@rollup/plugin-commonjs';
import typescript from '@rollup/plugin-typescript';
import { deleteAsync } from 'del';
import { glob } from 'glob';
export default async function ({ watch }) {
await deleteAsync(['.ts-tmp', 'build', 'tmp']);
const builds = [];
// Main
builds.push({
plugins: [
typescript({ cacheDir: '.ts-tmp', tsconfig: 'src/tsconfig.json' }),
],
input: ['src/index.ts'],
output: [
{
dir: 'build/',
format: 'esm',
entryFileNames: '[name].js',
chunkFileNames: '[name].js',
},
{
dir: 'build/',
format: 'cjs',
entryFileNames: '[name].cjs',
chunkFileNames: '[name].cjs',
},
],
});
// Minified iife
builds.push({
input: 'build/index.js',
plugins: [
terser({
compress: { ecma: 2019 },
}),
],
output: {
file: 'build/umd.js',
format: 'umd',
esModule: false,
name: 'idb',
},
});
// Tests
if (!process.env.PRODUCTION) {
builds.push({
plugins: [
typescript({ cacheDir: '.ts-tmp', tsconfig: 'test/tsconfig.json' }),
resolve(),
commonjs(),
{
async generateBundle() {
this.emitFile({
type: 'asset',
source: await fsp.readFile('test/index.html'),
fileName: 'index.html',
});
},
},
],
input: [
'test/index.ts',
'test/main.ts',
'test/open.ts',
'test/iterate.ts',
],
output: {
dir: 'build/test',
format: 'esm',
},
});
}
builds.push(
...(await glob('size-tests/*.js').then((paths) =>
paths.map((path) => ({
input: path,
plugins: [
terser({
compress: { ecma: 2020 },
}),
],
output: [
{
file: `tmp/size-tests/${basename(path)}`,
format: 'esm',
},
],
})),
)),
);
return builds;
}
================================================
FILE: size-tests/main.js
================================================
import { openDB } from '../build/index';
a(openDB);
================================================
FILE: src/async-iterators.ts
================================================
import { instanceOfAny, Func } from './util.js';
import { replaceTraps, reverseTransformCache, unwrap } from './wrap-idb-value.js';
import { IDBPObjectStore, IDBPIndex, IDBPCursor } from './entry.js';
const advanceMethodProps = ['continue', 'continuePrimaryKey', 'advance'];
const methodMap: { [s: string]: Func } = {};
const advanceResults = new WeakMap<IDBPCursor, Promise<IDBPCursor | null>>();
const ittrProxiedCursorToOriginalProxy = new WeakMap<IDBPCursor, IDBPCursor>();
const cursorIteratorTraps: ProxyHandler<any> = {
get(target, prop) {
if (!advanceMethodProps.includes(prop as string)) return target[prop];
let cachedFunc = methodMap[prop as string];
if (!cachedFunc) {
cachedFunc = methodMap[prop as string] = function (
this: IDBPCursor,
...args: any
) {
advanceResults.set(
this,
(ittrProxiedCursorToOriginalProxy.get(this) as any)[prop](...args),
);
};
}
return cachedFunc;
},
};
async function* iterate(
this: IDBPObjectStore | IDBPIndex | IDBPCursor,
...args: any[]
): AsyncIterableIterator<any> {
// tslint:disable-next-line:no-this-assignment
let cursor: typeof this | null = this;
if (!(cursor instanceof IDBCursor)) {
cursor = await (cursor as IDBPObjectStore | IDBPIndex).openCursor(...args);
}
if (!cursor) return;
cursor = cursor as IDBPCursor;
const proxiedCursor = new Proxy(cursor, cursorIteratorTraps);
ittrProxiedCursorToOriginalProxy.set(proxiedCursor, cursor);
// Map this double-proxy back to the original, so other cursor methods work.
reverseTransformCache.set(proxiedCursor, unwrap(cursor));
while (cursor) {
yield proxiedCursor;
// If one of the advancing methods was not called, call continue().
cursor = await (advanceResults.get(proxiedCursor) || cursor.continue());
advanceResults.delete(proxiedCursor);
}
}
function isIteratorProp(target: any, prop: number | string | symbol) {
return (
(prop === Symbol.asyncIterator &&
instanceOfAny(target, [IDBIndex, IDBObjectStore, IDBCursor])) ||
(prop === 'iterate' && instanceOfAny(target, [IDBIndex, IDBObjectStore]))
);
}
replaceTraps((oldTraps) => ({
...oldTraps,
get(target, prop, receiver) {
if (isIteratorProp(target, prop)) return iterate;
return oldTraps.get!(target, prop, receiver);
},
has(target, prop) {
return isIteratorProp(target, prop) || oldTraps.has!(target, prop);
},
}));
================================================
FILE: src/database-extras.ts
================================================
import { Func } from './util.js';
import { replaceTraps } from './wrap-idb-value.js';
import { IDBPDatabase, IDBPIndex } from './entry.js';
const readMethods = ['get', 'getKey', 'getAll', 'getAllKeys', 'count'];
const writeMethods = ['put', 'add', 'delete', 'clear'];
const cachedMethods = new Map<string, Func>();
function getMethod(
target: any,
prop: string | number | symbol,
): Func | undefined {
if (
!(
target instanceof IDBDatabase &&
!(prop in target) &&
typeof prop === 'string'
)
) {
return;
}
if (cachedMethods.get(prop)) return cachedMethods.get(prop);
const targetFuncName: string = prop.replace(/FromIndex$/, '');
const useIndex = prop !== targetFuncName;
const isWrite = writeMethods.includes(targetFuncName);
if (
// Bail if the target doesn't exist on the target. Eg, getAll isn't in Edge.
!(targetFuncName in (useIndex ? IDBIndex : IDBObjectStore).prototype) ||
!(isWrite || readMethods.includes(targetFuncName))
) {
return;
}
const method = async function (
this: IDBPDatabase,
storeName: string,
...args: any[]
) {
// isWrite ? 'readwrite' : undefined gzipps better, but fails in Edge :(
const tx = this.transaction(storeName, isWrite ? 'readwrite' : 'readonly');
let target:
| typeof tx.store
| IDBPIndex<unknown, string[], string, string, 'readwrite' | 'readonly'> =
tx.store;
if (useIndex) target = target.index(args.shift());
// Must reject if op rejects.
// If it's a write operation, must reject if tx.done rejects.
// Must reject with op rejection first.
// Must resolve with op value.
// Must handle both promises (no unhandled rejections)
return (
await Promise.all([
(target as any)[targetFuncName](...args),
isWrite && tx.done,
])
)[0];
};
cachedMethods.set(prop, method);
return method;
}
replaceTraps((oldTraps) => ({
...oldTraps,
get: (target, prop, receiver) =>
getMethod(target, prop) || oldTraps.get!(target, prop, receiver),
has: (target, prop) =>
!!getMethod(target, prop) || oldTraps.has!(target, prop),
}));
================================================
FILE: src/entry.ts
================================================
import { wrap } from './wrap-idb-value.js';
export interface OpenDBCallbacks<DBTypes extends DBSchema | unknown> {
/**
* Called if this version of the database has never been opened before. Use it to specify the
* schema for the database.
*
* @param database A database instance that you can use to add/remove stores and indexes.
* @param oldVersion Last version of the database opened by the user.
* @param newVersion Whatever new version you provided.
* @param transaction The transaction for this upgrade.
* This is useful if you need to get data from other stores as part of a migration.
* @param event The event object for the associated 'upgradeneeded' event.
*/
upgrade?(
database: IDBPDatabase<DBTypes>,
oldVersion: number,
newVersion: number | null,
transaction: IDBPTransaction<
DBTypes,
StoreNames<DBTypes>[],
'versionchange'
>,
event: IDBVersionChangeEvent,
): void;
/**
* Called if there are older versions of the database open on the origin, so this version cannot
* open.
*
* @param currentVersion Version of the database that's blocking this one.
* @param blockedVersion The version of the database being blocked (whatever version you provided to `openDB`).
* @param event The event object for the associated `blocked` event.
*/
blocked?(
currentVersion: number,
blockedVersion: number | null,
event: IDBVersionChangeEvent,
): void;
/**
* Called if this connection is blocking a future version of the database from opening.
*
* @param currentVersion Version of the open database (whatever version you provided to `openDB`).
* @param blockedVersion The version of the database that's being blocked.
* @param event The event object for the associated `versionchange` event.
*/
blocking?(
currentVersion: number,
blockedVersion: number | null,
event: IDBVersionChangeEvent,
): void;
/**
* Called if the browser abnormally terminates the connection.
* This is not called when `db.close()` is called.
*/
terminated?(): void;
}
/**
* Open a database.
*
* @param name Name of the database.
* @param version Schema version.
* @param callbacks Additional callbacks.
*/
export function openDB<DBTypes extends DBSchema | unknown = unknown>(
name: string,
version?: number,
{ blocked, upgrade, blocking, terminated }: OpenDBCallbacks<DBTypes> = {},
): Promise<IDBPDatabase<DBTypes>> {
const request = indexedDB.open(name, version);
const openPromise = wrap(request) as Promise<IDBPDatabase<DBTypes>>;
if (upgrade) {
request.addEventListener('upgradeneeded', (event) => {
upgrade(
wrap(request.result) as IDBPDatabase<DBTypes>,
event.oldVersion,
event.newVersion,
wrap(request.transaction!) as unknown as IDBPTransaction<
DBTypes,
StoreNames<DBTypes>[],
'versionchange'
>,
event,
);
});
}
if (blocked) {
request.addEventListener('blocked', (event) =>
blocked(
// Casting due to https://github.com/microsoft/TypeScript-DOM-lib-generator/pull/1405
(event as IDBVersionChangeEvent).oldVersion,
(event as IDBVersionChangeEvent).newVersion,
event as IDBVersionChangeEvent,
),
);
}
openPromise
.then((db) => {
if (terminated) db.addEventListener('close', () => terminated());
if (blocking) {
db.addEventListener('versionchange', (event) =>
blocking(event.oldVersion, event.newVersion, event),
);
}
})
.catch(() => {});
return openPromise;
}
export interface DeleteDBCallbacks {
/**
* Called if there are connections to this database open, so it cannot be deleted.
*
* @param currentVersion Version of the database that's blocking the delete operation.
* @param event The event object for the associated `blocked` event.
*/
blocked?(currentVersion: number, event: IDBVersionChangeEvent): void;
}
/**
* Delete a database.
*
* @param name Name of the database.
*/
export function deleteDB(
name: string,
{ blocked }: DeleteDBCallbacks = {},
): Promise<void> {
const request = indexedDB.deleteDatabase(name);
if (blocked) {
request.addEventListener('blocked', (event) =>
blocked(
// Casting due to https://github.com/microsoft/TypeScript-DOM-lib-generator/pull/1405
(event as IDBVersionChangeEvent).oldVersion,
event as IDBVersionChangeEvent,
),
);
}
return wrap(request).then(() => undefined);
}
export { unwrap, wrap } from './wrap-idb-value.js';
// === The rest of this file is type defs ===
type KeyToKeyNoIndex<T> = {
[K in keyof T]: string extends K ? never : number extends K ? never : K;
};
type ValuesOf<T> = T extends { [K in keyof T]: infer U } ? U : never;
type KnownKeys<T> = ValuesOf<KeyToKeyNoIndex<T>>;
type Omit<T, K> = Pick<T, Exclude<keyof T, K>>;
export interface DBSchema {
[s: string]: DBSchemaValue;
}
interface IndexKeys {
[s: string]: IDBValidKey;
}
interface DBSchemaValue {
key: IDBValidKey;
value: any;
indexes?: IndexKeys;
}
/**
* Extract known object store names from the DB schema type.
*
* @template DBTypes DB schema type, or unknown if the DB isn't typed.
*/
export type StoreNames<DBTypes extends DBSchema | unknown> =
DBTypes extends DBSchema ? KnownKeys<DBTypes> : string;
/**
* Extract database value types from the DB schema type.
*
* @template DBTypes DB schema type, or unknown if the DB isn't typed.
* @template StoreName Names of the object stores to get the types of.
*/
export type StoreValue<
DBTypes extends DBSchema | unknown,
StoreName extends StoreNames<DBTypes>,
> = DBTypes extends DBSchema ? DBTypes[StoreName]['value'] : any;
/**
* Extract database key types from the DB schema type.
*
* @template DBTypes DB schema type, or unknown if the DB isn't typed.
* @template StoreName Names of the object stores to get the types of.
*/
export type StoreKey<
DBTypes extends DBSchema | unknown,
StoreName extends StoreNames<DBTypes>,
> = DBTypes extends DBSchema ? DBTypes[StoreName]['key'] : IDBValidKey;
/**
* Extract the names of indexes in certain object stores from the DB schema type.
*
* @template DBTypes DB schema type, or unknown if the DB isn't typed.
* @template StoreName Names of the object stores to get the types of.
*/
export type IndexNames<
DBTypes extends DBSchema | unknown,
StoreName extends StoreNames<DBTypes>,
> = DBTypes extends DBSchema ? keyof DBTypes[StoreName]['indexes'] & string : string;
/**
* Extract the types of indexes in certain object stores from the DB schema type.
*
* @template DBTypes DB schema type, or unknown if the DB isn't typed.
* @template StoreName Names of the object stores to get the types of.
* @template IndexName Names of the indexes to get the types of.
*/
export type IndexKey<
DBTypes extends DBSchema | unknown,
StoreName extends StoreNames<DBTypes>,
IndexName extends IndexNames<DBTypes, StoreName>,
> = DBTypes extends DBSchema
? IndexName extends keyof DBTypes[StoreName]['indexes']
? DBTypes[StoreName]['indexes'][IndexName]
: IDBValidKey
: IDBValidKey;
type CursorSource<
DBTypes extends DBSchema | unknown,
TxStores extends ArrayLike<StoreNames<DBTypes>>,
StoreName extends StoreNames<DBTypes>,
IndexName extends IndexNames<DBTypes, StoreName> | unknown,
Mode extends IDBTransactionMode = 'readonly',
> = IndexName extends IndexNames<DBTypes, StoreName>
? IDBPIndex<DBTypes, TxStores, StoreName, IndexName, Mode>
: IDBPObjectStore<DBTypes, TxStores, StoreName, Mode>;
type CursorKey<
DBTypes extends DBSchema | unknown,
StoreName extends StoreNames<DBTypes>,
IndexName extends IndexNames<DBTypes, StoreName> | unknown,
> = IndexName extends IndexNames<DBTypes, StoreName>
? IndexKey<DBTypes, StoreName, IndexName>
: StoreKey<DBTypes, StoreName>;
type IDBPDatabaseExtends = Omit<
IDBDatabase,
'createObjectStore' | 'deleteObjectStore' | 'transaction' | 'objectStoreNames'
>;
export type DOMStringListSymbolIteratorType = DOMStringList extends { [Symbol.iterator](): infer R } ? R : IterableIterator<string>;
/**
* A variation of DOMStringList with precise string types
*/
export interface TypedDOMStringList<T extends string> extends DOMStringList {
contains(string: T): boolean;
item(index: number): T | null;
[index: number]: T;
/**
* To resolve https://github.com/jakearchibald/idb/issues/327,
* and for compatibility with TypeScript >= 5.6 with ArrayIterator.
*/
[Symbol.iterator](): IterableIterator<string> extends DOMStringListSymbolIteratorType ? IterableIterator<T> : DOMStringListSymbolIteratorType & Iterator<T>;
}
interface IDBTransactionOptions {
/**
* The durability of the transaction.
*
* The default is "default". Using "relaxed" provides better performance, but with fewer
* guarantees. Web applications are encouraged to use "relaxed" for ephemeral data such as caches
* or quickly changing records, and "strict" in cases where reducing the risk of data loss
* outweighs the impact to performance and power.
*/
durability?: 'default' | 'strict' | 'relaxed';
}
export interface IDBPDatabase<DBTypes extends DBSchema | unknown = unknown>
extends IDBPDatabaseExtends {
/**
* The names of stores in the database.
*/
readonly objectStoreNames: TypedDOMStringList<StoreNames<DBTypes>>;
/**
* Creates a new object store.
*
* Throws a "InvalidStateError" DOMException if not called within an upgrade transaction.
*/
createObjectStore<Name extends StoreNames<DBTypes>>(
name: Name,
optionalParameters?: IDBObjectStoreParameters,
): IDBPObjectStore<
DBTypes,
ArrayLike<StoreNames<DBTypes>>,
Name,
'versionchange'
>;
/**
* Deletes the object store with the given name.
*
* Throws a "InvalidStateError" DOMException if not called within an upgrade transaction.
*/
deleteObjectStore(name: StoreNames<DBTypes>): void;
/**
* Start a new transaction.
*
* @param storeNames The object store(s) this transaction needs.
* @param mode
* @param options
*/
transaction<
Name extends StoreNames<DBTypes>,
Mode extends IDBTransactionMode = 'readonly',
>(
storeNames: Name,
mode?: Mode,
options?: IDBTransactionOptions,
): IDBPTransaction<DBTypes, [Name], Mode>;
transaction<
Names extends ArrayLike<StoreNames<DBTypes>>,
Mode extends IDBTransactionMode = 'readonly',
>(
storeNames: Names,
mode?: Mode,
options?: IDBTransactionOptions,
): IDBPTransaction<DBTypes, Names, Mode>;
// Shortcut methods
/**
* Add a value to a store.
*
* Rejects if an item of a given key already exists in the store.
*
* This is a shortcut that creates a transaction for this single action. If you need to do more
* than one action, create a transaction instead.
*
* @param storeName Name of the store.
* @param value
* @param key
*/
add<Name extends StoreNames<DBTypes>>(
storeName: Name,
value: StoreValue<DBTypes, Name>,
key?: StoreKey<DBTypes, Name> | IDBKeyRange,
): Promise<StoreKey<DBTypes, Name>>;
/**
* Deletes all records in a store.
*
* This is a shortcut that creates a transaction for this single action. If you need to do more
* than one action, create a transaction instead.
*
* @param storeName Name of the store.
*/
clear(name: StoreNames<DBTypes>): Promise<void>;
/**
* Retrieves the number of records matching the given query in a store.
*
* This is a shortcut that creates a transaction for this single action. If you need to do more
* than one action, create a transaction instead.
*
* @param storeName Name of the store.
* @param key
*/
count<Name extends StoreNames<DBTypes>>(
storeName: Name,
key?: StoreKey<DBTypes, Name> | IDBKeyRange | null,
): Promise<number>;
/**
* Retrieves the number of records matching the given query in an index.
*
* This is a shortcut that creates a transaction for this single action. If you need to do more
* than one action, create a transaction instead.
*
* @param storeName Name of the store.
* @param indexName Name of the index within the store.
* @param key
*/
countFromIndex<
Name extends StoreNames<DBTypes>,
IndexName extends IndexNames<DBTypes, Name>,
>(
storeName: Name,
indexName: IndexName,
key?: IndexKey<DBTypes, Name, IndexName> | IDBKeyRange | null,
): Promise<number>;
/**
* Deletes records in a store matching the given query.
*
* This is a shortcut that creates a transaction for this single action. If you need to do more
* than one action, create a transaction instead.
*
* @param storeName Name of the store.
* @param key
*/
delete<Name extends StoreNames<DBTypes>>(
storeName: Name,
key: StoreKey<DBTypes, Name> | IDBKeyRange,
): Promise<void>;
/**
* Retrieves the value of the first record in a store matching the query.
*
* Resolves with undefined if no match is found.
*
* This is a shortcut that creates a transaction for this single action. If you need to do more
* than one action, create a transaction instead.
*
* @param storeName Name of the store.
* @param query
*/
get<Name extends StoreNames<DBTypes>>(
storeName: Name,
query: StoreKey<DBTypes, Name> | IDBKeyRange,
): Promise<StoreValue<DBTypes, Name> | undefined>;
/**
* Retrieves the value of the first record in an index matching the query.
*
* Resolves with undefined if no match is found.
*
* This is a shortcut that creates a transaction for this single action. If you need to do more
* than one action, create a transaction instead.
*
* @param storeName Name of the store.
* @param indexName Name of the index within the store.
* @param query
*/
getFromIndex<
Name extends StoreNames<DBTypes>,
IndexName extends IndexNames<DBTypes, Name>,
>(
storeName: Name,
indexName: IndexName,
query: IndexKey<DBTypes, Name, IndexName> | IDBKeyRange,
): Promise<StoreValue<DBTypes, Name> | undefined>;
/**
* Retrieves all values in a store that match the query.
*
* This is a shortcut that creates a transaction for this single action. If you need to do more
* than one action, create a transaction instead.
*
* @param storeName Name of the store.
* @param query
* @param count Maximum number of values to return.
*/
getAll<Name extends StoreNames<DBTypes>>(
storeName: Name,
query?: StoreKey<DBTypes, Name> | IDBKeyRange | null,
count?: number,
): Promise<StoreValue<DBTypes, Name>[]>;
/**
* Retrieves all values in an index that match the query.
*
* This is a shortcut that creates a transaction for this single action. If you need to do more
* than one action, create a transaction instead.
*
* @param storeName Name of the store.
* @param indexName Name of the index within the store.
* @param query
* @param count Maximum number of values to return.
*/
getAllFromIndex<
Name extends StoreNames<DBTypes>,
IndexName extends IndexNames<DBTypes, Name>,
>(
storeName: Name,
indexName: IndexName,
query?: IndexKey<DBTypes, Name, IndexName> | IDBKeyRange | null,
count?: number,
): Promise<StoreValue<DBTypes, Name>[]>;
/**
* Retrieves the keys of records in a store matching the query.
*
* This is a shortcut that creates a transaction for this single action. If you need to do more
* than one action, create a transaction instead.
*
* @param storeName Name of the store.
* @param query
* @param count Maximum number of keys to return.
*/
getAllKeys<Name extends StoreNames<DBTypes>>(
storeName: Name,
query?: StoreKey<DBTypes, Name> | IDBKeyRange | null,
count?: number,
): Promise<StoreKey<DBTypes, Name>[]>;
/**
* Retrieves the keys of records in an index matching the query.
*
* This is a shortcut that creates a transaction for this single action. If you need to do more
* than one action, create a transaction instead.
*
* @param storeName Name of the store.
* @param indexName Name of the index within the store.
* @param query
* @param count Maximum number of keys to return.
*/
getAllKeysFromIndex<
Name extends StoreNames<DBTypes>,
IndexName extends IndexNames<DBTypes, Name>,
>(
storeName: Name,
indexName: IndexName,
query?: IndexKey<DBTypes, Name, IndexName> | IDBKeyRange | null,
count?: number,
): Promise<StoreKey<DBTypes, Name>[]>;
/**
* Retrieves the key of the first record in a store that matches the query.
*
* Resolves with undefined if no match is found.
*
* This is a shortcut that creates a transaction for this single action. If you need to do more
* than one action, create a transaction instead.
*
* @param storeName Name of the store.
* @param query
*/
getKey<Name extends StoreNames<DBTypes>>(
storeName: Name,
query: StoreKey<DBTypes, Name> | IDBKeyRange,
): Promise<StoreKey<DBTypes, Name> | undefined>;
/**
* Retrieves the key of the first record in an index that matches the query.
*
* Resolves with undefined if no match is found.
*
* This is a shortcut that creates a transaction for this single action. If you need to do more
* than one action, create a transaction instead.
*
* @param storeName Name of the store.
* @param indexName Name of the index within the store.
* @param query
*/
getKeyFromIndex<
Name extends StoreNames<DBTypes>,
IndexName extends IndexNames<DBTypes, Name>,
>(
storeName: Name,
indexName: IndexName,
query: IndexKey<DBTypes, Name, IndexName> | IDBKeyRange,
): Promise<StoreKey<DBTypes, Name> | undefined>;
/**
* Put an item in the database.
*
* Replaces any item with the same key.
*
* This is a shortcut that creates a transaction for this single action. If you need to do more
* than one action, create a transaction instead.
*
* @param storeName Name of the store.
* @param value
* @param key
*/
put<Name extends StoreNames<DBTypes>>(
storeName: Name,
value: StoreValue<DBTypes, Name>,
key?: StoreKey<DBTypes, Name> | IDBKeyRange,
): Promise<StoreKey<DBTypes, Name>>;
}
type IDBPTransactionExtends = Omit<
IDBTransaction,
'db' | 'objectStore' | 'objectStoreNames'
>;
export interface IDBPTransaction<
DBTypes extends DBSchema | unknown = unknown,
TxStores extends ArrayLike<StoreNames<DBTypes>> = ArrayLike<
StoreNames<DBTypes>
>,
Mode extends IDBTransactionMode = 'readonly',
> extends IDBPTransactionExtends {
/**
* The transaction's mode.
*/
readonly mode: Mode;
/**
* The names of stores in scope for this transaction.
*/
readonly objectStoreNames: TypedDOMStringList<TxStores[number]>;
/**
* The transaction's connection.
*/
readonly db: IDBPDatabase<DBTypes>;
/**
* Promise for the completion of this transaction.
*/
readonly done: Promise<void>;
/**
* The associated object store, if the transaction covers a single store, otherwise undefined.
*/
readonly store: TxStores[1] extends undefined
? IDBPObjectStore<DBTypes, TxStores, TxStores[0], Mode>
: undefined;
/**
* Returns an IDBObjectStore in the transaction's scope.
*/
objectStore<StoreName extends TxStores[number]>(
name: StoreName,
): IDBPObjectStore<DBTypes, TxStores, StoreName, Mode>;
}
type IDBPObjectStoreExtends = Omit<
IDBObjectStore,
| 'transaction'
| 'add'
| 'clear'
| 'count'
| 'createIndex'
| 'delete'
| 'get'
| 'getAll'
| 'getAllKeys'
| 'getKey'
| 'index'
| 'openCursor'
| 'openKeyCursor'
| 'put'
| 'indexNames'
>;
export interface IDBPObjectStore<
DBTypes extends DBSchema | unknown = unknown,
TxStores extends ArrayLike<StoreNames<DBTypes>> = ArrayLike<
StoreNames<DBTypes>
>,
StoreName extends StoreNames<DBTypes> = StoreNames<DBTypes>,
Mode extends IDBTransactionMode = 'readonly',
> extends IDBPObjectStoreExtends {
/**
* The names of indexes in the store.
*/
readonly indexNames: TypedDOMStringList<IndexNames<DBTypes, StoreName>>;
/**
* The associated transaction.
*/
readonly transaction: IDBPTransaction<DBTypes, TxStores, Mode>;
/**
* Add a value to the store.
*
* Rejects if an item of a given key already exists in the store.
*/
add: Mode extends 'readonly'
? undefined
: (
value: StoreValue<DBTypes, StoreName>,
key?: StoreKey<DBTypes, StoreName> | IDBKeyRange,
) => Promise<StoreKey<DBTypes, StoreName>>;
/**
* Deletes all records in store.
*/
clear: Mode extends 'readonly' ? undefined : () => Promise<void>;
/**
* Retrieves the number of records matching the given query.
*/
count(
key?: StoreKey<DBTypes, StoreName> | IDBKeyRange | null,
): Promise<number>;
/**
* Creates a new index in store.
*
* Throws an "InvalidStateError" DOMException if not called within an upgrade transaction.
*/
createIndex: Mode extends 'versionchange'
? <IndexName extends IndexNames<DBTypes, StoreName>>(
name: IndexName,
keyPath: string | string[],
options?: IDBIndexParameters,
) => IDBPIndex<DBTypes, TxStores, StoreName, IndexName, Mode>
: undefined;
/**
* Deletes records in store matching the given query.
*/
delete: Mode extends 'readonly'
? undefined
: (key: StoreKey<DBTypes, StoreName> | IDBKeyRange) => Promise<void>;
/**
* Retrieves the value of the first record matching the query.
*
* Resolves with undefined if no match is found.
*/
get(
query: StoreKey<DBTypes, StoreName> | IDBKeyRange,
): Promise<StoreValue<DBTypes, StoreName> | undefined>;
/**
* Retrieves all values that match the query.
*
* @param query
* @param count Maximum number of values to return.
*/
getAll(
query?: StoreKey<DBTypes, StoreName> | IDBKeyRange | null,
count?: number,
): Promise<StoreValue<DBTypes, StoreName>[]>;
/**
* Retrieves the keys of records matching the query.
*
* @param query
* @param count Maximum number of keys to return.
*/
getAllKeys(
query?: StoreKey<DBTypes, StoreName> | IDBKeyRange | null,
count?: number,
): Promise<StoreKey<DBTypes, StoreName>[]>;
/**
* Retrieves the key of the first record that matches the query.
*
* Resolves with undefined if no match is found.
*/
getKey(
query: StoreKey<DBTypes, StoreName> | IDBKeyRange,
): Promise<StoreKey<DBTypes, StoreName> | undefined>;
/**
* Get a query of a given name.
*/
index<IndexName extends IndexNames<DBTypes, StoreName>>(
name: IndexName,
): IDBPIndex<DBTypes, TxStores, StoreName, IndexName, Mode>;
/**
* Opens a cursor over the records matching the query.
*
* Resolves with null if no matches are found.
*
* @param query If null, all records match.
* @param direction
*/
openCursor(
query?: StoreKey<DBTypes, StoreName> | IDBKeyRange | null,
direction?: IDBCursorDirection,
): Promise<IDBPCursorWithValue<
DBTypes,
TxStores,
StoreName,
unknown,
Mode
> | null>;
/**
* Opens a cursor over the keys matching the query.
*
* Resolves with null if no matches are found.
*
* @param query If null, all records match.
* @param direction
*/
openKeyCursor(
query?: StoreKey<DBTypes, StoreName> | IDBKeyRange | null,
direction?: IDBCursorDirection,
): Promise<IDBPCursor<DBTypes, TxStores, StoreName, unknown, Mode> | null>;
/**
* Put an item in the store.
*
* Replaces any item with the same key.
*/
put: Mode extends 'readonly'
? undefined
: (
value: StoreValue<DBTypes, StoreName>,
key?: StoreKey<DBTypes, StoreName> | IDBKeyRange,
) => Promise<StoreKey<DBTypes, StoreName>>;
/**
* Iterate over the store.
*/
[Symbol.asyncIterator](): AsyncIterableIterator<
IDBPCursorWithValueIteratorValue<
DBTypes,
TxStores,
StoreName,
unknown,
Mode
>
>;
/**
* Iterate over the records matching the query.
*
* @param query If null, all records match.
* @param direction
*/
iterate(
query?: StoreKey<DBTypes, StoreName> | IDBKeyRange | null,
direction?: IDBCursorDirection,
): AsyncIterableIterator<
IDBPCursorWithValueIteratorValue<
DBTypes,
TxStores,
StoreName,
unknown,
Mode
>
>;
}
type IDBPIndexExtends = Omit<
IDBIndex,
| 'objectStore'
| 'count'
| 'get'
| 'getAll'
| 'getAllKeys'
| 'getKey'
| 'openCursor'
| 'openKeyCursor'
>;
export interface IDBPIndex<
DBTypes extends DBSchema | unknown = unknown,
TxStores extends ArrayLike<StoreNames<DBTypes>> = ArrayLike<
StoreNames<DBTypes>
>,
StoreName extends StoreNames<DBTypes> = StoreNames<DBTypes>,
IndexName extends IndexNames<DBTypes, StoreName> = IndexNames<
DBTypes,
StoreName
>,
Mode extends IDBTransactionMode = 'readonly',
> extends IDBPIndexExtends {
/**
* The IDBObjectStore the index belongs to.
*/
readonly objectStore: IDBPObjectStore<DBTypes, TxStores, StoreName, Mode>;
/**
* Retrieves the number of records matching the given query.
*/
count(
key?: IndexKey<DBTypes, StoreName, IndexName> | IDBKeyRange | null,
): Promise<number>;
/**
* Retrieves the value of the first record matching the query.
*
* Resolves with undefined if no match is found.
*/
get(
query: IndexKey<DBTypes, StoreName, IndexName> | IDBKeyRange,
): Promise<StoreValue<DBTypes, StoreName> | undefined>;
/**
* Retrieves all values that match the query.
*
* @param query
* @param count Maximum number of values to return.
*/
getAll(
query?: IndexKey<DBTypes, StoreName, IndexName> | IDBKeyRange | null,
count?: number,
): Promise<StoreValue<DBTypes, StoreName>[]>;
/**
* Retrieves the keys of records matching the query.
*
* @param query
* @param count Maximum number of keys to return.
*/
getAllKeys(
query?: IndexKey<DBTypes, StoreName, IndexName> | IDBKeyRange | null,
count?: number,
): Promise<StoreKey<DBTypes, StoreName>[]>;
/**
* Retrieves the key of the first record that matches the query.
*
* Resolves with undefined if no match is found.
*/
getKey(
query: IndexKey<DBTypes, StoreName, IndexName> | IDBKeyRange,
): Promise<StoreKey<DBTypes, StoreName> | undefined>;
/**
* Opens a cursor over the records matching the query.
*
* Resolves with null if no matches are found.
*
* @param query If null, all records match.
* @param direction
*/
openCursor(
query?: IndexKey<DBTypes, StoreName, IndexName> | IDBKeyRange | null,
direction?: IDBCursorDirection,
): Promise<IDBPCursorWithValue<
DBTypes,
TxStores,
StoreName,
IndexName,
Mode
> | null>;
/**
* Opens a cursor over the keys matching the query.
*
* Resolves with null if no matches are found.
*
* @param query If null, all records match.
* @param direction
*/
openKeyCursor(
query?: IndexKey<DBTypes, StoreName, IndexName> | IDBKeyRange | null,
direction?: IDBCursorDirection,
): Promise<IDBPCursor<DBTypes, TxStores, StoreName, IndexName, Mode> | null>;
/**
* Iterate over the index.
*/
[Symbol.asyncIterator](): AsyncIterableIterator<
IDBPCursorWithValueIteratorValue<
DBTypes,
TxStores,
StoreName,
IndexName,
Mode
>
>;
/**
* Iterate over the records matching the query.
*
* Resolves with null if no matches are found.
*
* @param query If null, all records match.
* @param direction
*/
iterate(
query?: IndexKey<DBTypes, StoreName, IndexName> | IDBKeyRange | null,
direction?: IDBCursorDirection,
): AsyncIterableIterator<
IDBPCursorWithValueIteratorValue<
DBTypes,
TxStores,
StoreName,
IndexName,
Mode
>
>;
}
type IDBPCursorExtends = Omit<
IDBCursor,
| 'key'
| 'primaryKey'
| 'source'
| 'advance'
| 'continue'
| 'continuePrimaryKey'
| 'delete'
| 'update'
>;
export interface IDBPCursor<
DBTypes extends DBSchema | unknown = unknown,
TxStores extends ArrayLike<StoreNames<DBTypes>> = ArrayLike<
StoreNames<DBTypes>
>,
StoreName extends StoreNames<DBTypes> = StoreNames<DBTypes>,
IndexName extends IndexNames<DBTypes, StoreName> | unknown = unknown,
Mode extends IDBTransactionMode = 'readonly',
> extends IDBPCursorExtends {
/**
* The key of the current index or object store item.
*/
readonly key: CursorKey<DBTypes, StoreName, IndexName>;
/**
* The key of the current object store item.
*/
readonly primaryKey: StoreKey<DBTypes, StoreName>;
/**
* Returns the IDBObjectStore or IDBIndex the cursor was opened from.
*/
readonly source: CursorSource<DBTypes, TxStores, StoreName, IndexName, Mode>;
/**
* Advances the cursor a given number of records.
*
* Resolves to null if no matching records remain.
*/
advance<T>(this: T, count: number): Promise<T | null>;
/**
* Advance the cursor by one record (unless 'key' is provided).
*
* Resolves to null if no matching records remain.
*
* @param key Advance to the index or object store with a key equal to or greater than this value.
*/
continue<T>(
this: T,
key?: CursorKey<DBTypes, StoreName, IndexName>,
): Promise<T | null>;
/**
* Advance the cursor by given keys.
*
* The operation is 'and' – both keys must be satisfied.
*
* Resolves to null if no matching records remain.
*
* @param key Advance to the index or object store with a key equal to or greater than this value.
* @param primaryKey and where the object store has a key equal to or greater than this value.
*/
continuePrimaryKey<T>(
this: T,
key: CursorKey<DBTypes, StoreName, IndexName>,
primaryKey: StoreKey<DBTypes, StoreName>,
): Promise<T | null>;
/**
* Delete the current record.
*/
delete: Mode extends 'readonly' ? undefined : () => Promise<void>;
/**
* Updated the current record.
*/
update: Mode extends 'readonly'
? undefined
: (
value: StoreValue<DBTypes, StoreName>,
) => Promise<StoreKey<DBTypes, StoreName>>;
/**
* Iterate over the cursor.
*/
[Symbol.asyncIterator](): AsyncIterableIterator<
IDBPCursorIteratorValue<DBTypes, TxStores, StoreName, IndexName, Mode>
>;
}
type IDBPCursorIteratorValueExtends<
DBTypes extends DBSchema | unknown = unknown,
TxStores extends ArrayLike<StoreNames<DBTypes>> = ArrayLike<
StoreNames<DBTypes>
>,
StoreName extends StoreNames<DBTypes> = StoreNames<DBTypes>,
IndexName extends IndexNames<DBTypes, StoreName> | unknown = unknown,
Mode extends IDBTransactionMode = 'readonly',
> = Omit<
IDBPCursor<DBTypes, TxStores, StoreName, IndexName, Mode>,
'advance' | 'continue' | 'continuePrimaryKey'
>;
export interface IDBPCursorIteratorValue<
DBTypes extends DBSchema | unknown = unknown,
TxStores extends ArrayLike<StoreNames<DBTypes>> = ArrayLike<
StoreNames<DBTypes>
>,
StoreName extends StoreNames<DBTypes> = StoreNames<DBTypes>,
IndexName extends IndexNames<DBTypes, StoreName> | unknown = unknown,
Mode extends IDBTransactionMode = 'readonly',
> extends IDBPCursorIteratorValueExtends<
DBTypes,
TxStores,
StoreName,
IndexName,
Mode
> {
/**
* Advances the cursor a given number of records.
*/
advance<T>(this: T, count: number): void;
/**
* Advance the cursor by one record (unless 'key' is provided).
*
* @param key Advance to the index or object store with a key equal to or greater than this value.
*/
continue<T>(this: T, key?: CursorKey<DBTypes, StoreName, IndexName>): void;
/**
* Advance the cursor by given keys.
*
* The operation is 'and' – both keys must be satisfied.
*
* @param key Advance to the index or object store with a key equal to or greater than this value.
* @param primaryKey and where the object store has a key equal to or greater than this value.
*/
continuePrimaryKey<T>(
this: T,
key: CursorKey<DBTypes, StoreName, IndexName>,
primaryKey: StoreKey<DBTypes, StoreName>,
): void;
}
export interface IDBPCursorWithValue<
DBTypes extends DBSchema | unknown = unknown,
TxStores extends ArrayLike<StoreNames<DBTypes>> = ArrayLike<
StoreNames<DBTypes>
>,
StoreName extends StoreNames<DBTypes> = StoreNames<DBTypes>,
IndexName extends IndexNames<DBTypes, StoreName> | unknown = unknown,
Mode extends IDBTransactionMode = 'readonly',
> extends IDBPCursor<DBTypes, TxStores, StoreName, IndexName, Mode> {
/**
* The value of the current item.
*/
readonly value: StoreValue<DBTypes, StoreName>;
/**
* Iterate over the cursor.
*/
[Symbol.asyncIterator](): AsyncIterableIterator<
IDBPCursorWithValueIteratorValue<
DBTypes,
TxStores,
StoreName,
IndexName,
Mode
>
>;
}
// Some of that sweeeeet Java-esque naming.
type IDBPCursorWithValueIteratorValueExtends<
DBTypes extends DBSchema | unknown = unknown,
TxStores extends ArrayLike<StoreNames<DBTypes>> = ArrayLike<
StoreNames<DBTypes>
>,
StoreName extends StoreNames<DBTypes> = StoreNames<DBTypes>,
IndexName extends IndexNames<DBTypes, StoreName> | unknown = unknown,
Mode extends IDBTransactionMode = 'readonly',
> = Omit<
IDBPCursorWithValue<DBTypes, TxStores, StoreName, IndexName, Mode>,
'advance' | 'continue' | 'continuePrimaryKey'
>;
export interface IDBPCursorWithValueIteratorValue<
DBTypes extends DBSchema | unknown = unknown,
TxStores extends ArrayLike<StoreNames<DBTypes>> = ArrayLike<
StoreNames<DBTypes>
>,
StoreName extends StoreNames<DBTypes> = StoreNames<DBTypes>,
IndexName extends IndexNames<DBTypes, StoreName> | unknown = unknown,
Mode extends IDBTransactionMode = 'readonly',
> extends IDBPCursorWithValueIteratorValueExtends<
DBTypes,
TxStores,
StoreName,
IndexName,
Mode
> {
/**
* Advances the cursor a given number of records.
*/
advance<T>(this: T, count: number): void;
/**
* Advance the cursor by one record (unless 'key' is provided).
*
* @param key Advance to the index or object store with a key equal to or greater than this value.
*/
continue<T>(this: T, key?: CursorKey<DBTypes, StoreName, IndexName>): void;
/**
* Advance the cursor by given keys.
*
* The operation is 'and' – both keys must be satisfied.
*
* @param key Advance to the index or object store with a key equal to or greater than this value.
* @param primaryKey and where the object store has a key equal to or greater than this value.
*/
continuePrimaryKey<T>(
this: T,
key: CursorKey<DBTypes, StoreName, IndexName>,
primaryKey: StoreKey<DBTypes, StoreName>,
): void;
}
================================================
FILE: src/index.ts
================================================
export * from './entry.js';
import './database-extras.js';
import './async-iterators.js';
================================================
FILE: src/tsconfig.json
================================================
{
"extends": "../generic-tsconfig.json",
"compilerOptions": {
"lib": ["esnext", "dom"],
"tsBuildInfoFile": "../.ts-tmp/.src.tsbuildinfo",
"declarationDir": "../build"
}
}
================================================
FILE: src/util.ts
================================================
export type Constructor = new (...args: any[]) => any;
export type Func = (...args: any[]) => any;
export const instanceOfAny = (
object: any,
constructors: Constructor[],
): boolean => constructors.some((c) => object instanceof c);
================================================
FILE: src/wrap-idb-value.ts
================================================
import {
IDBPCursor,
IDBPCursorWithValue,
IDBPDatabase,
IDBPIndex,
IDBPObjectStore,
IDBPTransaction,
} from './entry.js';
import { Constructor, Func, instanceOfAny } from './util.js';
let idbProxyableTypes: Constructor[];
let cursorAdvanceMethods: Func[];
// This is a function to prevent it throwing up in node environments.
function getIdbProxyableTypes(): Constructor[] {
return (
idbProxyableTypes ||
(idbProxyableTypes = [
IDBDatabase,
IDBObjectStore,
IDBIndex,
IDBCursor,
IDBTransaction,
])
);
}
// This is a function to prevent it throwing up in node environments.
function getCursorAdvanceMethods(): Func[] {
return (
cursorAdvanceMethods ||
(cursorAdvanceMethods = [
IDBCursor.prototype.advance,
IDBCursor.prototype.continue,
IDBCursor.prototype.continuePrimaryKey,
])
);
}
const transactionDoneMap: WeakMap<
IDBTransaction,
Promise<void>
> = new WeakMap();
const transformCache = new WeakMap();
export const reverseTransformCache = new WeakMap();
function promisifyRequest<T>(request: IDBRequest<T>): Promise<T> {
const promise = new Promise<T>((resolve, reject) => {
const unlisten = () => {
request.removeEventListener('success', success);
request.removeEventListener('error', error);
};
const success = () => {
resolve(wrap(request.result as any) as any);
unlisten();
};
const error = () => {
reject(request.error);
unlisten();
};
request.addEventListener('success', success);
request.addEventListener('error', error);
});
// This mapping exists in reverseTransformCache but doesn't exist in transformCache. This
// is because we create many promises from a single IDBRequest.
reverseTransformCache.set(promise, request);
return promise;
}
function cacheDonePromiseForTransaction(tx: IDBTransaction): void {
// Early bail if we've already created a done promise for this transaction.
if (transactionDoneMap.has(tx)) return;
const done = new Promise<void>((resolve, reject) => {
const unlisten = () => {
tx.removeEventListener('complete', complete);
tx.removeEventListener('error', error);
tx.removeEventListener('abort', error);
};
const complete = () => {
resolve();
unlisten();
};
const error = () => {
reject(tx.error || new DOMException('AbortError', 'AbortError'));
unlisten();
};
tx.addEventListener('complete', complete);
tx.addEventListener('error', error);
tx.addEventListener('abort', error);
});
// Cache it for later retrieval.
transactionDoneMap.set(tx, done);
}
let idbProxyTraps: ProxyHandler<any> = {
get(target, prop, receiver) {
if (target instanceof IDBTransaction) {
// Special handling for transaction.done.
if (prop === 'done') return transactionDoneMap.get(target);
// Make tx.store return the only store in the transaction, or undefined if there are many.
if (prop === 'store') {
return receiver.objectStoreNames[1]
? undefined
: receiver.objectStore(receiver.objectStoreNames[0]);
}
}
// Else transform whatever we get back.
return wrap(target[prop]);
},
set(target, prop, value) {
target[prop] = value;
return true;
},
has(target, prop) {
if (
target instanceof IDBTransaction &&
(prop === 'done' || prop === 'store')
) {
return true;
}
return prop in target;
},
};
export function replaceTraps(
callback: (currentTraps: ProxyHandler<any>) => ProxyHandler<any>,
): void {
idbProxyTraps = callback(idbProxyTraps);
}
function wrapFunction<T extends Func>(func: T): Function {
// Due to expected object equality (which is enforced by the caching in `wrap`), we
// only create one new func per func.
// Cursor methods are special, as the behaviour is a little more different to standard IDB. In
// IDB, you advance the cursor and wait for a new 'success' on the IDBRequest that gave you the
// cursor. It's kinda like a promise that can resolve with many values. That doesn't make sense
// with real promises, so each advance methods returns a new promise for the cursor object, or
// undefined if the end of the cursor has been reached.
if (getCursorAdvanceMethods().includes(func)) {
return function (this: IDBPCursor, ...args: Parameters<T>) {
// Calling the original function with the proxy as 'this' causes ILLEGAL INVOCATION, so we use
// the original object.
func.apply(unwrap(this), args);
return wrap(this.request);
};
}
return function (this: any, ...args: Parameters<T>) {
// Calling the original function with the proxy as 'this' causes ILLEGAL INVOCATION, so we use
// the original object.
return wrap(func.apply(unwrap(this), args));
};
}
function transformCachableValue(value: any): any {
if (typeof value === 'function') return wrapFunction(value);
// This doesn't return, it just creates a 'done' promise for the transaction,
// which is later returned for transaction.done (see idbObjectHandler).
if (value instanceof IDBTransaction) cacheDonePromiseForTransaction(value);
if (instanceOfAny(value, getIdbProxyableTypes()))
return new Proxy(value, idbProxyTraps);
// Return the same value back if we're not going to transform it.
return value;
}
/**
* Enhance an IDB object with helpers.
*
* @param value The thing to enhance.
*/
export function wrap(value: IDBDatabase): IDBPDatabase;
export function wrap(value: IDBIndex): IDBPIndex;
export function wrap(value: IDBObjectStore): IDBPObjectStore;
export function wrap(value: IDBTransaction): IDBPTransaction;
export function wrap(
value: IDBOpenDBRequest,
): Promise<IDBPDatabase | undefined>;
export function wrap<T>(value: IDBRequest<T>): Promise<T>;
export function wrap(value: any): any {
// We sometimes generate multiple promises from a single IDBRequest (eg when cursoring), because
// IDB is weird and a single IDBRequest can yield many responses, so these can't be cached.
if (value instanceof IDBRequest) return promisifyRequest(value);
// If we've already transformed this value before, reuse the transformed value.
// This is faster, but it also provides object equality.
if (transformCache.has(value)) return transformCache.get(value);
const newValue = transformCachableValue(value);
// Not all types are transformed.
// These may be primitive types, so they can't be WeakMap keys.
if (newValue !== value) {
transformCache.set(value, newValue);
reverseTransformCache.set(newValue, value);
}
return newValue;
}
/**
* Revert an enhanced IDB object to a plain old miserable IDB one.
*
* Will also revert a promise back to an IDBRequest.
*
* @param value The enhanced object to revert.
*/
interface Unwrap {
(value: IDBPCursorWithValue<any, any, any, any, any>): IDBCursorWithValue;
(value: IDBPCursor<any, any, any, any, any>): IDBCursor;
(value: IDBPDatabase<any>): IDBDatabase;
(value: IDBPIndex<any, any, any, any, any>): IDBIndex;
(value: IDBPObjectStore<any, any, any, any>): IDBObjectStore;
(value: IDBPTransaction<any, any, any>): IDBTransaction;
<T extends any>(value: Promise<IDBPDatabase<T>>): IDBOpenDBRequest;
(value: Promise<IDBPDatabase>): IDBOpenDBRequest;
<T>(value: Promise<T>): IDBRequest<T>;
}
export const unwrap: Unwrap = (value: any): any =>
reverseTransformCache.get(value);
================================================
FILE: test/index.html
================================================
<!DOCTYPE html>
<link href="../../node_modules/mocha/mocha.css" rel="stylesheet" />
<div id="mocha"></div>
<script type="module" src="index.js"></script>
================================================
FILE: test/index.ts
================================================
// Since this library proxies IDB, I haven't retested all of IDB. I've tried to cover parts of the
// library that behave differently to IDB, or may cause accidental differences.
import 'mocha/mocha';
import { deleteDatabase } from './utils';
mocha.setup('tdd');
function loadScript(url: string): Promise<void> {
return new Promise((resolve, reject) => {
const script = document.createElement('script');
script.type = 'module';
script.src = url;
script.onload = () => resolve();
script.onerror = () => reject(Error('Script load error'));
document.body.appendChild(script);
});
}
(async function () {
const edgeCompat = navigator.userAgent.includes('Edge/');
if (!edgeCompat) await loadScript('./open.js');
await loadScript('./main.js');
if (!edgeCompat) await loadScript('./iterate.js');
await deleteDatabase();
mocha.run();
})();
================================================
FILE: test/iterate.ts
================================================
// Since this library proxies IDB, I haven't retested all of IDB. I've tried to cover parts of the
// library that behave differently to IDB, or may cause accidental differences.
import 'mocha/mocha';
import { assert } from 'chai';
import { IDBPDatabase, IDBPCursorWithValueIteratorValue } from '../src/';
import '../src/async-iterators';
import { assert as typeAssert, IsExact } from 'conditional-type-checks';
import {
deleteDatabase,
openDBWithData,
TestDBSchema,
ObjectStoreValue,
} from './utils';
suite('Async iterators', () => {
let db: IDBPDatabase;
teardown('Close DB', async () => {
if (db) db.close();
await deleteDatabase();
});
test('object stores', async () => {
const schemaDB = await openDBWithData();
db = schemaDB as IDBPDatabase;
{
const store = schemaDB.transaction('key-val-store').store;
const keys = [];
const values = [];
assert.isTrue(Symbol.asyncIterator in store);
for await (const cursor of store) {
typeAssert<
IsExact<
typeof cursor,
IDBPCursorWithValueIteratorValue<
TestDBSchema,
['key-val-store'],
'key-val-store',
unknown
>
>
>(true);
typeAssert<IsExact<typeof cursor.key, string>>(true);
typeAssert<IsExact<typeof cursor.value, number>>(true);
keys.push(cursor.key);
values.push(cursor.value);
}
assert.deepEqual(values, [456, 123, 789], 'Correct values');
assert.deepEqual(keys, ['bar', 'foo', 'hello'], 'Correct keys');
}
{
const store = db.transaction('key-val-store').store;
const keys = [];
const values = [];
for await (const cursor of store) {
typeAssert<
IsExact<
typeof cursor,
IDBPCursorWithValueIteratorValue<
unknown,
['key-val-store'],
'key-val-store',
unknown
>
>
>(true);
typeAssert<IsExact<typeof cursor.key, IDBValidKey>>(true);
typeAssert<IsExact<typeof cursor.value, any>>(true);
keys.push(cursor.key);
values.push(cursor.value);
}
assert.deepEqual(values, [456, 123, 789], 'Correct values');
assert.deepEqual(keys, ['bar', 'foo', 'hello'], 'Correct keys');
}
});
test('object stores iterate', async () => {
const schemaDB = await openDBWithData();
db = schemaDB as IDBPDatabase;
{
const store = schemaDB.transaction('key-val-store').store;
assert.property(store, 'iterate');
typeAssert<
IsExact<
Parameters<typeof store.iterate>[0],
string | IDBKeyRange | undefined | null
>
>(true);
for await (const _ of store.iterate('blah')) {
assert.fail('This should not be called');
}
}
{
const store = db.transaction('key-val-store').store;
typeAssert<
IsExact<
Parameters<typeof store.iterate>[0],
IDBValidKey | IDBKeyRange | undefined | null
>
>(true);
for await (const _ of store.iterate('blah')) {
assert.fail('This should not be called');
}
}
});
test('Can delete during iteration', async () => {
const schemaDB = await openDBWithData();
db = schemaDB as IDBPDatabase;
const tx = schemaDB.transaction('key-val-store', 'readwrite');
for await (const cursor of tx.store) {
cursor.delete();
}
assert.strictEqual(await schemaDB.count('key-val-store'), 0);
});
test('index', async () => {
const schemaDB = await openDBWithData();
db = schemaDB as IDBPDatabase;
{
const index = schemaDB.transaction('object-store').store.index('date');
const keys = [];
const values = [];
assert.isTrue(Symbol.asyncIterator in index);
for await (const cursor of index) {
typeAssert<
IsExact<
typeof cursor,
IDBPCursorWithValueIteratorValue<
TestDBSchema,
['object-store'],
'object-store',
'date'
>
>
>(true);
typeAssert<IsExact<typeof cursor.key, Date>>(true);
typeAssert<IsExact<typeof cursor.value, ObjectStoreValue>>(true);
keys.push(cursor.key);
values.push(cursor.value);
}
assert.deepEqual(
values,
[
{
id: 4,
title: 'Article 4',
date: new Date('2019-01-01'),
},
{
id: 3,
title: 'Article 3',
date: new Date('2019-01-02'),
},
{
id: 2,
title: 'Article 2',
date: new Date('2019-01-03'),
},
{
id: 1,
title: 'Article 1',
date: new Date('2019-01-04'),
},
],
'Correct values',
);
assert.deepEqual(
keys,
[
new Date('2019-01-01'),
new Date('2019-01-02'),
new Date('2019-01-03'),
new Date('2019-01-04'),
],
'Correct keys',
);
}
{
const index = db.transaction('object-store').store.index('title');
const keys = [];
const values = [];
assert.isTrue(Symbol.asyncIterator in index);
for await (const cursor of index) {
typeAssert<
IsExact<
typeof cursor,
IDBPCursorWithValueIteratorValue<
unknown,
['object-store'],
'object-store',
'title'
>
>
>(true);
typeAssert<IsExact<typeof cursor.key, IDBValidKey>>(true);
typeAssert<IsExact<typeof cursor.value, any>>(true);
keys.push(cursor.key);
values.push(cursor.value);
}
assert.deepEqual(
values,
[
{
id: 1,
title: 'Article 1',
date: new Date('2019-01-04'),
},
{
id: 2,
title: 'Article 2',
date: new Date('2019-01-03'),
},
{
id: 3,
title: 'Article 3',
date: new Date('2019-01-02'),
},
{
id: 4,
title: 'Article 4',
date: new Date('2019-01-01'),
},
],
'Correct values',
);
assert.deepEqual(
keys,
['Article 1', 'Article 2', 'Article 3', 'Article 4'],
'Correct keys',
);
}
});
test('index iterate', async () => {
const schemaDB = await openDBWithData();
db = schemaDB as IDBPDatabase;
{
const index = schemaDB.transaction('object-store').store.index('date');
assert.property(index, 'iterate');
typeAssert<
IsExact<
Parameters<typeof index.iterate>[0],
Date | IDBKeyRange | undefined | null
>
>(true);
for await (const _ of index.iterate(new Date('2020-01-01'))) {
assert.fail('This should not be called');
}
}
{
const index = db.transaction('object-store').store.index('title');
assert.property(index, 'iterate');
typeAssert<
IsExact<
Parameters<typeof index.iterate>[0],
IDBValidKey | IDBKeyRange | undefined | null
>
>(true);
for await (const _ of index.iterate('foo')) {
assert.fail('This should not be called');
}
}
});
test('cursor', async () => {
const schemaDB = await openDBWithData();
db = schemaDB as IDBPDatabase;
const store = schemaDB.transaction('key-val-store').store;
const cursor = await store.openCursor();
if (!cursor) throw Error('expected cursor');
const keys = [];
const values = [];
assert.isTrue(Symbol.asyncIterator in cursor);
for await (const cursorIter of cursor) {
typeAssert<
IsExact<
typeof cursorIter,
IDBPCursorWithValueIteratorValue<
TestDBSchema,
['key-val-store'],
'key-val-store',
unknown
>
>
>(true);
typeAssert<IsExact<typeof cursorIter.key, string>>(true);
typeAssert<IsExact<typeof cursorIter.value, number>>(true);
keys.push(cursorIter.key);
values.push(cursorIter.value);
}
assert.deepEqual(values, [456, 123, 789], 'Correct values');
assert.deepEqual(keys, ['bar', 'foo', 'hello'], 'Correct keys');
});
});
================================================
FILE: test/main.ts
================================================
import 'mocha/mocha';
import { assert } from 'chai';
import {
IDBPDatabase,
IDBPTransaction,
wrap,
unwrap,
IDBPObjectStore,
IDBPCursorWithValue,
IDBPCursor,
IDBPIndex,
TypedDOMStringList,
openDB,
DBSchema,
} from '../src';
import { assert as typeAssert, IsExact } from 'conditional-type-checks';
import {
deleteDatabase,
openDBWithSchema,
openDBWithData,
ObjectStoreValue,
TestDBSchema,
getNextVersion,
dbName,
} from './utils';
suite('IDBPDatabase', () => {
let db: IDBPDatabase;
teardown('Close DB', async () => {
if (db) db.close();
await deleteDatabase();
});
test('objectStoreNames', async () => {
const schemaDB = await openDBWithSchema();
db = schemaDB as IDBPDatabase;
typeAssert<
IsExact<
typeof schemaDB.objectStoreNames,
TypedDOMStringList<'key-val-store' | 'object-store'>
>
>(true);
typeAssert<IsExact<typeof db.objectStoreNames, TypedDOMStringList<string>>>(
true,
);
});
test('createObjectStore', async () => {
const schemaDB = await openDBWithSchema();
db = schemaDB as IDBPDatabase;
typeAssert<
IsExact<
Parameters<typeof schemaDB.createObjectStore>[0],
'key-val-store' | 'object-store'
>
>(true);
typeAssert<IsExact<Parameters<typeof db.createObjectStore>[0], string>>(
true,
);
});
test('deleteObjectStore', async () => {
const schemaDB = await openDBWithSchema();
db = schemaDB as IDBPDatabase;
typeAssert<
IsExact<
Parameters<typeof schemaDB.deleteObjectStore>[0],
'key-val-store' | 'object-store'
>
>(true);
typeAssert<IsExact<Parameters<typeof db.deleteObjectStore>[0], string>>(
true,
);
});
test('transaction', async () => {
const schemaDB = await openDBWithSchema();
db = schemaDB as IDBPDatabase;
typeAssert<
IsExact<
Parameters<typeof schemaDB.transaction>[0],
ArrayLike<'key-val-store' | 'object-store'>
>
>(true);
typeAssert<
IsExact<Parameters<typeof db.transaction>[0], ArrayLike<string>>
>(true);
// Function getters should return the same instance.
assert.strictEqual(db.transaction, db.transaction, 'transaction');
});
test('transaction - all stores', async () => {
const schemaDB = await openDBWithSchema();
db = schemaDB as IDBPDatabase;
const tx = schemaDB.transaction(schemaDB.objectStoreNames);
const tx2 = db.transaction(db.objectStoreNames);
typeAssert<
IsExact<
typeof tx.objectStoreNames,
TypedDOMStringList<'key-val-store' | 'object-store'>
>
>(true);
typeAssert<
IsExact<typeof tx2.objectStoreNames, TypedDOMStringList<string>>
>(true);
});
test('get', async () => {
const schemaDB = await openDBWithData();
db = schemaDB as IDBPDatabase;
assert.property(schemaDB, 'get', 'Method exists');
typeAssert<
IsExact<
Parameters<typeof schemaDB.get>[0],
'key-val-store' | 'object-store'
>
>(true);
const val = await schemaDB.get('key-val-store', 'foo');
typeAssert<IsExact<typeof val, number | undefined>>(true);
assert.strictEqual(val, 123, 'Correct value from store');
const val2 = await db.get('key-val-store', 'bar');
typeAssert<IsExact<typeof val2, any>>(true);
assert.strictEqual(val2, 456, 'Correct value from store');
});
test('getFromIndex', async () => {
const schemaDB = await openDBWithData();
db = schemaDB as IDBPDatabase;
assert.property(schemaDB, 'getFromIndex', 'Method exists');
const val = await schemaDB.getFromIndex(
'object-store',
'title',
'Article 1',
);
typeAssert<IsExact<typeof val, ObjectStoreValue | undefined>>(true);
assert.deepStrictEqual(
val,
{
id: 1,
title: 'Article 1',
date: new Date('2019-01-04'),
},
'Correct value from store',
);
const val2 = await db.getFromIndex('object-store', 'title', 'Article 2');
typeAssert<IsExact<typeof val2, any>>(true);
assert.deepStrictEqual(
val2,
{
id: 2,
title: 'Article 2',
date: new Date('2019-01-03'),
},
'Correct value from store',
);
});
test('getKey', async function () {
if (!('getKey' in IDBObjectStore.prototype)) this.skip();
const schemaDB = await openDBWithData();
db = schemaDB as IDBPDatabase;
assert.property(schemaDB, 'getKey', 'Method exists');
typeAssert<
IsExact<
Parameters<typeof schemaDB.getKey>[0],
'key-val-store' | 'object-store'
>
>(true);
const val = await schemaDB.getKey(
'key-val-store',
IDBKeyRange.lowerBound('a'),
);
typeAssert<IsExact<typeof val, string | undefined>>(true);
assert.strictEqual(val, 'bar', 'Correct value');
const val2 = await db.getKey('key-val-store', IDBKeyRange.lowerBound('c'));
typeAssert<IsExact<typeof val2, IDBValidKey | undefined>>(true);
assert.strictEqual(val2, 'foo', 'Correct value');
});
test('getKeyFromIndex', async function () {
if (!('getKey' in IDBObjectStore.prototype)) this.skip();
const schemaDB = await openDBWithData();
db = schemaDB as IDBPDatabase;
assert.property(schemaDB, 'getKeyFromIndex', 'Method exists');
const val = await schemaDB.getKeyFromIndex(
'object-store',
'title',
IDBKeyRange.lowerBound('A'),
);
typeAssert<IsExact<typeof val, number | undefined>>(true);
assert.strictEqual(val, 1, 'Correct value');
const val2 = await db.getKeyFromIndex(
'object-store',
'date',
IDBKeyRange.lowerBound(new Date('1990-01-01')),
);
typeAssert<IsExact<typeof val2, IDBValidKey | undefined>>(true);
assert.strictEqual(val2, 4, 'Correct value');
});
test('getAll', async function () {
if (!('getAll' in IDBObjectStore.prototype)) this.skip();
const schemaDB = await openDBWithData();
db = schemaDB as IDBPDatabase;
assert.property(schemaDB, 'getAll', 'Method exists');
typeAssert<
IsExact<
Parameters<typeof schemaDB.getAll>[0],
'key-val-store' | 'object-store'
>
>(true);
const val = await schemaDB.getAll('key-val-store');
typeAssert<IsExact<typeof val, number[]>>(true);
assert.deepStrictEqual(val, [456, 123, 789], 'Correct values from store');
const val2 = await db.getAll('key-val-store');
typeAssert<IsExact<typeof val2, any[]>>(true);
assert.deepStrictEqual(val2, [456, 123, 789], 'Correct values from store');
});
test('getAllFromIndex', async function () {
if (!('getAll' in IDBObjectStore.prototype)) this.skip();
const schemaDB = await openDBWithData();
db = schemaDB as IDBPDatabase;
assert.property(schemaDB, 'getAllFromIndex', 'Method exists');
const val = await schemaDB.getAllFromIndex('object-store', 'date');
typeAssert<IsExact<typeof val, ObjectStoreValue[]>>(true);
assert.deepStrictEqual(
val,
[
{
id: 4,
title: 'Article 4',
date: new Date('2019-01-01'),
},
{
id: 3,
title: 'Article 3',
date: new Date('2019-01-02'),
},
{
id: 2,
title: 'Article 2',
date: new Date('2019-01-03'),
},
{
id: 1,
title: 'Article 1',
date: new Date('2019-01-04'),
},
],
'Correct values from store',
);
const val2 = await db.getAllFromIndex('object-store', 'title');
typeAssert<IsExact<typeof val2, any[]>>(true);
assert.deepStrictEqual(
val2,
[
{
id: 1,
title: 'Article 1',
date: new Date('2019-01-04'),
},
{
id: 2,
title: 'Article 2',
date: new Date('2019-01-03'),
},
{
id: 3,
title: 'Article 3',
date: new Date('2019-01-02'),
},
{
id: 4,
title: 'Article 4',
date: new Date('2019-01-01'),
},
],
'Correct values from store',
);
});
test('getAllKeys', async function () {
if (!('getAllKeys' in IDBObjectStore.prototype)) this.skip();
const schemaDB = await openDBWithData();
db = schemaDB as IDBPDatabase;
assert.property(schemaDB, 'getAllKeys', 'Method exists');
typeAssert<
IsExact<
Parameters<typeof schemaDB.getAllKeys>[0],
'key-val-store' | 'object-store'
>
>(true);
const val = await schemaDB.getAllKeys('key-val-store');
typeAssert<IsExact<typeof val, string[]>>(true);
assert.deepStrictEqual(
val,
['bar', 'foo', 'hello'],
'Correct values from store',
);
const val2 = await db.getAllKeys('key-val-store');
typeAssert<IsExact<typeof val2, IDBValidKey[]>>(true);
assert.deepStrictEqual(
val2,
['bar', 'foo', 'hello'],
'Correct values from store',
);
});
test('getAllKeysFromIndex', async function () {
if (!('getAllKeys' in IDBObjectStore.prototype)) this.skip();
const schemaDB = await openDBWithData();
db = schemaDB as IDBPDatabase;
assert.property(schemaDB, 'getAllKeysFromIndex', 'Method exists');
const val = await schemaDB.getAllKeysFromIndex('object-store', 'date');
typeAssert<IsExact<typeof val, number[]>>(true);
assert.deepStrictEqual(val, [4, 3, 2, 1], 'Correct values from store');
const val2 = await db.getAllKeysFromIndex('object-store', 'title');
typeAssert<IsExact<typeof val2, IDBValidKey[]>>(true);
assert.deepStrictEqual(val2, [1, 2, 3, 4], 'Correct values from store');
});
test('count', async () => {
const schemaDB = await openDBWithData();
db = schemaDB as IDBPDatabase;
assert.property(schemaDB, 'count', 'Method exists');
typeAssert<
IsExact<
Parameters<typeof schemaDB.count>[0],
'key-val-store' | 'object-store'
>
>(true);
const val = await schemaDB.count('key-val-store');
typeAssert<IsExact<typeof val, number>>(true);
assert.strictEqual(val, 3, 'Correct count');
const val2 = await db.count('object-store');
typeAssert<IsExact<typeof val2, number>>(true);
assert.strictEqual(val2, 4, 'Correct count');
});
test('countFromIndex', async () => {
const schemaDB = await openDBWithData();
db = schemaDB as IDBPDatabase;
assert.property(schemaDB, 'countFromIndex', 'Method exists');
const val = await schemaDB.countFromIndex('object-store', 'date');
typeAssert<IsExact<typeof val, number>>(true);
assert.strictEqual(val, 4, 'Correct count');
const val2 = await db.countFromIndex(
'object-store',
'title',
IDBKeyRange.lowerBound('Article 10'),
);
typeAssert<IsExact<typeof val2, number>>(true);
assert.strictEqual(val2, 3, 'Correct count');
});
test('put', async () => {
const schemaDB = await openDBWithData();
db = schemaDB as IDBPDatabase;
assert.property(schemaDB, 'put', 'Method exists');
typeAssert<
IsExact<
Parameters<typeof schemaDB.put>[0],
'key-val-store' | 'object-store'
>
>(true);
const key = await schemaDB.put('key-val-store', 234, 'new');
typeAssert<IsExact<typeof key, string>>(true);
assert.strictEqual(key, 'new');
const val = await schemaDB.get('key-val-store', 'new');
assert.strictEqual(val, 234, 'Correct value from store');
const key2 = await db.put('object-store', {
id: 5,
title: 'Article 5',
date: new Date('2018-05-09'),
});
typeAssert<IsExact<typeof key2, IDBValidKey>>(true);
assert.strictEqual(key2, 5);
const val2 = await db.get('object-store', 5);
typeAssert<IsExact<typeof val2, any>>(true);
assert.deepStrictEqual(
val2,
{
id: 5,
title: 'Article 5',
date: new Date('2018-05-09'),
},
'Correct value from store',
);
});
test('add', async () => {
const schemaDB = await openDBWithData();
db = schemaDB as IDBPDatabase;
assert.property(schemaDB, 'add', 'Method exists');
typeAssert<
IsExact<
Parameters<typeof schemaDB.add>[0],
'key-val-store' | 'object-store'
>
>(true);
const key = await schemaDB.add('key-val-store', 234, 'new');
typeAssert<IsExact<typeof key, string>>(true);
assert.strictEqual(key, 'new');
const val = await schemaDB.get('key-val-store', 'new');
assert.strictEqual(val, 234, 'Correct value from store');
const key2 = await db.add('object-store', {
id: 5,
title: 'Article 5',
date: new Date('2018-05-09'),
});
typeAssert<IsExact<typeof key2, IDBValidKey>>(true);
assert.strictEqual(key2, 5);
const val2 = await db.get('object-store', 5);
typeAssert<IsExact<typeof val2, any>>(true);
assert.deepStrictEqual(
val2,
{
id: 5,
title: 'Article 5',
date: new Date('2018-05-09'),
},
'Correct value from store',
);
});
test('add - error type', async () => {
const schemaDB = await openDBWithData();
db = schemaDB as IDBPDatabase;
// This test ensures the shortcut methods correctly pass-through the
// error generated by the operation, rather then deferring to the
// transaction abort.
try {
await schemaDB.add('object-store', {
title: 'Foo',
date: new Date(),
id: 1,
});
const error = new Error(`Didn't throw`);
error.name = 'DidntThrowError';
throw error;
} catch (error) {
assert.instanceOf(error, DOMException);
assert.strictEqual((error as DOMException).name, 'ConstraintError');
}
});
test('add - avoid unhandled rejection', async () => {
let unhandledRejection = false;
let errored = false;
const onUnhandledRejection = () => (unhandledRejection = true);
self.addEventListener('unhandledrejection', onUnhandledRejection);
const schemaDB = await openDBWithData();
db = schemaDB as IDBPDatabase;
try {
await schemaDB.add('key-val-store', 123, 'foo');
} catch (err) {
errored = true;
}
// Wait for a frame so tasks are processed
await new Promise((r) => requestAnimationFrame(r));
assert.isTrue(errored, 'Add errored');
assert.isFalse(unhandledRejection, 'No unhandled rejection');
self.removeEventListener('unhandledrejection', onUnhandledRejection);
});
test('delete', async () => {
const schemaDB = await openDBWithData();
db = schemaDB as IDBPDatabase;
assert.property(schemaDB, 'delete', 'Method exists');
typeAssert<
IsExact<
Parameters<typeof schemaDB.delete>[0],
'key-val-store' | 'object-store'
>
>(true);
await schemaDB.delete('key-val-store', 'foo');
const val = await schemaDB.get('key-val-store', 'foo');
assert.strictEqual(val, undefined, 'Correct value from store');
await db.delete('object-store', 1);
const val2 = await db.get('object-store', 1);
assert.strictEqual(val2, undefined, 'Correct value from store');
});
test('clear', async () => {
const schemaDB = await openDBWithData();
db = schemaDB as IDBPDatabase;
assert.property(schemaDB, 'clear', 'Method exists');
typeAssert<
IsExact<
Parameters<typeof schemaDB.clear>[0],
'key-val-store' | 'object-store'
>
>(true);
await schemaDB.clear('key-val-store');
const val = await schemaDB.count('key-val-store');
assert.strictEqual(val, 0, 'Correct value from store');
await db.clear('object-store');
const val2 = await db.count('object-store');
assert.strictEqual(val2, 0, 'Correct value from store');
});
});
suite('IDBPTransaction', () => {
let db: IDBPDatabase;
teardown('Close DB', async () => {
if (db) db.close();
});
test('mode', async () => {
const schemaDB = await openDBWithSchema();
db = schemaDB as IDBPDatabase;
const tx1 = schemaDB.transaction('key-val-store');
const tx2 = schemaDB.transaction('key-val-store', 'readonly');
const tx3 = schemaDB.transaction('key-val-store', 'readwrite');
typeAssert<IsExact<typeof tx1, typeof tx2>>(true);
typeAssert<IsExact<typeof tx1, typeof tx3>>(false);
});
test('objectStoreNames', async () => {
const schemaDB = await openDBWithSchema();
db = schemaDB as IDBPDatabase;
const tx1 = schemaDB.transaction('key-val-store');
const tx2 = schemaDB.transaction('object-store');
const tx3 = schemaDB.transaction(['object-store', 'key-val-store']);
typeAssert<
IsExact<typeof tx1.objectStoreNames, TypedDOMStringList<'key-val-store'>>
>(true);
typeAssert<
IsExact<typeof tx2.objectStoreNames, TypedDOMStringList<'object-store'>>
>(true);
typeAssert<
IsExact<
typeof tx3.objectStoreNames,
TypedDOMStringList<'object-store' | 'key-val-store'>
>
>(true);
// Without schema it should still work:
const tx4 = db.transaction('key-val-store');
typeAssert<
IsExact<typeof tx4.objectStoreNames, TypedDOMStringList<'key-val-store'>>
>(true);
});
test('db', async () => {
const schemaDB = await openDBWithSchema();
db = schemaDB as IDBPDatabase;
const tx = schemaDB.transaction('key-val-store');
typeAssert<IsExact<typeof tx.db, IDBPDatabase<TestDBSchema>>>(true);
const tx2 = db.transaction('key-val-store');
typeAssert<IsExact<typeof tx2.db, IDBPDatabase>>(true);
});
test('done', async () => {
const schemaDB = await openDBWithSchema();
db = schemaDB as IDBPDatabase;
const tx = schemaDB.transaction('key-val-store');
assert.property(tx, 'done');
assert.instanceOf(tx.done, Promise);
});
test('store', async () => {
const schemaDB = await openDBWithSchema();
db = schemaDB as IDBPDatabase;
const tx = schemaDB.transaction('key-val-store');
assert.property(tx, 'store');
typeAssert<
IsExact<
typeof tx.store,
IDBPObjectStore<TestDBSchema, ['key-val-store'], 'key-val-store'>
>
>(true);
assert.strictEqual(tx.store.name, 'key-val-store');
assert.instanceOf(tx.store.get('blah'), Promise, 'Is the store wrapped?');
assert.instanceOf(tx.store, IDBObjectStore);
const tx2 = schemaDB.transaction(['key-val-store', 'object-store']);
assert.property(tx2, 'store');
typeAssert<IsExact<typeof tx2.store, undefined>>(true);
assert.isUndefined(tx2.store);
});
test('objectStore', async () => {
const schemaDB = await openDBWithSchema();
db = schemaDB as IDBPDatabase;
const tx1 = schemaDB.transaction('key-val-store');
const tx2 = schemaDB.transaction('key-val-store');
const tx3 = schemaDB.transaction(['key-val-store', 'object-store']);
const tx4 = db.transaction('object-store');
// Functions should be equal across instances.
assert.strictEqual(tx1.objectStore, tx2.objectStore);
typeAssert<IsExact<Parameters<typeof tx1.objectStore>[0], 'key-val-store'>>(
true,
);
typeAssert<
IsExact<
Parameters<typeof tx3.objectStore>[0],
'key-val-store' | 'object-store'
>
>(true);
typeAssert<IsExact<Parameters<typeof tx4.objectStore>[0], 'object-store'>>(
true,
);
// The spec says object stores from the same transaction should be equal.
assert.strictEqual(
tx1.objectStore('key-val-store'),
tx1.objectStore('key-val-store'),
'objectStore on same tx',
);
// The spec says object stores from different transaction should not be equal.
assert.notEqual(
tx1.objectStore('key-val-store'),
tx2.objectStore('key-val-store'),
'objectStore on different tx',
);
const store = tx1.objectStore('key-val-store');
const schemalessStore = tx4.objectStore('object-store');
typeAssert<
IsExact<
typeof store,
IDBPObjectStore<TestDBSchema, ['key-val-store'], 'key-val-store'>
>
>(true);
typeAssert<
IsExact<
typeof schemalessStore,
IDBPObjectStore<unknown, ['object-store'], 'object-store'>
>
>(true);
assert.strictEqual(store.name, 'key-val-store');
assert.strictEqual(schemalessStore.name, 'object-store');
});
test('abort', async () => {
const schemaDB = await openDBWithSchema();
db = schemaDB as IDBPDatabase;
const tx = schemaDB.transaction('key-val-store');
tx.abort();
let threw = false;
let error: Error | null = null;
try {
await tx.done;
} catch (e) {
threw = true;
error = e as Error;
}
assert(threw, 'Done threw');
assert.instanceOf(error, DOMException);
assert.strictEqual(error?.name, 'AbortError');
});
test('wrap', async () => {
const schemaDB = await openDBWithSchema();
db = schemaDB as IDBPDatabase;
const idb = unwrap(db);
const tx = idb.transaction('key-val-store');
assert.notProperty(tx, 'store');
const wrappedTx = wrap(tx);
typeAssert<
IsExact<typeof wrappedTx, IDBPTransaction<unknown, ArrayLike<string>>>
>(true);
assert.property(wrappedTx, 'store');
});
test('unwrap', async () => {
const schemaDB = await openDBWithSchema();
db = schemaDB as IDBPDatabase;
const tx = schemaDB.transaction('key-val-store');
const tx2 = db.transaction('key-val-store');
const tx3 = schemaDB.transaction('key-val-store', 'readwrite');
const unwrappedTx = unwrap(tx);
const unwrappedTx2 = unwrap(tx2);
const unwrappedTx3 = unwrap(tx3);
typeAssert<IsExact<typeof unwrappedTx, IDBTransaction>>(true);
typeAssert<IsExact<typeof unwrappedTx2, IDBTransaction>>(true);
typeAssert<IsExact<typeof unwrappedTx3, IDBTransaction>>(true);
assert.notProperty(unwrappedTx, 'store');
assert.notProperty(unwrappedTx2, 'store');
assert.notProperty(unwrappedTx3, 'store');
});
});
export interface RenamedDBSchema extends DBSchema {
'key-val-store-renamed': {
key: string;
value: number;
};
'object-store': {
value: ObjectStoreValue;
key: number;
indexes: { 'date-renamed': Date; title: string };
};
}
suite('IDBPObjectStore', () => {
let db: IDBPDatabase;
teardown('Close DB', async () => {
if (db) db.close();
await deleteDatabase();
});
test('mode', async () => {
const schemaDB = await openDBWithSchema();
db = schemaDB as IDBPDatabase;
const store1 = schemaDB.transaction('key-val-store', 'readonly').store;
const store2 = schemaDB.transaction('key-val-store', 'readwrite').store;
typeAssert<
IsExact<
typeof store1,
IDBPObjectStore<
TestDBSchema,
['key-val-store'],
'key-val-store',
'readonly'
>
>
>(true);
typeAssert<
IsExact<
typeof store2,
IDBPObjectStore<
TestDBSchema,
['key-val-store'],
'key-val-store',
'readwrite'
>
>
>(true);
typeAssert<IsExact<typeof store1.add, undefined>>(true);
typeAssert<IsExact<typeof store1.put, undefined>>(true);
typeAssert<IsExact<typeof store1.delete, undefined>>(true);
typeAssert<IsExact<typeof store1.clear, undefined>>(true);
typeAssert<IsExact<typeof store1.createIndex, undefined>>(true);
typeAssert<
IsExact<
typeof store2.add,
(
value: number,
key?: string | IDBKeyRange | undefined,
) => Promise<string>
>
>(true);
typeAssert<
IsExact<
typeof store2.put,
(
value: number,
key?: string | IDBKeyRange | undefined,
) => Promise<string>
>
>(true);
typeAssert<
IsExact<
typeof store2.delete,
(key: string | IDBKeyRange) => Promise<void>
>
>(true);
typeAssert<IsExact<typeof store2.clear, () => Promise<void>>>(true);
typeAssert<IsExact<typeof store2.createIndex, undefined>>(true);
});
test('indexNames', async () => {
const schemaDB = await openDBWithSchema();
db = schemaDB as IDBPDatabase;
const tx = schemaDB.transaction('object-store');
const tx2 = db.transaction('object-store');
typeAssert<
IsExact<typeof tx.store.indexNames, TypedDOMStringList<'date' | 'title'>>
>(true);
typeAssert<
IsExact<typeof tx2.store.indexNames, TypedDOMStringList<string>>
>(true);
});
test('set name', async () => {
const schemaDB = await openDBWithSchema();
schemaDB.close();
const newDB = await openDB<RenamedDBSchema>(dbName, getNextVersion(), {
upgrade(db, oldVersion, newVersion, tx) {
const store = (tx as unknown as IDBPTransaction).objectStore(
'key-val-store',
);
store.name = 'key-val-store-renamed';
},
});
db = newDB as IDBPDatabase;
assert(newDB.objectStoreNames.contains('key-val-store-renamed'));
});
test('transaction', async () => {
const schemaDB = await openDBWithSchema();
db = schemaDB as IDBPDatabase;
const tx = schemaDB.transaction('object-store');
const tx2 = db.transaction('object-store');
const store = schemaDB
.transaction(['object-store', 'key-val-store'])
.objectStore('object-store');
typeAssert<
IsExact<
typeof tx.store.transaction,
IDBPTransaction<TestDBSchema, ['object-store']>
>
>(true);
typeAssert<
IsExact<
typeof tx2.store.transaction,
IDBPTransaction<unknown, ['object-store']>
>
>(true);
typeAssert<
IsExact<
typeof store.transaction,
IDBPTransaction<TestDBSchema, ('object-store' | 'key-val-store')[]>
>
>(true);
});
test('add', async () => {
const schemaDB = await openDBWithData();
db = schemaDB as IDBPDatabase;
const store1 = schemaDB.transaction('key-val-store', 'readwrite').store;
typeAssert<IsExact<Parameters<typeof store1.add>[0], number>>(true);
typeAssert<
IsExact<
Parameters<typeof store1.add>[1],
string | IDBKeyRange | undefined
>
>(true);
const key = await store1.add(234, 'new');
typeAssert<IsExact<typeof key, string>>(true);
const val = await store1.get('new');
assert.strictEqual(val, 234, 'Correct value from store');
const store2 = db.transaction('object-store', 'readwrite').store;
typeAssert<IsExact<Parameters<typeof store2.add>[0], any>>(true);
typeAssert<
IsExact<
Parameters<typeof store2.add>[1],
IDBValidKey | IDBKeyRange | undefined
>
>(true);
const key2 = await store2.add({
id: 5,
title: 'Article 5',
date: new Date('2018-05-09'),
});
typeAssert<IsExact<typeof key2, IDBValidKey>>(true);
const val2 = await store2.get(5);
typeAssert<IsExact<typeof val2, any>>(true);
assert.deepStrictEqual(
val2,
{
id: 5,
title: 'Article 5',
date: new Date('2018-05-09'),
},
'Correct value from store',
);
});
test('clear', async () => {
const schemaDB = await openDBWithData();
db = schemaDB as IDBPDatabase;
const store1 = schemaDB.transaction('key-val-store', 'readwrite').store;
store1.clear();
const val = await store1.count();
assert.strictEqual(val, 0, 'Correct value from store');
const store2 = db.transaction('object-store', 'readwrite').store;
store2.clear();
const val2 = await store2.count();
assert.strictEqual(val2, 0, 'Correct value from store');
});
test('count', async () => {
const schemaDB = await openDBWithData();
db = schemaDB as IDBPDatabase;
const store1 = schemaDB.transaction('key-val-store').store;
typeAssert<
IsExact<
Parameters<typeof store1.count>[0],
string | IDBKeyRange | undefined | null
>
>(true);
const val = await store1.count();
typeAssert<IsExact<typeof val, number>>(true);
assert.strictEqual(val, 3, 'Correct count');
const store2 = db.transaction('object-store').store;
typeAssert<
IsExact<
Parameters<typeof store2.count>[0],
IDBValidKey | IDBKeyRange | undefined | null
>
>(true);
const val2 = await store2.count();
typeAssert<IsExact<typeof val2, number>>(true);
assert.strictEqual(val2, 4, 'Correct count');
});
test('createIndex (db with DBTypes)', async () => {
db = (await openDB<TestDBSchema>(dbName, getNextVersion(), {
upgrade(db, oldVersion, newVersion, tx) {
const store = db.createObjectStore('object-store');
typeAssert<
IsExact<Parameters<typeof store.createIndex>[0], 'date' | 'title'>
>(true);
},
})) as IDBPDatabase;
});
test('createIndex (db without DBTypes)', async () => {
db = (await openDB(dbName, getNextVersion(), {
upgrade(db, oldVersion, newVersion, tx) {
const store = db.createObjectStore('object-store');
typeAssert<IsExact<Parameters<typeof store.createIndex>[0], string>>(
true,
);
},
})) as IDBPDatabase;
});
test('delete', async () => {
const schemaDB = await openDBWithData();
db = schemaDB as IDBPDatabase;
const store1 = schemaDB.transaction('key-val-store', 'readwrite').store;
typeAssert<
IsExact<Parameters<typeof store1.delete>[0], string | IDBKeyRange>
>(true);
await store1.delete('foo');
const val = await store1.get('foo');
assert.strictEqual(val, undefined, 'Correct value from store');
const store2 = db.transaction('object-store', 'readwrite').store;
typeAssert<
IsExact<Parameters<typeof store2.delete>[0], IDBValidKey | IDBKeyRange>
>(true);
await store2.delete(1);
const val2 = await store2.get(1);
assert.strictEqual(val2, undefined, 'Correct value from store');
});
test('get', async () => {
const schemaDB = await openDBWithData();
db = schemaDB as IDBPDatabase;
const store1 = schemaDB.transaction('key-val-store').store;
typeAssert<IsExact<Parameters<typeof store1.get>[0], string | IDBKeyRange>>(
true,
);
const val = await store1.get('foo');
typeAssert<IsExact<typeof val, number | undefined>>(true);
assert.strictEqual(val, 123, 'Correct value from store');
const store2 = db.transaction('key-val-store').store;
typeAssert<
IsExact<Parameters<typeof store2.get>[0], IDBValidKey | IDBKeyRange>
>(true);
const val2 = await store2.get('bar');
typeAssert<IsExact<typeof val2, any>>(true);
assert.strictEqual(val2, 456, 'Correct value from store');
});
test('getAll', async function () {
if (!('getAll' in IDBObjectStore.prototype)) this.skip();
const schemaDB = await openDBWithData();
db = schemaDB as IDBPDatabase;
const store1 = schemaDB.transaction('key-val-store').store;
typeAssert<
IsExact<
Parameters<typeof store1.getAll>[0],
string | IDBKeyRange | undefined | null
>
>(true);
const val = await store1.getAll();
typeAssert<IsExact<typeof val, number[]>>(true);
assert.deepStrictEqual(val, [456, 123, 789], 'Correct values from store');
const store2 = db.transaction('key-val-store').store;
typeAssert<
IsExact<
Parameters<typeof store2.getAll>[0],
IDBValidKey | IDBKeyRange | undefined | null
>
>(true);
const val2 = await store2.getAll();
typeAssert<IsExact<typeof val2, any[]>>(true);
assert.deepStrictEqual(val2, [456, 123, 789], 'Correct values from store');
});
test('getAllKeys', async function () {
if (!('getAllKeys' in IDBObjectStore.prototype)) this.skip();
const schemaDB = await openDBWithData();
db = schemaDB as IDBPDatabase;
const store1 = schemaDB.transaction('key-val-store').store;
typeAssert<
IsExact<
Parameters<typeof store1.getAllKeys>[0],
string | IDBKeyRange | undefined | null
>
>(true);
const val = await store1.getAllKeys();
typeAssert<IsExact<typeof val, string[]>>(true);
assert.deepStrictEqual(
val,
['bar', 'foo', 'hello'],
'Correct values from store',
);
const store2 = db.transaction('key-val-store').store;
typeAssert<
IsExact<
Parameters<typeof store2.getAllKeys>[0],
IDBValidKey | IDBKeyRange | undefined | null
>
>(true);
const val2 = await store2.getAllKeys();
typeAssert<IsExact<typeof val2, IDBValidKey[]>>(true);
assert.deepStrictEqual(
val2,
['bar', 'foo', 'hello'],
'Correct values from store',
);
});
test('getKey', async function () {
if (!('getKey' in IDBObjectStore.prototype)) this.skip();
const schemaDB = await openDBWithData();
db = schemaDB as IDBPDatabase;
const store1 = schemaDB.transaction('key-val-store').store;
typeAssert<
IsExact<Parameters<typeof store1.getKey>[0], string | IDBKeyRange>
>(true);
const val = await store1.getKey(IDBKeyRange.lowerBound('a'));
typeAssert<IsExact<typeof val, string | undefined>>(true);
assert.strictEqual(val, 'bar', 'Correct value');
const store2 = db.transaction('key-val-store').store;
typeAssert<
IsExact<Parameters<typeof store2.getKey>[0], IDBValidKey | IDBKeyRange>
>(true);
const val2 = await store2.getKey(IDBKeyRange.lowerBound('c'));
typeAssert<IsExact<typeof val2, IDBValidKey | undefined>>(true);
assert.strictEqual(val2, 'foo', 'Correct value');
});
test('index', async () => {
const schemaDB = await openDBWithData();
db = schemaDB as IDBPDatabase;
const store1 = schemaDB.transaction('object-store').store;
typeAssert<IsExact<Parameters<typeof store1.index>[0], 'date' | 'title'>>(
true,
);
const store2 = db.transaction('object-store').store;
typeAssert<IsExact<Parameters<typeof store2.index>[0], string>>(true);
});
test('openCursor', async () => {
const schemaDB = await openDBWithData();
db = schemaDB as IDBPDatabase;
const store1 = schemaDB.transaction('key-val-store').store;
typeAssert<
IsExact<
Parameters<typeof store1.openCursor>[0],
string | IDBKeyRange | undefined | null
>
>(true);
const cursor1 = await store1.openCursor();
typeAssert<
IsExact<
typeof cursor1,
IDBPCursorWithValue<
TestDBSchema,
['key-val-store'],
'key-val-store',
unknown
> | null
>
>(true);
assert.instanceOf(cursor1, IDBCursorWithValue);
const store2 = db.transaction('object-store').store;
typeAssert<
IsExact<
Parameters<typeof store2.openCursor>[0],
IDBValidKey | IDBKeyRange | undefined | null
>
>(true);
const cursor2 = await store2.openCursor();
typeAssert<
IsExact<
typeof cursor2,
IDBPCursorWithValue<
unknown,
['object-store'],
'object-store',
unknown
> | null
>
>(true);
assert.instanceOf(cursor2, IDBCursorWithValue);
});
test('openKeyCursor', async function () {
if (!('openKeyCursor' in IDBObjectStore.prototype)) this.skip();
const schemaDB = await openDBWithData();
db = schemaDB as IDBPDatabase;
const store1 = schemaDB.transaction('key-val-store').store;
typeAssert<
IsExact<
Parameters<typeof store1.openKeyCursor>[0],
string | IDBKeyRange | undefined | null
>
>(true);
const cursor1 = await store1.openKeyCursor();
typeAssert<
IsExact<
typeof cursor1,
IDBPCursor<
TestDBSchema,
['key-val-store'],
'key-val-store',
unknown
> | null
>
>(true);
const store2 = db.transaction('object-store').store;
typeAssert<
IsExact<
Parameters<typeof store2.openKeyCursor>[0],
IDBValidKey | IDBKeyRange | undefined | null
>
>(true);
const cursor2 = await store2.openKeyCursor();
typeAssert<
IsExact<
typeof cursor2,
IDBPCursor<unknown, ['object-store'], 'object-store', unknown> | null
>
>(true);
});
test('put', async () => {
const schemaDB = await openDBWithData();
db = schemaDB as IDBPDatabase;
const store1 = schemaDB.transaction('key-val-store', 'readwrite').store;
typeAssert<IsExact<Parameters<typeof store1.put>[0], number>>(true);
typeAssert<
IsExact<
Parameters<typeof store1.put>[1],
string | IDBKeyRange | undefined
>
>(true);
const key = await store1.put(234, 'new');
typeAssert<IsExact<typeof key, string>>(true);
const val = await store1.get('new');
assert.strictEqual(val, 234, 'Correct value from store');
const store2 = db.transaction('object-store', 'readwrite').store;
typeAssert<IsExact<Parameters<typeof store2.put>[0], any>>(true);
typeAssert<
IsExact<
Parameters<typeof store2.put>[1],
IDBValidKey | IDBKeyRange | undefined
>
>(true);
const key2 = await store2.put({
id: 5,
title: 'Article 5',
date: new Date('2018-05-09'),
});
typeAssert<IsExact<typeof key2, IDBValidKey>>(true);
const val2 = await store2.get(5);
typeAssert<IsExact<typeof val2, any>>(true);
assert.deepStrictEqual(
val2,
{
id: 5,
title: 'Article 5',
date: new Date('2018-05-09'),
},
'Correct value from store',
);
});
test('wrap', async () => {
const schemaDB = await openDBWithSchema();
db = schemaDB as IDBPDatabase;
const tx = schemaDB.transaction('key-val-store');
const idbTx = unwrap(tx);
const store = idbTx.objectStore('key-val-store');
assert.instanceOf(store.get('blah'), IDBRequest);
const wrappedStore = wrap(store);
typeAssert<IsExact<typeof wrappedStore, IDBPObjectStore>>(true);
assert.instanceOf(wrappedStore.get('blah'), Promise);
});
test('unwrap', async () => {
const schemaDB = await openDBWithSchema();
db = schemaDB as IDBPDatabase;
const store1 = schemaDB.transaction('key-val-store').store;
const store2 = db.transaction('key-val-store').store;
const store3 = schemaDB.transaction('key-val-store', 'readwrite').store;
const unwrappedStore1 = unwrap(store1);
const unwrappedStore2 = unwrap(store2);
const unwrappedStore3 = unwrap(store3);
typeAssert<IsExact<typeof unwrappedStore1, IDBObjectStore>>(true);
typeAssert<IsExact<typeof unwrappedStore2, IDBObjectStore>>(true);
typeAssert<IsExact<typeof unwrappedStore3, IDBObjectStore>>(true);
assert.instanceOf(unwrappedStore1.get('foo'), IDBRequest);
assert.instanceOf(unwrappedStore2.get('foo'), IDBRequest);
assert.instanceOf(unwrappedStore3.get('foo'), IDBRequest);
});
});
suite('IDBPIndex', () => {
let db: IDBPDatabase;
teardown('Close DB', async () => {
if (db) db.close();
await deleteDatabase();
});
test('mode', async () => {
db = (await openDB<TestDBSchema>(dbName, getNextVersion(), {
upgrade(db, oldVersion, newVersion, tx) {
const store = db.createObjectStore('object-store');
const index = store.createIndex('date', 'date');
typeAssert<
IsExact<
typeof index,
IDBPIndex<
TestDBSchema,
['object-store'],
'object-store',
'date',
'versionchange'
>
>
>(true);
},
})) as IDBPDatabase;
});
test('objectStore', async () => {
const schemaDB = await openDBWithSchema();
db = schemaDB as IDBPDatabase;
const index1 = schemaDB.transaction('object-store').store.index('date');
const index2 = schemaDB
.transaction(['object-store', 'key-val-store'])
.objectStore('object-store')
.index('date');
const index3 = db.transaction('object-store').store.index('date');
typeAssert<
IsExact<
typeof index1.objectStore,
IDBPObjectStore<TestDBSchema, ['object-store'], 'object-store'>
>
>(true);
typeAssert<
IsExact<
typeof index2.objectStore,
IDBPObjectStore<
TestDBSchema,
('object-store' | 'key-val-store')[],
'object-store'
>
>
>(true);
typeAssert<
IsExact<
typeof index3.objectStore,
IDBPObjectStore<unknown, ['object-store'], 'object-store'>
>
>(true);
});
test('set name', async () => {
const schemaDB = await openDBWithSchema();
schemaDB.close();
const newDB = await openDB<RenamedDBSchema>(dbName, getNextVersion(), {
upgrade(db, oldVersion, newVersion, tx) {
const store = tx.objectStore(
'object-store',
) as unknown as IDBObjectStore;
const index = store.index('date');
index.name = 'date-renamed';
},
});
db = newDB as IDBPDatabase;
const tx = newDB.transaction('object-store');
assert(tx.store.indexNames.contains('date-renamed'));
});
test('count', async () => {
const schemaDB = await openDBWithData();
db = schemaDB as IDBPDatabase;
const index1 = schemaDB.transaction('object-store').store.index('date');
typeAssert<
IsExact<
Parameters<typeof index1.count>[0],
Date | IDBKeyRange | undefined | null
>
>(true);
const val = await index1.count();
typeAssert<IsExact<typeof val, number>>(true);
assert.strictEqual(val, 4, 'Correct count');
const index2 = db.transaction('object-store').store.index('title');
typeAssert<
IsExact<
Parameters<typeof index2.count>[0],
IDBValidKey | IDBKeyRange | undefined | null
>
>(true);
const val2 = await index2.count();
typeAssert<IsExact<typeof val2, number>>(true);
assert.strictEqual(val2, 4, 'Correct count');
});
test('get', async () => {
const schemaDB = await openDBWithData();
db = schemaDB as IDBPDatabase;
const index1 = schemaDB.transaction('object-store').store.index('date');
typeAssert<IsExact<Parameters<typeof index1.get>[0], Date | IDBKeyRange>>(
true,
);
const val = await index1.get(new Date('2019-01-03'));
typeAssert<IsExact<typeof val, ObjectStoreValue | undefined>>(true);
assert.deepStrictEqual(
val,
{
id: 2,
title: 'Article 2',
date: new Date('2019-01-03'),
},
'Correct value from store',
);
const index2 = db.transaction('object-store').store.index('title');
typeAssert<
IsExact<Parameters<typeof index2.get>[0], IDBValidKey | IDBKeyRange>
>(true);
const val2 = await index2.get('Article 2');
typeAssert<IsExact<typeof val2, any>>(true);
assert.deepStrictEqual(
val2,
{
id: 2,
title: 'Article 2',
date: new Date('2019-01-03'),
},
'Correct value from store',
);
});
test('getAll', async function () {
if (!('getAll' in IDBIndex.prototype)) this.skip();
const schemaDB = await openDBWithData();
db = schemaDB as IDBPDatabase;
{
const index = schemaDB.transaction('object-store').store.index('date');
typeAssert<
IsExact<
Parameters<typeof index.getAll>[0],
Date | IDBKeyRange | undefined | null
>
>(true);
const val = await index.getAll();
typeAssert<IsExact<typeof val, ObjectStoreValue[]>>(true);
assert.deepStrictEqual(
val,
[
{
id: 4,
title: 'Article 4',
date: new Date('2019-01-01'),
},
{
id: 3,
title: 'Article 3',
date: new Date('2019-01-02'),
},
{
id: 2,
title: 'Article 2',
date: new Date('2019-01-03'),
},
{
id: 1,
title: 'Article 1',
date: new Date('2019-01-04'),
},
],
'Correct values from store',
);
}
{
const index = db.transaction('object-store').store.index('title');
typeAssert<
IsExact<
Parameters<typeof index.getAll>[0],
IDBValidKey | IDBKeyRange | undefined | null
>
>(true);
const val = await index.getAll();
typeAssert<IsExact<typeof val, any[]>>(true);
assert.deepStrictEqual(
val,
[
{
id: 1,
title: 'Article 1',
date: new Date('2019-01-04'),
},
{
id: 2,
title: 'Article 2',
date: new Date('2019-01-03'),
},
{
id: 3,
title: 'Article 3',
date: new Date('2019-01-02'),
},
{
id: 4,
title: 'Article 4',
date: new Date('2019-01-01'),
},
],
'Correct values from store',
);
}
});
test('getAllKeys', async function () {
if (!('getAllKeys' in IDBIndex.prototype)) this.skip();
const schemaDB = await openDBWithData();
db = schemaDB as IDBPDatabase;
{
const index = schemaDB.transaction('object-store').store.index('date');
typeAssert<
IsExact<
Parameters<typeof index.getAllKeys>[0],
Date | IDBKeyRange | undefined | null
>
>(true);
const val = await index.getAllKeys();
typeAssert<IsExact<typeof val, number[]>>(true);
assert.deepStrictEqual(val, [4, 3, 2, 1], 'Correct values from store');
}
{
const index = db.transaction('object-store').store.index('title');
typeAssert<
IsExact<
Parameters<typeof index.getAllKeys>[0],
IDBValidKey | IDBKeyRange | undefined | null
>
>(true);
const val = await index.getAllKeys();
typeAssert<IsExact<typeof val, IDBValidKey[]>>(true);
assert.deepStrictEqual(val, [1, 2, 3, 4], 'Correct values from store');
}
});
test('getKey', async () => {
const schemaDB = await openDBWithData();
db = schemaDB as IDBPDatabase;
{
const index = schemaDB.transaction('object-store').store.index('date');
typeAssert<
IsExact<Parameters<typeof index.getKey>[0], Date | IDBKeyRange>
>(true);
const val = await index.getKey(
IDBKeyRange.lowerBound(new Date('1990-01-01')),
);
typeAssert<IsExact<typeof val, number | undefined>>(true);
assert.strictEqual(val, 4, 'Correct value');
}
{
const index = db.transaction('object-store').store.index('title');
typeAssert<
IsExact<Parameters<typeof index.getKey>[0], IDBValidKey | IDBKeyRange>
>(true);
const val = await index.getKey(IDBKeyRange.lowerBound('A'));
typeAssert<IsExact<typeof val, IDBValidKey | undefined>>(true);
assert.strictEqual(val, 1, 'Correct value');
}
});
test('openCursor', async () => {
const schemaDB = await openDBWithData();
db = schemaDB as IDBPDatabase;
{
const index = schemaDB.transaction('object-store').store.index('date');
typeAssert<
IsExact<
Parameters<typeof index.openCursor>[0],
Date | IDBKeyRange | undefined | null
>
>(true);
const cursor = await index.openCursor();
typeAssert<
IsExact<
typeof cursor,
IDBPCursorWithValue<
TestDBSchema,
['object-store'],
'object-store',
'date'
> | null
>
>(true);
assert.instanceOf(cursor, IDBCursorWithValue);
}
{
const index = db.transaction('object-store').store.index('title');
typeAssert<
IsExact<
Parameters<typeof index.openCursor>[0],
IDBValidKey | IDBKeyRange | undefined | null
>
>(true);
const cursor = await index.openCursor();
typeAssert<
IsExact<
typeof cursor,
IDBPCursorWithValue<
unknown,
['object-store'],
'object-store',
'title'
> | null
>
>(true);
assert.instanceOf(cursor, IDBCursorWithValue);
}
});
test('openKeyCursor', async () => {
const schemaDB = await openDBWithData();
db = schemaDB as IDBPDatabase;
{
const index = schemaDB.transaction('object-store').store.index('date');
typeAssert<
IsExact<
Parameters<typeof index.openKeyCursor>[0],
Date | IDBKeyRange | undefined | null
>
>(true);
const cursor = await index.openKeyCursor();
typeAssert<
IsExact<
typeof cursor,
IDBPCursor<
TestDBSchema,
['object-store'],
'object-store',
'date'
> | null
>
>(true);
assert.instanceOf(cursor, IDBCursor);
}
{
const index = db.transaction('object-store').store.index('title');
typeAssert<
IsExact<
Parameters<typeof index.openKeyCursor>[0],
IDBValidKey | IDBKeyRange | undefined | null
>
>(true);
const cursor = await index.openKeyCursor();
typeAssert<
IsExact<
typeof cursor,
IDBPCursor<unknown, ['object-store'], 'object-store', 'title'> | null
>
>(true);
assert.instanceOf(cursor, IDBCursor);
}
});
test('wrap', async () => {
const schemaDB = await openDBWithSchema();
db = schemaDB as IDBPDatabase;
const tx = schemaDB.transaction('object-store');
const idbTx = unwrap(tx);
const index = idbTx.objectStore('object-store').index('date');
assert.instanceOf(index.get('blah'), IDBRequest);
const wrappedIndex = wrap(index);
typeAssert<IsExact<typeof wrappedIndex, IDBPIndex>>(true);
assert.instanceOf(wrappedIndex.get('blah'), Promise);
});
test('unwrap', async () => {
const schemaDB = await openDBWithSchema();
db = schemaDB as IDBPDatabase;
const index1 = schemaDB.transaction('object-store').store.index('date');
const index2 = db.transaction('object-store').store.index('title');
const index3 = schemaDB
.transaction('object-store', 'readwrite')
.store.index('date');
const unwrappedIndex1 = unwrap(index1);
const unwrappedIndex2 = unwrap(index2);
const unwrappedIndex3 = unwrap(index3);
typeAssert<IsExact<typeof unwrappedIndex1, IDBIndex>>(true);
typeAssert<IsExact<typeof unwrappedIndex2, IDBIndex>>(true);
typeAssert<IsExact<typeof unwrappedIndex3, IDBIndex>>(true);
assert.instanceOf(unwrappedIndex1.get('foo'), IDBRequest);
assert.instanceOf(unwrappedIndex2.get('foo'), IDBRequest);
assert.instanceOf(unwrappedIndex3.get('foo'), IDBRequest);
});
});
suite('IDBPCursor', () => {
let db: IDBPDatabase;
teardown('Close DB', async () => {
if (db) db.close();
await deleteDatabase();
});
test('mode', async () => {
const schemaDB = await openDBWithSchema();
db = schemaDB as IDBPDatabase;
const store = schemaDB.transaction('object-store', 'readwrite').store;
const cursor = store.openCursor();
typeAssert<
IsExact<
typeof cursor,
Promise<IDBPCursorWithValue<
TestDBSchema,
['object-store'],
'object-store',
unknown,
'readwrite'
> | null>
>
>(true);
});
test('key', async () => {
const schemaDB = await openDBWithData();
db = schemaDB as IDBPDatabase;
{
const index = schemaDB.transaction('object-store').store.index('date');
const cursor = await index.openCursor();
if (!cursor) {
assert.fail('Expected cursor');
return;
}
typeAssert<IsExact<typeof cursor.key, Date>>(true);
assert.instanceOf(cursor.key, Date);
assert.strictEqual(
cursor.key.valueOf(),
new Date('2019-01-01').valueOf(),
);
}
{
const index = db.transaction('object-store').store.index('title');
const cursor = await index.openCursor();
if (!cursor) {
assert.fail('Expected cursor');
return;
}
typeAssert<IsExact<typeof cursor.key, IDBValidKey>>(true);
assert.strictEqual(cursor.key, 'Article 1');
}
});
test('primaryKey', async () => {
const schemaDB = await openDBWithData();
db = schemaDB as IDBPDatabase;
{
const index = schemaDB.transaction('object-store').store.index('date');
const cursor = await index.openCursor();
if (!cursor) {
assert.fail('Expected cursor');
return;
}
typeAssert<IsExact<typeof cursor.primaryKey, number>>(true);
assert.strictEqual(cursor.primaryKey, 4);
}
{
const index = db.transaction('object-store').store.index('title');
const cursor = await index.openCursor();
if (!cursor) {
assert.fail('Expected cursor');
return;
}
typeAssert<IsExact<typeof cursor.primaryKey, IDBValidKey>>(true);
assert.strictEqual(cursor.primaryKey, 1);
}
});
test('source', async () => {
const schemaDB = await openDBWithData();
db = schemaDB as IDBPDatabase;
{
const index = schemaDB.transaction('object-store').store.index('date');
const cursor = await index.openCursor();
if (!cursor) {
assert.fail('Expected cursor');
return;
}
typeAssert<
IsExact<
typeof cursor.source,
IDBPIndex<TestDBSchema, ['object-store'], 'object-store', 'date'>
>
>(true);
}
{
const index = db.transaction('object-store').store.index('title');
const cursor = await index.openCursor();
if (!cursor) {
assert.fail('Expected cursor');
return;
}
typeAssert<
IsExact<
typeof cursor.source,
IDBPIndex<unknown, ['object-store'], 'object-store', 'title'>
>
>(true);
}
});
test('advance', async () => {
const schemaDB = await openDBWithData();
db = schemaDB as IDBPDatabase;
{
const index = schemaDB.transaction('object-store').store.index('date');
let cursor = await index.openCursor();
if (!cursor) {
assert.fail('Expected cursor');
return;
}
cursor = await cursor.advance(2);
if (!cursor) {
assert.fail('Expected cursor');
return;
}
assert.strictEqual(cursor.primaryKey, 2);
}
{
const index = db.transaction('object-store').store.index('title');
let cursor = await index.openCursor();
if (!cursor) {
assert.fail('Expected cursor');
return;
}
cursor = await cursor.advance(2);
if (!cursor) {
assert.fail('Expected cursor');
return;
}
assert.strictEqual(cursor.primaryKey, 3);
}
});
test('continue', async () => {
const schemaDB = await openDBWithData();
db = schemaDB as IDBPDatabase;
{
const index = schemaDB.transaction('object-store').store.index('date');
let cursor = await index.openCursor();
if (!cursor) {
assert.fail('Expected cursor');
return;
}
typeAssert<
IsExact<Parameters<typeof cursor.continue>[0], Date | undefined>
>(true);
cursor = await cursor.continue(new Date('2019-01-02T05:00:00.000Z'));
if (!cursor) {
assert.fail('Expected cursor');
return;
}
assert.strictEqual(cursor.primaryKey, 2);
}
{
const index = db.transaction('object-store').store.index('title');
let cursor = await index.openCursor();
if (!cursor) {
assert.fail('Expected cursor');
return;
}
typeAssert<
IsExact<Parameters<typeof cursor.continue>[0], IDBValidKey | undefined>
>(true);
cursor = await cursor.continue('Article 20');
if (!cursor) {
assert.fail('Expected cursor');
return;
}
assert.strictEqual(cursor.primaryKey, 3);
}
});
test('continuePrimaryKey', async function () {
if (!('continuePrimaryKey' in IDBCursor.prototype)) this.skip();
const schemaDB = await openDBWithData();
db = schemaDB as IDBPDatabase;
{
const index = schemaDB.transaction('object-store').store.index('date');
let cursor = await index.openCursor();
if (!cursor) {
assert.fail('Expected cursor');
return;
}
typeAssert<
IsExact<Parameters<typeof cursor.continuePrimaryKey>[0], Date>
>(true);
typeAssert<
IsExact<Parameters<typeof cursor.continuePrimaryKey>[1], number>
>(true);
cursor = await cursor.continuePrimaryKey(
new Date('2019-01-02T05:00:00.000Z'),
1.5,
);
if (!cursor) {
assert.fail('Expected cursor');
return;
}
assert.strictEqual(cursor.primaryKey, 2);
}
{
const index = db.transaction('object-store').store.index('title');
let cursor = await index.openCursor();
if (!cursor) {
assert.fail('Expected cursor');
return;
}
typeAssert<
IsExact<Parameters<typeof cursor.continuePrimaryKey>[0], IDBValidKey>
>(true);
typeAssert<
IsExact<Parameters<typeof cursor.continuePrimaryKey>[1], IDBValidKey>
>(true);
cursor = await cursor.continuePrimaryKey('Article 3', 3.5);
if (!cursor) {
assert.fail('Expected cursor');
return;
}
assert.strictEqual(cursor.primaryKey, 4);
}
});
test('delete', async function () {
if (!('delete' in IDBCursor.prototype)) this.skip();
const schemaDB = await openDBWithData();
db = schemaDB as IDBPDatabase;
{
const store = schemaDB.transaction('key-val-store', 'readwrite').store;
let cursor = await store.openCursor();
while (cursor) {
if (cursor.value === 456) cursor.delete();
cursor = await cursor.continue();
}
assert.deepEqual(await store.getAll(), [123, 789]);
}
{
const store = db.transaction('key-val-store', 'readwrite').store;
let cursor = await store.openCursor();
while (cursor) {
if (cursor.value === 789) cursor.delete();
cursor = await cursor.continue();
}
assert.deepEqual(await store.getAll(), [123]);
}
});
test('update', async function () {
if (!('update' in IDBCursor.prototype)) this.skip();
const schemaDB = await openDBWithData();
db = schemaDB as IDBPDatabase;
{
const store = schemaDB.transaction('key-val-store', 'readwrite').store;
let cursor = await store.openCursor();
while (cursor) {
typeAssert<IsExact<Parameters<typeof cursor.update>[0], number>>(true);
cursor.update(cursor.value + 1);
cursor = await cursor.continue();
}
assert.deepEqual(await store.getAll(), [457, 124, 790]);
}
{
const store = db.transaction('key-val-store', 'readwrite').store;
let cursor = await store.openCursor();
while (cursor) {
typeAssert<IsExact<Parameters<typeof cursor.update>[0], any>>(true);
cursor.update(cursor.value + 1);
cursor = await cursor.continue();
}
assert.deepEqual(await store.getAll(), [458, 125, 791]);
}
});
test('unwrap', async () => {
const schemaDB = await openDBWithData();
db = schemaDB as IDBPDatabase;
{
const cursor = await schemaDB
.transaction('object-store')
.store.openCursor();
if (!cursor) throw Error('expected cursor');
const unwrappedCursor = unwrap(cursor);
typeAssert<IsExact<typeof unwrappedCursor, IDBCursorWithValue>>(true);
assert.strictEqual(unwrappedCursor.continue(), undefined);
}
{
const cursor = await db.transaction('object-store').store.openCursor();
if (!cursor) throw Error('expected cursor');
const unwrappedCursor = unwrap(cursor);
typeAssert<IsExact<typeof unwrappedCursor, IDBCursorWithValue>>(true);
assert.strictEqual(unwrappedCursor.continue(), undefined);
}
});
});
suite('IDBPCursorWithValue', () => {
let db: IDBPDatabase;
teardown('Close DB', async () => {
if (db) db.close();
await deleteDatabase();
});
test('unwrap', async () => {
const schemaDB = await openDBWithData();
db = schemaDB as IDBPDatabase;
{
const cursor = await schemaDB
.transaction('object-store', 'readwrite')
.store.openCursor();
if (!cursor) throw Error('expected cursor');
const unwrappedCursor = unwrap(cursor);
typeAssert<IsExact<typeof unwrappedCursor, IDBCursorWithValue>>(true);
assert.instanceOf(
unwrappedCursor.update(unwrappedCursor.value),
IDBRequest,
);
}
{
const cursor = await db
.transaction('object-store', 'readwrite')
.store.openCursor();
if (!cursor) throw Error('expected cursor');
const unwrappedCursor = unwrap(cursor);
typeAssert<IsExact<typeof unwrappedCursor, IDBCursorWithValue>>(true);
assert.instanceOf(
unwrappedCursor.update(unwrappedCursor.value),
IDBRequest,
);
}
});
});
================================================
FILE: test/missing-types.d.ts
================================================
declare module 'chai/chai' {
var chai: typeof import('chai');
export default chai;
}
================================================
FILE: test/open.ts
================================================
import 'mocha/mocha';
import { assert } from 'chai';
import { openDB, IDBPDatabase, IDBPTransaction, wrap, unwrap } from '../src/';
import { assert as typeAssert, IsExact } from 'conditional-type-checks';
import {
getNextVersion,
TestDBSchema,
dbName,
openDBWithSchema,
deleteDatabase,
} from './utils';
suite('openDb', () => {
let db: IDBPDatabase;
teardown('Close DB', () => {
if (db) db.close();
});
test('upgrade', async () => {
let upgradeRun = false;
const version = getNextVersion();
db = (await openDB<TestDBSchema>(dbName, version, {
upgrade(db, oldVersion, newVersion, tx, event) {
upgradeRun = true;
typeAssert<IsExact<typeof db, IDBPDatabase<TestDBSchema>>>(true);
assert.instanceOf(db, IDBDatabase, 'db instance');
assert.strictEqual(oldVersion, 0);
assert.strictEqual(newVersion, version);
typeAssert<
IsExact<
typeof tx,
IDBPTransaction<
TestDBSchema,
('key-val-store' | 'object-store')[],
'versionchange'
>
>
>(true);
assert.instanceOf(tx, IDBTransaction, 'transaction');
assert.strictEqual(tx.mode, 'versionchange', 'tx mode');
assert.instanceOf(event, IDBVersionChangeEvent, 'event');
typeAssert<IsExact<typeof event, IDBVersionChangeEvent>>(true);
},
})) as IDBPDatabase;
assert.isTrue(upgradeRun, 'upgrade run');
});
test('open without version - upgrade should not run', async () => {
let upgradeRun = false;
db = (await openDB<TestDBSchema>(dbName, undefined, {
upgrade(db, oldVersion, newVersion, tx) {
upgradeRun = true;
},
})) as IDBPDatabase;
assert.isFalse(upgradeRun, 'upgrade not run');
assert.strictEqual(db.version, 1);
});
test('open without version - database never existed', async () => {
db = (await openDB<TestDBSchema>(dbName)) as IDBPDatabase;
assert.strictEqual(db.version, 1);
});
test('open with undefined version - database never existed', async () => {
db = (await openDB<TestDBSchema>(dbName, undefined, {})) as IDBPDatabase;
assert.strictEqual(db.version, 1);
});
test('open without version - database previously created', async () => {
const version = getNextVersion();
db = (await openDB<TestDBSchema>(dbName, version)) as IDBPDatabase;
db.close();
db = (await openDB<TestDBSchema>(dbName)) as IDBPDatabase;
assert.strictEqual(db.version, version);
});
test('open with undefined version - database previously created', async () => {
const version = getNextVersion();
db = (await openDB<TestDBSchema>(dbName, version)) as IDBPDatabase;
db.close();
db = (await openDB<TestDBSchema>(dbName, undefined, {})) as IDBPDatabase;
assert.strictEqual(db.version, version);
});
test('upgrade - schemaless', async () => {
let upgradeRun = false;
const version = getNextVersion();
db = await openDB(dbName, version, {
upgrade(db, oldVersion, newVersion, tx) {
upgradeRun = true;
typeAssert<IsExact<typeof db, IDBPDatabase>>(true);
typeAssert<
IsExact<
typeof tx,
IDBPTransaction<unknown, string[], 'versionchange'>
>
>(true);
},
});
assert.isTrue(upgradeRun, 'upgrade run');
});
test('blocked and blocking', async () => {
let blockedCalled = false;
let blockingCalled = false;
let newDbBlockedCalled = false;
let newDbBlockingCalled = false;
const firstVersion = getNextVersion();
const nextVersion = getNextVersion();
db = (await openDB<TestDBSchema>(dbName, firstVersion, {
blocked() {
blockedCalled = true;
},
blocking(currentVersion, blockedVersion, event) {
blockingCalled = true;
assert.strictEqual(currentVersion, firstVersion);
assert.strictEqual(blockedVersion, nextVersion);
assert.instanceOf(event, IDBVersionChangeEvent, 'event');
typeAssert<IsExact<typeof event, IDBVersionChangeEvent>>(true);
// 'blocked' isn't called if older databases close once blocking fires.
// Using set timeout so closing isn't immediate.
setTimeout(() => db.close(), 0);
},
})) as IDBPDatabase;
assert.isFalse(blockedCalled);
assert.isFalse(blockingCalled);
db = (await openDB<TestDBSchema>(dbName, nextVersion, {
blocked(currentVersion, blockedVersion, event) {
newDbBlockedCalled = true;
assert.strictEqual(currentVersion, firstVersion);
assert.strictEqual(blockedVersion, nextVersion);
assert.instanceOf(event, IDBVersionChangeEvent, 'event');
typeAssert<IsExact<typeof event, IDBVersionChangeEvent>>(true);
},
blocking() {
newDbBlockingCalled = true;
},
})) as IDBPDatabase;
assert.isFalse(blockedCalled);
assert.isTrue(blockingCalled);
assert.isTrue(newDbBlockedCalled);
assert.isFalse(newDbBlockingCalled);
});
test('wrap', async () => {
let wrappedRequest: Promise<IDBPDatabase | undefined> =
Promise.resolve(undefined);
// Let's do it the old fashioned way
const idb = await new Promise<IDBDatabase>(async (resolve) => {
const request = indexedDB.open(dbName, getNextVersion());
wrappedRequest = wrap(request);
request.addEventListener('success', () => resolve(request.result));
});
assert.instanceOf(wrappedRequest, Promise, 'Wrapped request type');
db = wrap(idb);
typeAssert<IsExact<typeof db, IDBPDatabase>>(true);
assert.instanceOf(db, IDBDatabase, 'DB type');
assert.property(db, 'getAllFromIndex', 'DB looks wrapped');
assert.strictEqual(
db,
await wrappedRequest,
'Wrapped request and wrapped db are same',
);
});
test('unwrap', async () => {
const openPromise = openDB<TestDBSchema>(dbName, getNextVersion());
const request = unwrap(openPromise);
typeAssert<IsExact<typeof request, IDBOpenDBRequest>>(true);
assert.instanceOf(request, IDBOpenDBRequest, 'Request type');
const simpleDB = await openPromise;
simpleDB.close();
const schemaDb = await openDBWithSchema();
db = schemaDb as IDBPDatabase;
const idb = unwrap(schemaDb);
typeAssert<IsExact<typeof idb, IDBDatabase>>(true);
assert.instanceOf(idb, IDBDatabase, 'DB type');
assert.isFalse('getAllFromIndex' in idb, 'DB looks unwrapped');
});
});
suite('deleteDb', () => {
let db: IDBPDatabase;
teardown('Close DB', () => {
if (db) db.close();
});
test('deleteDb', async () => {
db = (await openDBWithSchema()) as IDBPDatabase;
assert.lengthOf(db.objectStoreNames, 2, 'DB has two stores');
db.close();
await deleteDatabase();
db = await openDB(dbName, getNextVersion());
assert.lengthOf(db.objectStoreNames, 0, 'DB has no stores');
});
test('blocked', async () => {
let blockedCalled = false;
let blockingCalled = false;
let closeDbBlockedCalled = false;
const version = getNextVersion();
db = await openDB(dbName, version, {
blocked() {
blockedCalled = true;
},
blocking() {
blockingCalled = true;
// 'blocked' isn't called if older databases close once blocking fires.
// Using set timeout so closing isn't immediate.
setTimeout(() => db.close(), 0);
},
});
assert.isFalse(blockedCalled);
assert.isFalse(blockingCalled);
await deleteDatabase({
blocked(currentVersion, event) {
closeDbBlockedCalled = true;
assert.strictEqual(currentVersion, version);
assert.instanceOf(event, IDBVersionChangeEvent, 'event');
typeAssert<IsExact<typeof event, IDBVersionChangeEvent>>(true);
},
});
assert.isFalse(blockedCalled);
assert.isTrue(blockingCalled);
assert.isTrue(closeDbBlockedCalled);
});
});
================================================
FILE: test/tsconfig.json
================================================
{
"extends": "../generic-tsconfig.json",
"compilerOptions": {
"esModuleInterop": true,
"lib": ["esnext", "dom"],
"tsBuildInfoFile": "../.ts-tmp/.test.tsbuildinfo",
"declarationDir": "../build/test"
},
"references": [{ "path": "../src" }]
}
================================================
FILE: test/utils.ts
================================================
import {
DBSchema,
IDBPDatabase,
openDB,
DeleteDBCallbacks,
deleteDB,
} from '../src/';
export interface ObjectStoreValue {
id: number;
title: string;
date: Date;
}
export interface TestDBSchema extends DBSchema {
'key-val-store': {
key: string;
value: number;
};
'object-store': {
value: ObjectStoreValue;
key: number;
indexes: { date: Date; title: string };
};
}
export const dbName = 'test-db';
let version = 0;
export function getNextVersion(): number {
version += 1;
return version;
}
let dbWithSchemaCreated = false;
export function openDBWithSchema(): Promise<IDBPDatabase<TestDBSchema>> {
if (dbWithSchemaCreated) return openDB<TestDBSchema>(dbName, version);
dbWithSchemaCreated = true;
return openDB<TestDBSchema>(dbName, getNextVersion(), {
upgrade(db) {
db.createObjectStore('key-val-store');
const store = db.createObjectStore('object-store', { keyPath: 'id' });
store.createIndex('date', 'date');
store.createIndex('title', 'title');
},
});
}
let dbWithDataCreated = false;
export async function openDBWithData() {
if (dbWithDataCreated) return openDB<TestDBSchema>(dbName, version);
dbWithDataCreated = true;
const db = await openDBWithSchema();
const tx = db.transaction(['key-val-store', 'object-store'], 'readwrite');
const keyStore = tx.objectStore('key-val-store');
const objStore = tx.objectStore('object-store');
keyStore.put(123, 'foo');
keyStore.put(456, 'bar');
keyStore.put(789, 'hello');
objStore.put({
id: 1,
title: 'Article 1',
date: new Date('2019-01-04'),
});
objStore.put({
id: 2,
title: 'Article 2',
date: new Date('2019-01-03'),
});
objStore.put({
id: 3,
title: 'Article 3',
date: new Date('2019-01-02'),
});
objStore.put({
id: 4,
title: 'Article 4',
date: new Date('2019-01-01'),
});
return db;
}
export function deleteDatabase(callbacks: DeleteDBCallbacks = {}) {
version = 0;
dbWithSchemaCreated = false;
dbWithDataCreated = false;
return deleteDB(dbName, callbacks);
}
gitextract_epojnbq1/
├── .github/
│ └── ISSUE_TEMPLATE/
│ ├── bug_report.md
│ └── feature_request.md
├── .gitignore
├── .prettierrc.json
├── CHANGELOG.md
├── LICENSE
├── README.md
├── generic-tsconfig.json
├── lib/
│ └── size-report.mjs
├── package.json
├── rollup.config.mjs
├── size-tests/
│ └── main.js
├── src/
│ ├── async-iterators.ts
│ ├── database-extras.ts
│ ├── entry.ts
│ ├── index.ts
│ ├── tsconfig.json
│ ├── util.ts
│ └── wrap-idb-value.ts
└── test/
├── index.html
├── index.ts
├── iterate.ts
├── main.ts
├── missing-types.d.ts
├── open.ts
├── tsconfig.json
└── utils.ts
SYMBOL INDEX (79 symbols across 10 files)
FILE: rollup.config.mjs
method generateBundle (line 62) | async generateBundle() {
FILE: src/async-iterators.ts
method get (line 11) | get(target, prop) {
function isIteratorProp (line 59) | function isIteratorProp(target: any, prop: number | string | symbol) {
method get (line 69) | get(target, prop, receiver) {
method has (line 73) | has(target, prop) {
FILE: src/database-extras.ts
function getMethod (line 9) | function getMethod(
FILE: src/entry.ts
type OpenDBCallbacks (line 3) | interface OpenDBCallbacks<DBTypes extends DBSchema | unknown> {
function openDB (line 65) | function openDB<DBTypes extends DBSchema | unknown = unknown>(
type DeleteDBCallbacks (line 114) | interface DeleteDBCallbacks {
function deleteDB (line 129) | function deleteDB(
type KeyToKeyNoIndex (line 151) | type KeyToKeyNoIndex<T> = {
type ValuesOf (line 154) | type ValuesOf<T> = T extends { [K in keyof T]: infer U } ? U : never;
type KnownKeys (line 155) | type KnownKeys<T> = ValuesOf<KeyToKeyNoIndex<T>>;
type Omit (line 157) | type Omit<T, K> = Pick<T, Exclude<keyof T, K>>;
type DBSchema (line 159) | interface DBSchema {
type IndexKeys (line 163) | interface IndexKeys {
type DBSchemaValue (line 167) | interface DBSchemaValue {
type StoreNames (line 178) | type StoreNames<DBTypes extends DBSchema | unknown> =
type StoreValue (line 187) | type StoreValue<
type StoreKey (line 198) | type StoreKey<
type IndexNames (line 209) | type IndexNames<
type IndexKey (line 221) | type IndexKey<
type CursorSource (line 231) | type CursorSource<
type CursorKey (line 241) | type CursorKey<
type IDBPDatabaseExtends (line 249) | type IDBPDatabaseExtends = Omit<
type DOMStringListSymbolIteratorType (line 254) | type DOMStringListSymbolIteratorType = DOMStringList extends { [Symbol.i...
type TypedDOMStringList (line 259) | interface TypedDOMStringList<T extends string> extends DOMStringList {
type IDBTransactionOptions (line 271) | interface IDBTransactionOptions {
type IDBPDatabase (line 283) | interface IDBPDatabase<DBTypes extends DBSchema | unknown = unknown>
type IDBPTransactionExtends (line 564) | type IDBPTransactionExtends = Omit<
type IDBPTransaction (line 569) | interface IDBPTransaction<
type IDBPObjectStoreExtends (line 606) | type IDBPObjectStoreExtends = Omit<
type IDBPObjectStore (line 625) | interface IDBPObjectStore<
type IDBPIndexExtends (line 795) | type IDBPIndexExtends = Omit<
type IDBPIndex (line 807) | interface IDBPIndex<
type IDBPCursorExtends (line 930) | type IDBPCursorExtends = Omit<
type IDBPCursor (line 942) | interface IDBPCursor<
type IDBPCursorIteratorValueExtends (line 1015) | type IDBPCursorIteratorValueExtends<
type IDBPCursorIteratorValue (line 1028) | interface IDBPCursorIteratorValue<
type IDBPCursorWithValue (line 1068) | interface IDBPCursorWithValue<
type IDBPCursorWithValueIteratorValueExtends (line 1096) | type IDBPCursorWithValueIteratorValueExtends<
type IDBPCursorWithValueIteratorValue (line 1109) | interface IDBPCursorWithValueIteratorValue<
FILE: src/util.ts
type Constructor (line 1) | type Constructor = new (...args: any[]) => any;
type Func (line 2) | type Func = (...args: any[]) => any;
FILE: src/wrap-idb-value.ts
function getIdbProxyableTypes (line 15) | function getIdbProxyableTypes(): Constructor[] {
function getCursorAdvanceMethods (line 29) | function getCursorAdvanceMethods(): Func[] {
function promisifyRequest (line 47) | function promisifyRequest<T>(request: IDBRequest<T>): Promise<T> {
function cacheDonePromiseForTransaction (line 71) | function cacheDonePromiseForTransaction(tx: IDBTransaction): void {
method get (line 99) | get(target, prop, receiver) {
method set (line 113) | set(target, prop, value) {
method has (line 117) | has(target, prop) {
function replaceTraps (line 128) | function replaceTraps(
function wrapFunction (line 134) | function wrapFunction<T extends Func>(func: T): Function {
function transformCachableValue (line 159) | function transformCachableValue(value: any): any {
function wrap (line 186) | function wrap(value: any): any {
type Unwrap (line 213) | interface Unwrap {
FILE: test/index.ts
function loadScript (line 8) | function loadScript(url: string): Promise<void> {
FILE: test/main.ts
type RenamedDBSchema (line 855) | interface RenamedDBSchema extends DBSchema {
method upgrade (line 959) | upgrade(db, oldVersion, newVersion, tx) {
method upgrade (line 1117) | upgrade(db, oldVersion, newVersion, tx) {
method upgrade (line 1128) | upgrade(db, oldVersion, newVersion, tx) {
method upgrade (line 1525) | upgrade(db, oldVersion, newVersion, tx) {
method upgrade (line 1586) | upgrade(db, oldVersion, newVersion, tx) {
FILE: test/open.ts
method upgrade (line 24) | upgrade(db, oldVersion, newVersion, tx, event) {
method upgrade (line 58) | upgrade(db, oldVersion, newVersion, tx) {
method upgrade (line 103) | upgrade(db, oldVersion, newVersion, tx) {
method blocked (line 128) | blocked() {
method blocking (line 131) | blocking(currentVersion, blockedVersion, event) {
method blocked (line 150) | blocked(currentVersion, blockedVersion, event) {
method blocking (line 159) | blocking() {
method blocked (line 240) | blocked() {
method blocking (line 243) | blocking() {
method blocked (line 255) | blocked(currentVersion, event) {
FILE: test/utils.ts
type ObjectStoreValue (line 9) | interface ObjectStoreValue {
type TestDBSchema (line 15) | interface TestDBSchema extends DBSchema {
function getNextVersion (line 30) | function getNextVersion(): number {
function openDBWithSchema (line 37) | function openDBWithSchema(): Promise<IDBPDatabase<TestDBSchema>> {
function openDBWithData (line 52) | async function openDBWithData() {
function deleteDatabase (line 85) | function deleteDatabase(callbacks: DeleteDBCallbacks = {}) {
Condensed preview — 27 files, each showing path, character count, and a content snippet. Download the .json file or copy for the full structured content (162K chars).
[
{
"path": ".github/ISSUE_TEMPLATE/bug_report.md",
"chars": 348,
"preview": "---\nname: Bug report\nabout: Create a report to help us improve\ntitle: ''\nlabels: ''\nassignees: ''\n\n---\n\n<!-- Bug reports"
},
{
"path": ".github/ISSUE_TEMPLATE/feature_request.md",
"chars": 365,
"preview": "---\nname: Feature request\nabout: Suggest an idea for this project\ntitle: ''\nlabels: ''\nassignees: ''\n\n---\n\n**Is your fea"
},
{
"path": ".gitignore",
"chars": 45,
"preview": "node_modules\n.ts-tmp\nbuild\ntmp\n.idea\n.vscode\n"
},
{
"path": ".prettierrc.json",
"chars": 52,
"preview": "{\n \"singleQuote\": true,\n \"trailingComma\": \"all\"\n}\n"
},
{
"path": "CHANGELOG.md",
"chars": 3301,
"preview": "# Breaking changes in 8.x\n\n- Finally dropped support for old EdgeHTML engine.\n- Dropped support for browsers that don't "
},
{
"path": "LICENSE",
"chars": 776,
"preview": "ISC License (ISC)\nCopyright (c) 2016, Jake Archibald <jaffathecake@gmail.com>\n\nPermission to use, copy, modify, and/or d"
},
{
"path": "README.md",
"chars": 15392,
"preview": "# IndexedDB with usability.\n\nThis is a tiny (~1.19kB brotli'd) library that mostly mirrors the IndexedDB API, but with s"
},
{
"path": "generic-tsconfig.json",
"chars": 304,
"preview": "{\n \"compilerOptions\": {\n \"target\": \"ES2019\",\n \"downlevelIteration\": true,\n \"module\": \"esnext\",\n \"strict\": t"
},
{
"path": "lib/size-report.mjs",
"chars": 1147,
"preview": "/**\n * Copyright 2019 Google Inc. All Rights Reserved.\n * Licensed under the Apache License, Version 2.0 (the \"License\")"
},
{
"path": "package.json",
"chars": 1478,
"preview": "{\n \"name\": \"idb\",\n \"version\": \"8.0.3\",\n \"description\": \"A small wrapper that makes IndexedDB usable\",\n \"main\": \"./bu"
},
{
"path": "rollup.config.mjs",
"chars": 2224,
"preview": "import { promises as fsp } from 'fs';\nimport { basename } from 'path';\n\nimport terser from '@rollup/plugin-terser';\nimpo"
},
{
"path": "size-tests/main.js",
"chars": 52,
"preview": "import { openDB } from '../build/index';\na(openDB);\n"
},
{
"path": "src/async-iterators.ts",
"chars": 2468,
"preview": "import { instanceOfAny, Func } from './util.js';\nimport { replaceTraps, reverseTransformCache, unwrap } from './wrap-idb"
},
{
"path": "src/database-extras.ts",
"chars": 2155,
"preview": "import { Func } from './util.js';\nimport { replaceTraps } from './wrap-idb-value.js';\nimport { IDBPDatabase, IDBPIndex }"
},
{
"path": "src/entry.ts",
"chars": 35094,
"preview": "import { wrap } from './wrap-idb-value.js';\n\nexport interface OpenDBCallbacks<DBTypes extends DBSchema | unknown> {\n /*"
},
{
"path": "src/index.ts",
"chars": 90,
"preview": "export * from './entry.js';\nimport './database-extras.js';\nimport './async-iterators.js';\n"
},
{
"path": "src/tsconfig.json",
"chars": 189,
"preview": "{\n \"extends\": \"../generic-tsconfig.json\",\n \"compilerOptions\": {\n \"lib\": [\"esnext\", \"dom\"],\n \"tsBuildInfoFile\": \""
},
{
"path": "src/util.ts",
"chars": 238,
"preview": "export type Constructor = new (...args: any[]) => any;\nexport type Func = (...args: any[]) => any;\n\nexport const instanc"
},
{
"path": "src/wrap-idb-value.ts",
"chars": 7480,
"preview": "import {\n IDBPCursor,\n IDBPCursorWithValue,\n IDBPDatabase,\n IDBPIndex,\n IDBPObjectStore,\n IDBPTransaction,\n} from "
},
{
"path": "test/index.html",
"chars": 154,
"preview": "<!DOCTYPE html>\n<link href=\"../../node_modules/mocha/mocha.css\" rel=\"stylesheet\" />\n<div id=\"mocha\"></div>\n<script type="
},
{
"path": "test/index.ts",
"chars": 875,
"preview": "// Since this library proxies IDB, I haven't retested all of IDB. I've tried to cover parts of the\n// library that behav"
},
{
"path": "test/iterate.ts",
"chars": 8593,
"preview": "// Since this library proxies IDB, I haven't retested all of IDB. I've tried to cover parts of the\n// library that behav"
},
{
"path": "test/main.ts",
"chars": 61797,
"preview": "import 'mocha/mocha';\nimport { assert } from 'chai';\nimport {\n IDBPDatabase,\n IDBPTransaction,\n wrap,\n unwrap,\n IDB"
},
{
"path": "test/missing-types.d.ts",
"chars": 89,
"preview": "declare module 'chai/chai' {\n var chai: typeof import('chai');\n export default chai;\n}\n"
},
{
"path": "test/open.ts",
"chars": 7987,
"preview": "import 'mocha/mocha';\nimport { assert } from 'chai';\nimport { openDB, IDBPDatabase, IDBPTransaction, wrap, unwrap } from"
},
{
"path": "test/tsconfig.json",
"chars": 264,
"preview": "{\n \"extends\": \"../generic-tsconfig.json\",\n \"compilerOptions\": {\n \"esModuleInterop\": true,\n \"lib\": [\"esnext\", \"do"
},
{
"path": "test/utils.ts",
"chars": 2096,
"preview": "import {\n DBSchema,\n IDBPDatabase,\n openDB,\n DeleteDBCallbacks,\n deleteDB,\n} from '../src/';\n\nexport interface Obje"
}
]
About this extraction
This page contains the full source code of the jakearchibald/idb GitHub repository, extracted and formatted as plain text for AI agents and large language models (LLMs). The extraction includes 27 files (151.4 KB), approximately 39.4k tokens, and a symbol index with 79 extracted functions, classes, methods, constants, and types. Use this with OpenClaw, Claude, ChatGPT, Cursor, Windsurf, or any other AI tool that accepts text input. You can copy the full output to your clipboard or download it as a .txt file.
Extracted by GitExtract — free GitHub repo to text converter for AI. Built by Nikandr Surkov.