web-storage.md

SCION Toolkit	Projects Overview	Changelog	Contributing	Sponsoring

SCION Toolkit > WebStorage

The NPM sub-module @scion/toolkit/storage allows the observation of values contained in local or session storage.

Local Storage maintains a persistent storage area per origin. Data does not expire and remains after the browser restarts. Session Storage also provides a separate storage area per origin, which, however, is only available for the duration of the page session (as long as the browser is open, including page reloads and restores). Each browser tab has its separate page session.

Usage

1. Install @scion/toolkit using the NPM command-line tool:

   npm install --save @scion/toolkit
   

2. Create an instance of the WebStorage class by passing the storage implementor as constructor argument.

   import { WebStorage } from '@scion/toolkit/storage';
    
   export const sessionStorage = new WebStorage(window.sessionStorage);
   export const localStorage = new WebStorage(window.localStorage);

3. Observe items in the storage, as following:

   sessionStorage.observe$('key').subscribe(item => {
   });

---

For Angular projects

If using Angular, you can provide WebStorage for dependency injection into services, components, directives, or pipes.

1. Create a LocalStorage and SessionStorage class, both extending the WebStorage class. In the constructor, call the super constructor, passing either window.localStorage or window.sessionStorage.

    @Injectable({providedIn: 'root'})
    export class SessionStorage extends WebStorage {
      constructor() {
        super(window.sessionStorage);
      }
    } 

    @Injectable({providedIn: 'root'})
    export class LocalStorage extends WebStorage {
      constructor() {
        super(window.localStorage);
      }
    }

2. Inject LocalStorage or SessionStorage, as following:

    export class YourComponent {
      constructor(private localStorage: LocalStorage, private sessionStorage: SessionStorage) {
      }
    }

---

Alternatively, you could also use a DI token to provide WebStorage for dependency injection.

1. Create a DI token under which to provide the storage.

    export const SESSION_STORAGE = new InjectionToken<WebStorage>('SESSION_STORAGE', {
     factory: () => new WebStorage(window.sessionStorage),
    });
   
    export const LOCAL_STORAGE = new InjectionToken<WebStorage>('LOCAL_STORAGE', {
      factory: () => new WebStorage(window.localStorage),
    });

2. Inject the storage as following:

    export class YourComponent {
      constructor(@Inject(SESSION_STORAGE) private sessionStorage: WebStorage,
                  @Inject(LOCAL_STORAGE) private localStorage: WebStorage) {
      }
    }

Methods:

observe$

Observes the item associated with the given key.

Upon subscription, it emits the current item from the storage, but, by default, only if present, and then continuously emits when the item associated with the given key changes. It never completes.

When removing the item from the storage, by default, the Observable does not emit.

Set emitIfAbsent to true if to emit undefined when removing the item, or if there is no item associated with the given key upon subscription. By default, emitIfAbsent is set to false.

absent$

Notifies when no item is present for the given key. The Observable never completes.

put

Puts the given item into storage. The item is serialized to JSON.

putIfAbsent

Puts the given item into storage, but only if not present. The item is serialized to JSON.
Instead of an item you can pass a provider function to produce the item.

remove

Removes the item associated with the given key.

isPresent

Checks if an item is present in the storage. Present also includes null and undefined items.