cachified

wrap virtually everything that can store by key to act as cache with ttl/ma...

CachingKey-Value
Xiphe/cachifiedcachified

README

cachified


🧙One API to cache them all


wrap virtually everything that can store by key to act as cache with ttl/max-age, stale-while-validate, parallel fetch protection and type-safety support

🤔Idea and 💻initial implementation by@kentcdodds 👏💜


Install


  1. ``` shell
  2. npm install cachified
  3. # yarn add cachified
  4. ```

Usage


  1. ``` ts
  2. import { LRUCache } from 'lru-cache';
  3. import { cachified, CacheEntry } from 'cachified';

  5. /* lru cache is not part of this package but a simple non-persistent cache */
  6. const lru = new LRUCache<string, CacheEntry>({ max: 1000 });

  8. function getUserById(userId: number) {
  9.   return cachified({
  10.     key: `user-${userId}`,
  11.     cache: lru,
  12.     async getFreshValue() {
  13.       /* Normally we want to either use a type-safe API or `checkValue` but
  14.          to keep this example simple we work with `any` */
  15.       const response = await fetch(
  16.         `https://jsonplaceholder.typicode.com/users/${userId}`,
  17.       );
  18.       return response.json();
  19.     },
  20.     /* 5 minutes until cache gets invalid
  21.      * Optional, defaults to Infinity */
  22.     ttl: 300_000,
  23.   });
  24. }

  26. // Let's get through some calls of `getUserById`:

  28. console.log(await getUserById(1));
  29. // > logs the user with ID 1
  30. // Cache was empty, `getFreshValue` got invoked and fetched the user-data that
  31. // is now cached for 5 minutes

  33. // 2 minutes later
  34. console.log(await getUserById(1));
  35. // > logs the exact same user-data
  36. // Cache was filled an valid. `getFreshValue` was not invoked

  38. // 10 minutes later
  39. console.log(await getUserById(1));
  40. // > logs the user with ID 1 that might have updated fields
  41. // Cache timed out, `getFreshValue` got invoked to fetch a fresh copy of the user
  42. // that now replaces current cache entry and is cached for 5 minutes
  43. ```

Options


  1. ``` ts
  2. interface CachifiedOptions<Value> {
  3.   /**
  4.    * Required
  5.    *
  6.    * The key this value is cached by
  7.    * Must be unique for each value
  8.    */
  9.   key: string;
  10.   /**
  11.    * Required
  12.    *
  13.    * Cache implementation to use
  14.    *
  15.    * Must conform with signature
  16.    *  - set(key: string, value: object): void | Promise
  17.    *  - get(key: string): object | Promise
  18.    *  - delete(key: string): void | Promise
  19.    */
  20.   cache: Cache;
  21.   /**
  22.    * Required
  23.    *
  24.    * Function that is called when no valid value is in cache for given key
  25.    * Basically what we would do if we wouldn't use a cache
  26.    *
  27.    * Can be async and must return fresh value or throw
  28.    *
  29.    * receives context object as argument
  30.    *  - context.metadata.ttl?: number
  31.    *  - context.metadata.swr?: number
  32.    *  - context.metadata.createdTime: number
  33.    *  - context.background: boolean
  34.    */
  35.   getFreshValue: GetFreshValue<Value>;
  36.   /**
  37.    * Time To Live; often also referred to as max age
  38.    *
  39.    * Amount of milliseconds the value should stay in cache
  40.    * before we get a fresh one
  41.    *
  42.    * Setting any negative value will disable caching
  43.    * Can be infinite
  44.    *
  45.    * Default: `Infinity`
  46.    */
  47.   ttl?: number;
  48.   /**
  49.    * Amount of milliseconds that a value with exceeded ttl is still returned
  50.    * while a fresh value is refreshed in the background
  51.    *
  52.    * Should be positive, can be infinite
  53.    *
  54.    * Default: `0`
  55.    */
  56.   staleWhileRevalidate?: number;
  57.   /**
  58.    * Alias for staleWhileRevalidate
  59.    */
  60.   swr?: number;
  61.   /**
  62.    * Validator that checks every cached and fresh value to ensure type safety
  63.    *
  64.    * Can be a zod schema or a custom validator function
  65.    *
  66.    * Value considered ok when:
  67.    *  - zod schema.parseAsync succeeds
  68.    *  - validator returns
  69.    *    - true
  70.    *    - migrate(newValue)
  71.    *    - undefined
  72.    *    - null
  73.    *
  74.    * Value considered bad when:
  75.    *  - zod schema.parseAsync throws
  76.    *  - validator:
  77.    *    - returns false
  78.    *    - returns reason as string
  79.    *    - throws
  80.    *
  81.    * A validator function receives two arguments:
  82.    *  1. the value
  83.    *  2. a migrate callback, see https://github.com/Xiphe/cachified#migrating-values
  84.    *
  85.    * Default: `undefined` - no validation
  86.    */
  87.   checkValue?: CheckValue<Value> | Schema<Value, unknown>;
  88.   /**
  89.    * Set true to not even try reading the currently cached value
  90.    *
  91.    * Will write new value to cache even when cached value is
  92.    * still valid.
  93.    *
  94.    * Default: `false`
  95.    */
  96.   forceFresh?: boolean;
  97.   /**
  98.    * Weather of not to fall back to cache when getting a forced fresh value
  99.    * fails
  100.    *
  101.    * Can also be a positive number as the maximum age in milliseconds that a
  102.    * fallback value might have
  103.    *
  104.    * Default: `Infinity`
  105.    */
  106.   fallbackToCache?: boolean | number;
  107.   /**
  108.    * Amount of time in milliseconds before revalidation of a stale
  109.    * cache entry is started
  110.    *
  111.    * Must be positive and finite
  112.    *
  113.    * Default: `0`
  114.    */
  115.   staleRefreshTimeout?: number;
  116.   /**
  117.    * A reporter receives events during the runtime of
  118.    * cachified and can be used for debugging and monitoring
  119.    *
  120.    * Default: `undefined` - no reporting
  121.    */
  122.   reporter?: CreateReporter<Value>;
  123. }
  124. ```

    125. Adapters


    There are some build-in adapters for common caches, using them makes sure the used caches cleanup outdated values themselves.

    Adapter for lru-cache


    1. ``` ts
    2. import { LRUCache } from 'lru-cache';
    3. import { cachified, lruCacheAdapter, CacheEntry } from 'cachified';

    5. const lru = new LRUCache<string, CacheEntry>({ max: 1000 });
    6. const cache = lruCacheAdapter(lru);

    8. await cachified({
    9.   cache,
    10.   key: 'user-1',
    11.   getFreshValue() {
    12.     return 'user@example.org';
    13.   },
    14. });
    15. ```

    Adapter for redis


    1. ``` ts
    2. import { createClient } from 'redis';
    3. import { cachified, redisCacheAdapter } from 'cachified';

    5. const redis = createClient({
    6.   /* ...opts */
    7. });
    8. const cache = redisCacheAdapter(redis);

    10. await cachified({
    11.   cache,
    12.   key: 'user-1',
    13.   getFreshValue() {
    14.     return 'user@example.org';
    15.   },
    16. });
    17. ```

    Adapter for redis@3


    1. ``` ts
    2. import { createClient } from 'redis';
    3. import { cachified, redis3CacheAdapter } from 'cachified';

    5. const redis = createClient({
    6.   /* ...opts */
    7. });
    8. const cache = redis3CacheAdapter(redis);

    10. const data = await cachified({
    11.   cache,
    12.   key: 'user-1',
    13.   getFreshValue() {
    14.     return 'user@example.org';
    15.   },
    16. });
    17. ```

    Advanced Usage


    Stale while revalidate


    Specify a time window in which a cached value is returned even though it's ttl is exceeded while the cache is updated in the background for the next
    call.

    1. ``` ts
    2. import { cachified } from 'cachified';

    4. const cache = new Map();

    6. function getUserById(userId: number) {
    7.   return cachified({
    8.     ttl: 120_000 /* Two minutes */,
    9.     staleWhileRevalidate: 300_000 /* Five minutes */,

    11.     cache,
    12.     key: `user-${userId}`,
    13.     async getFreshValue() {
    14.       const response = await fetch(
    15.         `https://jsonplaceholder.typicode.com/users/${userId}`,
    16.       );
    17.       return response.json();
    18.     },
    19.   });
    20. }

    22. console.log(await getUserById(1));
    23. // > logs the user with ID 1
    24. // Cache is empty, `getFreshValue` gets invoked and and its value returned and
    25. // cached for 7 minutes total. After 2 minutes the cache will start refreshing in background

    27. // 30 seconds later
    28. console.log(await getUserById(1));
    29. // > logs the exact same user-data
    30. // Cache is filled an valid. `getFreshValue` is not invoked, cached value is returned

    32. // 4 minutes later
    33. console.log(await getUserById(1));
    34. // > logs the exact same user-data
    35. // Cache timed out but stale while revalidate is not exceeded.
    36. // cached value is returned immediately, `getFreshValue` gets invoked in the
    37. // background and its value is cached for the next 7 minutes

    39. // 30 seconds later
    40. console.log(await getUserById(1));
    41. // > logs fresh user-data from the previous call
    42. // Cache is filled an valid. `getFreshValue` is not invoked, cached value is returned
    43. ```

    Forcing fresh values and falling back to cache


    We can use forceFreshto get a fresh value regardless of the values ttl or stale while validate

    1. ``` ts
    2. import { cachified } from 'cachified';

    4. const cache = new Map();

    6. function getUserById(userId: number, forceFresh?: boolean) {
    7.   return cachified({
    8.     forceFresh,
    9.     /* when getting a forced fresh value fails we fall back to cached value
    10.        as long as it's not older then 5 minutes */
    11.     fallbackToCache: 300_000 /* 5 minutes, defaults to Infinity */,

    13.     cache,
    14.     key: `user-${userId}`,
    15.     async getFreshValue() {
    16.       const response = await fetch(
    17.         `https://jsonplaceholder.typicode.com/users/${userId}`,
    18.       );
    19.       return response.json();
    20.     },
    21.   });
    22. }

    24. console.log(await getUserById(1));
    25. // > logs the user with ID 1
    26. // Cache is empty, `getFreshValue` gets invoked and and its value returned

    28. console.log(await getUserById(1, true));
    29. // > logs fresh user with ID 1
    30. // Cache is filled an valid. but we forced a fresh value, so `getFreshValue` is invoked
    31. ```

    Type-safety


    In practice we can not be entirely sure that values from cache are of the types we assume. For example other parties could also write to the cache or code is changed while cache
    stays the same.

    1. ``` ts
    2. import { cachified, createCacheEntry } from 'cachified';

    4. const cache = new Map();

    6. /* Assume something bad happened and we have an invalid cache entry... */
    7. cache.set('user-1', createCacheEntry('INVALID') as any);

    9. function getUserById(userId: number) {
    10.   return cachified({
    11.     checkValue(value: unknown) {
    12.       if (!isRecord(value)) {
    13.         /* We can either throw to indicate a bad value */
    14.         throw new Error(`Expected user to be object, got ${typeof value}`);
    15.       }

    17.       if (typeof value.email !== 'string') {
    18.         /* Or return a reason/message string */
    19.         return `Expected user-${userId} to have an email`;
    20.       }

    22.       if (typeof value.username !== 'string') {
    23.         /* Or just say no... */
    24.         return false;
    25.       }

    27.       /* undefined, true or null are considered OK */
    28.     },

    30.     cache,
    31.     key: `user-${userId}`,
    32.     async getFreshValue() {
    33.       const response = await fetch(
    34.         `https://jsonplaceholder.typicode.com/users/${userId}`,
    35.       );
    36.       return response.json();
    37.     },
    38.   });
    39. }

    41. function isRecord(value: unknown): value is Record<string, unknown> {
    42.   return typeof value === 'object' && value !== null && !Array.isArray(value);
    43. }

    45. console.log(await getUserById(1));
    46. // > logs the user with ID 1
    47. // Cache was not empty but value was invalid, `getFreshValue` got invoked and
    48. // and the cache was updated

    50. console.log(await getUserById(1));
    51. // > logs the exact same data as above
    52. // Cache was filled an valid. `getFreshValue` was not invoked
    53. ```

    ℹ️checkValueis also invoked with the return value of getFreshValue


    Type-safety with zod


    We can also use zod schemas to ensure correct types

    1. ``` ts
    2. import { cachified, createCacheEntry } from 'cachified';
    3. import z from 'zod';

    5. const cache = new Map();
    6. /* Assume something bad happened and we have an invalid cache entry... */
    7. cache.set('user-1', createCacheEntry('INVALID') as any);

    9. function getUserById(userId: number) {
    10.   return cachified({
    11.     checkValue: z.object({
    12.       email: z.string(),
    13.     }),

    15.     cache,
    16.     key: `user-${userId}`,
    17.     async getFreshValue() {
    18.       const response = await fetch(
    19.         `https://jsonplaceholder.typicode.com/users/${userId}`,
    20.       );
    21.       return response.json();
    22.     },
    23.   });
    24. }

    26. console.log(await getUserById(1));
    27. // > logs the user with ID 1
    28. // Cache was not empty but value was invalid, `getFreshValue` got invoked and
    29. // and the cache was updated

    31. console.log(await getUserById(1));
    32. // > logs the exact same data as above
    33. // Cache was filled an valid. `getFreshValue` was not invoked
    34. ```

    Manually working with the cache


    During normal app lifecycle there usually is no need for this but for maintenance and testing these helpers might come handy.

    1. ``` ts
    2. import { createCacheEntry, assertCacheEntry, cachified } from 'cachified';

    4. const cache = new Map();

    6. /* Manually set an entry to cache */
    7. cache.set(
    8.   'user-1',
    9.   createCacheEntry(
    10.     'someone@example.org',
    11.     /* Optional CacheMetadata */
    12.     { ttl: 300_000, swr: Infinity },
    13.   ),
    14. );

    16. /* Receive the value with cachified */
    17. const value: string = await cachified({
    18.   cache,
    19.   key: 'user-1',
    20.   getFreshValue() {
    21.     throw new Error('This is not called since cache is set earlier');
    22.   },
    23. });
    24. console.log(value);
    25. // > logs "someone@example.org"

    27. /* Manually get a value from cache */
    28. const entry: unknown = cache.get('user-1');
    29. assertCacheEntry(entry); // will throw when entry is not a valid CacheEntry
    30. console.log(entry.value);
    31. // > logs "someone@example.org"

    33. /* Manually remove an entry from cache */
    34. cache.delete('user-1');
    35. ```

    Migrating Values


    When the format of cached values is changed during the apps lifetime they can be migrated on read like this:

    1. ``` ts
    2. import { cachified, createCacheEntry } from 'cachified';

    4. const cache = new Map();

    6. /* Let's assume we've previously only stored emails not user objects */
    7. cache.set('user-1', createCacheEntry('someone@example.org'));

    9. function getUserById(userId: number) {
    10.   return cachified({
    11.     checkValue(value, migrate) {
    12.       if (typeof value === 'string') {
    13.         return migrate({ email: value });
    14.       }
    15.       /* other validations... */
    16.     },

    18.     key: 'user-1',
    19.     cache,
    20.     getFreshValue() {
    21.       throw new Error('This is never called');
    22.     },
    23.   });
    24. }

    26. console.log(await getUserById(1));
    27. // > logs { email: 'someone@example.org' }
    28. // Cache is filled and invalid but value can be migrated from email to user-object
    29. // `getFreshValue` is not invoked

    31. console.log(await getUserById(1));
    32. // > logs the exact same data as above
    33. // Cache is filled an valid.
    34. ```

    Soft-purging entries


    Soft-purging cached data has the benefit of not immediately putting pressure on the app to update all cached values at once and instead allows to get them updated over time.

    More details: Soft vs. hard purge

    1. ``` ts
    2. import { cachified, softPurge } from 'cachified';

    4. const cache = new Map();

    6. function getUserById(userId: number) {
    7.   return cachified({
    8.     cache,
    9.     key: `user-${userId}`,
    10.     ttl: 300_000,
    11.     async getFreshValue() {
    12.       const response = await fetch(
    13.         `https://jsonplaceholder.typicode.com/users/${userId}`,
    14.       );
    15.       return response.json();
    16.     },
    17.   });
    18. }

    20. console.log(await getUserById(1));
    21. // > logs user with ID 1
    22. // cache was empty, fresh value was requested and is cached for 5 minutes

    24. await softPurge({
    25.   cache,
    26.   key: 'user-1',
    27. });
    28. // This internally sets the ttl to 0 and staleWhileRevalidate to 300_000

    30. // 10 seconds later
    31. console.log(await getUserById(1));
    32. // > logs the outdated, soft-purged data
    33. // cache has been soft-purged, the cached value got returned and a fresh value
    34. // is requested in the background and again cached for 5 minutes

    36. // 1 minute later
    37. console.log(await getUserById(1));
    38. // > logs the fresh data that got refreshed by the previous call

    40. await softPurge({
    41.   cache,
    42.   key: 'user-1',
    43.   // manually overwrite how long the stale data should stay in cache
    44.   staleWhileRevalidate: 60_000 /* one minute from now on */,
    45. });

    47. // 2 minutes later
    48. console.log(await getUserById(1));
    49. // > logs completely fresh data
    50. ```

    ℹ️In case we need to fully purge the value, we delete the key directly from our cache


    Fine-tuning cache metadata based on fresh values


    There are scenarios where we want to change the cache time based on the fresh value (ref #25 ). For example when an API might either provide our data or nulland in case we get an empty result we want to retry the API much faster.

    1. ``` ts
    2. import { cachified } from 'cachified';

    4. const cache = new Map();

    6. const value: null | string = await cachified({
    7.   ttl: 60_000 /* Default cache of one minute... */,
    8.   async getFreshValue(context) {
    9.     const response = await fetch(
    10.       `https://jsonplaceholder.typicode.com/users/1`,
    11.     );
    12.     const data = await response.json();

    14.     if (data === null) {
    15.       /* On an empty result, prevent caching */
    16.       context.metadata.ttl = -1;
    17.     }

    19.     return data;
    20.   },

    22.   cache,
    23.   key: 'user-1',
    24. });
    25. ```

    Batch requesting values


    In case multiple values can be requested in a batch action, but it's not clear which values are currently in cache we can use the createBatchhelper

    1. ``` ts
    2. import { cachified, createBatch } from 'cachified';

    4. const cache = new Map();

    6. async function getFreshValues(idsThatAreNotInCache: number[]) {
    7.   const res = await fetch(
    8.     `https://example.org/api?ids=${idsThatAreNotInCache.join(',')}`,
    9.   );
    10.   const data = await res.json();

    12.   // Validate data here...

    14.   return data;
    15. }

    17. function getUsersWithId(ids: number[]) {
    18.   const batch = createBatch(getFreshValues);

    20.   return Promise.all(
    21.     ids.map((id) =>
    22.       cachified({
    23.         getFreshValue: batch.add(
    24.           id,
    25.           /* onValue callback is optional but can be used to manipulate
    26.            * cache metadata based on the received value. (see section above) */
    27.           ({ value, ...context }) => {},
    28.         ),

    30.         cache,
    31.         key: `entry-${id}`,
    32.         ttl: 60_000,
    33.       }),
    34.     ),
    35.   );
    36. }

    38. console.log(await getUsersWithId([1, 2]));
    39. // > logs user objects for ID 1 & ID 2
    40. // Caches is completely empty. `getFreshValues` is invoked with `[1, 2]`
    41. // and its return values cached separately

    43. // 1 minute later
    44. console.log(await getUsersWithId([2, 3]));
    45. // > logs user objects for ID 2 & ID 3
    46. // User with ID 2 is in cache, `getFreshValues` is invoked with `[3]`
    47. // cachified returns with one value from cache and one fresh value
    48. ```

    Reporting


    A reporter might be passed to cachified to log caching events, we ship a reporter resembling the logging from Kents implementation

    1. ``` ts
    2. import { cachified, verboseReporter } from 'cachified';

    4. const cache = new Map();

    6. await cachified({
    7.   reporter: verboseReporter(),

    9.   cache,
    10.   key: 'user-1',
    11.   async getFreshValue() {
    12.     const response = await fetch(
    13.       `https://jsonplaceholder.typicode.com/users/1`,
    14.     );
    15.     return response.json();
    16.   },
    17. });
    18. ```

    please refer to the implementation of verboseReporter when you want to implement a custom reporter.