|
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: Atul Varma <atul at mozilla dot com>
- Champion: Atul Varma <atul at mozilla dot com>
- Status: Draft
- Type: API Track
- Created: 27 May 2009
- Reference Implementation: None
- JEP Index
Introduction and Rationale
This JEP describes a simple mechanism through which Jetpacks can persistently and asynchronously store JS primitives and blobs of JSON data. Asynchronicity is desirable because a Jetpack's usage of persistent storage should not block the browser's front-end.
The API of this proposal is constrained by what is possible to implement using JavaScript 1.8, since distributing binary components with the Jetpack extension is nontrivial.
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
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.
Synchronous versus Asynchronous
A lot of discussion has gone into whether the this proposal should be synchronous or asynchronous. An asynchronous API provides a more developer ergonomic API, whereas a synchronous API doesn't incur an I/O hit.
Given that (1) window.localStorage is synchronous, and (2) by putting Jetpacks into their own threads we remove the I/O hit of synchronicity, this proposal opts for a synchronous API.
Storing Values
jetpack.storage.simple.set(key, value, callback)
Arguments
key: A string uniquely identifying the data to be placed in persistent storage. If key is not a string, an exception is thrown.
value: A JS primitive or JSON-able JS object that represents the data to be stored in persistent storage. If some other data with the given key is already being stored, it is overwritten by value. If value is not a JS primitive or a JSON-able JS object, an exception is thrown.
callback: A callback. onResult and onError will be passed key and value.
Return value
This function has no return value.
jetpack.storage.simple.set(keyValueDict, callback)
Arguments
keyValueDict: An object containing key-value pairs as above. For example { foo: 1, bar: true, baz: "example" }.
callback: A callback. onResult and onError will be passed key and value.
Retrieving Values
jetpack.storage.simple.get(key, callback)
Arguments
key: A string uniquely identifying the data to be retrieved from persistent storage. If key is not a string, an exception is thrown.
callback: A callback. onResult will be passed key and a value. If key exists in the store, then the value will be key's associated data. If no such key exists, then the value will be undefined. onError will be passed only key.
Return value
This function has no return value.
Removing Values
jetpack.storage.simple.remove(key, callback)
Removes the key and its associated data from persistent storage. Calling jetpack.storage.simple.remove(key) is the same as calling jetpack.storage.simple.set(key, undefined).
Arguments
key: The string uniquely identifying the data to be removed from persistent storage. If key is not a string, an exception is thrown.
callback: A callback. onResult and onError will be passed only key.
Return value
This function has no return value.
Other Notes
Equivalence vs. Equality
The values passed into set() and returned from get() are all serialized/de-serialized at the time of calling; this means that, for instance, given the following code:
var original = {foo: 'bar'};
jetpack.storage.simple.set('test', original);
the following condition will hold:
jetpack.storage.simple.get('test', function (key, val) {
assert(val != original);
});