browser-storage-utilities v1.0.7

Live example in Angular :movie_camera:

Browser Storage Utilities :hammer_and_pick:

:fire: StorageUtilities is a front-end library that provides handy methods to facilitate CRUD operations to data stored in the browser. It also allows global/class level settings to easily, and consistently, manage the state of the stored data.

StorageUtilities provides optional expiry/TTL (Time To Live) functionality to allow temporary data storage. It also allows subscribers to be notified of any state changes to stored data.

The internal implementation relys on the web storage objects localStorage and sessionStorage, as well as the methods they provide setItem/getItem/removeItem/clear

:pencil2: Key Goals

• Simplify CRUD operations to stored data in localStorage & sessionStorage
• Allow global/class level settings for consistency
• Support expiry/TTL (Time To Live) feature
• Provide state change notifications to subscribers
• Can be easily used in any front-end JavaScript codebase application

:arrow_down: Installation

npm install browser-storage-utilities --save

Usage :bulb:

TypeScript

import { StorageUtilities } from 'browser-storage-utilities';

export class UserStorageService extends StorageUtilities <User> {
    ...

    constructor() {
        super({ /* global settings (optional) */ });
    }

}

The settings interface :checkered_flag:

export interface IStorageSettings {
    keyPrefix? : string; // prefixes all items' keys prior to being stored, e.g. 'user-'
    type? : StorageTypes; // localStorage (default) / sessionStorage
    setExpiryMilliseconds? : number; // time to live (TTL), e.g. 5000ms
    setReturnType? : StorageReturnTypes; // the item(s) to be returned as a Promise or Observable
    notifiedOfStateChanges? : boolean; // for subscriber(s) to be notified of any storage state changes
}

Note: :bulb: Some of these settings (type, setExpiryMilliseconds, and setReturnType) can be applied per method as well, which always take precedence over global settings:

// set globally
...
constructor() {
   super({ keyPrefix: 'user-', setExpiryMilliseconds: 5000, notifiedOfStateChanges: true, setReturnType: StorageReturnTypes.Promise, type: StorageTypes.SESSION });
...

// set per method
this.userStorageService.addUser('123', user, 5000, StorageTypes.SESSION);

// return item
const storedUser = this.userStorageService.getUser('123', StorageTypes.SESSION);
console.log('storedUser: ', storedUser); // user data

// return item as a Promise
const storedUserPromise = this.userStorageService.getUser('123', StorageTypes.SESSION, StorageReturnTypes.Promise);

storedUserPromise.then(user => {
  console.log('user: ', user); //user data
})

Default settings :pushpin:

export const defaultSettings: IStorageSettings = {
    keyPrefix: '',
    type: StorageTypes.LOCAL // set to localStorage by default
};

Example :rocket:

import { StorageUtilities, StorageTypes } from 'browser-storage-utilities';

export class UserStorageService extends StorageUtilities <User> {

    constructor() {
        super({ keyPrefix: 'user-', notifiedOfStateChanges: true, type: StorageTypes.SESSION });
    }

    addUser(id: string, user: User, expiry? : number, storageType? : StorageTypes): void {
        this.addItem(id, user, expiry, storageType);
    }

    getUser(id: string, storageType? : StorageTypes): User {
        return this.getItem(id, storageType);
    }

    updateUserProperty(id: string, propName: string, newValue: any, storageType ? : StorageTypes): User {
        return this.updateItemProperty(id, propName, newValue, storageType);
    }

    removeUserProperty(id: string, propName: string, storageType? : StorageTypes): User {
        return this.updateItemProperty(id, propName, newValue, storageType);
    }

    removeUser(id: string, storageType? : StorageTypes): void {
        this.removeItem(id, storageType);
    }

    removeUsers(ids: string[], storageType? : StorageTypes): void {
        this.removeItems(ids, storageType);
    }

}

Subscribe to storage state changes :dart:

import { IStorageNotifier } from 'browser-storage-utilities';

...

this.userStorageService.storageStateChanged.subscribe((userData: IStorageNotifier <User> ) => {
    if (userData) {
        console.log('storage: ', userData.storage); // localStorage or sessionStorage
        console.log('oldValue: ', userData.oldValue); // previous data
        console.log('newValue: ', userData.newValue); // current data
    }
});

Store data with a 5 second expiry (TTL) :hourglass_flowing_sand:

...

this.userStorageService.addUser('123', user, 5000);
/* 
localStorage: {
  expiry: 1590853867699,
  value: {
    id: '123',
    firstName: 'John',
    lastName: 'Doe',
    ...
  }
}
*/

// if expiry time has elapsed, item is removed from storage, and null will be returned.
const storedUser = this.userStorageService.getUser('123');

console.log('storedUser: ', storedUser); // null

:page_facing_up: Settings API

:page_facing_up: Core methods API

:page_facing_up: Additional methods API

Author :books:

Ahmed Alatawi