setItem(key, value, [extra])

Last updated 5 months ago

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

Even though setItem uses buildKey internally, that built key is not passed in postSetItem event handler's object's properties. If key is somehow changed (with some plugin) during preBuildKey or postGetKey event handlers, 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 (no extra)
cache.setitem('key', 'value', { some: 'extra data' }); // Item (with extra)