Labs/Jetpack/JEP/11

	THIS PAGE IS A WORKING DRAFT
	The page may be difficult to navigate, and some information on its subject might be incomplete and/or evolving rapidly. If you have any questions or ideas, please add them as a new topic on the discussion page.

JEP 11 - Simple Persistent Storage

• Author: Drew Willcoxon, <adw at mozilla dot com>
• Editors: Atul Varma <atul at mozilla dot com>, Aza Raskin <aza at mozilla dot com>
• Champion: Drew Willcoxon
• Status: Implementing
• Type: API Track
• Created: 27 May 2009
• Reference Implementation: None
• Relevant Bugs: bug 503466, bug 499871, bug 496694
• JEP Index

Introduction and Rationale

This JEP describes a simple mechanism through which Jetpacks can persistently store JS primitives and blobs of JSON data.

This proposal is favored over DOM Storage because the latter only supports storing strings, which forces the developer to manually perform error-prone parsing tasks for almost any kind of use case. It should also be noted that the simple storage outlined in this proposal can be implemented on the web using DOM Storage; as such, this proposal should not be considered "breaking the web".

Part of this proposal involves adding a jetpack.storage namespace.

Proposal

Simple, persistent storage will live at jetpack.storage.simple. The jetpack.storage namespace will provide access to any other available storage systems, such as SQLite, secure/password storage, and so on. The current jetpack.sessionStorage object, which allows arbitrary JS objects (they need not be JSON-able) to be stored between reloads of a Jetpack within the same Firefox session, will be renamed to jetpack.storage.session.

Simple storage is really simple. jetpack.storage.simple is a single, persistent JavaScript object available and private to each Jetpack feature. For the most part this object is like any other JavaScript object, and a feature can set whatever properties it wants on it. To manipulate its persistent data, a feature therefore need only use the various standard JavaScript functions and operators.

The jetpack.simple.storage object is automatically flushed to disk. How and when it is flushed is an implementation detail -- either periodically and on onload or, perhaps in the future if using catch-alls, when a property is set on the object. Storage may be flushed manually, however, by calling jetpack.storage.simple.sync(). The object can be forced to reload its data from disk by calling jetpack.storage.simple.open(), although the data comes loaded automatically.

Flushing Storage to Disk

As described above, the jetpack.storage.simple object is automatically written to disk, but a feature may force flush by calling:

jetpack.storage.simple.sync()

Arguments

This method takes no arguments.

Return value

This method has no return value.

Repopulating Storage

As described above, the jetpack.storage.simple object is automatically populated when a feature is loaded, but a feature may force the object to read from disk by calling:

jetpack.storage.simple.open()

Note that any properties already on the object will be overwritten, but no properties are deleted before loading.

Arguments

This method takes no arguments.

Return value

This method has no return value.

Example Usage

This code persistently stores some data:

jetpack.future.import("storage.simple");
var myStorage = jetpack.storage.simple;
myStorage.fribblefrops = [1, 3, 3, 7];
myStorage.heimelfarbs = { bar: "baz" };

And then to use these objects later:

var myStorage = jetpack.storage.simple;
myStorage.fribblefrops.forEach(function (elt) console.log(elt));
var bar = myStorage.heimelfarbs.bar;

That's all there is to it! (These examples create a myStorage variable to emphasize the fact that jetpack.storage.simple is just a normal JavaScript object. We could have simply used jetpack.storage.simple directly.)