README | ZBW

This library is an attempt to make the fastest possible memoization library in JavaScript that supports N arguments.

Installation

Usage

const memoize = require('fast-memoize')

const fn = function (one, two, three) { /* ... */ }

const memoized = memoize(fn)

memoized('foo', 3, 'bar')
memoized('foo', 3, 'bar') // Cache hit

Custom cache

The fastest cache is used for the running environment, but it is possible to pass a custom cache to be used.

const memoized = memoize(fn, {
  cache: {
    create() {
      var store = {};
      return {
        has(key) { return (key in store); },
        get(key) { return store[key]; },
        set(key, value) { store[key] = value; }
      };
    }
  }
})

The custom cache should be an object containing a create method that returns an object implementing the following methods: - get - set - has

Custom serializer

const memoized = memoize(fn, {
  serializer: customSerializer
})

The serializer is a function that receives one argument and outputs a string that represents it. It has to be a deterministic algorithm meaning that, given one input, it always returns the same output.

Benchmark

Below you can see a performance benchmark between some of the most popular libraries for memoization.

To run the benchmark, clone the repo, install the dependencies and run npm run benchmark.

Against another git hash

Gotchas

Rest & Default Parameters

We check for function.length to get upfront the expected number of arguments in order to use the fastest strategy. But when rest & default parameters are being used, we don’t receive the right number of arguments (see details).

// Rest parameter example
function multiply (multiplier, ...theArgs) {
  return theArgs.map(function (element) {
    return multiplier * element
  })
}
multiply.length // => 1

// Default parameter example
function divide (element, divisor = 1) {
  return divisor * element
}
divide.length // => 1

So if you use rest & default parameters, explicitly set the strategy to variadic.

const memoizedMultiply = memoize(multiply, {
  strategy: memoize.strategies.variadic
})

Function Arguments

The default serializer uses JSON.stringify which will serialize functions as null. This means that if you are passing any functions as arguments you will get the same output regardless of whether you pass in different functions or indeed no function at all. The cache key generated will always be the same. To get around this you can give each function a unique ID and use that.

let id = 0
function memoizedId(x) {
  if (!x.__memoizedId) x.__memoizedId = ++id
  return { __memoizedId: x.__memoizedId }
}

memoize((aFunction, foo) => {
  return aFunction.bind(foo)
}, {
  serializer: args => {
    const argumentsWithFuncIds = Array.from(args).map(x => {
      if (typeof x === 'function') return memoizedId(x)
      return x
    })
    return JSON.stringify(argumentsWithFuncIds)
  }
})

fast-memoize