Nonsense Parser Microframework

    memoize-one
    TypeScript icon, indicating that this package has built-in type declarations

    5.2.1 • Public • Published

    memoize-one

    A memoization library that only caches the result of the most recent arguments.

    Also async version.

    Build Status npm types dependencies minzip Downloads per month

    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

    // 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

    Installation

    # yarn
    yarn add memoize-one
    
    # npm
    npm install memoize-one --save

    Function argument equality

    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:

    1. there is same amount of arguments
    2. each new argument has strict equality (===) with the previous argument
    3. [special case] if two arguments are not === and they are both NaN then the two arguments are treated as equal

    What this looks like in practice:

    import memoizeOne from 'memoize-one';
    
    // add all numbers provided to the function
    const add = (...args = []) =>
      args.reduce((current, value) => {
        return current + value;
      }, 0);
    const memoizedAdd = memoizeOne(add);
    1. 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);
    1. 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);
    1. [special case] if the arguments are not === and they are both NaN then the argument is treated as equal
    memoizedAdd(NaN);
    // Even though NaN !== NaN these arguments are treated as equal
    memoizedAdd(NaN);

    Custom equality function

    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' });
    
    result1 === result2; // false - different object 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:

    • 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:

    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.

    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.

    When your result function throws

    There is no caching when your result function throws

    If your result function throws 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) {
      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 🚀

    Tiny

    memoize-one is super lightweight at min minified and minzip 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

    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 👍

    • Tested with all built in JavaScript types.
    • 100% code coverage
    • Continuous integration to run tests and type checks.
    • Written in Typescript
    • Correct typing for Typescript and flow type systems
    • No dependencies

    Install

    npm i memoize-one

    DownloadsWeekly Downloads

    3,410,525

    Version

    5.2.1

    License

    MIT

    Unpacked Size

    21.8 kB

    Total Files

    13

    Last publish

    Collaborators

    • avatar