Kiwup/cache-cache


Cache all the things: memoize functions, cache objects etc

License: Apache-2.0

Language: TypeScript

Keywords: cache, in-memory, memoize, redis, typescript


Cache-cache

Version codecov CircleCI

Motivation

You are right, there are already a few package that does that:

So why bother re-writting one from scratch ? Here are the reasons:

  • They are quite old, some are a mix of callback and promises, hard to maintain
  • Some packages doesn't handle multiple caches layer (in-memory/redis)
  • Generally expose a complex API to end user
  • When using redis as cache, they weren't handling failures from upstream servers (timeout, errors).

Our objectives when writting that package were simple:

  • Simply to use
  • Easy to read how it works
  • Typings (avoid quite a lof of errors)
  • Handle failures correctly:
    • When memoizing function we wanted to always do something, even if our cache is down, we wanted to call the expensive function instead of reporting an error even if it's slower.

API

Config

By default the package is configured to use the MEMORY cache layer with a TTL of 15s, you can of course change those default: Each method accept a whole configuration, if you want to have a common one, you can use useAsDefault:

import { getMemoize, useAsDefault, AvailableCacheLayer } from '@rlvt/cache-cache'

// those default we be applied to all following new cache.
useAsDefault({
  layerConfigs: {
    [AvailableCacheLayer.MEMORY]: {
      ttl: 10 * 1000
    },
    [AvailableCachelayer.REDIS]: {
      ttl: 30 * 60 * 1000
    }
  },
  layerOrder: [
    AvailableCacheLayer.MEMORY,
    AvailableCacheLayer.REDIS
  ]
})

const expensiveFunction = async () => {
  // do something expensive
  return {}
}

// and you can override them per method if you want
const noMoreExpensive = getMemoize(expensiveFunction, {
  layerConfigs: {
    [AvailableCacheLayer.MEMORY]: {
      ttl: 10 * 1000
    }
  },
  layerOrder: [
    AvailableCacheLayer.MEMORY
  ]
})

Things to know:

  • Each getMemoize call

Memoize a function

NOTE: You can only memoize async function since call to cache can be asynchronous

You currently have two API to memoize a function:

  • if you are in Typescript, you can use the @Memoize decorator
import { Memoize } from '@rlvt/cache-cache'

@Memoize({
  layerConfigs: {
    [AvailableCacheLayer.MEMORY]: {
      ttl: 10 * 1000
    }
  },
  layerOrder: [
    AvailableCacheLayer.MEMORY
  ]
})
const expensiveFunction = async () => {
  // do something expensive
  return {}
}

// calling expensiveFunction will now automatically use the memoized version
  • Use the getMemoize API:
import { Memoize } from '@rlvt/cache-cache'

const expensiveFunction = async () => {
  // do something expensive
  return {}
}

// and you can override them per method if you want
const noMoreExpensive = getMemoize(expensiveFunction, {
  layerConfigs: {
    [AvailableCacheLayer.MEMORY]: {
      ttl: 10 * 1000
    }
  },
  layerOrder: [
    AvailableCacheLayer.MEMORY
  ]
})

Simple key/value cache

You can use the getStore API to get a cache that you can use with simple get/set functions:

import { getStore } from '@rlvt/cache-cache'

const store = getStore({
  layerConfigs: {
    [AvailableCacheLayer.MEMORY]: {
      ttl: 10 * 1000
    }
  },
  layerOrder: [
    AvailableCacheLayer.MEMORY
  ]
})
await store.set('key', { value: 1 })
const obj = await store.get('key')
// obj.value === 1
await store.clear('key')
const obj = await store.get('key')
// obj === undefined

Typescript typing

Since the data stored inside the cache isn't typed, by default you will only get raw object as type when fetching from cache. We implement our API to accept a generic argument that is the type of what is stored inside the cache:

import { Memoize } from '@rlvt/cache-cache'

type Person = {
 age: number
 name: number
}

@Memoize<Person>()
const expensiveFunction = async () => {
  // do something expensive
  return {}
}

Full configuration reference

enum AvailableCacheLayer {
  MEMORY = 'MEMORY',
  REDIS = 'REDIS'
}

type Config = {
  /**
   * Configuration for each cache layer 
   */
  layerConfigs: {
    [AvailableCacheLayer.REDIS]?: {
      /**
       * Default Time-To-Live for all keys on this layer
       */
      ttl: number,
      /**
       * When applying a custom ttl to a specific key you may want to increase the TTL
       * for a given layer, you can use this multiplier that will be applied to compute the
       * final TTL for the layer.
       */
      ttlMultiplier?: number
      /**
       * How much time to wait for the cache to respond when fetching a key
       * if it reach the timeout, the next layer will be called (or if no layer is left)
       * it will call the original function.
       */
      timeout?: number
      /**
       * Shallow errors should be set as true if you want to ignore all caches issues
       * (like failing to connect to a redis server) and fallback to undefined
       */
      shallowErrors?: boolean
      /**
       * Provide your own ioredis client
       */
      redisClient: IORedis.Redis,
      /**
       * A custom prefix used to differenciate keys
       * By default memoized function use their name as prefix
       */
      prefix?: string
    }
    [AvailableCacheLayer.MEMORY]?: {
      /**
       * Default Time-To-Live for all keys on this layer
       */
      ttl: number,
      /**
       * When applying a custom ttl to a specific key you may want to increase the TTL
       * for a given layer, you can use this multiplier that will be applied to compute the
       * final TTL for the layer.
       */
      ttlMultiplier?: number
      /**
       * How much time to wait for the cache to respond when fetching a key
       * if it reach the timeout, the next layer will be called (or if no layer is left)
       * it will call the original function.
       */
      timeout?: number
      /**
       * Shallow errors should be set as true if you want to ignore all caches issues
       * (like failing to connect to a redis server) and fallback to undefined
       */
      shallowErrors?: boolean
      /**
       * Maximum number of keys to store inside the in-memory cache, if it's reached
       * the cache implement the `least-recently-used` algorithm, see
       * https://github.com/isaacs/node-lru-cache
       *
       * default to 100000 keys
       */
      maxEntries?: number
    }
  }
  /**
   * Order in the array is the order in which each layer will be called when getting a value
   */
  layerOrder: AvailableCacheLayer[]
}

License

Apache-2.0

Project Statistics

Sourcerank 3
Repository Size 166 KB
Stars 7
Forks 0
Watchers 6
Open issues 0
Dependencies 859
Contributors 2
Tags 7
Created
Last updated
Last pushed

Top Contributors See all

Valentin Marchaud Valentin T.

Recent Tags See all

v0.7.0 November 26, 2019
v0.6.0 November 26, 2019
v0.5.0 November 25, 2019
v0.4.0 November 22, 2019
v0.3.0 November 21, 2019
v0.2.0 November 20, 2019
v0.1.0 November 19, 2019

Something wrong with this page? Make a suggestion

Last synced: 2019-11-25 17:01:54 UTC

Login to resync this repository