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>
• Editors: Drew Willcoxon <adw at mozilla dot com>
• Champion: Atul Varma
• Status: Implementing
• Type: API Track
• Created: 27 May 2009
• Reference Implementation: None
• Relevant Bugs: bug 496694, bug 499871
• 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.

The arguments passed to onResult and onError depend on the API method to which the callback is passed. Each method's description below indicates how it calls its callback.

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

Storing a Single Item

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

Arguments

key: A string uniquely identifying the data to be placed into persistent storage.

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 undefined, this method is equivalent to jetpack.storage.simple.remove.

callback: A callback. onResult and onError are called as follows:

• onResult(key, value)
• onError(errorMessage, key, value)

Return value

This method has no return value.

Storing Multiple Items

jetpack.storage.simple.set(itemsObject, callback)

Arguments

itemsObject: An object whose properties and their values identify the data to be placed into persistent storage. As in the single item form of this method, if some other data with a given key is already being stored, it is overwritten by the value in itemsObject. If a given value is undefined, its key is removed from the store.

callback: A callback. onResult and onError are called as follows:

• onResult(itemsObject)
• onError(errorMessage, itemsObject)

Return value

This method has no return value.

Retrieving a Single Item

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

Arguments

key: A string uniquely identifying the data to be retrieved from persistent storage.

callback: A callback. onResult and onError are called as follows:

• onResult(key, value)
  • value is key's associated data.
  • If key does not exist in the store, value is undefined.
• onError(errorMessage, key)

Return value

This method has no return value.

Retrieving Multiple Items

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

Arguments

keyArray: An array of strings, each of which uniquely identifies data to be retrieved from persistent storage.

callback: A callback. onResult and onError are called as follows:

• onResult(itemsObject)
  • The properties and values of itemsObject are the key-value pairs corresponding to the keys in keyArray.
  • If a key does not exist in the store, its associated value in itemsObject is undefined.
• onError(errorMessage, keyArray)

Return value

This method has no return value.

Retrieving All Items

jetpack.storage.simple.get(callback)

Arguments

callback: A callback. onResult and onError are called as follows:

• onResult(allItemsObject)
  • The properties and values of allItemsObject are all of the key-value pairs in the store.
• onError(errorMessage)

Return value

This method has no return value.

Removing a Single Item

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.

callback: A callback. onResult and onError are called as follows:

• onResult(key)
• onError(errorMessage, key)

Return value

This method has no return value.

Removing Multiple Items

jetpack.storage.simple.remove(keyArray, callback)

Arguments

key: An array of strings, each of which uniquely identifies data to be removed from persistent storage.

callback: A callback. onResult and onError are called as follows:

• onResult(keyArray)
• onError(errorMessage, keyArray)

Return value

This method has no return value.

Removing All Items

jetpack.storage.simple.clear(callback)

Arguments

callback: A callback. onResult and onError are called as follows:

• onResult()
• onError(errorMessage)

Return value

This method has no return value.

Testing the Existence of a Single Item

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

Arguments

key: A string uniquely identifying the data whose existence in persistent storage is to be checked.

callback: A callback. onResult and onError are called as follows:

• onResult(key, exists)
  • exists is true if key exists in the store and false otherwise.
• onError(errorMessage, key)

Return value

This method has no return value.

Testing the Existence of Multiple Items

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

Arguments

keyArray: An array of strings, each of which uniquely identifies data whose existence in persistent storage is to be checked.

callback: A callback. onResult and onError are called as follows:

• onResult(keyArray, existsObject)
  • existsObject is a JS object whose properties map to the keys in keyArray and whose values are true if their associated keys exist and false otherwise.
• onError(errorMessage, keyArray)

Return value

This method has no return value.

Enumerating Specific Items

jetpack.storage.simple.forEachItem(keyArray, callback)

Arguments

keyArray: An array of strings, each of which uniquely identifies data to retrieve from the store.

callback: A callback. onResult and onError are called as follows:

• onResult(key, value)
  • onResult(key, value) is called for each key given in keyArray. If a given key does not exist in the store, value will be undefined. Items are enumerated in the same order that their keys are given in keyArray.
• onResult(null, null)
  • When all items are exhausted, onResult(null, null) is called to signal that enumeration is complete.
• onError(errorMessage, keyArray)

Return value

This method has no return value.

Enumerating All Items

jetpack.storage.simple.forEachItem(callback)

Arguments

callback: A callback. onResult and onError are called as follows:

• onResult(key, value)
  • onResult(key, value) is called for each key-value pair in the store. The order of enumeration is arbitrary.
• onResult(null, null)
  • When all items are exhausted, onResult(null, null) is called to signal that enumeration is complete.
• onError(errorMessage)

Return value

This method has no return value.

Enumerating Keys

jetpack.storage.simple.forEachKey(callback)

Arguments

callback: A callback. onResult and onError are called as follows:

• onResult(key)
  • onResult(key) is called for each key in the store. The order of enumeration is arbitrary.
• onResult(null)
  • When all keys are exhausted, onResult(null) is called to signal that enumeration is complete.
• onError(errorMessage)

Return value

This method has no return value.

Enumerating Specific Values

jetpack.storage.simple.forEachValue(keyArray, callback)

Arguments

keyArray: An array of strings, each of which uniquely identifies data to retrieve from the store.

callback: A callback. onResult and onError are called as follows:

• onResult(value)
  • onResult(value) is called for each key given in keyArray. If a given key does not exist in the store, value will be undefined. Values are enumerated in the same order that their keys are given in keyArray.
• onResult(null)
  • When all values are exhausted, onResult(null) is called to signal that enumeration is complete.
• onError(errorMessage, keyArray)

Return value

This method has no return value.

Enumerating All Values

jetpack.storage.simple.forEachValue(callback)

Arguments

callback: A callback. onResult and onError are called as follows:

• onResult(value)
  • onResult(value) is called for each value in the store. The order of enumeration is arbitrary.
• onResult(null)
  • When all values are exhausted, onResult(null) is called to signal that enumeration is complete.
• onError(errorMessage)

Return value

This method has no return value.

Retrieving All Keys

jetpack.storage.simple.keys(callback)

Arguments

callback: A callback. onResult and onError are called as follows:

• onResult(keyArray)
  • keyArray contains all the keys of the store in an unordered array.
• onError(errorMessage)

Return value

This method has no return value.

Retrieving All Values

jetpack.storage.simple.values(callback)

Arguments

callback: A callback. onResult and onError are called as follows:

• onResult(valueArray)
  • valueArray contains all the values of the store in an unordered array.
• onError(errorMessage)

Return value

This method has no return value.

Retrieving the Number of Items

jetpack.storage.simple.size(callback)

Arguments

callback: A callback. onResult and onError are called as follows:

• onResult(numItems)
  • numItems is the number of key-value pairs in the store.
• onError(errorMessage)

Return value

This method has no return value.

Errors and Legal Keys and Values

A key must be a string. The empty string is a legal key. If an illegal key is passed to any method, that method will throw an IllegalKeyError. The prototype of IllegalKeyError is TypeError.

A value must be a non-null JS primitive or JSON-able object. If an illegal value is passed to any method, that method will throw an IllegalValueError. The prototype of IllegalValueError is TypeError.

Because of the polymorphic nature of this API, if any method is passed an unexpected argument, that method will throw an ArgumentError. The prototype of ArgumentError is TypeError.

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);
});