> moize

moize is a consistently blazing fast memoization library for JavaScript. It handles multiple parameters (including default values) without any additional configuration, and offers a large number of options to satisfy any number of potential use-cases.

- Importing
- ESM in browsers
- ESM in NodeJS
- CommonJS
- Usage
- Configuration options
- isDeepEqual
- isPromise
- isReact
- isSerialized
- isShallowEqual
- matchesArg
- matchesKey
- maxAge
- maxArgs
- maxSize
- onCacheAdd
- onCacheChange
- onCacheHit
- onExpire
- profileName
- serializer
- transformArgs
- updateCacheForKey
- updateExpire
- Usage with shortcut methods
- moize.deep
- moize.infinite
- moize.matchesArg
- moize.matchesKey
- moize.maxAge
- moize.maxArgs
- moize.maxSize
- moize.promise
- moize.react
- moize.serialize
- moize.serializeWith
- moize.shallow
- moize.transformArgs
- moize.updateCacheForKey
- useMoize hook
- Composition
- Collecting statistics
- Stats methods
- clearStats
- collectStats
- [getStats([profileName])](#getstatsprofilename)
- Introspection
- isCollectingStats
- isMoized
- Direct cache manipulation
- cache
- cacheSnapshot
- add(key, value)
- clear()
- get(key)
- getStats()
- has(key)
- keys()
- remove(key)
- update(key, value)
- values()
- Benchmarks
- Filesize
- Browser support
- Development

``
$ npm i moize --save
`

Importing

ESM in browsers

`ts
import moize from 'moize';
`

ESM in NodeJS

`ts
import moize from 'moize/mjs/index.mjs';
`

CommonJS

`ts
const moize = require('moize').default;
`

Usage

`ts
import moize from 'moize';

const method = (a: number, b: number) => a + b;

const memoized = moize(method);

memoized(2, 4); // 6
memoized(2, 4); // 6, pulled from cache
`

All parameter types are supported, including circular objects, functions, etc. There are also a number of shortcut methods to memoize for unique use-cases.

Configuration options

moize optionally accepts an object of options as either the second parameter or as the first step in a curried function:

`ts
// inline
moize(fn, options);

// curried
moize(options)(fn);
`

The full shape of these options:

`ts
type Options = {
// is the cache based on deep equality of each key argument
isDeepEqual: boolean;
// is the result a promise
isPromise: boolean;
// is the result a React component
isReact: boolean;
// should the parameters be serialized instead of directly referenced
isSerialized: boolean;
// is the cache based on shallow equality of each key argument
isShallowEqual: boolean;
// custom method to compare equality between two key arguments
matchesArg: (cachedKeyArg: any, keyArg: any) => boolean;
// custom method to compare equality across all key arguments
matchesKey: (cachedKey: any[], key: any[]) => boolean;
// amount of time in milliseconds before the cache will expire
maxAge: number;
// maximum number of arguments passed to use as key for caching
maxArgs: number;
// maximum size of cache for this method
maxSize: number;
// method fired when a new entry is added to cache
onCacheAdd: (
cache: moize.Cache,
options: moize.Options,
moized: (...args: any[]) => any
) => void;
// method fire when either a new entry is added to cache or the LRU ordering of the cache has changed
onCacheChange: (
cache: moize.Cache,
options: moize.Options,
moized: (...args: any[]) => any
) => void;
// method fired when an existing entry in cache is used
onCacheHit: (
cache: moize.Cache,
options: moize.Options,
moized: (...args: any[]) => any
) => void;
// method to fire when a cache entry expires (in combination with maxAge)
onExpire: (key: any[]) => void;
// the unique identifier to give the memoized method when collecting statistics
profileName: string;
// method to serialize the arguments to build a unique cache key
serializer: (key: any[]) => string;
// method to transform the args into a custom format for key storage in cache
transformArgs: (key: any[]) => any[];
// should the cache entry be refreshed by calling the underlying function with the same parameters and
// updating the value stored in cache to be the new result
updateCacheForKey: (key: any[]) => boolean;
// should the cache entry's expiration be refreshed when the cache entry is hit (in combination with maxAge)
updateExpire: boolean;
};
`

All default values can be found here.

isDeepEqual

_defaults to false_

Should deep equality be used to compare cache each key argument.

`ts
type Arg = {
one: {
nested: string;
};
two: string;
};

const fn = ({ one, two }: Arg) => [one, two];

const memoized = moize(fn, { isDeepEqual: true });

memoized({ one: { nested: 'one' }, two: 'two' });
memoized({ one: { nested: 'one' }, two: 'two' }); // pulls from cache
`

This is also available via the shortcut method of moize.deep

`ts
const memoized = moize.deep(fn);
`

isPromise

_defaults to false_

Is the computed value in the function a Promise.

`ts
const fn = async (item: Promise) => await item;

const memoized = moize(fn, { isPromise: true });
`

This is also available via the shortcut method of moize.promise.

`ts
const memoized = -moize.promise(fn);
`

The Promise itself will be stored in cache, so that cached returns will always maintain the Promise contract. For common usage reasons, if the Promise is rejected, the cache entry will be deleted.

isReact

_defaults to false_

Is the function passed a stateless functional React component.

`tsx
type Props = {
one: string;
two: number;
};

const Component = ({ one, two }: Props) => (


);

const MemoizedFoo = moize(Component, { isReact: true });
`

This is also available via the shortcut method of moize.react.

`ts
const MemoizedFoo = moize.react(Component);
`

The method will do a shallow equal comparison of both props and legacy context of the component based on strict equality. If you want to do a deep equals comparison, set isDeepEqual to true.

NOTE: This will memoize on each instance of the component passed, which is equivalent to PureComponent or React.memo. If you want to
memoize on _all_ instances (which is how this option worked prior to version 6), use the following options:

`ts
const memoized = moize(Component, { isShallowEqual: true, maxArgs: 2 });
`

isSerialized

_defaults to false_

Serializes the parameters passed into a string and uses this as the key for cache comparison.

`ts
const fn = (mutableObject: { one: Record }) =>
mutableObject.property;

const memoized = moize(fn, { isSerialized: true });
`

This is also available via the shortcut method of moize.serialize.

`ts
const memoized = moize.serialize(fn);
`

If serialize is combined with either maxArgs or transformArgs, the following order is used:

1. limit by maxArgs (if applicable)
1. transform by transformArgs (if applicable)
1. serialize by serializer

NOTE: This is much slower than the default key storage, and usually the same requirements can be meet with isDeepEqual, so use at your discretion.

isShallowEqual

_defaults to false_

Should shallow equality be used to compare cache each key argument.

`ts
type Arg = {
one: string;
two: string;
};

const fn = ({ one, two }: Arg) => [one, two];

const memoized = moize(fn, { isShallowEqual: true });

memoized({ one: 'one', two: 'two' });
memoized({ one: 'one', two: 'two' }); // pulls from cache
`

This is also available via the shortcut method of moize.shallow

`ts
const memoized = moize.shallow(fn);
`

matchesArg

_defaults to SameValueZero equality_

Custom method used to compare equality of keys for cache purposes by comparing each argument.

`ts
type Arg = {
one: string;
two: string;
};

const fn = ({ one, two }: Arg) => [one, two];

const hasOneProperty = (cacheKeyArg: Arg, keyArg: Arg) =>
Object.keys(cacheKeyArg).length === 1 && Object.keys(keyArg).length === 1;

const memoized = moize(fn, { matchesArg: hasOneProperty });

memoized({ one: 'two' };
memoized({ two: 'three' }); // pulls from cache
`

This is also available via the shortcut method of moize.matchesArg

`ts
const memoized = moize.matchesArg(hasOneProperty)(fn);
`

NOTE: This comparison is used iteratively on each argument, rather than comparing the two keys as a whole. If you want to compare the key as a whole, you should use matchesKey.

matchesKey

Custom method used to compare equality of keys for cache purposes by comparing the entire key.

`ts
type Arg = {
one: string;
two: string;
};

const fn = ({ one, two }: Arg) => [one, two];

const isFooEqualAndHasBar = (cacheKey: [Arg], key: [Arg]) =>
cacheKey[0].one === key[0].one &&
cacheKey[1].hasOwnProperty('two') &&
key[1].hasOwnProperty('two');

const memoized = moize(fn, { matchesKey: isFooEqualAndHasBar });

memoized({ one: 'two' }, { two: null });
memoized({ one: 'two' }, { two: 'three' }); // pulls from cache
`

This is also available via the shortcut method of moize.matchesKey

`ts
const memoized = moize.matchesKey(isFooEqualAndHasBar)(fn);
`

NOTE: This comparison uses the two keys as a whole, which is usually less performant than the matchArg comparison used iteratively on each argument. Generally speaking you should use the matchArg option for equality comparison.

maxAge

The maximum amount of time in milliseconds that you want a computed value to be stored in cache for this method.

`ts
const fn = (item: Record) => item;

const MAX_AGE = 1000 60 5; // five minutes;

const memoized = moize(fn, { maxAge: MAX_AGE });
`

This is also available via the shortcut method of moize.maxAge.

`ts
const memoized = moize.maxAge(MAX_AGE)(fn);
`

TIP: A common usage of this is in tandom with isPromise for AJAX calls, and in that scenario the expected behavior is usually to have the maxAge countdown begin upon resolution of the promise. If this is your intended use case, you should also apply the updateExpire option.

maxArgs

The maximum number of arguments (starting from the first) used in creating the key for the cache.

`ts
const fn = (item1: string, item2: string, item3: string) =>
item1 + item2 + item3;

const memoized = moize(fn, { maxArgs: 2 });

memoize('one', 'two', 'three');
memoize('one', 'two', 'four'); // pulls from cache, as the first two args are the same
`

This is also available via the shortcut method of moize.maxArgs.

`ts
const memoized = moize.maxArgs(2)(fn);
`

If maxArgs is combined with either serialize or transformArgs, the following order is used:

1. limit by maxArgs
1. transform by transformArgs (if applicable)
1. serialize by serializer (if applicable)

maxSize

_defaults to 1_

The maximum number of values you want stored in cache for this method. Clearance of the cache once the maxSize is reached is on a Least Recently Used basis.

`ts
const fn = (item: string) => item;

const memoized = moize(fn, { maxSize: 5 });
`

This is also available via the shortcut method of moize.maxSize.

`ts
const memoized = moize.maxSize(5)(fn);
`

onCacheAdd

Method to fire when an item has been added to cache. Receives the cache, options, and memoized function as a parameters.

`ts
const fn = (one: string, two: string) => [one, two];

const logCacheKeys = (
cache: Cache,
options: Options,
moized: Moized
) => console.log(cache.keys);

const moized = moize(fn, { maxSize: 2, onCacheAdd: logCacheKeys });

moized('one', 'two'); // [["one","two"]]
moized('one', 'two');
moized('two', 'one'); // [["two","one"], ["one","two"]]
moized('one', 'two');
`

NOTE: When combined with onCacheChange, this method will always fire first.

onCacheChange

Method to fire when an item has been either added to cache, or existing cache was reordered based on a cache hit. Receives the cache, options, and memoized function as a parameters.

`ts
const fn = (one: string, two: string) => [one, two];

const logCacheKeys = (
cache: Cache,
options: Options,
moized: Moized
) => console.log(cache.keys);

const moized = moize(fn, { maxSize: 2, onCacheChange: logCacheKeys });

moized('one', 'two'); // [["one","two"]]
moized('one', 'two');
moized('two', 'one'); // [["two","one"], ["one","two"]]
moized('one', 'two'); // [["one","two"], ["two","one"]]
`

NOTE: When combined with onCacheAdd or onCacheHit, this method will always fire last.

onCacheHit

Method to fire when an existing cache item is found. Receives the cache, options, and memoized function as a parameters.

`ts
const fn = (one: string, two: string) => [one, two];

const logCacheKeys = (
cache: Cache,
options: Options,
moized: Moized
) => console.log(cache.keys);

const moized = moize(fn, { maxSize: 2, onCacheHit: logCacheKeys });

moized('one', 'two');
moized('one', 'two'); // [["one","two"]]
moized('two', 'one');
moized('one', 'two'); // [["two","one"], ["one","two"]]
`

NOTE: When combined with onCacheChange, this method will always fire first.

onExpire

A callback that is called when the cached entry expires.

`ts
const fn = (item: string) => item;

const logKey = (key: Key) => console.log(key);

const memoized = moize(fn, { maxAge: 10000, onExpire: logKey });
`

If you return false from this method, it will prevent the key's removal and refresh the expiration in the same vein as updateExpire based on maxAge:

`ts
const fn = (item: string) => item;

let expirationAttempts = 0;

const limitExpirationAttempts = (key: Key) => {
expirationAttempts += 1;

return expirationAttempts < 2;
};

const memoized = moize(fn, {
maxAge: 10000,
onExpire: limitExpirationAttempts,
});

memoized('one'); // will expire key after 30 seconds, or 3 expiration attempts
`

NOTE: You must set a maxAge for this option to take effect.

profileName

_defaults to function name and file/line location_

Name to use as unique identifier for the function when collecting statistics.

`ts
moize.collectStats();

const fn = (item: string) => item;

const memoized = moize(fn, { profileName: 'my fancy identity' });
`

This is also available via the shortcut method of moize.profile.

`ts
const memoized = moize.profile('profile-name')(fn);
`

NOTE: You must be collecting statistics for this option to take effect.

serializer

_defaults to serializeArguments in utils.js_

Method used in place of the internal serializer when serializing the parameters for cache key comparison. The function accepts a single argument, the Array of args, and must also return an Array.

`ts
const fn = (one: string, two: string) => [one, two];

const customSerializer = (args: string[]) => [JSON.stringify(args[0])];

const memoized = moize(fn, {
isSerialized: true,
serializer,
});
`

This is also available via the shortcut method of moize.serializeWith.

`ts
const memoized = moize.serializeWith(customSerializer)(fn);
`

NOTE: You must set isSerialized for this option to take effect.

transformArgs

Transform the arguments passed before it is used as a key. The function accepts a single argument, the Array of args, and must also return an Array.

`ts
const fn = (one: string | null, two: string | null, three: string | null) => [
two,
three,
];

const ignoreFirstArg = (args: (string | null)[]) => args.slice(1);

const moized = moize(fn, { transformArgs: ignoreFirstArg });

moize('one', 'two', 'three');
moize(null, 'two', 'three'); // pulled from cache
`

This is also available via the shortcut method of moize.transformArgs.

`ts
const memoized = moize.transformArgs(argTransformer)(fn);
`

If transformArgs is combined with either maxArgs or serialize, the following order is used:

1. limit by maxArgs (if applicable)
1. transform by transformArgs
1. serialize by serializer (if applicable)

updateCacheForKey

If you want to update the cache for a given key instead of leverage the value currently stored in cache.

`ts
const fn = (item: string) => item;

let lastUpdate = Date.now();

const memoized = moize(fn, {
updateCacheForKey([item]: [string]) {
const now = Date.now();
const last = lastUpdated;

lastUpdate = now;

// its been more than 5 minutes since last update
return last + 300000 < now;
},
});

memoized('one');
memoized('one'); // pulled from cache

// 5 minutes later

memoized('one'); // re-calls method and updates cache
`

This is also available via the shortcut method of moize.updateCacheForKey.

`ts
const memoized = moize.updateCacheForKey(shouldCacheUpdate)(fn);
`

updateExpire

When a maxAge is set, clear the scheduled expiration of the key when that key is retrieved, setting a new expiration based on the most recent retrieval from cache.

`ts
const fn = (item: string) => item;

const MAX_AGE = 1000 60 5; // five minutes

const memoized = moize(fn, { maxAge: MAX_AGE, updateExpire: true });

memoized('one');

setTimeout(() => {
/**
* hits cache, which updates the expire to be 5 minutes
* from this run instead of the first
*/
memoized('one');
}, 1000 * 60);
`

Usage with shortcut methods

moize.deep

Pre-applies the isDeepEqual option.

`ts
import moize from 'moize';

const fn = (one: string, two: string) => ${one} ${two};

export default moize.deep(fn);
`

moize.infinite

Pre-applies the maxSize option with Infinity.

`ts
import moize from 'moize';

const fn = (one: string, two: string) => ${one} ${two};

export default moize.infinite(fn);
`

NOTE: This mimics default behavior of moize prior to version 6.

moize.matchesArg

Pre-applies the matchesArg option as a curriable method.

`ts
import moize from 'moize';

const isEqualOrFoo = (cacheKeyArg: string, keyArg: string) =>
cacheKeyArg === keyArg || keyArg === 'one';

const fn = (one: string, two: string) => ${one} ${two};

export default moize.matchesArg(isEqualOrFoo)(fn);
`

moize.matchesKey

Pre-applies the matchesKey option as a curriable method.

`ts
import moize from 'moize';

const fn = (one: string, two: string) => ${one} ${two};

const isEqualOrHasFoo = (cacheKey: Key, key: Key) =>
key.every((keyArg, index) => keyArg === cacheKey[index]) ||
key.some((keyArg) => keyArg === 'one');

export default moize.matchesKey(isEqualOrHasFoo)(fn);
`

moize.maxAge

Pre-applies the maxAge option as a curriable method.

`ts
import moize from 'moize';

const fn = (one: string, two: string) => ${one} ${two};

export default moize.maxAge(5000)(fn);
`

moize.maxArgs

Pre-applies the maxArgs option as a curriable method.

`ts
import moize from 'moize';

const fn = (one: string, two: string) => ${one} ${two};

export default moize.maxArgs(1)(fn);
`

moize.maxSize

Pre-applies the maxSize option as a curriable method.

`ts
import moize from 'moize';

const fn = (one: string, two: string) => ${one} ${two};

export default moize.maxSize(5)(fn);
`

moize.promise

Pre-applies the isPromise and updateExpire options. The updateExpire option does nothing if maxAge is not also applied, but ensures that the expiration begins at the resolution of the promise rather than the instantiation of it.

`ts
import moize from 'moize';

const fn = async (one: string, two: Record) =>
await someApiCall(one, two);

export default moize.promise(fn);
`

NOTE: If you do not want the promise to update its expiration when the cache is hit, then you should use the isPromise option directly instead.

moize.react

Pre-applies the isReact) option for memoizing functional components in React. Key comparisons are based on a shallow equal comparison of both props and legacy context.

`tsx
import moize from 'moize';

type Props = {
one: string;
two: number;
};

const Component = ({ one, two }: Props) => (


);

export default moize.react(Component);
`

NOTE: This method will not operate with components made via the class instantiation, as they do not offer the same referential transparency.

moize.serialize

Pre-applies the isSerialized option.

`ts
import moize from 'moize';

const fn = (one: Record, two: Record) => ({
one,
two,
});

export default moize.serialize(fn);
`

NOTE: If you want to provide a custom serializer, you should use moize.serializeWith:

`ts
moize.serializeWith(customSerializer)(fn);
`

moize.serializeWith

Pre-applies the isSerialized and serializer options.

`ts
import moize from 'moize';

const fn = (one: Record, two: Record) => ({
one,
two,
});

export default moize.serializeWith(JSON.stringify)(fn);
`

NOTE: If you want to use the default serializer, you should use moize.serialize:

`ts
moize.serialize(customSerializer)(fn);
`

moize.shallow

Pre-applies the isShallowEqual option.

`ts
import moize from 'moize';

const fn = (one: string, two: string) => ${one} ${two};

export default moize.shallow(fn);
`

moize.transformArgs

Pre-applies the transformArgs option.

`ts
import moize from 'moize';

const fn = ([one, two]: string[]) => [${one} ${two}];

export default moize.transformArgs(fn);
`

moize.updateCacheForKey

Pre-applies the updateCacheForKey option.

`ts
import moize from 'moize';

let lastUpdated = Date.now();

const fn = () => {
const now = Date.now();
const last = lastUpdated;

lastUpdate = now;

// its been more than 5 minutes since last update
return last + 300000 < now;
};

export default moize.updateCacheForKey(fn);
`

useMoize hook

If you are using React 16.8+ and are using hooks, you can easily create a custom useMoize hook for your project:

`ts
import { useRef } from 'react';

export function useMoize(fn, args, options) {
const moizedFnRef = useRef(moize(fn, options));

return moizedFnRef.current(...args);
}
`

Which can then be used as such:

`tsx
import React from 'react';

import { useMoize } from './moize-hooks';

function MyComponent({ first, second, object }) {
// standard usage
const sum = useMoize((a, b) => a + b, [first, second]);
// with options
const deepSum = useMoize((obj) => obj.a + obj.b, [object], {
isDeepEqual: true,
});

return (



);
}
`

Naturally you can tweak as needed for your project (default options, option-specific hooks, etc).

NOTE: This is very similar to useCallback built-in hook, with two main differences:

- There is a third parameter passed (the options passed to moize)
- The second argument array is the list of arguments passed to the memoized function

In both useCallback and useMemo, the array is a list of _dependencies_ which determine whether the funciton is called. These can be different than the arguments, although in general practice they are equivalent. The decision to use them directly was both for this common use-case reasons, but also because the implementation complexity would have increased substantially if not.

Composition

Starting with version 2.3.0, you can compose moize methods. This will create a new memoized method with the original function that shallowly merges the options of the two setups. Example:

`tsx
import moize from 'moize';

const Component = (props: Record) =>