Skip to content
A polyfill for IndexedDB using WebSql
JavaScript Other
Latest commit 9ca9910 Jun 29, 2016 @brettz9 brettz9 - Testing (W3C): Fix: In IDBCursor.continue.js, flip mistaken order w…
…ithin test "attempt to call continue two times"

- Testing (W3C): Ensure expected exceptions match error name
- Testing (Grunt): Remove journal files for db.sqlite
- Fix: Ensure `__versionTransaction` set to `null` and set before `oncomplete`
    so that `versionchange` checks inside `e.target.transaction.oncomplete`
    within `onupgradeneeded` or inside `onsuccess` will fail (and thus will
    attempts to create or delete object stores)
Failed to load latest commit information.
dist - Testing (W3C): Fix: In IDBCursor.continue.js, flip mistaken order w… Jun 29, 2016
examples Rmv redundant or unneeded eslint rules; linting Jun 12, 2016
src - Testing (W3C): Fix: In IDBCursor.continue.js, flip mistaken order w… Jun 29, 2016
tests-mocha - Fix: More refined sorting for multi-entry cursors Jun 27, 2016
tests-polyfill - Testing (W3C): Fix: In IDBCursor.continue.js, flip mistaken order w… Jun 29, 2016
tests-qunit - Fix: Allow test to recover if objectStore.openKeyCursor is not supp… Jun 16, 2016
.babelrc Properly use babel (incomplete) Jun 12, 2016
.editorconfig Added unit tests for #200 May 27, 2015
.eslintignore Testing: Add tests-polyfill (should still make DOMException checks mo… Jun 15, 2016
.eslintrc Rmv redundant or unneeded eslint rules; linting Jun 12, 2016
.gitignore - Testing fix (W3C): Bump timeout for key sort order test in IDBFacto… Jun 29, 2016
.npmignore - Testing fix (W3C): Bump timeout for key sort order test in IDBFacto… Jun 29, 2016
.remarkrc Add back README.md in easier-to-find upper-case; tweak md-linting Jun 13, 2016
.travis.yml Update Node version with Travis (was having problem with ES6 features… Jun 26, 2016
CHANGES.md - Testing (W3C): Fix: In IDBCursor.continue.js, flip mistaken order w… Jun 29, 2016
CONTRIBUTING.md Convert JSHint to ESLint and lint; (#246) Jun 12, 2016
Gruntfile.js - Testing (W3C): Fix: In IDBCursor.continue.js, flip mistaken order w… Jun 29, 2016
IndexedDBShim.nuspec Fixing broken links caused by character-casing Apr 14, 2015
LICENSE-APACHE Dual license under MIT and apache Jun 13, 2014
LICENSE-MIT Add back MIT license Jun 12, 2016
README.md Further npm scripts for testing Jun 17, 2016
bower.json Update npmignore/bower.json ignore Jun 26, 2016
index.html Fixed issue #92 #92 Apr 16, 2015
package.json Add `browser` field to `package.json` as per spec: https://github.com… Jun 20, 2016
travis.sh Changed github user to github token Jun 22, 2013

README.md

IndexedDB Polyfill

Use a single offline storage API across all desktop and mobile browsers and Node.js

Build Status Dependencies npm Bower License

Live Demo!

Features

Installation

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

Node

npm install indexeddbshim

To set up:

const setGlobalVars = require('indexeddbshim');
// This function defines `shimIndexedDB`, `indexedDB`, `IDBFactory`, etc. on
//  one of the following objects in order of precedence:
// 1. A passed in object
// 2. `window` (for Node, define `GLOBAL.window = GLOBAL;`)
// 3. A new object
GLOBAL.window = GLOBAL; // We'll allow ourselves to use `window.indexedDB` or `indexedDB` as a global
setGlobalVars();

Bower

bower install IndexedDBShim

Using the polyfill

Add the script to your page

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

If the browser already natively supports IndexedDB, then the script won't do anything. Otherwise, it'll add the IndexedDB API to the browser. Either way, you can use IndexedDB just like normal. Here's an example

Fixing Problems in Native IndexedDB

Even if a browser natively supports IndexedDB, you may still want to use this shim. Some native IndexedDB implemenatations are very buggy. Others are missing certain features. There are also many minor inconsistencies between different browser implementations of IndexedDB, such as how errors are handled, how transaction timing works, how records are sorted, how cursors behave, etc. Using this shim will ensure consistent behavior across all browsers.

To force IndexedDBShim to shim the browser's native IndexedDB, add this line to your script:

window.shimIndexedDB.__useShim()

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.

Debugging

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:

window.shimIndexedDB.__debug(true);

Known Issues

All code has bugs, and this project is no exception. If you find a bug, please let us know about it. Or better yet, send us a fix! Please make sure someone else hasn't already reported the same bug though.

There are a few bugs that are outside of our power to fix. Namely:

iOS

Due to a bug in WebKit, the window.indexedDB property is read-only and cannot be overridden by IndexedDBShim. There are two possible workarounds for this:

  1. Use window.shimIndexedDB instead of window.indexedDB
  2. Create an indexedDB variable in your closure

By creating a variable named indexedDB, all the code within that closure will use the variable instead of the window.indexedDB property. For example:

(function() {
    // This works on all browsers, and only uses IndexedDBShim as a final fallback
    var indexedDB = window.indexedDB || window.mozIndexedDB || window.webkitIndexedDB || window.msIndexedDB || window.shimIndexedDB;

    // This code will use the native IndexedDB, if it exists, or the shim otherwise
    indexedDB.open("MyDatabase", 1);
})();

Windows Phone

IndexedDBShim works on Windows Phone via a Cordova/PhoneGap plug-in. There are two plugins available: cordova-plugin-indexedDB and cordova-plugin-indexeddb-async. Both plug-ins rely on a WebSQL-to-SQLite adapter, but there are differences in their implementations. Try them both and see which one works best for your app.

Building

To build the project locally on your computer:

  1. Clone this repo git clone https://github.com/axemclion/IndexedDBShim.git

  2. Install dev dependencies npm install

  3. Run the build script npm start

  4. Done

The output files will be generated in the dist directory

Testing

There are currently three folders for tests, tests-qunit, tests-mocha and tests-polyfill (the latter are also Mocha-based tests, but at present only work in Node).

They can be run through a variety of means as described below.

To properly build the files (lint, browserify, and minify), use npm start or to also keep a web server, run npm run dev (or grunt dev).

The tests produce various database files. These are avoided in .gitignore and should be cleaned up if the tests pass, but if you wish to delete them all manually, run npm run clean.

Browser testing

All QUnit-based browser tests should pass except one index.openCursor(range) test when run on PhantomJS due apparently to a bug with the PhantomJS implementation (but the test reports itself as having this problem).

All Mocha-based browser tests should pass except for one test having a problem in Firefox.

Headless browser unit testing

Follow all of the steps above to build the project, then run npm test (or npm run phantom-qunit or grunt phantom-qunit) to run the unit tests. The tests are run in PhantomJS, which is a headless WebKit browser.

Manual browser testing

If you want to run the tests in a normal web browser, you'll need to spin-up a local web server and then open tests-qunit/index.html?noglobals and/or tests-mocha/index.html in your browser. You can also run npm run dev and point your browser to http://localhost:9999/tests-qunit/index.html or http://localhost:9999/tests-mocha/index.html.

Note that, for the Mocha tests, you probably wish to "Switch to IndexedDBShim" when doing the testing since otherwise, it will only test the native implementation.

Node Testing

To run the Node tests, run the following:

  1. npm run qunit - The full test suite sometimes does not complete execution.
  2. npm run mocha
  3. npm run tests-polyfill (or its components npm run fake, npm run mock, npm run w3c). Note that none of these are currently passing in full, however.

To run a specific Mocha test (which includes the tests-polyfill tests), run npm --test=... run mocha.

Testing in a Cordova/PhoneGap app

If you want to run the tests in a Cordova or PhoneGap app, then you'll need to create a new Cordova/PhoneGap project, and add the IndexedDB plug-in. Then copy the contents of our tests directory into your project's www directory. Delete our index.html file and rename cordova.html to index.html.

Contributing

Pull requests or Bug reports welcome!!

Something went wrong with that request. Please try again.