Skip to content

Hacklone/coool-cachestate

Repository files navigation

@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();

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

About

Aspect-oriented cached state library for TypeScript

Resources

License

Stars

Watchers

Forks

Packages

No packages published