@dumbmatter/idb 7.0.0 → 8.0.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+# 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.

package/README.md

@@ -1,6 +1,6 @@
 # IndexedDB with usability.
 
-This is a tiny (~1.05k brotli'd) library that mostly mirrors the IndexedDB API, but with small improvements that make a big difference to 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)
@@ -42,7 +42,7 @@ async function doDatabaseStuff() {
 
 ```html
 <script type="module">
-  import { openDB, deleteDB, wrap, unwrap } from 'https://cdn.jsdelivr.net/npm/idb@7/+esm';
+  import { openDB, deleteDB, wrap, unwrap } from 'https://cdn.jsdelivr.net/npm/idb@8/+esm';
 
   async function doDatabaseStuff() {
     const db = await openDB(…);
@@ -53,7 +53,7 @@ async function doDatabaseStuff() {
 ### Using external script reference
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/idb@7/build/umd.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/idb@8/build/umd.js"></script>
 <script>
   async function doDatabaseStuff() {
     const db = await idb.openDB(…);
@@ -71,8 +71,6 @@ A global, `idb`, will be created, containing all exports of the module version.
 
 This library targets modern browsers, as in Chrome, Firefox, Safari, and other browsers that use those engines, such as Edge. IE is not supported.
 
-If you want to target much older versions of those browsers, you can transpile the library using something like [Babel](https://babeljs.io/). You can't transpile the library for IE, as it relies on a proper implementation of [JavaScript proxies](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy).
-
 # API
 
 ## `openDB`
@@ -81,13 +79,13 @@ This method opens a database, and returns a promise for an enhanced [`IDBDatabas
 
 ```js
 const db = await openDB(name, version, {
-  upgrade(db, oldVersion, newVersion, transaction) {
+  upgrade(db, oldVersion, newVersion, transaction, event) {
     // …
   },
-  blocked() {
+  blocked(currentVersion, blockedVersion, event) {
     // …
   },
-  blocking() {
+  blocking(currentVersion, blockedVersion, event) {
     // …
   },
   terminated() {
@@ -103,8 +101,15 @@ const db = await openDB(name, version, {
   - `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`
@@ -121,6 +126,8 @@ await deleteDB(name, {
 
 - `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`
 
@@ -142,8 +149,6 @@ 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.
 
-This doesn't work with `IDBCursor`, [due to missing primitives](https://github.com/w3c/IndexedDB/issues/255). Also, if you wrap an `IDBTransaction`, `tx.store` and `tx.objectStoreNames` won't work in Edge. To avoid these issues, wrap the `IDBDatabase` object, and use the wrapped object to create a new transaction.
-
 ## General enhancements
 
 Once you've opened the database the API is the same as IndexedDB, except for a few changes to make things easier.
@@ -261,15 +266,7 @@ while (cursor) {
 
 ## Async iterators
 
-Async iterator support isn't included by default (Edge doesn't support them). To include them, import `idb/with-async-ittr` instead of `idb` (this increases the library size to ~1.28k brotli'd):
-
-```js
-import { openDB } from 'idb/with-async-ittr';
-```
-
-Or `https://cdn.jsdelivr.net/npm/idb@7/build/umd-with-async-ittr.js` if you're using the non-module version.
-
-Now you can iterate over stores, indexes, and cursors:
+You can iterate over stores, indexes, and cursors:
 
 ```js
 const tx = db.transaction(storeName);
@@ -320,19 +317,19 @@ const dbPromise = openDB('keyval-store', 1, {
 
 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

package/build/entry.d.ts

@@ -6,19 +6,28 @@ export interface OpenDBCallbacks<DBTypes extends DBSchema | unknown> {
      * @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 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'>): void;
+    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?(): void;
+    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?(): void;
+    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.
@@ -36,8 +45,11 @@ export declare function openDB<DBTypes extends DBSchema | unknown = unknown>(nam
 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?(): void;
+    blocked?(currentVersion: number, event: IDBVersionChangeEvent): void;
 }
 /**
  * Delete a database.
@@ -45,7 +57,7 @@ export interface DeleteDBCallbacks {
  * @param name Name of the database.
  */
 export declare function deleteDB(name: string, { blocked }?: DeleteDBCallbacks): Promise<void>;
-export { unwrap, wrap } from './wrap-idb-value';
+export { unwrap, wrap } from './wrap-idb-value.js';
 declare type KeyToKeyNoIndex<T> = {
     [K in keyof T]: string extends K ? never : number extends K ? never : K;
 };

package/build/index.cjs

@@ -2,7 +2,164 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
-var wrapIdbValue = require('./wrap-idb-value.cjs');
+const instanceOfAny = (object, constructors) => constructors.some((c) => object instanceof c);
+
+let idbProxyableTypes;
+let cursorAdvanceMethods;
+// This is a function to prevent it throwing up in node environments.
+function getIdbProxyableTypes() {
+    return (idbProxyableTypes ||
+        (idbProxyableTypes = [
+            IDBDatabase,
+            IDBObjectStore,
+            IDBIndex,
+            IDBCursor,
+            IDBTransaction,
+        ]));
+}
+// This is a function to prevent it throwing up in node environments.
+function getCursorAdvanceMethods() {
+    return (cursorAdvanceMethods ||
+        (cursorAdvanceMethods = [
+            IDBCursor.prototype.advance,
+            IDBCursor.prototype.continue,
+            IDBCursor.prototype.continuePrimaryKey,
+        ]));
+}
+const transactionDoneMap = new WeakMap();
+const transformCache = new WeakMap();
+const reverseTransformCache = new WeakMap();
+function promisifyRequest(request) {
+    const promise = new Promise((resolve, reject) => {
+        const unlisten = () => {
+            request.removeEventListener('success', success);
+            request.removeEventListener('error', error);
+        };
+        const success = () => {
+            resolve(wrap(request.result));
+            unlisten();
+        };
+        const error = () => {
+            reject(request.error);
+            unlisten();
+        };
+        request.addEventListener('success', success);
+        request.addEventListener('error', error);
+    });
+    // This mapping exists in reverseTransformCache but doesn't 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) {
+    // Early bail if we've already created a done promise for this transaction.
+    if (transactionDoneMap.has(tx))
+        return;
+    const done = new Promise((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 = {
+    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;
+    },
+};
+function replaceTraps(callback) {
+    idbProxyTraps = callback(idbProxyTraps);
+}
+function wrapFunction(func) {
+    // 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 (...args) {
+            // 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 (...args) {
+        // 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) {
+    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;
+}
+function wrap(value) {
+    // 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;
+}
+const unwrap = (value) => reverseTransformCache.get(value);
 
 /**
  * Open a database.
@@ -13,20 +170,24 @@ var wrapIdbValue = require('./wrap-idb-value.cjs');
  */
 function openDB(name, version, { blocked, upgrade, blocking, terminated } = {}) {
     const request = indexedDB.open(name, version);
-    const openPromise = wrapIdbValue.wrap(request);
+    const openPromise = wrap(request);
     if (upgrade) {
         request.addEventListener('upgradeneeded', (event) => {
-            upgrade(wrapIdbValue.wrap(request.result), event.oldVersion, event.newVersion, wrapIdbValue.wrap(request.transaction));
+            upgrade(wrap(request.result), event.oldVersion, event.newVersion, wrap(request.transaction), event);
         });
     }
-    if (blocked)
-        request.addEventListener('blocked', () => blocked());
+    if (blocked) {
+        request.addEventListener('blocked', (event) => blocked(
+        // Casting due to https://github.com/microsoft/TypeScript-DOM-lib-generator/pull/1405
+        event.oldVersion, event.newVersion, event));
+    }
     openPromise
         .then((db) => {
         if (terminated)
             db.addEventListener('close', () => terminated());
-        if (blocking)
-            db.addEventListener('versionchange', () => blocking());
+        if (blocking) {
+            db.addEventListener('versionchange', (event) => blocking(event.oldVersion, event.newVersion, event));
+        }
     })
         .catch(() => { });
     return openPromise;
@@ -38,9 +199,12 @@ function openDB(name, version, { blocked, upgrade, blocking, terminated } = {})
  */
 function deleteDB(name, { blocked } = {}) {
     const request = indexedDB.deleteDatabase(name);
-    if (blocked)
-        request.addEventListener('blocked', () => blocked());
-    return wrapIdbValue.wrap(request).then(() => undefined);
+    if (blocked) {
+        request.addEventListener('blocked', (event) => blocked(
+        // Casting due to https://github.com/microsoft/TypeScript-DOM-lib-generator/pull/1405
+        event.oldVersion, event));
+    }
+    return wrap(request).then(() => undefined);
 }
 
 const readMethods = ['get', 'getKey', 'getAll', 'getAllKeys', 'count'];
@@ -82,13 +246,67 @@ function getMethod(target, prop) {
     cachedMethods.set(prop, method);
     return method;
 }
-wrapIdbValue.replaceTraps((oldTraps) => ({
+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),
 }));
 
-exports.unwrap = wrapIdbValue.unwrap;
-exports.wrap = wrapIdbValue.wrap;
+const advanceMethodProps = ['continue', 'continuePrimaryKey', 'advance'];
+const methodMap = {};
+const advanceResults = new WeakMap();
+const ittrProxiedCursorToOriginalProxy = new WeakMap();
+const cursorIteratorTraps = {
+    get(target, prop) {
+        if (!advanceMethodProps.includes(prop))
+            return target[prop];
+        let cachedFunc = methodMap[prop];
+        if (!cachedFunc) {
+            cachedFunc = methodMap[prop] = function (...args) {
+                advanceResults.set(this, ittrProxiedCursorToOriginalProxy.get(this)[prop](...args));
+            };
+        }
+        return cachedFunc;
+    },
+};
+async function* iterate(...args) {
+    // tslint:disable-next-line:no-this-assignment
+    let cursor = this;
+    if (!(cursor instanceof IDBCursor)) {
+        cursor = await cursor.openCursor(...args);
+    }
+    if (!cursor)
+        return;
+    cursor = cursor;
+    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, prop) {
+    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);
+    },
+}));
+
 exports.deleteDB = deleteDB;
 exports.openDB = openDB;
+exports.unwrap = unwrap;
+exports.wrap = wrap;

package/build/index.d.ts

@@ -1,2 +1,3 @@
-export * from './entry';
-import './database-extras';
+export * from './entry.js';
+import './database-extras.js';
+import './async-iterators.js';