InstaCache

A simple, async caching library powered by RxJS.

Installation

Install the library via NPM.

npm install --save instacache

Getting Started

Initializing the Cache

The cache is initialized simply with key and a generator. The generator is a lambda returning an Observable, Promise, or value. Internally the value yielded by the generator is converted to an Observable. The cache method is lazy, meaning it will not generate its first result until it is requested with get.

// Initialize cache with lazy entries
const instaCache = new InstaCache()
  .cache('markets', () =>
    this.http.get('http://api.bitcoincharts.com/v1/markets.json')
  )
  .cache('prices', () =>
    this.http.get('http://api.bitcoincharts.com/v1/weighted_prices.json')
  );

Getting Cached Data

Use the get method to grab the current value and subscribe to any future updates.

instaCache.get('markets').subscribe(data => console.log(data));

If race conditions are an issue, or if you want to eagerly retrieve your data, you can supply an optional second parameter to get.

// If 'markets' does not exist, it will be initialized with the
// supplied generator.
instaCache
  .get('markets', () =>
    this.http.get('http://api.bitcoincharts.com/v1/markets.json')
  )
  .subscribe(data => console.log(data));

If your using Angular, you can load values directly in your template using the async pipe. Angular will automatically re-render new data if the cache is refreshed.

<pre>{{instaCache.get('markets') | async}}</pre>

Refreshing a Cache Entry

To get the latest value yielded by an existing generator simply call the refresh method.

instaCache.refresh('markets');

Note that refresh returns an Observable<any> so it can be subscribed too if you need the latest result.

instaCache.refresh('markets').subscribe(console.log);

Update an Entry

To cache a fresh value in an existing entry use the update method. This will broadcast the new entry to all subscribers. Note that if refresh is called it will replace this value with whatever is supplied by the generator.

instaCache.update('markets', someNewData);

Clearing Data

To clear an entry use the clear method. This will send a complete event to each subscriber, ending their subscriptions.

instaCache.clear('markets');

To clear everything, and complete all subscriptions use clearAll.

instaCache.clearAll();

Methods

cache

cache(key: string, generator: () => any): InstaCache

The cache method will create a lazy entry in the cache.

get

get(key: string, miss?: () => any): Observable<any> | undefined

The get method will retrieve a key from the cache. If miss is supplied, and the key has not been defined, a new entry will be created.

refresh

refresh(key: string): Observable<any> | undefined

refresh will call key's the generator, cache the new result, and broadcast the result to all subscribers.

update

update(key: string, value: any): boolean

update will cache and broadcast to all subscribers for a given key. update will return true if an entry was removed and false otherwise.

clear

clear(key: string): boolean

clear will remove a key from the cache, sending a complete event to each subscriber (ending their subscriptions). clear will return true if an entry was removed and false otherwise.

clearAll

clearAll(): void

clearAll will complete all subscriptions, for any key, and start fresh.

isInitialized

isInitialized(key: string): boolean

isInitialized will return true if the provided key is both present and the value has been initialized (get or refresh have been called on the key). This is useful for detecting if calling get on a key will return immediately.

has

has(key: string): boolean

has will return true if the provided key is present (regardless of whether or not it is initialized).