# IndexedDB Promised

This is a tiny library that mirrors IndexedDB, but replaces the weird `IDBRequest` objects with promises, plus a couple of other small changes.

# Installation

If you're using Rollup/Webpack or similar:

```sh
npm install idb
```

Then in your JS:

```js
import { openDb, deleteDb } from 'idb';

await openDb(…);
```

Or include [the script](https://github.com/jakearchibald/idb/blob/master/build/idb.js) as it is, and `idb` will exist on the global scope.

# Changes from 2.x

The library is now a module. To take advantage of this, importing has changed slightly:

```js
// Old 2.x way:
import idb from 'idb';
idb.open(…);
idb.delete(…);

// New way:
import { openDb, deleteDb } from 'idb';
openDb(…);
deleteDb(…);
```

# 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
const dbPromise = openDb('keyval-store', 1, upgradeDB => {
  upgradeDB.createObjectStore('keyval');
});

const idbKeyval = {
  async get(key) {
    const db = await dbPromise;
    return db.transaction('keyval').objectStore('keyval').get(key);
  },
  async set(key, val) {
    const db = await dbPromise;
    const tx = db.transaction('keyval', 'readwrite');
    tx.objectStore('keyval').put(val, key);
    return tx.complete;
  },
  async delete(key) {
    const db = await dbPromise;
    const tx = db.transaction('keyval', 'readwrite');
    tx.objectStore('keyval').delete(key);
    return tx.complete;
  },
  async clear() {
    const db = await dbPromise;
    const tx = db.transaction('keyval', 'readwrite');
    tx.objectStore('keyval').clear();
    return tx.complete;
  },
  async keys() {
    const db = await dbPromise;
    return db.transaction('keyval').objectStore('keyval').getAllKeys(key);
  },
};
```

### Usage

```js
idbKeyval.set('foo', {hello: 'world'});

// logs: {hello: 'world'}
idbKeyval.get('foo').then(val => console.log(val));
```

## Set of objects

Imagine we had a set of objects like…

```json
{
  "id": 123456,
  "data": {"foo": "bar"}
}
```

### Upgrading existing DB

```js
const dbPromise = openDb('keyval-store', 2, upgradeDB => {
  // Note: we don't use 'break' in this switch statement,
  // the fall-through behaviour is what we want.
  switch (upgradeDB.oldVersion) {
    case 0:
      upgradeDB.createObjectStore('keyval');
    case 1:
      upgradeDB.createObjectStore('objs', {keyPath: 'id'});
  }
});
```

### Adding

```js
dbPromise.then(db => {
  const tx = db.transaction('objs', 'readwrite');
  tx.objectStore('objs').put({
    id: 123456,
    data: {foo: "bar"}
  });
  return tx.complete;
});
```

### Getting all

```js
dbPromise.then(db => {
  return db.transaction('objs')
    .objectStore('objs').getAll();
}).then(allObjs => console.log(allObjs));
```

### Getting by ID

```js
dbPromise.then(db => {
  return db.transaction('objs')
    .objectStore('objs').get(123456);
}).then(obj => console.log(obj));
```

# Limitations

## Transaction lifetime

An IDB transaction will auto-close if it doesn't have anything to do once microtasks have been processed. As a result, this works fine:

```js
dbPromise.then(async db => {
  const tx = db.transaction('keyval', 'readwrite');
  const store = tx.objectStore('keyval');
  const val = await store.get('counter') || 0;
  store.put(val + 1, 'counter');
  return tx.complete;
});
```

But this doesn't:

```js
dbPromise.then(async db => {
  const tx = db.transaction('keyval', 'readwrite');
  const store = tx.objectStore('keyval');
  const val = await store.get('counter') || 0;
  // The transaction will auto-close while the fetch is in-progress
  const newVal = await fetch('/increment?val=' + val)
  store.put(newVal, 'counter');
  return tx.complete;
});
```

## Promise issues in older browsers

Some older browsers don't handle promises properly, which causes issues if you do more than one thing in a transaction:

```js
dbPromise.then(async db => {
  const tx = db.transaction('keyval', 'readwrite');
  const store = tx.objectStore('keyval');
  const val = await store.get('counter') || 0;
  // In some older browsers, the transaction closes here.
  // Meaning this next line fails:
  store.put(val + 1, 'counter');
  return tx.complete;
});
```

All modern browsers have fixed this. [Test your browser](https://simple-idb-demo.glitch.me/microtask-issue.html).

You can work around this in some versions of Firefox by using a promise polyfill that correctly uses microtasks, such as [es6-promise](https://github.com/jakearchibald/es6-promise).

# API

## `idb`

This is your entry point to the API. It's exposed to the global scope unless you're using a module system such as browserify, in which case it's the exported object. If you are using native ES modules, the functions are provided as individual exports, so you can `import * as idb from 'idb'` or `import { openDb, deleteDb } from 'idb'`.

### `openDb(name, version, upgradeCallback)`

This method returns a promise that resolves to a `DB`.

`name` and `version` behave as they do in `indexedDB.open`.

`upgradeCallback` is called if `version` is greater than the version last opened. It's similar to IDB's `onupgradeneeded`. The callback receives an instance of `UpgradeDB`.

```js
openDb('keyval-store', 2, upgradeDB => {
  // Note: we don't use 'break' in this switch statement,
  // the fall-through behaviour is what we want.
  switch (upgradeDB.oldVersion) {
    case 0:
      upgradeDB.createObjectStore('keyval');
    case 1:
      upgradeDB.createObjectStore('stuff', {keyPath: ''});
  }
}).then(db => console.log("DB opened!", db));
```

### `deleteDb(name)`

Behaves like `indexedDB.deleteDatabase`, but returns a promise.

```js
deleteDb('keyval-store').then(() => console.log('done!'));
```

## `DB`

Properties:

* Same as equivalent properties on an instance of `IDBDatabase`:
  * `name`
  * `version`
  * `objectStoreNames`

Methods:

* `close` - as `idbDatabase.close`
* `transaction` - as `idbDatabase.transaction`, but returns a `Transaction`

## `UpgradeDB`

As `DB`, except:

Properties:

* `transaction` - this is a property rather than a method. It's a `Transaction` representing the upgrade transaction
* `oldVersion` - the previous version of the DB seen by the browser, or 0 if it's new

Methods:

* `createObjectStore` - as `idbDatabase.createObjectStore`, but returns an `ObjectStore`
* `deleteObjectStore` - as `idbDatabase.deleteObjectStore`

## `Transaction`

Properties:

* `complete` - a promise. Resolves when transaction completes, rejects if transaction aborts or errors
* Same as equivalent properties on an instance of `IDBTransaction`:
  * `objectStoreNames`
  * `mode`

Methods:

* `abort` - as `idbTransaction.abort`
* `objectStore` - as `idbTransaction.objectStore`, but returns an `ObjectStore`

```js
openDb('keyval-store', 1, upgradeDB => {
  switch (upgradeDB.oldVersion) {
    case 0:
      upgradeDB.createObjectStore('keyval');
  }
}).then(db => {
  const tx = db.transaction('keyval', 'readwrite');
  tx.objectStore('keyval').put('hello', 'world');
  return tx.complete;
}).then(() => console.log("Done!"));
```

## `ObjectStore`

Properties:

* Same as equivalent properties on an instance of `IDBObjectStore`:
  * `name`
  * `keyPath`
  * `indexNames`
  * `autoIncrement`

Methods:

* Same as equivalent methods on an instance of `IDBObjectStore`, but returns a promise that resolves/rejects based on operation success/failure:
  * `put`
  * `add`
  * `delete`
  * `clear`
  * `get`
  * `getAll`
  * `getAllKeys`
  * `count`
* Same as equivalent methods on an instance of `IDBObjectStore`, but returns a promise that resolves with a `Cursor`:
  * `openCursor`
  * `openKeyCursor`
* `deleteIndex` - as `idbObjectStore.deleteIndex`
* Same as equivalent methods on an instance of `IDBObjectStore`, but returns an `Index`:
  * `createIndex`
  * `index`
* `iterateCursor` - see below
* `iterateKeyCursor` - see below


### `iterateCursor` & `iterateKeyCursor`

Due to the microtask issues in some browsers, iterating over a cursor using promises doesn't always work:

```js
const tx = db.transaction('stuff');
tx.objectStore('stuff').openCursor().then(function cursorIterate(cursor) {
  if (!cursor) return;
  console.log(cursor.value);
  return cursor.continue().then(cursorIterate);
});
tx.complete.then(() => console.log('done'));
```

So in the mean time, `iterateCursor` and `iterateKeyCursor` map to `openCursor` & `openKeyCursor`, take identical arguments, plus an additional callback that receives an `IDBCursor`, so the above example becomes:

```js
const tx = db.transaction('stuff');
tx.objectStore('stuff').iterateCursor(cursor => {
  if (!cursor) return;
  console.log(cursor.value);
  cursor.continue();
});
tx.complete.then(() => console.log('done'));
```

The intent is to remove `iterateCursor` and `iterateKeyCursor` from the library once browsers support promises and microtasks correctly.

## `Index`

Properties:

* Same as equivalent properties on an instance of `IDBIndex`:
  * `name`
  * `keyPath`
  * `multiEntry`
  * `unique`

Methods:

* Same as equivalent methods on an instance of `IDBIndex`, but returns a promise that resolves/rejects based on operation success/failure:
  * `get`
  * `getKey`
  * `getAll`
  * `getAllKeys`
  * `count`
* Same as equivalent methods on an instance of `IDBIndex`, but returns a promise that resolves with a `Cursor`:
  * `openCursor`
  * `openKeyCursor`
* `iterateCursor` - as `objectStore.iterateCursor` but over the index
* `iterateKeyCursor` - as `objectStore.iterateKeyCursor` but over the index

## Cursor

Properties:

* Same as equivalent properties on an instance of `IDBCursor`:
  * `direction`
  * `key`
  * `primaryKey`
  * `value`

Methods:

* Same as equivalent methods on an instance of `IDBCursor`, but returns a promise that resolves/rejects based on operation success/failure:
  * `update`
  * `delete`
* Same as equivalent methods on an instance of `IDBCursor`, but returns a promise that resolves with a `Cursor`:
  * `advance`
  * `continue`
  * `continuePrimaryKey`