CacheInstance

• addHook(hook)
• addHooks(hooks)
• getHooks()
• buildKey(key)
• getItem(key)
• getExtra(key)
• addExtra(key, extra)
• setExtra(key, extra)
• setItem(key, value, [extra])
• hasItem(key)
• removeItem(key)

Important: read about lifecycle of methods and plugins first.

Important: as cacheInstance uses adapters to get / set / find / remove items, they (adapters) can throw on the way. Those throws (what and when) are not mentioned here, but are described in detail in adapters API methods.

addHook(hook)

This method adds hook (to hooks list). Hook is added to the end of the list. See getHooks method and plugins.

Arguments

1. hook (Hook): An object with event and handler properties. See plugins for more info.

Throws

1. If event is not a string, it will throw an error Hook's event must be a string.
2. If event doesn't begin with pre or post, it will throw an error Hook's event must start with 'pre' or 'post'.
3. If handler is not a function, it will throw an error Hook's handler must be a function.

Example

// assuming that you already have cache instance prepared
const hook = {
    event: 'preGetItem',
    handler: () => { ... } // some function that does something, not relevant here
}

cache.addHook(hook);

addHooks(hooks)

This method adds hooks (to hooks list). Hooks are added to the end of the list. See getHooks method and plugins.

Arguments

1. hooks (array): Array of hooks.

Throws

1. If event for any hook is not a string, it will throw an error Hook's event must be a string.
2. If event for any hook doesn't begin with pre or post, it will throw an error Hook's event must start with 'pre' or 'post'.
3. If handler for any hook is not a function, it will throw an error Hook's handler must be a function.

Example

// assuming that you already have cache instance prepared
const hook1 = {
    event: 'preGetItem',
    handler: () => { ... } // some function that does something, not relevant here
}
const hook2 = {
    event: 'postSetItem',
    handler: () => { ... } // some function that does something, not relevant here
}



cache.addHooks([ hook1, hook2 ]);

getHooks()

Returns hooks.

Returns

(object): Object with hooks.

Hooks, when added, are stored in an object. Properties of that object are hook's events and values are arrays of handlers.

Examples

// assuming that you already have cache instance prepared
const hook1 = {
    event: 'preGetItem',
    handler: () => { ... } // some function that does something, not relevant here
}
const hook2 = {
    event: 'postSetItem',
    handler: () => { ... } // some function that does something, not relevant here
}

cache.addHooks([ hook1, hook2 ]);

// In cache, hooks will be stored like so:
{
    hooks: {
        preGetItem: [
            () => {} // handler from hook1
        ],
        postSetItem: [
            () => {} // handler from hook2
        ]
    }
}

cache.getHooks(); // it will return object shown above

What will happen when I will add more hooks with same events?

// continuing from the example above
const hook3 = {
    event: 'preGetItem',
    handler: () => {}
}

cache.addHook(hook3);

//right now hooks will look like so:
{
    hooks: {
        preGetItem: [
            () => {} // handler from hook1,
            () => {} // handler from hook3, added to the end of the list of hooks for given event
        ],
        postSetItem: [
            () => {} // handler from hook2
        ]
    }
}

buildKey(key)

This method builds a key. See also keys (basic usage) and buildKey(key) in adapter API.

Arguments

1. key (string): String to build a key of.

Lifecycle

1. preBuildKey

   Event name: preBuiltKey
   Properties passed:

   • cacheInstance reference to cache instance (this)

   • key key passed to buildKey method

   Returns: (object): object containing properties:

   • cacheInstance reference to cache instance (this)

   • key key passed through handlers added for preBuildKey event

2. postBuildKey

   Event name: postBuiltKey
   Properties passed:

   • cacheInstance reference to cache instance (this) returned by preBuildKey

   • key key built by adapter using its buildKey(key) method

   Returns: (object): object containing properties:

   • cacheInstance reference to cache instance (this)

   • key key passed through handlers added for postBuildKey event

   Eventually buildKey returns key returned by postBuildKey.

Returns

(string): Built key. Depends on adapter being used.

Example

// assuming that you already have cache instance prepared
const builtKey = cache.buildKey('key');

getItem(key)

Returns an item.

Arguments

1. key (string): Key to get an item by.

Lifecycle

1. preGetItem

   Event name: preGetItem
   Properties passed:

   • cacheInstance reference to cache instance (this)

   • key key passed to getItem method

   Returns: (object): object containing properties:

   • cacheInstance reference to cache instance (this)

   • key key passed through handlers added for preGetItem event

2. postGetItem

   Event name: postGetItem
   Properties passed:

   • cacheInstance reference to cache instance (this) returned by preGetItem

   • key key returned by preGetItem

   • item item returned by adapter using its getItem(key) method

   Returns: (object): object containing properties:

   • cacheInstance reference to cache instance (this)

   • key key passed through handlers added for postGetItem event

   • item item passed through handlers added for postGetItem event

   Eventually getItem returns item returned by postGetItem.

Important: even though getItem uses buildKey internally, that build key is not passed in postGetItem event handler's object's properties. If key is somehow changed (with some plugin) during preBuildKey or postGetKey events, that key is not passed further in getItem. If you need access to built key, you can still obtain it from returned item to which you have access in postGetItem.

Important: make sure that item exists when writing plugins, always. When item is passed to event handler for this event, it might not be an actual item, but undefined. Why? Some plugin before one you will use to operate on this item, might have already removed it. How? Here's an example:

• you have a ttl plugin that will automatically remove an item once it's lifetime is over,
• you have another plugin that does something with item's data,
• order of executing plugins matter, therefore when first plugin will remove that item and pass undefined further down, every next plugin will operate on that undefined value. So do not try to access value or anything from that item, your app will crash.

Returns

(Item): Item, an object.

(undefined): If item is not found, returns undefined.

Example

// assuming that you already have cache instance prepared
cache.getItem('key'); // Item
cache.getItem('keyForItemThatDoesNotExist'); // undefined

getExtra(key)

Returns extra (for given object for given key).

Arguments

1. key (string): Key to get an extra by.

Lifecycle

1. preGetExtra

   Event name: preGetExtra
   Properties passed:

   • cacheInstance reference to cache instance (this)

   • key key passed to getExtra method

   Returns: (object): object containing properties:

   • cacheInstance reference to cache instance (this)

   • key key passed through handlers added for preGetExtra event

2. postGetExtra

   Event name: postGetExtra
   Properties passed:

   • cacheInstance reference to cache instance (this) returned by preGetExtra

   • key key returned by preGetExtra

   • extra extra (object) returned by adapter using its getExtra(key) method

   Returns: (object): object containing properties:

   • cacheInstance reference to cache instance (this)

   • key key passed through handlers added for postGetExtra event

   • extra extra passed through handlers added for postGetExtra event

   Eventually getExtra returns extra returned by postGetExtra.

Important: even though getExtra uses buildKey internally, that build key is not passed in postGetExtra event handler's object's properties. If key is somehow changed (using some plugin) during preBuildKey or postGetKey events, that key is not passed further in getExtra. If you need access to built key, you can still obtain it from returned item to which you have access in postGetExtra.

Important: make sure that extra exists when writing plugins, always. When extra is passed to event handler for this event, it might not exist anymore, and be undefined. Why? Some plugin before one you will use to operate on this extra, might have already removed item (from which this extra is taken from). How? Here's an example:

• you have a ttl plugin that will automatically remove an item once it's lifetime is over,
• you have another plugin that does something with this item's extra,
• order of executing plugins matter, therefore when first plugin will remove that item and pass undefined further down, every next plugin will operate on that undefined value. So do not try to access any property from that extra, your app will crash.

Returns

(object): Object, extra from item.

(undefined): If item is not found (thus no extra can be taken from it), returns undefined.

Example

// assuming that you already have cache instance prepared
cache.getExtra('key'); // object, extra for that item
cache.getExtra('keyForItemThatDoesNotExist'); // undefined

addExtra(key, extra)

Adds extra to item's existing extra. New properties are added, existing are overwritten.

Arguments

1. key (string): Key to store the extra under (represents given item).
2. extra (object): Extra data to store.

Throws

1. If extra is not an object, it will throw 'extra' must be an object.

Lifecycle

1. preAddExtra

   Event name: preAddExtra
   Properties passed:

   • cacheInstance reference to cache instance (this)

   • key key passed to addExtra method

   • extra extra passed to addExtra method

   Returns: (object): object containing properties:

   • cacheInstance reference to cache instance (this)

   • key key passed through handlers added for preAddExtra event

   • extra extra passed through handlers added for preAddExtra event

2. postAddExtra

   Event name: postAddExtra
   Properties passed:

   • cacheInstance reference to cache instance (this) returned by preAddExtra

   • key key returned by preAddExtra

   • extra extra (object) returned by adapter using its addExtra(key, extra) method

   Returns: (object): object containing properties:

   • cacheInstance reference to cache instance (this)

   • key key passed through handlers added for postAddExtra event

   • extra extra passed through handlers added for postAddExtra event

   Eventually addExtra returns extra returned by postAddExtra.

Example

// Existing extra
{ 
    some: 'data'
}

cache.addExtra(key, { foo: 'bar' });

// Extra after adding new one
{
    foo: 'bar',
    some: 'data'
}

cache.addExtra(key, { foo: 'baz' });

// Extra after another round of adding stuff to it
{
    foo: 'baz', // <-- notice that this value's changed
    some: 'data'
}

setExtra(key, extra)

Sets (replaces existing) extra in an item.

Important: as existing extra is being overwritten, be careful how / when you use it. Simply, use this method with caution.

Arguments

1. key (string): Key to store the extra under (represents given item).
2. extra (object): Extra data to replace existing one.

Throws

1. If extra is not an object, it will throw 'extra' must be an object.

Lifecycle

1. preSetExtra

   Event name: preSetExtra
   Properties passed:

   • cacheInstance reference to cache instance (this)

   • key key passed to setExtra method

   • extra extra passed to setExtra method

   Returns: (object): object containing properties:

   • cacheInstance reference to cache instance (this)

   • key key passed through handlers added for preSetExtra event

   • extra extra passed through handlers added for preSetExtra event

2. postSetExtra

   Event name: postSetExtra
   Properties passed:

   • cacheInstance reference to cache instance (this) returned by preSetExtra

   • key key returned by preSetExtra

   • extra extra (object) returned by adapter using its setExtra(key, extra) method

   Returns: (object): object containing properties:

   • cacheInstance reference to cache instance (this)

   • key key passed through handlers added for postSetExtra event

   • extra extra passed through handlers added for postSetExtra event

   Eventually setExtra returns extra returned by postSetExtra.

Example

// Existing extra
{ 
    some: 'data'
}

cache.setExtra(key, { foo: 'bar' });

// Extra after setting new one
{
    foo: 'bar'
}

setItem(key, value, [extra])

Sets an item (and returns it, once created).

Arguments

1. key (string): Key to store the value under.
2. value (any): Any value to store in item. See values.
3. extra (object): Optional, defaults to empty object if not passed. Extra data to store alongside value in item.

Lifecycle

1. preSetItem

   Event name: preSetItem
   Properties passed:

   • cacheInstance reference to cache instance (this)

   • key key passed to setItem method

   • value value passed to setItem method

   • extra extra passed to setItem method

   Returns: (object): object containing properties:

   • cacheInstance reference to cache instance (this)

   • key key passed through handlers added for preSetItem event

   • value value passed through handlers added for preSetItem event

   • extra extra passed through handlers added for preSetItem event

2. postSetItem

   Event name: postSetItem
   Properties passed:

   • cacheInstance reference to cache instance (this) returned by preSetItem

   • key key returned by preSetItem

   • value value returned by preSetItem

   • extra extra returned by preSetItem

   • item returned by adapter using setItem(key, value, extra) method

   Returns: (object): object containing properties:

   • cacheInstance reference to cache instance (this)

   • key key passed through handlers added for postSetItem event

   • value value passed through handlers added for postSetItem event

   • extra extra passed through handlers added for postSetItem event

   • item item passed through handlers added for postSetItem event

   Eventually setItem returns item returned by postSetItem.

Important: even though setItem uses buildKey internally, that build key is not passed in postSetItem event handler's object's properties. If key is somehow changed (with some plugin) during preBuildKey or postGetKey events, that key is not passed further in setItem. If you need access to built key, you can still obtain it from returned item to which you have access in postSetItem.

Returns

(Item): Stored (thus created) item.

Example

// assuming that you already have cache instance prepared
cache.setItem('key', 'value'); // Item, the very one set here
cache.setitem('key', 'value', { some: 'extra data' }); // Item, the very one set here

hasItem(key)

Checks if item exists.

Arguments

1. key (string): Key to check if an item exists by.

Lifecycle

1. preHasItem

   Event name: preHasItem
   Properties passed:

   • cacheInstance reference to cache instance (this)

   • key key passed to hasItem method

   Returns: (object): object containing properties:

   • cacheInstance reference to cache instance (this)

   • key key passed through handlers added for preHasItem event

2. postHasItem

   Event name: postHasItem
   Properties passed:

   • cacheInstance reference to cache instance (this) returned by preHasItem

   • key key returned by preHasItem

   • result boolean value returned by adapter using its hasItem(key) method

   Returns: (object): object containing properties:

   • cacheInstance reference to cache instance (this)

   • key key passed through handlers added for postHasItem event

   • result boolean value passed through handlers added for postHasItem event

   Eventually hasItem returns result returned by postHasItem.

Important: even though hasItem uses buildKey internally, that build key is not passed in postHasItem event handler's object's properties. If key is somehow changed (with some plugin) during preBuildKey or postGetKey events, that key is not passed further in hasItem. If you need access to built key, you can still obtain it from returned item to which you have access in postHasItem.

Returns

(bool): true if item exists, false otherwise.

Example

// assuming that you already have cache instance prepared
cache.hasItem('key'); // true
cache.hasItem('keyForItemThatDoesNotExist'); // false

removeItem(key)

Removes an item.

Arguments

1. key (string): Key to remove an item by.

Lifecycle

1. preRemoveItem

   Event name: preRemoveItem
   Properties passed:

   • cacheInstance reference to cache instance (this)

   • key key passed to removeItem method

   Returns: (object): object containing properties:

   • cacheInstance reference to cache instance (this)

   • key key passed through handlers added for preRemoveItem event

2. postRemoveItem

   Event name: postRemoveItem
   Properties passed:

   • cacheInstance reference to cache instance (this) returned by preRemoveItem

   • key key returned by preRemoveItem

   • result boolean value returned by adapter using its removeItem(key) method

   Returns: (object): object containing properties:

   • cacheInstance reference to cache instance (this)

   • key key passed through handlers added for postRemoveItem event

   • result boolean value passed through handlers added for postRemoveItem event

   Eventually removeItem returns result returned by postRemoveItem.

Important: even though removeItem uses buildKey internally, that build key is not passed in postRemoveItem event handler's object's properties. If key is somehow changed (with some plugin) during preBuildKey or postGetKey events, that key is not passed further in removeItem. If you need access to built key, you can still obtain it from returned item to which you have access in postRemoveItem.

Returns

(bool): true if item was removed, false otherwise.

Example

// assuming that you already have cache instance prepared
cache.removeItem('key'); // true
cache.removeItem('keyForItemThatDoesNotExist'); // false