IndexedDB in Dart

WARNING: As of 2012-02-27, and after further hacking, there are two blocking issues preventing IndexedDB from working properly. You can't delete an object by a key, and retrieved objects aren't actually objects.

IndexedDB is the new way to store key and indexed objects for offline retrieval in web apps. Learn how to use IndexedDB in your Dart application.

(Warning: this code isn't pretty, and many bugs were filed. This should get cleaned up soon. Regardless, it works! Also, you'll need the bleeding_edge branch of code, as of 2012-02-23.)

Why offline data storage?

Use client side local data storage to reduce bandwidth bills, decrease latency, increase UI performance, and allow your application to run offline.

Local data storage options

There are three options for storing local data for your web apps.

Local Storage (aka Web storage) is a very simple key/value store, however it can only store strings and is a blocking/synchronous API. Local Storage is better than cookies, but try to avoid it. Local Storage does have good cross browser coverage.

WebSQL is a SQLite database in the browser, supported by Webkit based browsers. WebSQL is powerful and fairly well understood, but will not be implemented in Firefox or Internet Explorer, and the spec is in limbo.

IndexedDB is on a standards track, and does have Chrome, Firefox, and (soon) Internet Explorer implementations. IndexedDB is the future of offline, local object storage for your web apps.

Ideally, you should use something like Lawnchair as an interface for object storage, and let the library implementation choose the best storage available. Lawnchair isn't ported to Dart... yet... so we'll look at direct IndexedDB code.

IndexedDB Reference

IndexedDB is a bit of a moving target. I used a combination of the Simple Todo List Using HTML5 IndexedDB from HTML5 Rocks and the MDN reference docs for IndexedDB. Of course, I also consulted the Dart API Docs.

The Bugs

During this exercise, I encountered and filed the following bugs:
Even with all the bugs above, you can still run IndexedDB in Dart. A big thanks to the Dart engineers that quickly fixed the blocking bugs.

The Code

IndexedDB currently works best with dart:dom. I used types so the Dart Editor helped me out with code completion and early error checks.

If you're not familiar with IndexedDB, this will look verbose to you. The API has been designed to use callbacks whenever possible to help ensure the main UI thread of your web app isn't blocked on slow IO calls.

-----------------------------------------------

#import('dart:dom', prefix:'dom');
#import('dart:html');

String VERSION = "1";
String TODOS_STORE = 'todos';

initDb(db) {
  if (VERSION != db.version) {
    dom.IDBVersionChangeRequest versionChange = db.setVersion(VERSION);
    versionChange.addEventListener('success', (e) {
      print("Set version");
      db.createObjectStore(TODOS_STORE);
      displayItems(db);
    });
    versionChange.addEventListener('error', (e) {
      print("Could not set version: $e");
    });
  } else {
    print("DB is at version ${db.version}");
    displayItems(db);
  }
}

displayItems(dom.IDBDatabase db) {
  dom.IDBTransaction txn = db.transaction(TODOS_STORE, dom.IDBTransaction.READ_ONLY);
  dom.IDBObjectStore objectStore = txn.objectStore(TODOS_STORE);
  dom.IDBRequest cursorRequest = objectStore.openCursor();
  cursorRequest.addEventListener("success", (e) {
    dom.IDBCursor cursor = e.target.result;
    if (cursor != null) {
      renderItem(cursor.value);
      cursor.continueFunction();
    }
  });
  cursorRequest.addEventListener('error', (e) {
    print("Could not open cursor: $e");
  });
}

renderItem(value) {
  var ul = document.query('#items');
  var li = new Element.tag("li");
  li.text = value;
  ul.elements.add(li);
}

addItem(db) {
  var msg = "Stuff ${new Date.now().value}";
  dom.IDBTransaction txn = db.transaction(TODOS_STORE, dom.IDBTransaction.READ_WRITE);
  dom.IDBObjectStore objectStore = txn.objectStore(TODOS_STORE);
  dom.IDBRequest addRequest = objectStore.put(msg, new Date.now().value);
  addRequest.addEventListener("success", (e) {
    renderItem(msg);
  });
  addRequest.addEventListener("error", (e) => print("Could not add: $e"));
}

registerButtons(db) {
  var add = document.query("#add");
  add.on.click.add((e) {
    addItem(db);
  });
}

// Chrome only for now,
// see bug http://code.google.com/p/chromium/issues/detail?id=108223
void main() {
  dom.IDBRequest request = dom.window.webkitIndexedDB.open('todo');
  request.addEventListener('success', (e) {
    print("Opened DB");
    dom.IDBDatabase db = e.target.result;
    // the following is Chrome only for now :(
    initDb(db);
    registerButtons(db);
  });
  request.addEventListener('error', (e) {
    print('Could not open db: $e');
  });
}

-----------------------------------------------

The above code only works in Chrome right now, as unfortunately Chrome hasn't caught up with the spec yet. With just a tiny bit of tweaking, you'll be able to get this to work in Firefox, too.

You can fork this code from the original Gist.

Summary

IndexedDB is a key/object store with support for indexes, and it is the eventual replacement for WebSQL database for complex object storage requirements. The API is heavily callback driven, ensuring the main browser UI thread isn't blocked by expensive I/O calls.

IndexedDB (at least, creating a database, reading entries, and adding entries) now works with Dart when compiled to JavaScript! Though we're still waiting for direct Dartium support, you can begin to add IndexedDB to your modern web apps.

Popular posts from this blog

The 29 Healthiest Foods on the Planet

The 29 Healthiest Foods on the Planet > The following is a "healthy food hot list" consisting of the 29 food that will give you the biggest nutritional bang for you caloric buck, as well as decrease your risk for deadly illnesses like cancer, diabetes and heart disease.
Read more

Lists and arrays in Dart

(This is Part 3 in a series about Dart. Check out Part 2, Function in Dart .) Warning : We expect the Dart libraries to undergo potentially sweeping changes before Dart goes to alpha. This document is relevant as of 2011-12-22. Intro Dart is a "batteries included" effort to help app developers build modern web apps. An important "battery" is the bundled core Dart libraries, providing common and rich functionality. Dart is building a solution for large, complex web apps, and providing well tested, integrated, and common libraries is key to helping a web app developer be more productive out of the box. The Collection libraries are a crucial set of APIs that Dart developers get for free. Much more than simple arrays and maps, the Collection library includes standard ways to filter, iterate, inspect, compose, and sort your data. This post specifically looks at List<E> , Dart's ordered, indexable collection of objects. Aside: The Dart project is lucky...
Read more

Converting Array to List in Scala

Now, this has to have a built-in somewhere in Scala , because it just seems too common. So, how to convert an Array to a List in Scala? Why do I need this? I needed to drop to Java for some functionality, which in this case returns an Array. I wanted to get that Array into a List to practice my functional programming skillz. **Update**: I figured out how to convert Arrays to Lists the Scala way. Turns out it's a piece of cake. val myList = List.fromArray(Array("one", "two", "three")) or val myList = Array("one","two","three").elements.toList The call to elements returns an Iterator , and from there you can convert to a List via toList . Nice. Because my first version wasn't actually tail recursive, what follows is a true tail recursive solution, if I were to implement this by hand. The above, built in mechanism is much better, though. object ArrayUtil { def toList[a](array: Array[a]): List[a] = { d...
Read more