ember-cli-storagekit

A thin layer on top of the HTML5 localStorage and sessionStorage services. It also has a third type of storage called instanceStorage which is used as a failover when localStorage or sessionStorage are not available (such as when a user intentionally disables them).

This addon does not assume your application uses ember data. That being said it would serve well as part of a custom local, session, instance storage adapter.

Installation

ember install ember-cli-storagekit

Basic Usage

Storagekit takes care of JSON.stringify() and JSON.parse() for you, and supports the following methods:

• setItem
• getItem
• removeItem
• clear
• length
• key

Storagekit makes no assumptions about where you would like to make the service available. As such you need to specify your own injections.

initializer

  export function initialize(registry, application) {
    // inject the storage service, which contains each storage type.
    application.inject('route', 'storage', 'storagekit/service:storage');
    
    // you can also inject each service individually if that is your thing.
    application.inject('route', 'localStorage', 'storagekit/service:local-storage');
    application.inject('route', 'sessionStorage', 'storagekit/service:session-storage');
    application.inject('route', 'instanceStorage', 'storagekit/service:instance-storage');
  }

  export default {
    name: 'inject-storage-service',
    after: 'inject-storagekit',
    initialize: initialize
  };

Local

  // A controller...or route
  // ...snip...
  actions: {
    savePreferences(preferences) {
      // with storage
      this.get('storage.local').setItem('preferences', preferences);
      
      // with localStorage
      this.get('localStorage').setItem('preferences', preferences);
    }
  }
  // ...snip...

Session

  // A controller...or route
  // ...snip...
  actions: {
    saveSession(session) {
      // with storage
      this.get('storage.session').setItem('session', session);
    
      // with sessionStorage
      this.get('sessionStorage').setItem('session', session);
    }
  }
  // ...snip...

Instance

  // A controller...or route
  // ...snip...
  actions: {
    storeTemporarily(temporaryData) {
      // with storage
      this.get('storage.instance').setItem('temporaryData', temporaryData);
    
      // with instanceStorage
      this.get('instanceStorage').setItem('temporaryData', temporaryData);
    }
  }
  // ...snip...

Namespacing

The storagekit env config provides a means for namespacing your application keys. This is how it works:

  // ...snip...
  APP: {
    storagekit: {
      namespace: 'storagekit'
    }
  }
  // ...snip...

Now your incoming keys will be stored like this:

'storagekit:mykey'

IMPORTANT: The namespace defines the storage "world" for all operations, and will give a result based solely on keys that are namespaced within it. Such methods include: #clear, #keys, #length, and #key.

Why is this useful? Because it allows you to change your namespace based on the current environment. For example, you can define a different namespace for your test environment and keep yourself shielded from any setup and teardown methods that modify your browsers local or session storage.

If you do not specify a namespace, then your keys will be stored in the same form that they are received. If you specify a key directly in one of the adapters it will supercede the namespace in the env config.

Generating the Docs

This addon has yuidoc annotations, and uses ember-cli-yuidoc in order to generate and serve them.

Running Tests

• ember test
• ember test --server

For more information on using ember-cli, visit http://www.ember-cli.com/.