fruitdown

FruitDOWN

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

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

• WKWebView, which doesn't have WebSQL
• Safari/iOS, but you don't want an annoying popup after you reach 5MB
• Safari/iOS, but you need to store more than 50MB, which doesn't work in WebSQL but works in IndexedDB

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

Install

npm install fruitdown

Background

Cross-browser IndexedDB support is pretty awful these days. Every browser except for Chrome and Firefox has tons of bugs, but Apple'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 crazy 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 things 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.

All keys are kept in memory at all times, which is bad for memory usage but actually improves performance, because 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 keys are indexed twice. ¯\_(ツ)_/¯

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. This should have zero impact on performance.

Browser support

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

• Safari 7.1+
• iOS 8+
• IE 10+
• Chrome 23+
• Firefox 10+
• Android 4.4+

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.

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 test

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

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.