Following on from our popular $localStorage and $sessionStorage services for AngularJS; we've created new services for Angular 2 projects.
Early release
It's extremely early in the development phase and we've literally just cobbled it together right now; there are no unit tests and it could most likely do with a refactor.
As of v0.0.5; it is functional and can easily be used in your TypeScript based Angular 2 application.
The functionality shouldn't change tom much if at all so future updates shouldn't introduce any breaking changes.
We do plan to package this properly for use with other languages so more people can use it in their Angular 2 applications.
Description
Provides a key-value (string-object) storage, that is backed by Local Storage or Session Storage with support for expiry (in minutes).
Objects put or retrieved from this storage are automatically serialized or deserialized by JSON.stringify / JSON.parse and are also held within a session Object cache for optimal retrieval.
Session Storage
Storing items in Session Storage is useful for persisting data within the current browser session.
Data stored in this manner will not be deleted if the page is refreshed but will be deleted when the browser (or browser tab) is closed.
Storing items in Session Storage is useful for persisting data within the current browser session.
Local Storage
Storing items in Local Storage is useful for persisting data between browser sessions.
Data stored in this manner will not be deleted when the browser (or browser tab) is closed; nor if the page is refreshed.
N.B. For browsers with Web Storage disabled or in private browsing mode; a simple session Object fallback is used - please be aware of the limitations in this scenario.
Dependencies
The services are written in TypeScript for Angular 2, and have been tested with version 2.1.1.
Installation
The services can be installed with npm; to install use:
npm install --save-dev @scriptwerx/web-storage
The services can also be installed with yarn; to install use:
yarn add @scriptwerx/web-storage --dev
Or; you can find the source on GitHub
Usage
The services have been designed for simplicity.
You can import both services just like any other Angular 2 service and use them independently:
import { LocalStorageService, SessionStorageService } from '@scriptwerx/web-storage';
They function just as our popular AngularJS 1.x services.
Available Methods
The following examples detail SessionStorageService but the same methods are the also available within LocalStorageService and essentially work the in same way; albeit storing and retrieving from Session and Local Storage respectively.
The examples also assume that the following has been set within your Component constructor:
constructor(private sessionStorageService: SessionStorageService) {
// Empty
}
Method: put
In order to set a value; the put method should be used as follows:
sessionStorageService.put('myKey', 'myValue');
The key; specified as ’myKey’ is used to allow retrieval of the value, in this case ’myValue’.
The value can be set as any type (Number, String, Object, Array) and will be deserialized when stored.
An optional expiry (in days) is available; in order to set a value to expire after 30 days you should use:
sessionStorageService.put('myKey', 'myValue', 30);
If you need to store a value for less, or more time - you can always calculate more/less days.
For example; to store data for (approximately) two years you could use:
sessionStorageService.put('myKey', 'myValue', 365 * 2);
To store data for one hour; you could use:
sessionStorageService.put('myKey', 'myValue', 1 / 24);
N.B. Data stored will not be automatically discarded. When an expiry time is set; the data will only be deleted when it is retrieved by your application and the data is deemed as expired (see below).
Method: get
In order to retrieve a previously stored value; the get method should be used as follows:
sessionStorageService.get('myKey');
If the value is not available within Session Storage; undefined will be returned.
If the value has been stored with an expiry; this will be checked to ensure the value is still current - if so; the value will be returned, if not; the value will be deleted from Session Storage and undefined will be returned.
Method: remove
In order to remove a previously stored value; the remove method should be used as follows:
sessionStorageService.remove('myKey');
Once removed; any request to retrieve the value will return undefined.
Method: empty
You are able to clear all data stored within sessionStorage if required.
In order to clear everything stored by your application within Session Storage you should use the following:
sessionStorageService.empty();
This will only clear items stored by your application.