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: 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.

Callbacks

Because of the asynchronous nature of this API, its operations communicate their statuses and results to callers via callbacks. In the context of simple storage, a callback is either a function or an object that defines the methods onResult and onError. If a callback is a function, it is called when its associated asynchronous operation successfully completes. If a callback is an object, its onResult method (if defined) is called when the operation successfully completes, and its onError method (if defined) is called when an error occurs during the operation. This allows callers to provide a simple function in the common case; only if callers wish to be notified of errors do they need to use the more verbose object form.

In this proposal, onResult refers to either the function form or the object.onResult form. Since there is only one form for errors, onError refers to the object.onError form.

onResult is called when the callback's associated asynchronous operation successfully completes:

onResult(key, [value])

onError is called when an error occurs during the operation:

onError(key, [value,] errorMessage)

The definitions of key and value vary according to the simple storage operation associated with the callback, and depending on the context value may not be passed at all. Details follow in the sections below.

Callbacks are optional, but callers should never assume that an operation completes successfully if it is important that it actually does so.

Storing Values

jetpack.storage.simple.set(key, value, callback)

Arguments

key: A string uniquely identifying the data to be placed into persistent storage, or an object whose properties and their values identify the data to place into persistent storage. If key is not a string or an object, an exception is thrown.

value: A JS primitive or JSON-able JS object that represents the data to be stored in persistent storage. If key is an object, this argument is ignored. 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.

Retrieving Values

jetpack.storage.simple.get(key, callback)

Arguments

key: A string uniquely identifying the data to be retrieved from persistent storage, or an array of such keys. If key is not a string or array of strings, an exception is thrown.

callback: A callback.

If key is a string, 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.

If key is an array of strings, onResult will be passed key and an array of the values of the keys. For each key in key, if the key exists in the store, then the value of the element at the corresponding index in the array of values will be the 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, or an array of such strings. If key is not a string or an array, an exception is thrown.

callback: A callback. onResult and onError will be passed only key.

Return value

This function has no return value.

Checking For the Existence of Values

jetpack.storage.simple.has(key, callback)

Arguments

key: A string uniquely identifying the data whose existence in persistent storage is to be checked, or an array of such keys. If key is not a string or array of strings, an exception is thrown.

callback: A callback.

If key is a string, onResult will be passed key and a boolean value. If key exists in the store, then the value will be true. If no such key exists, then the value will be false. onError will be passed only key.

If key is an array of strings, onResult will be passed key and an array of boolean values. For each key in key, if the key exists in the store, then the value of the element at the corresponding index in the array of values will be true. If no such key exists, then the value will be false. 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);
});