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
hook
(Hook): An object withevent
andhandler
properties. See plugins for more info.
Throws
- If
event
is not a string, it will throw an errorHook's event must be a string.
- If
event
doesn't begin withpre
orpost
, it will throw an errorHook's event must start with 'pre' or 'post'.
- If
handler
is not a function, it will throw an errorHook'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
hooks
(array): Array of hooks.
Throws
- If
event
for any hook is not a string, it will throw an errorHook's event must be a string.
- If
event
for any hook doesn't begin withpre
orpost
, it will throw an errorHook's event must start with 'pre' or 'post'.
- If
handler
for any hook is not a function, it will throw an errorHook'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
key
(string): String to build a key of.
Lifecycle
preBuildKey
Event name:
preBuiltKey
Properties passed:cacheInstance
reference to cache instance (this
)key
key passed tobuildKey
method
Returns: (object): object containing properties:
cacheInstance
reference to cache instance (this
)key
key passed through handlers added forpreBuildKey
event
postBuildKey
Event name:
postBuiltKey
Properties passed:cacheInstance
reference to cache instance (this
) returned bypreBuildKey
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 forpostBuildKey
event
Eventually
buildKey
returns key returned bypostBuildKey
.
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
key
(string): Key to get an item by.
Lifecycle
preGetItem
Event name:
preGetItem
Properties passed:cacheInstance
reference to cache instance (this
)key
key passed togetItem
method
Returns: (object): object containing properties:
cacheInstance
reference to cache instance (this
)key
key passed through handlers added forpreGetItem
event
postGetItem
Event name:
postGetItem
Properties passed:cacheInstance
reference to cache instance (this
) returned bypreGetItem
key
key returned bypreGetItem
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 forpostGetItem
eventitem
item passed through handlers added forpostGetItem
event
Eventually
getItem
returns item returned bypostGetItem
.
Important: even though
getItem
usesbuildKey
internally, that build key is not passed inpostGetItem
event handler's object's properties. If key is somehow changed (with some plugin) duringpreBuildKey
orpostGetKey
events, that key is not passed further ingetItem
. If you need access to built key, you can still obtain it from returned item to which you have access inpostGetItem
.Important: make sure that
item
exists when writing plugins, always. Whenitem
is passed to event handler for this event, it might not be an actual item, butundefined
. 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 accessvalue
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
key
(string): Key to get an extra by.
Lifecycle
preGetExtra
Event name:
preGetExtra
Properties passed:cacheInstance
reference to cache instance (this
)key
key passed togetExtra
method
Returns: (object): object containing properties:
cacheInstance
reference to cache instance (this
)key
key passed through handlers added forpreGetExtra
event
postGetExtra
Event name:
postGetExtra
Properties passed:cacheInstance
reference to cache instance (this
) returned bypreGetExtra
key
key returned bypreGetExtra
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 forpostGetExtra
eventextra
extra passed through handlers added forpostGetExtra
event
Eventually
getExtra
returns extra returned bypostGetExtra
.
Important: even though
getExtra
usesbuildKey
internally, that build key is not passed inpostGetExtra
event handler's object's properties. If key is somehow changed (using some plugin) duringpreBuildKey
orpostGetKey
events, that key is not passed further ingetExtra
. If you need access to built key, you can still obtain it from returned item to which you have access inpostGetExtra
.Important: make sure that
extra
exists when writing plugins, always. Whenextra
is passed to event handler for this event, it might not exist anymore, and beundefined
. 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
key
(string): Key to store the extra under (represents given item).extra
(object): Extra data to store.
Throws
- If
extra
is not an object, it will throw'extra' must be an object.
Lifecycle
preAddExtra
Event name:
preAddExtra
Properties passed:cacheInstance
reference to cache instance (this
)key
key passed toaddExtra
methodextra
extra passed toaddExtra
method
Returns: (object): object containing properties:
cacheInstance
reference to cache instance (this
)key
key passed through handlers added forpreAddExtra
eventextra
extra passed through handlers added forpreAddExtra
event
postAddExtra
Event name:
postAddExtra
Properties passed:cacheInstance
reference to cache instance (this
) returned bypreAddExtra
key
key returned bypreAddExtra
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 forpostAddExtra
eventextra
extra passed through handlers added forpostAddExtra
event
Eventually
addExtra
returns extra returned bypostAddExtra
.
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
key
(string): Key to store the extra under (represents given item).extra
(object): Extra data to replace existing one.
Throws
- If
extra
is not an object, it will throw'extra' must be an object.
Lifecycle
preSetExtra
Event name:
preSetExtra
Properties passed:cacheInstance
reference to cache instance (this
)key
key passed tosetExtra
methodextra
extra passed tosetExtra
method
Returns: (object): object containing properties:
cacheInstance
reference to cache instance (this
)key
key passed through handlers added forpreSetExtra
eventextra
extra passed through handlers added forpreSetExtra
event
postSetExtra
Event name:
postSetExtra
Properties passed:cacheInstance
reference to cache instance (this
) returned bypreSetExtra
key
key returned bypreSetExtra
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 forpostSetExtra
eventextra
extra passed through handlers added forpostSetExtra
event
Eventually
setExtra
returns extra returned bypostSetExtra
.
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
key
(string): Key to store the value under.value
(any): Any value to store in item. See values.extra
(object): Optional, defaults to empty object if not passed. Extra data to store alongside value in item.
Lifecycle
preSetItem
Event name:
preSetItem
Properties passed:cacheInstance
reference to cache instance (this
)key
key passed tosetItem
methodvalue
value passed tosetItem
methodextra
extra passed tosetItem
method
Returns: (object): object containing properties:
cacheInstance
reference to cache instance (this
)key
key passed through handlers added forpreSetItem
eventvalue
value passed through handlers added forpreSetItem
eventextra
extra passed through handlers added forpreSetItem
event
postSetItem
Event name:
postSetItem
Properties passed:cacheInstance
reference to cache instance (this
) returned bypreSetItem
key
key returned bypreSetItem
value
value returned bypreSetItem
extra
extra returned bypreSetItem
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 forpostSetItem
eventvalue
value passed through handlers added forpostSetItem
eventextra
extra passed through handlers added forpostSetItem
eventitem
item passed through handlers added forpostSetItem
event
Eventually
setItem
returns item returned bypostSetItem
.
Important: even though
setItem
usesbuildKey
internally, that build key is not passed inpostSetItem
event handler's object's properties. If key is somehow changed (with some plugin) duringpreBuildKey
orpostGetKey
events, that key is not passed further insetItem
. If you need access to built key, you can still obtain it from returned item to which you have access inpostSetItem
.
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
key
(string): Key to check if an item exists by.
Lifecycle
preHasItem
Event name:
preHasItem
Properties passed:cacheInstance
reference to cache instance (this
)key
key passed tohasItem
method
Returns: (object): object containing properties:
cacheInstance
reference to cache instance (this
)key
key passed through handlers added forpreHasItem
event
postHasItem
Event name:
postHasItem
Properties passed:cacheInstance
reference to cache instance (this
) returned bypreHasItem
key
key returned bypreHasItem
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 forpostHasItem
eventresult
boolean value passed through handlers added forpostHasItem
event
Eventually
hasItem
returns result returned bypostHasItem
.
Important: even though
hasItem
usesbuildKey
internally, that build key is not passed inpostHasItem
event handler's object's properties. If key is somehow changed (with some plugin) duringpreBuildKey
orpostGetKey
events, that key is not passed further inhasItem
. If you need access to built key, you can still obtain it from returned item to which you have access inpostHasItem
.
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
key
(string): Key to remove an item by.
Lifecycle
preRemoveItem
Event name:
preRemoveItem
Properties passed:cacheInstance
reference to cache instance (this
)key
key passed toremoveItem
method
Returns: (object): object containing properties:
cacheInstance
reference to cache instance (this
)key
key passed through handlers added forpreRemoveItem
event
postRemoveItem
Event name:
postRemoveItem
Properties passed:cacheInstance
reference to cache instance (this
) returned bypreRemoveItem
key
key returned bypreRemoveItem
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 forpostRemoveItem
eventresult
boolean value passed through handlers added forpostRemoveItem
event
Eventually
removeItem
returns result returned bypostRemoveItem
.
Important: even though
removeItem
usesbuildKey
internally, that build key is not passed inpostRemoveItem
event handler's object's properties. If key is somehow changed (with some plugin) duringpreBuildKey
orpostGetKey
events, that key is not passed further inremoveItem
. If you need access to built key, you can still obtain it from returned item to which you have access inpostRemoveItem
.
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