Installation

You can download the development or production (minified) script, or install it using NPM.

For Mac, you may need to have CMake installed for the SQLite3 install to work (See Tools->How to Install For Command Line Use) as well as build SQLite3 from source via npm install --build-from-source in the node-sqlite3 directory. Also make sure Python (2.7) is installed.

npm

npm install indexeddbshim

or

yarn add indexeddbshim

Browser set-up

Add the following scripts to your page:

<script src="./node_modules/indexeddbshim/dist/indexeddbshim.min.js"></script>

If you need full Unicode compliance (handling special non-alphanumeric identifiers in store and index names), use the following instead:

<script src="./node_modules/indexeddbshim/dist/indexeddbshim-UnicodeIdentifiers.min.js"></script>

Node set-up

const setGlobalVars = require('indexeddbshim');
globalThis.window = globalThis; // We'll allow ourselves to use window.indexedDB or indexedDB as a global
setGlobalVars(); // See signature below

Deno set-up

The project works with Deno (and idb) according to a user.

Be sure to call with --location.

deno --location http:foo -A main.ts

The location must start with http: or https: per Deno.

Jest (or other test environments with a jsdom/Window-like global)

If you call setGlobalVars(global) (or setGlobalVars(window)) inside a Jest test/setup file, accessing indexedDB afterwards can throw:

TypeError: Illegal invocation

This happens because the indexedDB getter performs a brand check (much like native browsers do) to ensure it is invoked with the same this it was defined on. Under Jest, the object accessing indexedDB (e.g. jsdom's Window) is not always reference-equal to the object passed to setGlobalVars, so the check fails.

As a workaround, set shimNS on the target global before calling setGlobalVars, so the brand check is bypassed for that object:

// e.g., jest/testSetup.js
import setGlobalVars from 'indexeddbshim';
global.shimNS = true;
setGlobalVars(global);

I never call setGlobalVars myself (e.g. React Native/Expo + jest-expo)

You can still hit this even if your test never touches indexedDB directly (e.g. a plain component-render test). It means some module in your import chain (a dependency, a polyfill file, etc.) pulls in the invasive build of indexeddbshim, which auto-invokes setGlobalVars() as a side effect of being imported.

Because that happens at import time, you must set shimNS on the global before that import chain runs — a normal test file beforeEach/import is too late. Use Jest's setupFiles (which runs before the test framework and any test file imports are evaluated) for this:

// jest.config.js
module.exports = {
    preset: 'jest-expo',
    setupFiles: ['./jest/shim-ns-setup.js']
};

// jest/shim-ns-setup.js
if (typeof global.window === 'undefined') {
    global.window = global;
}
global.window.shimNS = true;
global.shimNS = true;

If you're using setupFilesAfterEnv instead (e.g. because you also need @testing-library/jest-native matchers), it will be too late if the offending import happens as part of loading another setupFilesAfterEnv module or the test file itself — keep the shimNS assignment in setupFiles so it always runs first.

ES6 Modules

Bundler for Browser

import setGlobalVars from 'indexeddbshim';

Bundler for Node

import setGlobalVars from 'indexeddbshim/src/node-UnicodeIdentifiers.js';
// Or without Unicode support
// import setGlobalVars from 'indexeddbshim/src/node.js';

Usage/API

For the browser scripts, if the browser already natively supports IndexedDB and is not known to be buggy, then the script won't do anything.

Otherwise, assuming WebSQL is available, the script will add the IndexedDB API to the browser (unless you use one of the non-invasive files, in which case setGlobalVars can be used to optionally add the API to an object of your choosing; if you also wish Unicode support, you will need to add it yourself).

Either way, you can use IndexedDB just like normal. Here's an example.

setGlobalVars(\null\>, initialConfig)

In the non-invasive builds (and Node.js), globals are not automatically set. You have the choice to set globals when you wish as well as to set the API on an object of your choosing in place of setting globals.

This is done through setGlobalVars() (which is otherwise called in the browser builds automatically with no arguments).

This function defines shimIndexedDB, indexedDB, IDBFactory, etc. on one of the following objects in order of precedence:

1. The passed in winObj object if defined
2. window (for Node, define global.window = global;)
3. self (for web workers)
4. global (for Node)
5. A new empty object

If you are adding your own window.openDatabase implementation, supplying it within initialConfig (keyed as openDatabase) will ensure that shimIndexedDB.__useShim() is auto-invoked for you if poor IndexedDB support is detected.

shimIndexedDB.\__useShim();

To force IndexedDBShim to shim the browser's native IndexedDB (if our code is not already auto-shimming your browser when detecting poor browser support), add this method call to your script.

On browsers that support WebSQL, this line will _completely replace_ the native IndexedDB implementation with the IndexedDBShim-to-WebSQL implementation.

On browsers that _don't_ support WebSQL, but _do_ support IndexedDB, this line will patch many known problems and add missing features. For example, on Internet Explorer, this will add support for compound keys.

If CFG.addNonIDBGlobals has been set (e.g., on the initialConfig argument of setGlobalVars), the other non-IndexedDB shims necessitated by this library will be polyfilled as possible on the chosen "global" (i.e., ShimEvent, ShimCustomEvent, ShimEventTarget, ShimDOMException, and ShimDOMStringList). Mostly useful for testing.

If CFG.replaceNonIDBGlobals is used, it will instead attempt to add, or if already present, overwrite these globals.

If CFG.fullIDLSupport has been set, the slow-performing Object.setPrototypeOf calls required for full WebIDL compliance will be used. Probably only needed for testing or environments where full introspection on class relationships is required. See this SO topic

shimIndexedDB.\__forceClose([dbName], [connIdx], [msg])

The spec anticipates the closing of a database connection with a forced flag.

The spec also mentions some circumstances where this may occur:

A connection may be closed by a user agent in exceptional circumstances,

for example due to loss of access to the file system, a permission change,

or clearing of the origin’s storage.

Since the latter examples are under the browser's control, this method may be more useful on the server or for unit-testing.

If the first argument, dbName is missing (or null or undefined), all connections to all databases will be force-closed.

If the second argument, connIdx is missing (or null or undefined), all connections with the given name will be force-closed. It can alternatively be an integer representing a 0-based index to indicate a specific connection to close.

The third argument msg will be appended to the AbortError that will be triggered on the transactions of the connection.

Individual IDBDatabase database instances can also be force-closed with a particular message:

db.__forceClose(msg);

shimIndexedDB.\__setConnectionQueueOrigin(origin = getOrigin())

Establishes a connectionQueue for the supplied (or current) origin.

The queue is otherwise only keyed to the detected origin on the loading of the IndexedDBShim script, though this is usually the desired behavior.

shimIndexedDB.\__debug(boolean)

The IndexedDB polyfill has sourcemaps enabled, so the polyfill can be debugged even if the minified file is included.

To print out detailed debug messages, add this line to your script:

shimIndexedDB.__debug(true);

shimIndexedDB.\__setConfig()

Rather than using globals, a method has been provided to share state across IndexedDBShim modules.

Configuration can be set early in the non-invasive browser and Node builds via the second argument to setGlobalVars() (see its definition above).

Its signature (for setting configuration after shimIndexedDB is created) is:

shimIndexedDB.__setConfig({
    property: value, property2: value2, ...otherProperties
});

or:

shimIndexedDB.__setConfig(property, value);

createDOMException(name, message)

A utility for creating a DOMException instance. Attempts to use any available native implementation.

Configuration options

The available properties relevant to browser or Node are:

• __DEBUG__ - Boolean (equivalent to calling shimIndexedDB.__debug(val))
• __cacheDatabaseInstances__ - Config to ensure that any repeat

• __checkOrigin__ - Boolean on whether to perform origin checks in IDBFactory

• __UnicodeIDStart__ and __UnicodeIDContinue__ - Invocation of

• __registerSCA__ - For data created in 3.* versions of IndexedDBShim to

• __fullIDLSupport__ - If set to true, the slow-performing

• __win__, Object on which there may be an openDatabase method (if any)

shimIndexedDB.__getConfig(property);