promise-cachify

Caching for promises.

Installation

npm install promise-cachify

Features

• Concurrent de-duplication.
• Caching resolved values while ignore rejected.
• Data persistance.
• Data isolation(fresh new data for each return).
• Strong and type-safe cache key generation.
• Customizable (key generation, exipre time... )
• Deletion of cached items.
• Debug mode
• Support two styles of usage.
• Fully typescript-ready.
• No dependencies

Get Started

Basic Usage

.do style (recommended)

import withCache, { setDefaults, DefaultKey } from 'promise-cachify';

const getDetail = withCache(function (id: number) {
  return yourFetchFn('/api/getDetail', { id });
});

await Promise.all([getDetail.do(1), getDetail.do(1), getDetail.do(1)]);
// concurrent request share the same http request.
// so the above results in just 1 http call;
// note the '.do(...)', that explicitly tell the reader
// "hi man, the result is probably from cache! "

await getDetail.do(1); // from cache;

as-it-is style

import { cache, setDefaults, DefaultKey } from 'promise-cachify';

const getDetail = cache(function (id: number) {
  return yourFetchFn('/api/getDetail', { id });
});

await Promise.all([getDetail(1), getDetail(1), getDetail(1)]);
await getDetail(1); // from cache;

APIs of Both styles are with the same signature. But APIs are under getDetail.cache when as-it-is style.

style	API signature	API location	Suitable scene
.do	same	fn.	new code
as-it-is	same	fn.cache.	old project

Deletion of cached items.

// clear all cached data for every 'id';
getDetail.clearAll();
// clear cached data for id=1
getDetail.clear(getDetail.getCacheKey(1));
// or the following, if you know how the cache key is generated;
getDetail.clear('$-1');

getDetail.do(1); // from server;

Customize cache key

Most of time you don't need to do this, but this is needed when your params is complex.

const getDetail = withCache(
  function (id: number) {
    return yourFetchFn('/api/getDetail', { id });
  },
  {
    // same signature as the first argument of withCache
    key: (id) => String(id),
    // key: 'or_your_static_key',
  }
);

Data persistance

const getDetail = withCache(
  function (id: number) {
    return yourFetchFn('/api/getDetail', { id });
  },
  {
    persist: 'your_global_unique_key',
    // persistMedia: 'sessionStorage', // default. Another available option is "localStorage"
  }
);
// this will respect to `expire` policy

Debug

const getDetail = withCache(
  function (id: number) {
    return yourFetchFn('/api/getDetail', { id });
  },
  { debug: true }
);
// track cache behavior.

Full example

const getDetail = withCache(
  function (id: number) {
    return yourFetchFn('/api/getDetail', { id });
  },
  {
    persist: 'CRM_USER_GETDETIAL',
    persistMedia: 'sessionStorage',
    maxAge: 2, // expire after 2 seconds
    debug: true,
    key: (id) => String(id),
  }
);

API

• do(...args: TArgs): Promise<TOut>
• getCacheKey(...args: TArgs): string | null;
• clear(key?: TKey): void;
• clearAll(): void;
• set(data: TOut | Promise<TOut>, key?: TKey): boolean;
• get(key?: TKey): Promise<TOut> | null;
• getAll(): Map<string, ICacheItem>;
• has(key?: TKey): boolean;

Key generation

auto-key-generation only supports signature with the following constraints;

type TValue = string | number | boolean;
fn(...args: ({ [key: string]: TValue } | TValue | TValue[])[])

• arguments that not satisfy the above constraints will cause no cache.
• the keys of an object will be sorted.
• none-string value will be prefixed with $-
• use default key if no arguments or one argument with undefined value

examples

signature	key
fn({ id: 1, name: 'xx', age: 1 })	'age=$-1&id=$-1&name=xx'
fn({ name: 'xx', age: 1, id: 1 })	'age=$-1&id=$-1&name=xx'
fn('1', [1, '2'], { id: 1, name: null })	'1&[$-1_2]&id=$-1&name=$-null'
fn({ id: 1 }, { id: 2 })	'id=$-1&id=$-2'
fn([1], ['2'])	'[$-1]&[2]'
fn({})	'{}'
fn(null)	'$-null'
fn('null')	'null'
fn() or fn(undefined)	'__INTERNAL_USE__'
fn({ id: 1, d: { name: 'el' } })	null and no cache will be performed

see more at the first test case in __test__/index.test.ts

Compatibility

browsers that support or polyfilled Map Promise

Licence

MIT