@coool/cachestate

A simple-to-use, minimal boilerplate flexible cached state.

Features

✅ Caching
✅ State Management
✅ Updates for cache consumers
✅ Works with any framework
✅ Local Storage Support
✅ Custom Storage Asynchronous Support
✅ Handles Simultaneous Requests
✅ Automatic & Manual Cache Busting
✅ Aspect-Oriented (Decorators)
✅ Out-of-the-box LocalStorage and SessionStorage cache data storage

Install

$ npm i --save @coool/cachestate

Basic Usage

Add CacheState to a function

import { CacheState } from '@coool/cachestate';

@CacheState()
function getItem$(itemId: ItemId): Observable<Item> {
  // Get latest version of item from the server
}

Consume CacheState

getItem$('1')
  .subscribe(item => {
    // You'll receive initial cached value and updates here
  });

Notify the CacheState that the value needs updating

import { CacheState, CacheStateUpdater } from '@coool/cachestate';

@CacheState({
  updatedNotifierKey: 'items-updated',
})
function getItem$(itemId: ItemId): Observable<Item> {
  // Get latest version of item from the server
}

@CacheStateUpdater({
  updatedNotifierKey: 'items-updated',
})
function updateItem() {
  // This will invalidate the cache and call the getItem$ function again then update cache consumers with the latest value 
}

Use-cases

Global Configuration

You can set configurations globally across all CacheStates. Local configuration will take precedence over global configuration.

import { GlobalCacheStateConfig } from '@coool/cachestate';

GlobalCacheStateConfig.maxAgeMS = 5 * 60 * 1000;

Invalidate cache without requesting update

import { CacheState, CacheStateInvalidator } from '@coool/cachestate';
import { Subject } from 'rxjs';

const cacheInvalidatedNotifier = new Subject<void>();

@CacheState({
  invalidatedNotifier: cacheInvalidatedNotifier,
})
function getItem$(itemId: ItemId): Observable<Item> {
}

@CacheStateInvalidator({
  invalidatedNotifier: cacheInvalidatedNotifier,
})
function updateItem() {
  // This will invalidate the cache and call the getItem$ function again then update cache consumers with the latest value 
}

Invalidate all cache globally

import { invalidateAllCache } from '@coool/cachestate';

invalidateAllCache();

Invalidate and update all cache globally

import { invalidateAndUpdateAllCache } from '@coool/cachestate';

invalidateAndUpdateAllCache();

LocalStorage data storage

import { GlobalCacheStateConfig, BrowserStorageCacheDataStorage } from '@coool/cachestate';

GlobalCacheStateConfig.cacheDataStorage = new BrowserStorageCacheDataStorage(window.localStorage);

SessionStorage data storage

import { GlobalCacheStateConfig, BrowserStorageCacheDataStorage } from '@coool/cachestate';

GlobalCacheStateConfig.cacheDataStorage = new BrowserStorageCacheDataStorage(window.sessionStorage);

Custom cache data storage

import { CacheDataStorage, GlobalCacheStateConfig } from '@coool/cachestate';

class MyCacheDataStorage implements CacheDataStorage {
  // Implement CacheDataStorage interface to store, retrieve and delete cache data
}

GlobalCacheStateConfig.cacheDataStorage = new MyCacheDataStorage(window.localStorage);

API

CacheState configuration

Property	Description	Default	Required
cacheKey.generator	Generates the cache key	Combination of cache key prefix and suffix (combination of class, method name and a hash of the function's arguments)	false
cacheKey.prefixGenerator	Prefix for the cache key	Combination of class and method name	false
cacheKey.suffixGenerator	Suffix for the cache key	A hash of the function's arguments	false
cacheDataStorage	A storage where the cache data is stored	Store cached values locally	false
maxAgeMS	Max age of cache in milliseconds	60000 (1 minute)	false
updatedObservable	When emits the cache is invalidated and updated. If CacheKey is passed then only that cache otherwise all related cache.	undefined	false
updatedObservableKey	When emits the cache is invalidated and updated. If CacheKey is passed then only that cache otherwise all related cache.	undefined	false
updateOnlySpecific	When updated notifier fires only update if specific cache key is defined.	false	false
invalidatedObservable	When emits the cache is invalidated. If CacheKey is passed then only that cache otherwise all related cache.	undefined	false
invalidatedObservableKey	When emits the cache is invalidated. If CacheKey is passed then only that cache otherwise all related cache.	undefined	false
invalidateOnlySpecific	When invalidated notifier fires only update if specific cache key is defined.	false	false
timestampProvider	Provides current timestamp, useful for testing		false

CacheStateUpdater configuration

Property	Description	Default	Required
updatedNotifier	When emits the cache is invalidated and updated. If CacheKey is passed then only that cache otherwise all related cache.	undefined	true (OR use updatedNotifierKey)
updatedNotifierKey	Global key identifying updatedNotifier	undefined	true (OR use updatedNotifier)
cacheKeyGenerator	Generates the cache key for the updated notifier	undefined	false

CacheStateInvalidator configuration

Property	Description	Default	Required
invalidatedNotifier	When emits the cache is invalidated. If CacheKey is passed then only that cache otherwise all related cache.	undefined	true (OR use invalidatedNotifierKey)
invalidatedNotifierKey	Global key identifying invalidatedNotifier.	undefined	true (OR use invalidatedNotifier)
cacheKeyGenerator	Generates the cache key for the updated notifier	undefined	false

Global configuration

Property	Description	Default	Required
cacheDataStorage	A storage where the cache data is stored	Store cached values locally	false
maxAgeMS	Max age of cache in milliseconds	60000 (1 minute)	false
timestampProvider	Provides current timestamp, useful for testing		false

Inspiration

This project is inspired by ts-cacheable