Home

Awesome

FruitDOWN project unmaintained Build Status

A browser-based LevelDOWN adapter that works over all implementations of IndexedDB, including Apple's buggy version.

⚠️⚠️⚠️

Update: Safari has largely fixed their IndexedDB issues, starting around Safari 10.1. If you are supporting recent versions of iOS and Safari (iOS >=10.3 and Safari >=10.1 roughly) then you do not need fruitdown. It is now unmaintained.

Original documentation follows:

⚠️⚠️⚠️

This is designed for environments where you can't use WebSQL as a polyfill for Safari browsers, such as:

This project is intended for use with the Level ecosystem, including as a PouchDB adapter.

Install

npm install fruitdown

Background

IndexedDB support is pretty awful these days. Every browser except for Chrome and Firefox has tons of bugs, but Safari's are arguably the worst. While there are well-known workarounds for Microsoft's bugs, most IndexedDB wrappers just gave up and didn't support Apple IndexedDB. PouchDB, LocalForage, YDN-DB, Lovefield, Dexie, and Level.js all either fall back to WebSQL or recommend that you use the IndexedDBShim.

This library is different. It does all the weird backflips you have to do to support Apple IndexedDB.

Design

This project is a fork of localstorage-down. It uses a tiny subset of the IndexedDB API – just those parts that are supported in Firefox, Chrome, Safari, and IE. The #1 goal is compatibility with as many browsers as possible. The #2 goal is performance.

Only one object store is ever opened, because Apple's implementation does not allow you to open more than one at once. So presumably you would use something like level-sublevel to prefix keys. Also every operation is its own transaction, so you should not count on standard IndexedDB transaction guarantees, even when you use batch(). However, internally the lib does its own batching, and supports snapshots.

All keys are kept in memory, which is bad for memory usage but actually a win for performance, since IDBCursors are slow. However, the database creates two indexes, because 1) the primary index does not support openKeyCursor() per the IndexedDB 1.0 spec, and we want to use it to avoid reading in large values during key iteration, but 2) secondary indexes do not correctly throw ConstraintErrors in Safari. So unfortunately there's a superfluous extra index. ¯\_(ツ)_/¯

Another limitation is that both keys and values are converted to strings before being stored. So instead of efficiently using Blobs or even JSON objects, binary strings are stored instead. This is okay, though, because Chrome < 43 (and therefore pre-Lollipop Android) does not store Blobs correctly, and Safari doesn't support Blob storage either.

To avoid concurrency bugs in IE/Edge, this project borrows PouchDB's system of maintaining a global cache of databases and only ever using one database per name. It also works around a bug with key ordering in Safari.

Browser support

FruitDOWN supports any browser that has IndexedDB, even those with partial support. Notably:

The buggy Samsung/HTC IndexedDB variants based on an older version of the IndexedDB spec, which you will occasionally find in Android 4.3, are not supported.

See .travis.yml for the full list of browsers that are tested in CI.

Future

Apple have pledged to fix IndexedDB. When they do, you should stop using this library and use Level.js or another IndexedDB wrapper instead.

Tests

npm run dev

Browse to http://localhost:9966. View console logs in the browser to see test output.

Automated tests

Browser:

BROWSER=firefox npm test
BROWSER=chrome npm test

FakeIndexedDB in Node:

npm run test-fakeindexeddb

PhantomJS tests:

npm run test-phantom

Thanks

Thanks to Anton Whalley, Adam Shih and everybody else who contributed to localstorage-down. Also thanks to everybody who worked on PouchDB, where most of these IndexedDB bugs were discovered.