@dlw-digitalworkplace/ts-storage-factory v4.0.1

Typescript Storage Factory

Use this package to implement client-side caching in your typescript project.

Features

• Supports local or session storage
• Supports generic types
• Option to auto-update cache objects
• Checks if storage is available

Functions

Constructor

Initialize a new storage factory class with the local or session storage objects.

const storageFactory = new StorageFactory(localStorage);

GetOrAdd

Gets or adds an item from/to the defined storage.

@param key: The key used to store an object in the storage
@param valueFunc: A function that retrieves the object to be cached and returns a promise
@param forceUpdate: A boolean to indicate if the cache object should be reloaded and updated (default = fale)
@param timeToLive: A Number in minutes to define how long the object should be valid (default = 0 = never expires)
@param autoUpdate: A boolean to indicate if the cache object should be updated. When the cache object is found,
it will be returned immediately, a asynchronous call to update the object will also be made (default = false)
@param callback: A function that can be used in combination with the auto update. When the update (default = null)
is finished this callback will be executed

Get

Gets an object from the cache. returns undefined when item is expired or not found

@param key The key used to store an object in the storage
@param timeToLive A Number in minutes to define how long the object should be valid (default = 0 = never expires)

UpdateItem

Updates the item in the storage.

@param key: The key used to store the object in the storage
@param value: The value object to store

Exists

Checks if an item is present in the storage.

@param key: The cache key for which you want to check the existence

Clear

Clears one or more items from the storage.

@param keys: Specify a key or an array of keys to remove from the storage

ClearAll

Clears the entire storage

Usage

Install the @dlw-digitalworkplace/ts-storage-factory package

npm i @dlw-digitalworkplace/ts-storage-factory

Import the StorageFactory object

import {StorageFactory} from "./StorageFactory";

Examples

Get or add an object

Get or add a cache object from the storage. If the object was found it will be returned, otherwise it will be fetched from the value function and returned when finished. The following example will cache the Item[] array to the localStorage and will never expire.

const storageFactory = new StorageFactory(localStorage);
const items  storageFactory.GetOrAdd<Item[]>(
    "TheCacheKey",() => itemService.GetItems()
);

The following example will cache the Item array to the localStorage for one hour. The item is fetched using the GetItemById function which accepts 1 parameter as a number.

const storageFactory = new StorageFactory(localStorage);
const items  storageFactory.GetOrAdd<Item>(
    "TheCacheKey", () => itemService.GetItemById(1), false, 60
);

Auto updates

The following example will cache the Item[] array to the localStorage for one hour but each time the function is executed, the cahce object will be updated in the backgroud. So the data will become available immediately (because it is loaded from the cache), but the value function is still executed in the background and the cache object will be updated when done.

const storageFactory = new StorageFactory(localStorage);
const items  storageFactory.GetOrAdd<Item[]>(
    "TheCacheKey", () => itemService.GetItems(), false, 60, true
);

Auto update with callback

The following example will cache the Item[] array to the localStorage for one hour but each time the function is executed, the cahce object will be updated in the backgroud. When the update is done, the callback function is executed so you can act upon this event (e.g. to update the react state object).

const storageFactory = new StorageFactory(localStorage);
const items  storageFactory.GetOrAdd<Item[]>(
    "TheCacheKey", 
    () => itemService.GetItems()
    false, 
    60, 
    true, 
    ((newItems: Item[]) => {
        this.setState({ items: items });
    })
);

this.setState({
    items: items
});

Clearing cache objects

Delete a specific item from the storage. The following example will clear 1 item with the given key from the cache.

new StorageFactory(localStorage).Clear("TheCacheKey");

Delete a multiple items from the storage. The following example will clear the cache objects with key TheCacheKey1 ane TheCacheKey2.

new StorageFactory(localStorage).Clear(["TheCacheKey1", "TheCacheKey2"]);

Check existence

The following function will check if the cache object with key TheCacheKey is present in the cache

const exists: boolean = new StorageFactory(localStorage).Exists("TheCacheKey");