1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
|
# memoize-one
A memoization library that only caches the result of the most recent arguments.
[](https://travis-ci.org/alexreardon/memoize-one)
[](https://www.npmjs.com/package/memoize-one)
[](https://david-dm.org/alexreardon/memoize-one)
[](https://www.npmjs.com/package/memoize-one)
[](https://www.npmjs.com/package/memoize-one)
[](https://www.npmjs.com/package/memoize-one)
## Rationale
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.
## Usage
### Standard usage
```js
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
```
## Installation
```bash
# yarn
yarn add memoize-one
# npm
npm install memoize-one --save
```
## Module usage
### ES6 module
```js
import memoizeOne from 'memoize-one';
```
### CommonJS
If you are in a CommonJS environment (eg [Node](https://nodejs.org)), then **you will need to add `.default` to your import**:
```js
const memoizeOne = require('memoize-one').default;
```
## Custom equality function
You can also pass in a custom function for checking the equality of two sets of arguments
```js
const memoized = memoizeOne(fn, isEqual);
type EqualityFn = (newArgs: mixed[], oldArgs: mixed[]) => boolean;
```
An equality function should return `true` if the arguments are equal. If `true` is returned then the wrapped function will not be called.
The default equality function is a shallow equal check of all arguments (each argument is compared with `===`). If the `length` of arguments change, then the default equality function makes no shallow equality checks. You are welcome to decide if you want to return `false` if the `length` of the arguments is not equal
```js
const simpleIsEqual: EqualityFn = (
newArgs: mixed[],
lastArgs: mixed[],
): boolean =>
newArgs.length === lastArgs.length &&
newArgs.every((newArg: mixed, index: number): boolean =>
shallowEqual(newArg, lastArgs[index]),
);
```
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 `lodash.isequal` deep equal equality check
> `lodash.isequal` correctly handles deep comparing two arrays
```js
import memoizeOne from 'memoize-one';
import isDeepEqual from 'lodash.isequal';
const identity = x => x;
const shallowMemoized = memoizeOne(identity);
const deepMemoized = memoizeOne(identity, isDeepEqual);
const result1 = shallowMemoized({ foo: 'bar' });
const result2 = shallowMemoized({ foo: 'bar' });
result1 === result2; // false - difference reference
const result3 = deepMemoized({ foo: 'bar' });
const result4 = deepMemoized({ foo: 'bar' });
result3 === result4; // true - arguments are deep equal
```
## `this`
### `memoize-one` correctly respects `this` control
This 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](https://github.com/getify/You-Dont-Know-JS/blob/master/this%20%26%20object%20prototypes/ch2.md):
- new bindings (`new`)
- explicit binding (`call`, `apply`, `bind`);
- implicit binding (call site: `obj.foo()`);
- default binding (`window` or `undefined` in `strict mode`);
- fat arrow binding (binding to lexical `this`)
- ignored this (pass `null` as `this` to explicit binding)
### Changes to `this` is considered an argument change
Changes 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:
```js
function getA() {
return this.a;
}
const temp1 = {
a: 20,
};
const temp2 = {
a: 30,
};
getA.call(temp1); // 20
getA.call(temp2); // 30
```
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](https://github.com/alexreardon/memoize-one/issues/3).
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](https://github.com/getify/You-Dont-Know-JS/blob/master/this%20%26%20object%20prototypes/ch2.md#explicit-binding) or [implicit binding](https://github.com/getify/You-Dont-Know-JS/blob/master/this%20%26%20object%20prototypes/ch2.md#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.
## When your result function `throw`s
> There 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`.
```js
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) {
firstError = e;
}
try {
memoized('throw');
// console.log => 'called'
// the result function was called again even though it was called twice
// with the 'throw' string
} catch (e) {
secondError = e;
}
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
```
## Performance :rocket:
### Tiny
`memoize-one` is super lightweight at [](https://www.npmjs.com/package/memoize-one) minified and [](https://www.npmjs.com/package/memoize-one) gzipped. (`1KB` = `1,024 Bytes`)
### Extremely fast
`memoize-one` performs better or on par with than other popular memoization libraries for the purpose of remembering the latest invocation.
**Results**
- [simple arguments](https://www.measurethat.net/Benchmarks/ShowResult/4452)
- [complex arguments](https://www.measurethat.net/Benchmarks/ShowResult/4488)
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.
## Code health :thumbsup:
- Tested with all built in [JavaScript types](https://github.com/getify/You-Dont-Know-JS/blob/master/types%20%26%20grammar/ch1.md).
- 100% code coverage
- [Continuous integration](https://travis-ci.org/alexreardon/memoize-one) to run tests and type checks.
- [`Flow` types](http://flowtype.org) for safer internal execution and external consumption. Also allows for editor autocompletion.
- Follows [Semantic versioning (2.0)](http://semver.org/) for safer consumption.
- No dependencies
|
