A memoization library that only caches the result of the most recent arguments.
Also async version.
Unlike other memoization libraries, memoize-one
only
remembers the latest arguments and result. No need to worry about cache
busting mechanisms such as maxAge
, maxSize
,
exclusions
and so on, which can be prone to memory leaks.
memoize-one
simply remembers the last arguments, and if the
function is next called with the same arguments then it returns the
previous result.
// memoize-one uses the default import
import memoizeOne from 'memoize-one';
const add = (a, b) => a + b;
const memoizedAdd = memoizeOne(add);
memoizedAdd(1, 2); // 3
memoizedAdd(1, 2); // 3
// Add function is not executed: previous result is returned
memoizedAdd(2, 3); // 5
// Add function is called to get new value
memoizedAdd(2, 3); // 5
// Add function is not executed: previous result is returned
memoizedAdd(1, 2); // 3
// Add function is called to get new value.
// While this was previously cached,
// it is not the latest so the cached result is lost
# yarn
yarn add memoize-one
# npm
npm install memoize-one --save
By default, we apply our own fast and naive equality function to determine whether the arguments provided to your function are equal. You can see the full code here: are-inputs-equal.ts.
(By default) function arguments are considered equal if:
===
) with the
previous argument===
and they are both NaN
then the two
arguments are treated as equalWhat this looks like in practice:
import memoizeOne from 'memoize-one';
// add all numbers provided to the function
const add = (...args = []) =>
.reduce((current, value) => {
argsreturn current + value;
, 0);
}const memoizedAdd = memoizeOne(add);
- there is same amount of arguments
memoizedAdd(1, 2);
// the amount of arguments has changed, so underlying add function is called
memoizedAdd(1, 2, 3);
- new arguments have strict equality (
===
) with the previous argument
memoizedAdd(1, 2);
// each argument is `===` to the last argument, so cache is used
memoizedAdd(1, 2);
// second argument has changed, so add function is called again
memoizedAdd(1, 3);
// the first value is not `===` to the previous first value (1 !== 3)
// so add function is called again
memoizedAdd(3, 1);
- [special case] if the arguments are not
===
and they are bothNaN
then the argument is treated as equal
memoizedAdd(NaN);
// Even though NaN !== NaN these arguments are treated as equal
memoizedAdd(NaN);
You can also pass in a custom function for checking the equality of two sets of arguments
const memoized = memoizeOne(fn, isEqual);
The equality function needs to conform to this type
:
type EqualityFn = (newArgs: any[], lastArgs: any[]) => boolean;
// You can import this type from memoize-one if you like
// typescript
import { EqualityFn } from 'memoize-one';
// flow
import type { EqualityFn } from 'memoize-one';
An equality function should return true
if the arguments
are equal. If true
is returned then the wrapped function
will not be called.
A custom equality function needs to compare Arrays
. The
newArgs
array will be a new reference every time so a
simple newArgs === lastArgs
will always return
false
.
Equality functions are not called if the this
context of
the function has changed (see below).
Here is an example that uses a dequal deep equal equality check
dequal
correctly handles deep comparing two arrays
import memoizeOne from 'memoize-one';
import { dequal as isDeepEqual } from 'dequal';
const identity = (x) => x;
const shallowMemoized = memoizeOne(identity);
const deepMemoized = memoizeOne(identity, isDeepEqual);
const result1 = shallowMemoized({ foo: 'bar' });
const result2 = shallowMemoized({ foo: 'bar' });
=== result2; // false - different object reference
result1
const result3 = deepMemoized({ foo: 'bar' });
const result4 = deepMemoized({ foo: 'bar' });
=== result4; // true - arguments are deep equal result3
this
memoize-one
correctly respects this
controlThis library takes special care to maintain, and allow control over
the the this
context for both the original
function being memoized as well as the returned memoized function. Both
the original function and the memoized function’s this
context respect all
the this
controlling techniques:
new
)call
, apply
,
bind
);obj.foo()
);window
or undefined
in
strict mode
);this
)null
as this
to
explicit binding)this
is considered an argument changeChanges to the running context (this
) of a function can
result in the function returning a different value even though its
arguments have stayed the same:
function getA() {
return this.a;
}
const temp1 = {
a: 20,
;
}const temp2 = {
a: 30,
;
}
.call(temp1); // 20
getA.call(temp2); // 30 getA
Therefore, in order to prevent against unexpected results,
memoize-one
takes into account the current execution
context (this
) of the memoized function. If
this
is different to the previous invocation then it is
considered a change in argument. further
discussion.
Generally this will be of no impact if you are not explicity
controlling the this
context of functions you want to
memoize with explicit
binding or implicit
binding. memoize-One
will detect when you are
manipulating this
and will then consider the
this
context as an argument. If this
changes,
it will re-execute the original function even if the arguments have not
changed.
throw
sThere is no caching when your result function throws
If your result function throw
s then the memoized
function will also throw. The throw will not break the memoized
functions existing argument cache. It means the memoized function will
pretend like it was never called with arguments that made it
throw
.
const canThrow = (name: string) => {
console.log('called');
if (name === 'throw') {
throw new Error(name);
}return { name };
;
}
const memoized = memoizeOne(canThrow);
const value1 = memoized('Alex');
// console.log => 'called'
const value2 = memoized('Alex');
// result function not called
console.log(value1 === value2);
// console.log => true
try {
memoized('throw');
// console.log => 'called'
catch (e) {
} = e;
firstError
}
try {
memoized('throw');
// console.log => 'called'
// the result function was called again even though it was called twice
// with the 'throw' string
catch (e) {
} = e;
secondError
}
console.log(firstError !== secondError);
const value3 = memoized('Alex');
// result function not called as the original memoization cache has not been busted
console.log(value1 === value3);
// console.log => true
memoize-one
is super lightweight at minified and
gzipped. (
1KB
=
1,024 Bytes
)
memoize-one
performs better or on par with than other
popular memoization libraries for the purpose of remembering the latest
invocation.
Results
The comparisons are not exhaustive and are primarily to show that
memoize-one
accomplishes remembering the latest invocation
really fast. The benchmarks do not take into account the differences in
feature sets, library sizes, parse time, and so on.
Typescript
Typescript
and flow
type systems