LocalStorage

LocalStorage

LocalStorage provides access to window.localStorage.

Support

LocalStorage only works when window.localStorage is an Object with the approproate interface. In environments where window.localStorage does not exist or does not have the correct interface all methods on LocalStorage are no-ops.

Automatic Encoding

Values set or retrieved from storage are automatically JSON encoded and decoded. A value that can not be JSON decoded is returned as-is when retrieving said value or dispatching events.

Global or Prefixed

Access to storage can be global or prefixed by setting opts.prefix to an empty string or a non-empty string respectively.

Global

When global it is possible for items set in storage to overwrite or replace items set by other packages or modules. Events are not filtered and you will receive StorageEvents for items you may not care to receive.

Prefixed

When prefixed items only overwrite or replace items set with the same prefix. Events for items are filtered by prefix and you will only receive events for items with a matching prefix.

Prefixes are automatically prepended or stripped from item keys as appropriate; you only need to set the prefix when creating an instance of LocalStorage.

Predictable Prefixes

LocalStorage is used to send data across browser tabs; therefore when using prefixes each tab needs to use the same prefix to only receive events it cares about.

UUIDs or other unique identifiers will not make good prefixes unless you implement a mechanism to share those values with every browser tab of your application.

Examples

Consider the following event handler for all of the examples:

const storageHandler = event => {
    console.log( 
        event.key, event.created, event.deleted, event.modified,
        event.oldValue, event.newValue
    );
}

Global

const storage = new LocalStorage();
let unregister = storage.register( storageHandler );

storage.set( 'message', 'Hello, World!' );
// console: message, true, false, false, null, 'Hello, World!'

storage.set( 'message', 'Good bye!' );
// console: message, false, false, true, 'Hello, World!', 'Good bye!'

unregister(); // Removes handler

// Only events for keys === 'total' will fire.
unregister = storage.registerItem( 'total', storageHandler );

storage.set( 'message', 'Hello, World!' );
storage.set( 'message', 'Good bye!' );
// Neither of the above will create console output.

storage.set( 'total', 42 );
// console: total, true, false, false, null, 42

Prefixed

const storage = new LocalStorage();
const prefixed = new LocalStorage( { prefix : 'some-unique-value' } );
let unregister = prefixed.register( storageHandler );

storage.set( 'message', 'Hello, World!' );
// No console output -- setting value on global storage does not
// trigger events on prefixed storage.

prefixed.set( 'someValue', 'important data' );
// console: someValue, true, false, false, null, 'important data'
// NB: Handlers on `storage` would fire as well with 
//     key as 'some-unique-value' + 'someValue'

Constructor

new LocalStorage(opts)

Source:
See:

Creates a new LocalStorage instance.

Parameters:
Name Type Description
opts Object

Options for LocalStorage.

Properties
Name Type Description
prefix string

If provided acts as a prefix for items set and retrieved in the storage; can be used to prevent name collisions.

Methods

destroy()

Source:

destroy unregisters all handlers and frees internal members.

It does not delete any of the data in local storage.

get(item) → {Object|string}

Source:

get returns the storage value for item.

Parameters:
Name Type Description
item string

The item to get.
Returns:
Type
Object | string

register(handler) → {func}

Source:

register registers an event handler for any change in the storage. Changes to specific items and clearing the storage will fire handler.

Parameters:
Name Type Description
handler func

Handler with signature (StorageEvent) => {}
Returns:

An unregister function.

Type
func

registerItem(item, handler) → {func}

Source:

registerItem registers an event handler for any change in storage for a specific storage item or key.

Parameters:
Name Type Description
item string

The item name or key.
handler func

Handler with signature (StorageEvent) => {}
Returns:

An unregister function.

Type
func

remove(item)

Source:

remove removes the data in the named item.

Parameters:
Name Type Description
item string

The item to remove.

set(item, value)

Source:

set sets the storage item to value. value will be JSON encoded.

Parameters:
Name Type Description
item string

The item to set.
value Object | string

The value to store.