Want to take your software engineering career to the next level? Join the mailing list for career tips & advice Click here


Star full 4f7b624809470f25b6493d5a7b30d9b9cb905931146e785d67c86ef0c205a402Star full 4f7b624809470f25b6493d5a7b30d9b9cb905931146e785d67c86ef0c205a402Star full 4f7b624809470f25b6493d5a7b30d9b9cb905931146e785d67c86ef0c205a402Star full 4f7b624809470f25b6493d5a7b30d9b9cb905931146e785d67c86ef0c205a402Star full 4f7b624809470f25b6493d5a7b30d9b9cb905931146e785d67c86ef0c205a402 (1 ratings)
Rated 5.0 out of 5
Subscribe to updates I use db

Statistics on db

Number of watchers on Github 98
Number of open issues 1
Average time to close an issue 3 months
Main language JavaScript
Average time to merge a PR about 4 hours
Open pull requests 0+
Closed pull requests 0+
Last commit over 7 years ago
Repo Created over 8 years ago
Repo Last Updated over 2 years ago
Size 965 KB
Organization / Authorwebreflection
Page Updated
Do you use db? Leave a review!
View db activity
View on github
Fresh, new opensource launches 🚀🚀🚀
Software engineers: It's time to get promoted. Starting NOW! Subscribe to my mailing list and I will equip you with tools, tips and actionable advice to grow in your career.
Evaluating db for your project? Score Explanation
Commits Score (?)
Issues & PR Score (?)

asyncStorage :: a developer friendly Asynchronous Storage

let's face reality, the status of storages in the Web is a mess. localStorage is a synchronous API not suitable at all to store data. WebSQL has been abandoned, still the only option, as non experimental, in Safari, Chrome, and Opera. Firefox is trying to support IndexedDB which right now is the most messed up API ever: loads of inconsistencies across platforms, included different versions of Firefox itself. Internet Explorer 10, the one not even out yet, has insignificant market sharing 'till now. My proposal to bring WebSQL back through Firefox extension has been banned, after approval, due potential securities issues ... so, what the hell we have to do in order to use a proper storage that is not ultra-complicated to understand, learn, and use?

The Problem with the WebStorage API

localStorage and sessionStorage have been around for quite a while and many developers are using these for any sort of task, including any sort of data stored in these synchronous storage without considering that:

  • your data is not safe, the first script that will easily perform a localStorage.clear() in the page your script is, your whole logic will magically fuck up without any notification (also because the event storage is completely randomly implemented)
  • synchronous means blocking, but we all agree that synchronous logic is easier to implement and maintain, right? ... well, unless you are not storing a few bytes once a while, you are making the browser potentially stuck ... just stop it, if you find this solution convenient
  • your data is limited, from 2mb up to 5mb but most important, the WebStorage API does not provide any way to know how much data is still available
  • you are doing it wrong ... and please don't judge me for this sentence, the problem is that 99% of online tutorials on localStorage are using direct property access, completely obtrusive for any sort of shimmable solution you would like to implement, plus 99% of the time these tutorials are not using a try{}catch(e){} statement around every single localStorage.setItem(key, value) call, which means your business logic is already broken

A Solution Based On WebStorage API

What if you have nothing new to learn, using exactly the same API the WebStorage offer, except how to handle callbacks? This is what is this project about, a basically identical API borrowed directly from the Web Storage one, with a couple of extra arguments per each asynchronous method such callback and errorback, where both are even optional.

The Concept

First of all, the main purpose of this project is to use any asynchronous possibility available in the browser through a key/value pairs based interface where both keys and values should be strings. It is not the purpose of this script to provide any JSON shim in your code, but of course as you have probably used JSON already to store data in a generic storage, you can do the same with this implementation, remembering to JSON.stringify(yourDataObject) before you store it. Back to the asynchronous concept, Where there is no possibility, the localStorage or even document.cookie is used as fallback so that even IE6 should work _without problems_, whenever you decided to harakiri supporting latter browser. The very first option, if available, is the WebSQL storage, the best thing ever destroyed by W3C, the most cross platform, for both Desktop and Mobile, storage possibility. IndexedDB would be the other option where WebSQL is not available. This order might change in the future preferring IndexedDB as first option. All others will fallback into localStorage or document.cookie and I am not discarding at all the possibility to use a SharedObject from the Flash Player world ... but, you know, I have abandoned Flash Player about 6 years ago and if I can make it without it, now that would be cool! What else? Oh well, it's easy!

So you made the localStorage asynchronous? Tell me how easier it is ...

asyncStorage.create("myDBName", function (db, numberOfEntries) {
    // database created, time to rock'n'roll!
    var callback = function (value, key) {
        if (value === "true") {
            // do amazing stuff for the very first time
        // do whatever you want to
    // check how many values you have stored so far
    if (numberOfEntries === 0) {
        // add some default entry
        db.setItem("neverLoaded", "true", callback);
    } else {
        db.setItem("neverLoaded", "false", callback);

Above is just an example of easiness provided by this asynchronousStorage but here few main pros:

  • unobtrusive, you chose your own database name as you would do for any of your libraries or namespaces . This simply means something like localStorage.clear(), performed by another library, will not erase your whole data. db.clear() aim is to clean only data you stored and nobody else.
  • asynchronous, since almost every method is made with async in mind. The only two things that are not asynchronous are db.length and, since length is synchronous, db.key(index) to retrieve the key associated to that index.
  • nothing new to learn which is the most annoying part of all these not fully defined yet options we have today in the Web scenario

AsynchronousStorage API

  • create(name, callback) creates a new database with specific name in order to, somehow, simulate namespaces in the storage itself. callback(db, numberOfEntries) will be fired once the database has been created.
  • create(name, callback, errorback) does the same, except you might want to handle potential errors during database creation (user denied, not enough space, etc).
  • create(name, callback, errorback, size) does the same, except you might want to specify in advance the size of the database. This overload works as expected with WebSQL only.
  • db.setItem(key, value[, callback[, errorback]]) set an item in the storage and calls callback(value, key, db) once the operation is completed. The errorback is called if something went wrong during this operation.
  • db.getItem(key[, callback[, errorback]]) retrieves a value from the storage, callback(value, key, db) is called once the operation is completed where the value is exactly null wherever key was not set before
  • db.removeItem(key[, callback[, errorback]]) remove an item from the storage, calls callback(key, db) once succeeded
  • db.clear([callback[, errorback]]) remove all keys associated to your database name, the one used to create the storage at the very beginning. callback(db, numberOfEntries) will be triggered once the operation has been completed, same signature of the storage creation for functions reusability.
  • db.key(index) returns synchronously the associated key for that index. This is necessary to make easier for developers loops over all keys as they do already with the localStorage, i.e.

    function isItLastOne() {
        if (!--i) {
    for (var i = 0; i < db.length; i++) {
        db.removeItem(db.key(i), isItLastOne);
  • db.length returns the length of all stored keys in your database name

  • db.name returns the name you chose for this storage instance

  • db.type returns the type of the database you are using such WebSQL, IndexedDB (not yet), localStorage, and cookie

And this is pretty much it ... wanna test? this page should be green

How to use it

after cloning the repo from github just type make

How to run the tests

just type ./test.sh


  • improve tests to test errorbacks too
  • optionally, consider a fifth fallback through Flash Player shared object (meh...!)
  • create a couple of wrappers for node.js (MongoDB,...)
db open issues Ask a question     (View All Issues)
  • about 7 years iOS - quota exceeded callback not fired
db questions on Stackoverflow (View All Questions)
  • Merge a data in db-table with new data
  • Entity Framework multiple mapping to same table DB first
  • Query for retrieving data from sqlite db with where clause using cursor
  • How to connect android app with nosqlcloudant db Ibm bluemix service?
  • Gradle Spring-data-dynamo db
  • Benefits of increasing DB initial size
  • CakePHP 3 - How not to fetch records from DB, if there is no translation available
  • WPF Application with Secure DB shippeda long with the application
  • Multiple DB Objects from Multiple flat files in SSDT/SSIS For Each Loop Container
  • How to delete a record in a Mysql DB without reload page with Codeigniter(3)
  • "A destination table has not been provided" when using variable for OLE DB Name SSIS
  • How to rollback my DB changes after a commit?
  • Pear php dir, DB module, Nominatim
  • Case statement for a date field with Mysql db
  • How to write Custom Plugin for Cordova /Swift CoreData Plugin for DB Access
  • is it possible to replace existing sqlite db file with other db file from directory in phongeap
  • How to add user specific unique id for a document in Cloudant DB using Javascript
  • Rails 2 hook to modify data before it is read/written to MySQL DB
  • mongo db connection issue "Cannot call method 'update' of undefined"
  • Multiple string check in oracle db
  • OBIEE issue: data is present in OLTP DB but not populating to OBIEE reports for a particular column
  • Scale Java webservice with Oracle DB
  • Fetch data from DB in UserSpice
  • ManyToMany relation : Data not persisting in DB
  • how to insert devlys font into mysql db through netbeans form? beca my book name is in hindi
  • how to enable remote shell with embedded db on SDN4?
  • Javascript -- Taffy DB adding phantom ID fields
  • Connect standalone script to joomla DB using framework
  • ASP.Net Server prints data from DB but won't write to DB
  • Retrieve table relationships from MS Access DB using C#
db list of languages used
Other projects in JavaScript