Skip to content

ellentorg/perferendis-aspernatur-eligendi

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

326 Commits

.github

.github

 
 

core

core

 
 

lib

lib

 
 

template

template

 
 

.gitignore

.gitignore

 
 

.npmignore

.npmignore

 
 

LICENSE

LICENSE

 
 

README.md

README.md

 
 

index.js

index.js

 
 

package-lock.json

package-lock.json

 
 

package.json

package.json

 
 

yarn.lock

yarn.lock

 
 

Repository files navigation

@ellentorg/perferendis-aspernatur-eligendi

@ellentorg/perferendis-aspernatur-eligendi 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.

$ npm i @ellentorg/perferendis-aspernatur-eligendi --save

Importing

ESM in browsers

import @ellentorg/perferendis-aspernatur-eligendi from '@ellentorg/perferendis-aspernatur-eligendi';

ESM in NodeJS

import @ellentorg/perferendis-aspernatur-eligendi from '@ellentorg/perferendis-aspernatur-eligendi/mjs/index.mjs';

CommonJS

const @ellentorg/perferendis-aspernatur-eligendi = require('@ellentorg/perferendis-aspernatur-eligendi');

Usage

import @ellentorg/perferendis-aspernatur-eligendi from '@ellentorg/perferendis-aspernatur-eligendi';

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

const me@ellentorg/perferendis-aspernatur-eligendid = @ellentorg/perferendis-aspernatur-eligendi(method);

me@ellentorg/perferendis-aspernatur-eligendid(2, 4); // 6
me@ellentorg/perferendis-aspernatur-eligendid(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 me@ellentorg/perferendis-aspernatur-eligendi for unique use-cases.

Configuration options

@ellentorg/perferendis-aspernatur-eligendi optionally accepts an object of options as either the second parameter or as the first step in a curried function:

// inline
@ellentorg/perferendis-aspernatur-eligendi(fn, options);

// curried
@ellentorg/perferendis-aspernatur-eligendi(options)(fn);

The full shape of these options:

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: @ellentorg/perferendis-aspernatur-eligendi.Cache,
        options: @ellentorg/perferendis-aspernatur-eligendi.Options,
        @ellentorg/perferendis-aspernatur-eligendid: (...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: @ellentorg/perferendis-aspernatur-eligendi.Cache,
        options: @ellentorg/perferendis-aspernatur-eligendi.Options,
        @ellentorg/perferendis-aspernatur-eligendid: (...args: any[]) => any
    ) => void;
    // method fired when an existing entry in cache is used
    onCacheHit: (
        cache: @ellentorg/perferendis-aspernatur-eligendi.Cache,
        options: @ellentorg/perferendis-aspernatur-eligendi.Options,
        @ellentorg/perferendis-aspernatur-eligendid: (...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 me@ellentorg/perferendis-aspernatur-eligendid 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.

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

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

const me@ellentorg/perferendis-aspernatur-eligendid = @ellentorg/perferendis-aspernatur-eligendi(fn, { isDeepEqual: true });

me@ellentorg/perferendis-aspernatur-eligendid({ one: { nested: 'one' }, two: 'two' });
me@ellentorg/perferendis-aspernatur-eligendid({ one: { nested: 'one' }, two: 'two' }); // pulls from cache

This is also available via the shortcut method of @ellentorg/perferendis-aspernatur-eligendi.deep

const me@ellentorg/perferendis-aspernatur-eligendid = @ellentorg/perferendis-aspernatur-eligendi.deep(fn);

isPromise

defaults to false

Is the computed value in the function a Promise.

const fn = async (item: Promise<string>) => await item;

const me@ellentorg/perferendis-aspernatur-eligendid = @ellentorg/perferendis-aspernatur-eligendi(fn, { isPromise: true });

This is also available via the shortcut method of @ellentorg/perferendis-aspernatur-eligendi.promise.

const me@ellentorg/perferendis-aspernatur-eligendid = -@ellentorg/perferendis-aspernatur-eligendi.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.

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

const Component = ({ one, two }: Props) => (
    <div>
        {one}: {two}
    </div>
);

const Me@ellentorg/perferendis-aspernatur-eligendidFoo = @ellentorg/perferendis-aspernatur-eligendi(Component, { isReact: true });

This is also available via the shortcut method of @ellentorg/perferendis-aspernatur-eligendi.react.

const Me@ellentorg/perferendis-aspernatur-eligendidFoo = @ellentorg/perferendis-aspernatur-eligendi.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 me@ellentorg/perferendis-aspernatur-eligendi on each instance of the component passed, which is equivalent to PureComponent or React.memo. If you want to me@ellentorg/perferendis-aspernatur-eligendi on all instances (which is how this option worked prior to version 6), use the following options:

const me@ellentorg/perferendis-aspernatur-eligendid = @ellentorg/perferendis-aspernatur-eligendi(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.

const fn = (mutableObject: { one: Record<string, any> }) =>
    mutableObject.property;

const me@ellentorg/perferendis-aspernatur-eligendid = @ellentorg/perferendis-aspernatur-eligendi(fn, { isSerialized: true });

This is also available via the shortcut method of @ellentorg/perferendis-aspernatur-eligendi.serialize.

const me@ellentorg/perferendis-aspernatur-eligendid = @ellentorg/perferendis-aspernatur-eligendi.serialize(fn);

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

  1. limit by maxArgs (if applicable)
  2. transform by transformArgs (if applicable)
  3. 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.

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

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

const me@ellentorg/perferendis-aspernatur-eligendid = @ellentorg/perferendis-aspernatur-eligendi(fn, { isShallowEqual: true });

me@ellentorg/perferendis-aspernatur-eligendid({ one: 'one', two: 'two' });
me@ellentorg/perferendis-aspernatur-eligendid({ one: 'one', two: 'two' }); // pulls from cache

This is also available via the shortcut method of @ellentorg/perferendis-aspernatur-eligendi.shallow

const me@ellentorg/perferendis-aspernatur-eligendid = @ellentorg/perferendis-aspernatur-eligendi.shallow(fn);

matchesArg

defaults to SameValueZero equality

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

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 me@ellentorg/perferendis-aspernatur-eligendid = @ellentorg/perferendis-aspernatur-eligendi(fn, { matchesArg: hasOneProperty });

me@ellentorg/perferendis-aspernatur-eligendid({ one: 'two' };
me@ellentorg/perferendis-aspernatur-eligendid({ two: 'three' }); // pulls from cache

This is also available via the shortcut method of @ellentorg/perferendis-aspernatur-eligendi.matchesArg

const me@ellentorg/perferendis-aspernatur-eligendid = @ellentorg/perferendis-aspernatur-eligendi.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.

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 me@ellentorg/perferendis-aspernatur-eligendid = @ellentorg/perferendis-aspernatur-eligendi(fn, { matchesKey: isFooEqualAndHasBar });

me@ellentorg/perferendis-aspernatur-eligendid({ one: 'two' }, { two: null });
me@ellentorg/perferendis-aspernatur-eligendid({ one: 'two' }, { two: 'three' }); // pulls from cache

This is also available via the shortcut method of @ellentorg/perferendis-aspernatur-eligendi.matchesKey

const me@ellentorg/perferendis-aspernatur-eligendid = @ellentorg/perferendis-aspernatur-eligendi.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.

const fn = (item: Record<string, any>) => item;

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

const me@ellentorg/perferendis-aspernatur-eligendid = @ellentorg/perferendis-aspernatur-eligendi(fn, { maxAge: MAX_AGE });

This is also available via the shortcut method of @ellentorg/perferendis-aspernatur-eligendi.maxAge.

const me@ellentorg/perferendis-aspernatur-eligendid = @ellentorg/perferendis-aspernatur-eligendi.maxAge(MAX_AGE)(fn);

TIP: A common usage of this is in tandem 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.

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

const me@ellentorg/perferendis-aspernatur-eligendid = @ellentorg/perferendis-aspernatur-eligendi(fn, { maxArgs: 2 });

me@ellentorg/perferendis-aspernatur-eligendi('one', 'two', 'three');
me@ellentorg/perferendis-aspernatur-eligendi('one', 'two', 'four'); // pulls from cache, as the first two args are the same

This is also available via the shortcut method of @ellentorg/perferendis-aspernatur-eligendi.maxArgs.

const me@ellentorg/perferendis-aspernatur-eligendid = @ellentorg/perferendis-aspernatur-eligendi.maxArgs(2)(fn);

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

  1. limit by maxArgs
  2. transform by transformArgs (if applicable)
  3. 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.

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

const me@ellentorg/perferendis-aspernatur-eligendid = @ellentorg/perferendis-aspernatur-eligendi(fn, { maxSize: 5 });

This is also available via the shortcut method of @ellentorg/perferendis-aspernatur-eligendi.maxSize.

const me@ellentorg/perferendis-aspernatur-eligendid = @ellentorg/perferendis-aspernatur-eligendi.maxSize(5)(fn);

onCacheAdd

Method to fire when an item has been added to cache. Receives the cache, options, and me@ellentorg/perferendis-aspernatur-eligendid function as a parameters.

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

const logCacheKeys = (
    cache: Cache,
    options: Options,
    @ellentorg/perferendis-aspernatur-eligendid: Moized<typeof fn>
) => console.log(cache.keys);

const @ellentorg/perferendis-aspernatur-eligendid = @ellentorg/perferendis-aspernatur-eligendi(fn, { maxSize: 2, onCacheAdd: logCacheKeys });

@ellentorg/perferendis-aspernatur-eligendid('one', 'two'); // [["one","two"]]
@ellentorg/perferendis-aspernatur-eligendid('one', 'two');
@ellentorg/perferendis-aspernatur-eligendid('two', 'one'); // [["two","one"], ["one","two"]]
@ellentorg/perferendis-aspernatur-eligendid('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 me@ellentorg/perferendis-aspernatur-eligendid function as a parameters.

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

const logCacheKeys = (
    cache: Cache,
    options: Options,
    @ellentorg/perferendis-aspernatur-eligendid: Moized<typeof fn>
) => console.log(cache.keys);

const @ellentorg/perferendis-aspernatur-eligendid = @ellentorg/perferendis-aspernatur-eligendi(fn, { maxSize: 2, onCacheChange: logCacheKeys });

@ellentorg/perferendis-aspernatur-eligendid('one', 'two'); // [["one","two"]]
@ellentorg/perferendis-aspernatur-eligendid('one', 'two');
@ellentorg/perferendis-aspernatur-eligendid('two', 'one'); // [["two","one"], ["one","two"]]
@ellentorg/perferendis-aspernatur-eligendid('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 me@ellentorg/perferendis-aspernatur-eligendid function as a parameters.

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

const logCacheKeys = (
    cache: Cache,
    options: Options,
    @ellentorg/perferendis-aspernatur-eligendid: Moized<typeof fn>
) => console.log(cache.keys);

const @ellentorg/perferendis-aspernatur-eligendid = @ellentorg/perferendis-aspernatur-eligendi(fn, { maxSize: 2, onCacheHit: logCacheKeys });

@ellentorg/perferendis-aspernatur-eligendid('one', 'two');
@ellentorg/perferendis-aspernatur-eligendid('one', 'two'); // [["one","two"]]
@ellentorg/perferendis-aspernatur-eligendid('two', 'one');
@ellentorg/perferendis-aspernatur-eligendid('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.

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

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

const me@ellentorg/perferendis-aspernatur-eligendid = @ellentorg/perferendis-aspernatur-eligendi(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:

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

let expirationAttempts = 0;

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

    return expirationAttempts < 2;
};

const me@ellentorg/perferendis-aspernatur-eligendid = @ellentorg/perferendis-aspernatur-eligendi(fn, {
    maxAge: 10000,
    onExpire: limitExpirationAttempts,
});

me@ellentorg/perferendis-aspernatur-eligendid('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 when it exists, or Anonymous {count} otherwise

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

@ellentorg/perferendis-aspernatur-eligendi.collectStats();

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

const me@ellentorg/perferendis-aspernatur-eligendid = @ellentorg/perferendis-aspernatur-eligendi(fn, { profileName: 'my fancy identity' });

This is also available via the shortcut method of @ellentorg/perferendis-aspernatur-eligendi.profile.

const me@ellentorg/perferendis-aspernatur-eligendid = @ellentorg/perferendis-aspernatur-eligendi.profile('profile-name')(fn);

NOTE: You must be collecting statistics for this option to provide value, as it is the identifier used for statistics collection.

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.

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

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

const me@ellentorg/perferendis-aspernatur-eligendid = @ellentorg/perferendis-aspernatur-eligendi(fn, {
    isSerialized: true,
    serializer,
});

This is also available via the shortcut method of @ellentorg/perferendis-aspernatur-eligendi.serializeWith.

const me@ellentorg/perferendis-aspernatur-eligendid = @ellentorg/perferendis-aspernatur-eligendi.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.

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

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

const @ellentorg/perferendis-aspernatur-eligendid = @ellentorg/perferendis-aspernatur-eligendi(fn, { transformArgs: ignoreFirstArg });

@ellentorg/perferendis-aspernatur-eligendi('one', 'two', 'three');
@ellentorg/perferendis-aspernatur-eligendi(null, 'two', 'three'); // pulled from cache

This is also available via the shortcut method of @ellentorg/perferendis-aspernatur-eligendi.transformArgs.

const me@ellentorg/perferendis-aspernatur-eligendid = @ellentorg/perferendis-aspernatur-eligendi.transformArgs(argTransformer)(fn);

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

  1. limit by maxArgs (if applicable)
  2. transform by transformArgs
  3. 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.

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

let lastUpdate = Date.now();

const me@ellentorg/perferendis-aspernatur-eligendid = @ellentorg/perferendis-aspernatur-eligendi(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;
    },
});

me@ellentorg/perferendis-aspernatur-eligendid('one');
me@ellentorg/perferendis-aspernatur-eligendid('one'); // pulled from cache

// 5 minutes later

me@ellentorg/perferendis-aspernatur-eligendid('one'); // re-calls method and updates cache

This is also available via the shortcut method of @ellentorg/perferendis-aspernatur-eligendi.updateCacheForKey.

const me@ellentorg/perferendis-aspernatur-eligendid = @ellentorg/perferendis-aspernatur-eligendi.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.

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

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

const me@ellentorg/perferendis-aspernatur-eligendid = @ellentorg/perferendis-aspernatur-eligendi(fn, { maxAge: MAX_AGE, updateExpire: true });

me@ellentorg/perferendis-aspernatur-eligendid('one');

setTimeout(() => {
    /**
     * hits cache, which updates the expire to be 5 minutes
     * from this run instead of the first
     */
    me@ellentorg/perferendis-aspernatur-eligendid('one');
}, 1000 * 60);

Usage with shortcut methods

@ellentorg/perferendis-aspernatur-eligendi.deep

Pre-applies the isDeepEqual option.

import @ellentorg/perferendis-aspernatur-eligendi from '@ellentorg/perferendis-aspernatur-eligendi';

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

export default @ellentorg/perferendis-aspernatur-eligendi.deep(fn);

@ellentorg/perferendis-aspernatur-eligendi.infinite

Pre-applies the maxSize option with Infinity.

import @ellentorg/perferendis-aspernatur-eligendi from '@ellentorg/perferendis-aspernatur-eligendi';

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

export default @ellentorg/perferendis-aspernatur-eligendi.infinite(fn);

NOTE: This mimics default behavior of @ellentorg/perferendis-aspernatur-eligendi prior to version 6.

@ellentorg/perferendis-aspernatur-eligendi.matchesArg

Pre-applies the matchesArg option as a curriable method.

import @ellentorg/perferendis-aspernatur-eligendi from '@ellentorg/perferendis-aspernatur-eligendi';

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

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

export default @ellentorg/perferendis-aspernatur-eligendi.matchesArg(isEqualOrFoo)(fn);

@ellentorg/perferendis-aspernatur-eligendi.matchesKey

Pre-applies the matchesKey option as a curriable method.

import @ellentorg/perferendis-aspernatur-eligendi from '@ellentorg/perferendis-aspernatur-eligendi';

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

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

export default @ellentorg/perferendis-aspernatur-eligendi.matchesKey(isEqualOrHasFoo)(fn);

@ellentorg/perferendis-aspernatur-eligendi.maxAge

Pre-applies the maxAge option as a curriable method.

import @ellentorg/perferendis-aspernatur-eligendi from '@ellentorg/perferendis-aspernatur-eligendi';

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

export default @ellentorg/perferendis-aspernatur-eligendi.maxAge(5000)(fn);

@ellentorg/perferendis-aspernatur-eligendi.maxArgs

Pre-applies the maxArgs option as a curriable method.

import @ellentorg/perferendis-aspernatur-eligendi from '@ellentorg/perferendis-aspernatur-eligendi';

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

export default @ellentorg/perferendis-aspernatur-eligendi.maxArgs(1)(fn);

@ellentorg/perferendis-aspernatur-eligendi.maxSize

Pre-applies the maxSize option as a curriable method.

import @ellentorg/perferendis-aspernatur-eligendi from '@ellentorg/perferendis-aspernatur-eligendi';

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

export default @ellentorg/perferendis-aspernatur-eligendi.maxSize(5)(fn);

@ellentorg/perferendis-aspernatur-eligendi.profile

Pre-applies the profileName option as a curriable method.

import @ellentorg/perferendis-aspernatur-eligendi from '@ellentorg/perferendis-aspernatur-eligendi';

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

export default @ellentorg/perferendis-aspernatur-eligendi.profile('my fancy identity')(fn);

NOTE: You must be collecting statistics for this option to provide value, as it is the identifier used for statistics collection.

@ellentorg/perferendis-aspernatur-eligendi.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.

import @ellentorg/perferendis-aspernatur-eligendi from '@ellentorg/perferendis-aspernatur-eligendi';

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

export default @ellentorg/perferendis-aspernatur-eligendi.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.

@ellentorg/perferendis-aspernatur-eligendi.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.

import @ellentorg/perferendis-aspernatur-eligendi from '@ellentorg/perferendis-aspernatur-eligendi';

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

const Component = ({ one, two }: Props) => (
    <div>
        {one} {two}
    </div>
);

export default @ellentorg/perferendis-aspernatur-eligendi.react(Component);

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

@ellentorg/perferendis-aspernatur-eligendi.serialize

Pre-applies the isSerialized option.

import @ellentorg/perferendis-aspernatur-eligendi from '@ellentorg/perferendis-aspernatur-eligendi';

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

export default @ellentorg/perferendis-aspernatur-eligendi.serialize(fn);

NOTE: If you want to provide a custom serializer, you should use @ellentorg/perferendis-aspernatur-eligendi.serializeWith:

@ellentorg/perferendis-aspernatur-eligendi.serializeWith(customSerializer)(fn);

@ellentorg/perferendis-aspernatur-eligendi.serializeWith

Pre-applies the isSerialized and serializer options.

import @ellentorg/perferendis-aspernatur-eligendi from '@ellentorg/perferendis-aspernatur-eligendi';

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

export default @ellentorg/perferendis-aspernatur-eligendi.serializeWith(JSON.stringify)(fn);

NOTE: If you want to use the default serializer, you should use @ellentorg/perferendis-aspernatur-eligendi.serialize:

@ellentorg/perferendis-aspernatur-eligendi.serialize(customSerializer)(fn);

@ellentorg/perferendis-aspernatur-eligendi.shallow

Pre-applies the isShallowEqual option.

import @ellentorg/perferendis-aspernatur-eligendi from '@ellentorg/perferendis-aspernatur-eligendi';

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

export default @ellentorg/perferendis-aspernatur-eligendi.shallow(fn);

@ellentorg/perferendis-aspernatur-eligendi.transformArgs

Pre-applies the transformArgs option.

import @ellentorg/perferendis-aspernatur-eligendi from '@ellentorg/perferendis-aspernatur-eligendi';

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

export default @ellentorg/perferendis-aspernatur-eligendi.transformArgs(fn);

@ellentorg/perferendis-aspernatur-eligendi.updateCacheForKey

Pre-applies the updateCacheForKey option.

import @ellentorg/perferendis-aspernatur-eligendi from '@ellentorg/perferendis-aspernatur-eligendi';

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 @ellentorg/perferendis-aspernatur-eligendi.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:

import { useRef } from 'react';

export function useMoize(fn, args, options) {
    const @ellentorg/perferendis-aspernatur-eligendidFnRef = useRef(@ellentorg/perferendis-aspernatur-eligendi(fn, options));

    return @ellentorg/perferendis-aspernatur-eligendidFnRef.current(...args);
}

Which can then be used as such:

import React from 'react';

import { useMoize } from './@ellentorg/perferendis-aspernatur-eligendi-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 (
        <div>
            Sum of {first} and {second} is {sum}. Sum of {object.a} and{' '}
            {object.b} is {deepSum}.
        </div>
    );
}

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 @ellentorg/perferendis-aspernatur-eligendi)
  • The second argument array is the list of arguments passed to the me@ellentorg/perferendis-aspernatur-eligendid 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 @ellentorg/perferendis-aspernatur-eligendi methods. This will create a new me@ellentorg/perferendis-aspernatur-eligendid method with the original function that shallowly merges the options of the two setups. Example:

import @ellentorg/perferendis-aspernatur-eligendi from '@ellentorg/perferendis-aspernatur-eligendi';

const Component = (props: Record<string, any>) => <div {...props} />;

// memoizing with react, as since 2.0.0
const Me@ellentorg/perferendis-aspernatur-eligendidFoo = @ellentorg/perferendis-aspernatur-eligendi.react(Component);

// creating a separately-me@ellentorg/perferendis-aspernatur-eligendid method that has maxSize of 5
const LastFiveFoo = @ellentorg/perferendis-aspernatur-eligendi.maxSize(5)(Me@ellentorg/perferendis-aspernatur-eligendidFoo);

You can also create an options-first curriable version of @ellentorg/perferendis-aspernatur-eligendi if you only pass the options:

import @ellentorg/perferendis-aspernatur-eligendi from '@ellentorg/perferendis-aspernatur-eligendi';

// creates a function that will me@ellentorg/perferendis-aspernatur-eligendi what is passed
const limitedSerializedMoize = @ellentorg/perferendis-aspernatur-eligendi({ maxSize: 5, serialize: true });

const getWord = (bird) => `${bird} is the word`;

const @ellentorg/perferendis-aspernatur-eligendidGetWord = limitedSerializedMoize(getWord);

You can also combine all of these options with @ellentorg/perferendis-aspernatur-eligendi.compose to create @ellentorg/perferendis-aspernatur-eligendi wrappers with pre-defined options.

import @ellentorg/perferendis-aspernatur-eligendi from '@ellentorg/perferendis-aspernatur-eligendi';

// creates a @ellentorg/perferendis-aspernatur-eligendir that will have the options of
// {isReact: true, maxAge: 5000, maxSize: 5}
const superLimitedReactMoize = @ellentorg/perferendis-aspernatur-eligendi.compose(
    @ellentorg/perferendis-aspernatur-eligendi.react,
    @ellentorg/perferendis-aspernatur-eligendi.maxSize(5),
    @ellentorg/perferendis-aspernatur-eligendi.maxAge(5000)
);

Collecting statistics

As-of version 5, you can collect statistics of @ellentorg/perferendis-aspernatur-eligendi to determine if your cached methods are effective.

import @ellentorg/perferendis-aspernatur-eligendi from '@ellentorg/perferendis-aspernatur-eligendi';

@ellentorg/perferendis-aspernatur-eligendi.collectStats();

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

const @ellentorg/perferendis-aspernatur-eligendid = @ellentorg/perferendis-aspernatur-eligendi(fn);

@ellentorg/perferendis-aspernatur-eligendid('one', 'two');
@ellentorg/perferendis-aspernatur-eligendid('one', 'two');

@ellentorg/perferendis-aspernatur-eligendid.getStats(); // {"calls": 2, "hits": 1, "usage": "50%"}

NOTE: It is recommended not to activate this in production, as it will have a performance decrease.

Stats methods

clearStats

Cear statistics on @ellentorg/perferendis-aspernatur-eligendid functions.

@ellentorg/perferendis-aspernatur-eligendi.clearStats(); // clears all stats
@ellentorg/perferendis-aspernatur-eligendi.clearStats('profile-name'); // clears stats only for 'profile-name'

collectStats

Set whether collecting statistics on @ellentorg/perferendis-aspernatur-eligendid functions.

@ellentorg/perferendis-aspernatur-eligendi.collectStats(true); // start collecting stats
@ellentorg/perferendis-aspernatur-eligendi.collectStats(); // same as passing true
@ellentorg/perferendis-aspernatur-eligendi.collectStats(false); // stop collecting stats

NOTE: If collecting statistics, it is recommended to provide a custom profileName or use @ellentorg/perferendis-aspernatur-eligendi.profile() for all me@ellentorg/perferendis-aspernatur-eligendid functions. This allows easier mapping of resulting statistics to their origin function when it has a common name or is anonymous.

getStats([profileName])

Get the statistics for a specific function, or globally.

@ellentorg/perferendis-aspernatur-eligendi.collectStats();

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

const @ellentorg/perferendis-aspernatur-eligendid = @ellentorg/perferendis-aspernatur-eligendi(fn);

const otherFn = (one: string[]) => one.slice(0, 1);

const otherMoized = @ellentorg/perferendis-aspernatur-eligendi(otherFn, { profileName: 'otherMoized' });

@ellentorg/perferendis-aspernatur-eligendid('one', 'two');
@ellentorg/perferendis-aspernatur-eligendid('one', 'two');

@ellentorg/perferendis-aspernatur-eligendid.getStats(); // {"calls": 2, "hits": 1, "usage": "50%"}

otherMoized(['three']);

@ellentorg/perferendis-aspernatur-eligendi.getStats('otherMoized'); // {"calls": 1, "hits": 0, "usage": "0%"}

@ellentorg/perferendis-aspernatur-eligendi.getStats();
/*
 {
   "calls": 3,
   "hits": 1,
   "profiles": {
     "fn at Object..src/utils.js (http://localhost:3000/app.js:153:68)": {
       "calls": 2,
       "hits": 1,
       "usage": "50%"
     },
     "otherMoized": {
       "calls": 1,
       "hits": 0,
       "usage": "0%"
     }
   },
   "usage": "33.3333%"
 }
 */

Introspection

isCollectingStats

Are statistics being collected on memoization usage.

@ellentorg/perferendis-aspernatur-eligendi.collectStats(true);
@ellentorg/perferendis-aspernatur-eligendi.isCollectingStats(); // true
@ellentorg/perferendis-aspernatur-eligendi.collectStats(false);
@ellentorg/perferendis-aspernatur-eligendi.isCollectingStats(); // false

isMoized

Is the function passed a @ellentorg/perferendis-aspernatur-eligendid function.

const fn = () => {};
const @ellentorg/perferendis-aspernatur-eligendidFn = @ellentorg/perferendis-aspernatur-eligendi(fn);

@ellentorg/perferendis-aspernatur-eligendi.isMoized(fn); // false
@ellentorg/perferendis-aspernatur-eligendi.isMoized(@ellentorg/perferendis-aspernatur-eligendidFn); // true

Direct cache manipulation

The cache is available on the @ellentorg/perferendis-aspernatur-eligendid function as a property, and while it is not recommended to modify it directly, that option is available for edge cases.

cache

The shape of the cache is as follows:

type Cache = {
    keys: any[][];
    size: number;
    values: any[];
};

Regardless of how the key is transformed, it is always stored as an array (if the value returned is not an array, it is coalesced to one).

NOTE: The order of keys and values should always align, so be aware when manually manipulating the cache that you need to manually keep in sync any changes to those arrays.

cacheSnapshot

The cache is mutated internally for performance reasons, so logging out the cache at a specific step in the workflow may not give you the information you need. As such, to help with debugging you can request the cacheSnapshot, which has the same shape as the cache but is a shallow clone of each property for persistence.

There are also convenience methods provided on the @ellentorg/perferendis-aspernatur-eligendid function which allow for programmatic manipulation of the cache.

add(key, value)

This will manually add the value at key in cache if key does not already exist. key should be an Array of values, meant to reflect the arguments passed to the method.

// single parameter is straightforward
const me@ellentorg/perferendis-aspernatur-eligendid = @ellentorg/perferendis-aspernatur-eligendi((item: string) => item: string);

me@ellentorg/perferendis-aspernatur-eligendid.add(['one'], 'two');

// pulls from cache
me@ellentorg/perferendis-aspernatur-eligendid('one');

NOTE: This will only add keys that do not exist in the cache, and will do nothing if the key already exists. If you want to update keys that already exist, use update.

clear()

This will clear all values in the cache, resetting it to an empty state.

const me@ellentorg/perferendis-aspernatur-eligendid = @ellentorg/perferendis-aspernatur-eligendi((item: string) => item);

me@ellentorg/perferendis-aspernatur-eligendid.clear();

get(key)

Returns the value in cache if the key matches, else returns undefined. key should be an Array of values, meant to reflect the arguments passed to the method.

const me@ellentorg/perferendis-aspernatur-eligendid = @ellentorg/perferendis-aspernatur-eligendi((one: string, two: string) => [one, two);

me@ellentorg/perferendis-aspernatur-eligendid('one', 'two');

console.log(me@ellentorg/perferendis-aspernatur-eligendid.get(['one', 'two'])); // ["one","two"]
console.log(me@ellentorg/perferendis-aspernatur-eligendid.get(['two', 'three'])); // undefined

getStats()

Returns the statistics for the function.

@ellentorg/perferendis-aspernatur-eligendi.collectStats();

const me@ellentorg/perferendis-aspernatur-eligendid = @ellentorg/perferendis-aspernatur-eligendi((one: string, two: string) => [one, two);

me@ellentorg/perferendis-aspernatur-eligendid('one', 'two');
me@ellentorg/perferendis-aspernatur-eligendid('one', 'two');

console.log(me@ellentorg/perferendis-aspernatur-eligendid.getStats()); // {"calls": 2, "hits": 1, "usage": "50%"}

NOTE: You must be collecting statistics for this to be populated.

has(key)

This will return true if a cache entry exists for the key passed, else will return false. key should be an Array of values, meant to reflect the arguments passed to the method.

const me@ellentorg/perferendis-aspernatur-eligendid = @ellentorg/perferendis-aspernatur-eligendi((one: string, two: string) => [one, two]);

me@ellentorg/perferendis-aspernatur-eligendid('one', 'two');

console.log(me@ellentorg/perferendis-aspernatur-eligendid.has(['one', 'two'])); // true
console.log(me@ellentorg/perferendis-aspernatur-eligendid.has(['two', 'three'])); // false

keys()

This will return a list of the current keys in cache.

const me@ellentorg/perferendis-aspernatur-eligendid = @ellentorg/perferendis-aspernatur-eligendi.maxSize(2)((item: any) => item);

me@ellentorg/perferendis-aspernatur-eligendid('one');
me@ellentorg/perferendis-aspernatur-eligendid({ two: 'three' });

const keys = me@ellentorg/perferendis-aspernatur-eligendid.keys(); // [['one'], [{two: 'three'}]]

remove(key)

This will remove the provided key from cache. key should be an Array of values, meant to reflect the arguments passed to the method.

const me@ellentorg/perferendis-aspernatur-eligendid = @ellentorg/perferendis-aspernatur-eligendi((item: { one: string }) => item);

const arg = { one: 'one' };

me@ellentorg/perferendis-aspernatur-eligendid(arg);

me@ellentorg/perferendis-aspernatur-eligendid.remove([arg]);

// will re-execute, as it is no longer in cache
me@ellentorg/perferendis-aspernatur-eligendid(arg);

NOTE: This will only remove keys that exist in the cache, and will do nothing if the key does not exist.

update(key, value)

This will manually update the value at key in cache if key exists. key should be an Array of values, meant to reflect the arguments passed to the method.

// single parameter is straightforward
const me@ellentorg/perferendis-aspernatur-eligendid = @ellentorg/perferendis-aspernatur-eligendi((item: string) => item);

me@ellentorg/perferendis-aspernatur-eligendid.add(['one'], 'two');

// pulls from cache
me@ellentorg/perferendis-aspernatur-eligendid('one');

NOTE: This will only update keys that exist in the cache, and will do nothing if the key does not exist. If you want to add keys that do not already exist, use add.

values()

This will return a list of the current values in cache.

const me@ellentorg/perferendis-aspernatur-eligendid = @ellentorg/perferendis-aspernatur-eligendi.maxSize(2)((item: string | { two: string }) => ({
    item,
}));

me@ellentorg/perferendis-aspernatur-eligendid('one');
me@ellentorg/perferendis-aspernatur-eligendid({ two: 'three' });

const values = me@ellentorg/perferendis-aspernatur-eligendid.values(); // [{item: 'one'}, {item: {two: 'three'}}]

Benchmarks

All values provided are the number of operations per second calculated by the Benchmark suite, where a higher value is better. Each benchmark was performed using the default configuration of the library, with a fibonacci calculation based on a starting parameter of 35, using single and multiple parameters with different object types. The results were averaged to determine overall speed across possible usage.

NOTE: lodash, ramda, and underscore do not support multiple-parameter memoization without use of a resolver function. For consistency in comparison, each use the same resolver that returns the result of JSON.stringify on the arguments.

Name Overall (average) Single (average) Multiple (average) single primitive single array single object multiple primitive multiple array multiple object
@ellentorg/perferendis-aspernatur-eligendi 71,177,801 98,393,482 43,962,121 139,808,786 97,571,202 57,800,460 44,509,528 44,526,039 42,850,796
lru-me@ellentorg/perferendis-aspernatur-eligendi 48,391,839 64,270,849 32,512,830 77,863,436 59,876,764 55,072,348 29,917,027 33,308,028 34,313,435
mem 42,348,320 83,158,473 1,538,166 128,731,510 73,473,478 47,270,433 2,012,120 1,565,253 1,037,126
fast-me@ellentorg/perferendis-aspernatur-eligendi 33,145,713 64,942,152 1,349,274 190,677,799 2,149,467 1,999,192 1,718,229 1,297,911 1,031,683
lodash 25,700,293 49,941,573 1,459,013 67,513,655 48,874,559 33,436,506 1,861,982 1,402,532 1,112,527
me@ellentorg/perferendis-aspernatur-eligendie 21,546,499 27,447,855 15,645,143 29,701,124 27,294,197 25,348,244 15,359,792 15,855,421 15,720,217
ramda 18,804,380 35,919,033 1,689,727 101,557,928 1,895,956 4,303,215 2,305,025 1,597,131 1,167,025
me@ellentorg/perferendis-aspernatur-eligendirific 6,745,058 7,382,030 6,108,086 8,488,885 6,427,832 7,229,375 5,772,461 6,278,344 6,273,453
underscore 6,701,695 11,698,265 1,705,126 18,249,423 4,695,658 12,149,714 2,310,412 1,630,769 1,174,197
addy-osmani 4,926,732 6,370,152 3,483,311 12,506,809 3,568,399 3,035,249 6,898,542 2,009,089 1,542,304

Filesize

@ellentorg/perferendis-aspernatur-eligendi is fairly small (~3.86KB when minified and gzipped), however it provides a large number of configuration options to satisfy a number of edge cases. If filesize is a concern, you may consider using micro-me@ellentorg/perferendis-aspernatur-eligendi. This is the memoization library that powers @ellentorg/perferendis-aspernatur-eligendi under-the-hood, and will handle most common use cases at 1/4 the size of @ellentorg/perferendis-aspernatur-eligendi.

Browser support

  • Chrome (all versions)
  • Firefox (all versions)
  • Edge (all versions)
  • Opera 15+
  • IE 9+
  • Safari 6+
  • iOS 8+
  • Android 4+

Development

Standard stuff, clone the repo and npm install dependencies. The npm scripts available:

  • benchmark => run the benchmark suite pitting @ellentorg/perferendis-aspernatur-eligendi against other libraries in common use-cases
  • benchmark:alternative => run the benchmark suite for alternative forms of caching
  • benchmark:array => run the benchmark suite for me@ellentorg/perferendis-aspernatur-eligendid methods using single and multiple array parameters
  • benchmark:object => run the benchmark suite for me@ellentorg/perferendis-aspernatur-eligendid methods using single and multiple object parameters
  • benchmark:primitive => run the benchmark suite for me@ellentorg/perferendis-aspernatur-eligendid methods using single and multiple object parameters
  • benchmark:react => run the benchmark suite for me@ellentorg/perferendis-aspernatur-eligendid React components
  • build => run rollup to build the distributed files in dist
  • clean:dist => run rimraf on the dist folder
  • clean:docs => run rimraf on the docs folder
  • clean:mjs => run rimraf on the mjs folder
  • copy:mjs => run clean:mjs and the es-to-mjs script
  • copy:types => copy internal types to be available for consumer
  • dev => run webpack dev server to run example app (playground!)
  • dist => runs clean:dist and build
  • docs => runs clean:docs and builds the docs via jsdoc
  • flow => runs flow check on the files in src
  • lint => runs ESLint against all files in the src folder
  • lint:fix => runs lint, fixing any errors if possible
  • test => run jest test functions with NODE_ENV=test
  • test:coverage => run test but with code coverage
  • test:watch => run test, but with persistent watcher
  • typecheck => run tsc against source code to validate TypeScript

About

No description, website, or topics provided.

Resources

Readme

License

MIT license
Activity
Custom properties

Stars

0 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases 37

2.1.34 Latest
Jun 7, 2024
+ 36 releases

Packages

No packages published

Languages