Adapter instance

Adapter instance is an object that holds methods that provide access to storage given adapter uses.

Available methods

buildKey(key)

This method is responsible for building key.

You might ask, why there is such a method when you already provide a key? Well, this has been partially answered in namespaces and keys docs.

Arguments

  1. key (string): A string used to store an item under in cache.
    Key is being validated, and happens only in this method (even though other methods also take key as an argument). Validation should usually be the same for all adapters, but not necessarily. Each adapter has its own validation description in its docs. Check it out there.

    About validation of key happening only in this method. As you know already, stash-it creates a cache instance using createCache method, which takes adapter as an argument. Cache instance is a proxy for it's resource - adapter. Now, whenever you call any cache's instance method, e.g. getItem(key), it will call adapter's getItem(key) method (like proxy would), but first, cache instance will build a key and that built key is used in all adapters methods (all but buildKey of course).

    If this is not clear yet, have a look. This is how it (almost) looks like in source code:

    {
    buildKey(key) {
        return adapter.buildKey(key);       
    },
    getItem(key) {
        const builtKey = this.buildKey(key);

        return adapter.getItem(builtKey);
    },
    hasItem(key) {
        const builtKey = this.buildKey(key);

        return adapter.hasItem(builtKey);
    }
    ...
}

    Therefore, key building is happening only in cache's instance buildKey method, and as such, validation is needed only in adapter's buildKey method, as that built key is used for other adapter's methods.

Returns

(string): Built key. Most of the times this will be a concatenation of some kind of namespace and passed key argument.

setItem(key, value, [extra])

This method sets an item and returns it as well. See createItem for details how item looks like.

Arguments

  1. key (string): A string used to store an item under.
  2. value (any): Any value that can be stored in cache. Depends on adapter you use (and storage this adapter grants access to). See values for more info.

  3. extra (object): It's optional. It allows you to pass additional (extra) data that you want to store alongside value. See how that can be used in lifecycle methods and plugins.
    If passed, it will be validated:

    • If it's not passed as an object, error will be thrown: 'extra' must be an object..
    • If it will contain namespace property, error will be thrown: 'extra' can't contain 'namespace' property. This property is checked, because namespace is, by default, stored in extra. Why? To have knowledge what namespace was used for that object. And if namespace was to be passed in extra, it would be overwritten. Check out createItem for detailed info how extra looks like.

Returns

(Item): Built item, an object.

Example

// without extra
const item1 = cache.setItem('key1', 'some value to store');

// with extra
const item2 = cache.setItem('key2', 'some other value', { extra: 'information to store' });

// this will throw: `extra` can't contain `namespace` property
const item3 = cache.setItem('key3', '...', { namespace: 'something' });

getItem(key)

This method returns an item for given key.

Arguments

  1. key (string): A string used to find and fetch item under.

Returns

(Item): Item, an object.

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

Example

// `item` will be either an object or undefined - depending if item exists or not
const item = cache.getItem('key');

getExtra(key)

This method returns extra for given item for given key. If item does not exist, it returns false. Check out createItem to know how an item is constructed.

Arguments

  1. key (string): A string used to find and fetch item's extra under.

Returns

(object): The extra part of Item.

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

Example

// `extra` will be either an object or undefined - depending if item exists or not
const extra = cache.getExtra('key');

addExtra(key, extra)

This method adds extra for given item for given key. If item does not exist, it returns undefined. New properties (in extra) 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.

Returns

(object): The extra part of Item including new or overwritten data that's been passed to be added.

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

Example

// `extra` will be either an object or undefined - depending if item exists or not
const extra = cache.addExtra('key', { some: 'data' });

setExtra(key, extra)

This method sets (replaces existing) extra for given item for given key. If item does not exist, it returns undefined.

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.

Returns

(object): The extra part of Item - here, the very same that was passed to be set.

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

Example

// `extra` will be either an object or undefined - depending if item exists or not
const extra = cache.setExtra('key', { some: 'data' });

hasItem(key)

This methods checks if item exists or not.

Arguments

  1. key (string): A string to find an item under.

Returns

(bool): true if item is found, false otherwise.

Example

// `result` will equal either `true` or `false` - depending if items exists or not
const result = cache.hasItem('key');

removeItem(key)

This method removes an item.

Arguments

  1. key (string): A string to remove an item under.

Returns

(bool): true if item is found and deleted, false otherwise.

Example

// `result` will equal either `true` or `false` - depending if item was found and successfully deleted 
const result = cache.removeItem('key');

results matching ""

    No results matching ""