User:Rektide/JEP-WebStorage

	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 WebStorage - HTML5 Web Storage for JavaScript Objects

• Author: rektide@voodoowarez.com
• Champion: rektide
• Status: Draft
• Type: API Track
• Created: 27 May 2009
• Reference Implementation: None
• JEP Index

Introduction and Rationale

This JEP describes two components:

1. an extension to HTML5 Web Storage for storing JavaScript objects
2. a Jetpack extension for giving Jetpacks access to JavaScript object storage.

The JavaScript Object Storage proposal is built around two specifications:

1. the HTML5 Storage object, which provides a polished and standardized interface for storing and accessing DOMStrings in a persistent and standards based manner, but lacks JavaScript storage capabilities.
2. EcmaScript 3.1, which provides native JSON support.

Neither of these two specifications are required to be natively implemented, and could be implemented as libraries if desired and done in a compliant manner. For example, Douglas Crockford has the required JSON implementation from EcmaScript 3.1 available in library form.

This JEP provides an alternative to Atul's JEP11 - Simple Persistent Storage, which proposes the creation of a new API for Jetpack.

DOM Storage and JEP11

In its Introduction and Rationale, JEP11 references DOM Storage as having too many limitations. Specifically, quote:

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

Extending DOM Storage

Rather than derive a new interface for JavaScript as JEP11, JEP11B proposes extending the existing DOM Storage interface to deal with JavaScript objects.

Storage Object

DOM Storage's base interface, HTML5 Storage, reads as follows:

interface Storage {
  readonly attribute unsigned long length;
  [IndexGetter] DOMString key(in unsigned long index);
  [NameGetter] DOMString getItem(in DOMString key);
  [NameSetter, NameCreator] void setItem(in DOMString key, in DOMString data);
  [NameDeleter] void removeItem(in DOMString key);
  void clear();
};

It describes a means of persisting string item's in permenant storage.

ObjectStorage Specification

The following additions ought be made to Storage to support JavaScript objects:

interface ObjectStorage : Storage {
  Object getObject(in DOMString key);
  Object setObject(in DOMString key, in Object object);
};

These extensions provide a means of persisting arbitrary JavaScript objects.

The implementation of getObject and setObject rely upon EcmaScript 3.1 compliant implementations of two functions (described in 12.15 of the EcmaScript 3.1 final draft):

1. JSON.parse( text ) to convert a stored DOMString into an Object.
2. JSON.stringify( value ) to convert an Object into a storeable DOMString.

getObject

Object getObject(in DOMString key)

This function MUST return a JavaScript object equivalent to:

JSON.parse( this.getItem(key) )

In keeping with the behavior of JSON.parse, getObject throws a SyntaxError if it encounters any item which can not be parsed to a JavaScript Object.

Objects returned by getObject are not assumed to have equivalence to an object used to setObject

setObject

Object setObject(in DOMString key, in Object data)

This function MUST store data in a fashion equivalent to the behavior of:

this.setItem( key, JSON.stringify(data) )

Implementation Hazards & Optimizations

Note that the internal workings of ObjectStorage do not dictate the native format of storage. Whether setItem or setObject is called, the only requirements imposed is the output of getItem and setItem. An implementation of setObject may persist a native JavaScript object, so long as getObject and getItem return an equivalent object and the objects JSON form, respectively.

Of particular note, its desireable to avoid continual parsing of JSON strings and stringifaction of JavaScript objects if the user is accessing primarily the the Object interfaces: a native JavaScript store would be ideal in these cases. The need for instantaneous commits abnegates any possibility of a Web Storage based library avoiding stringifying every single write, but there is still potential for a client side implementation of ObjectStorage to keep a local cache of objects to accelerate reads. Further improvement would have to be made possible by way of native browser enhancement.

ObjectStorage in Jetpack

Jetpack extensions will have access to their own fully independent ObjectStorage space at jetpack.storage.object, providing an place for objects to be persisted in and between browser sessions.

Future Enhancements

The Storage event should be extended with ObjectStorage extensions.