|
|
| Line 25: |
Line 25: |
| Persistent storage will live at <code>jetpack.storage.simple</code>. The <code>jetpack.storage</code> namespace will provide access to any other available storage systems, such as sqlite, secure/password storage, and so on. The current <code>jetpack.sessionStorage</code> 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 <code>jetpack.storage.session</code>. | | Persistent storage will live at <code>jetpack.storage.simple</code>. The <code>jetpack.storage</code> namespace will provide access to any other available storage systems, such as sqlite, secure/password storage, and so on. The current <code>jetpack.sessionStorage</code> 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 <code>jetpack.storage.session</code>. |
|
| |
|
| ==== Callbacks ==== | | ==== Synchronous versus Asynchronous ==== |
|
| |
|
| 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 <code>onResult</code> and <code>onError</code>. If a callback is a function, it is called when its associated asynchronous operation successfully completes. If a callback is an object, its <code>onResult</code> method (if defined) is called when the operation successfully completes, and its <code>onError</code> 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.
| | 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. |
|
| |
|
| In this proposal, <code>onResult</code> refers to either the function form or the <code>object.onResult</code> form. Since there is only one form for errors, <code>onError</code> refers to the <code>object.onError</code> form.
| | 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. |
| | |
| <code>onResult</code> is called when the callback's associated asynchronous operation successfully completes:
| |
| | |
| <pre class="brush:js;toolbar:false;">
| |
| onResult(key, [value])
| |
| </pre>
| |
| | |
| <code>onError</code> is called when an error occurs during the operation:
| |
| | |
| <pre class="brush:js;toolbar:false;">
| |
| onError(key, [value,] errorMessage)
| |
| </pre>
| |
| | |
| The definitions of <code>key</code> and <code>value</code> vary according to the simple storage operation associated with the callback, and depending on the context <code>value</code> 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 ==== | | ==== Storing Values ==== |