Wondering what’s next for npm?Check out our public roadmap! »

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

    2.1.3 • Public • Published

    proxyequal

    CircleCI status Greenkeeper badge

    Shallow equal is a good thing, but it compares thing you don't need.

    Proxy equal - "MobX"-like solution, which will "magically" compare only used keys.

    NPM

    Usage

    • Wrap an object with proxyState

    • Run some computations using providing proxyObject. proxyState returns object with shape

      • state - a double of provided state, with tracking enabled
      • affected - list of used keys in a state.
      • seal - disables tracking
      • unseal - enabled tracking
      • replaceState(newState) - replaces top level state, maintaining rest of data.
      • reset - resets tracked keys
    • proxy will collect all referenced or used keys

    • proxyEqual will compare all used "endpoint" keys of 2 objects

    • proxyShallow will compare all used NON "endpoint" keys of 2 objects.

    The difference between proxyEqual and proxyShallow is in expectations.

    • proxyShallow is similar to shallowEqual, it compares the top level objects. Might be they are still the same.
    • proxyEqual working on variable-value level, performing (very) deep comparison of objects.

    Extra API

    • spreadGuardsEnabled(boolean=[true]) - controls spread guards, or all-keys-enumeration, which makes proxyEqual ineffective.
    • sourceMutationsEnabled(boolean=[false]) - controls set behavior. By default proxied state is frozen.

    When to use proxyequal

    When you have a big state, for example redux state, but some function (redux selector, or mapStateToProps) uses just a small subset.

    Here proxyequal can shine, detecting the only used branches, and comparing only the used keys.

    Example

    import {proxyState, proxyEqual, proxyShallow} from 'proxyequal';
     
    // wrap the original state
    const trapped = proxyState(state);
     
    // use provided one in computations
    mapStateToProps(trapped.state);
     
    // first shallow compare
    proxyShallow(state, newState, trapped.affected);
     
    // next - deep compare
    proxyEqual(state, newState, trapped.affected);

    Don't forget to disable

    const trapped = proxyState(state);
    // do something
    workWith(trapped.state);
     
    trapped.seal();
     
    // now tracking is disabled
     
    trapped.unseal();
    // and enabled

    Speed

    Uses ES6 Proxy underneath to detect used branches(as MobX), and search-trie to filter out keys for shallow or equal compare.

    So - it is lighting fast.

    Limitations

    Unfortunately, due to Proxy wrappers all objects will be unique each run.

     shallowEqual(proxyState(A), proxyState(A)) === false

    There is a undocumented way to solve it, used internally in memoize-state library. Once it will be proven to work stable - we will expose it.

    Compatibility

    Requires Proxy support, so the proxy-polyfill is included in the common bundle for Internet Explorer 11. How this works may change in future, see issue #15 "ProxyPolyfill is unconditionally imported" for details.

    Licence

    MIT

    Install

    npm i proxyequal

    DownloadsWeekly Downloads

    1,568

    Version

    2.1.3

    License

    MIT

    Unpacked Size

    72.6 kB

    Total Files

    32

    Last publish

    Collaborators

    • avatar