Web Storage for Angular
Angular services for interacting with the Web Storage, implemented in JavaScript.
Installing via npm
From a command prompt, run:
$ npm install --save @cedx/ngx-webstorage
Usage
This package provides two injection tokens dedicated to the Web Storage: LocalStorage
and SessionStorage
.
These tokens are backed by the Storage
class which provides access to the underlying Web APIs. They need to be registered with the dependency injector by importing their module, the StorageModule
class:
import {NgModule} from '@angular/core';
import {BrowserModule} from '@angular/platform-browser';
import {StorageModule} from '@cedx/ngx-webstorage';
import {AppComponent} from './app_component';
// The root module.
export class AppModule {
// The class decorators.
static get annotations() {
return [new NgModule({
bootstrap: [AppComponent],
declarations: [AppComponent],
imports: [BrowserModule, StorageModule]
})];
}
}
Then, they will be available in the constructor of the component classes:
import {Component} from '@angular/core';
import {LocalStorage, SessionStorage} from '@cedx/ngx-webstorage';
// The main component.
export class AppComponent {
// The class decorators.
static get annotations() {
return [new Component({
selector: 'my-application',
template: '<h1>Hello World!</h1>'
})];
}
// The constructor parameters.
static get parameters() {
return [LocalStorage, SessionStorage];
}
// Initializes a new instance of the class.
constructor(localStorage, sessionStorage) {
localStorage.get('foo');
localStorage.getObject('bar');
sessionStorage.set('foo', 'bar');
sessionStorage.setObject('foo', {bar: 'baz'});
}
}
Programming interface
The Storage
class has the following API:
.keys: string[]
Returns the list of all the keys of the associated storage:
console.log(localStorage.keys); // []
localStorage.set('foo', 'bar');
console.log(localStorage.keys); // ["foo"]
.length: number
Returns the number of entries in the associated storage:
console.log(localStorage.length); // 0
localStorage.set('foo', 'bar');
console.log(localStorage.length); // 1
.clear()
Removes all entries from the associated storage:
localStorage.set('foo', 'bar');
console.log(localStorage.length); // 1
localStorage.clear();
console.log(localStorage.length); // 0
.get(key: string, defaultValue: any = null): string
Returns the value associated to the specified key:
localStorage.set('foo', 'bar');
console.log(localStorage.get('foo')); // "bar"
Returns the defaultValue
parameter if the key is not found:
console.log(localStorage.get('unknownKey')); // null
console.log(localStorage.get('unknownKey', 'foo')); // "foo"
.getObject(key: string, defaultValue: any = null): any
Deserializes and returns the value associated to the specified key:
localStorage.setObject('foo', {bar: 'baz'});
console.log(localStorage.getObject('foo')); // {bar: "baz"}
The value is deserialized using the
JSON.parse
method.
Returns the defaultValue
parameter if the key is not found:
console.log(localStorage.get('unknownKey')); // null
console.log(localStorage.get('unknownKey', false)); // false
.has(key: string): boolean
Returns a boolean value indicating whether the associated storage contains the specified key:
console.log(localStorage.has('foo')); // false
localStorage.set('foo', 'bar');
console.log(localStorage.has('foo')); // true
.remove(key: string)
Removes the value associated to the specified key:
localStorage.set('foo', 'bar');
console.log(localStorage.has('foo')); // true
localStorage.remove('foo');
console.log(localStorage.has('foo')); // false
.set(key: string, value: string)
Associates a given value to the specified key:
console.log(localStorage.get('foo')); // null
localStorage.set('foo', 'bar');
console.log(localStorage.get('foo')); // "bar"
.setObject(key: string, value: any)
Serializes and associates a given value to the specified key:
console.log(localStorage.getObject('foo')); // null
localStorage.setObject('foo', {bar: 'baz'});
console.log(localStorage.getObject('foo')); // {bar: "baz"}
The value is serialized using the
JSON.stringify
method.
Iteration
The Storage
class is iterable: you can go through all key/value pairs contained using a for...of
loop. Each entry is an array with two elements (e.g. the key and the value):
localStorage.set('foo', 'bar');
localStorage.set('anotherKey', 'anotherValue');
for (let entry of localStorage) {
console.log(entry);
// Round 1: ["foo", "bar"]
// Round 2: ["anotherKey", "anotherValue"]
}
Events
Every time one or several values are changed (added, removed or updated) through the Storage
class, a changes
event is triggered.
This event is exposed as an Observable, you can subscribe to it using the onChanges
property:
localStorage.onChanges.subscribe(
changes => console.log(changes)
);
The changes are expressed as an array of KeyValueChangeRecord
instances, where a null
reference indicates an absence of value:
localStorage.onChanges.subscribe(changes => console.log(changes[0]));
localStorage.set('foo', 'bar');
// Prints: {key: "foo", currentValue: "bar", previousValue: null}
localStorage.set('foo', 'baz');
// Prints: {key: "foo", currentValue: "baz", previousValue: "bar"}
localStorage.remove('foo');
// Prints: {key: "foo", currentValue: null, previousValue: "baz"}
The values contained in the currentValue
and previousValue
properties of the KeyValueChangeRecord
instances are the raw storage values. If you use the Storage#setObject
method to change a key, you will get the serialized string value, not the original value passed to the method:
localStorage.setObject('foo', {bar: 'baz'});
// Prints: {key: "foo", currentValue: "{\"bar\": \"baz\"}", previousValue: null}
See also
License
Web Storage for Angular is distributed under the Apache License, version 2.0.