Item

What items are? How do you use key, value, extra and how they build up the item that is stored.

stash-it doesn't store the key-value pairs just like that. It creates an item object and stores it. Such object consists of key, value and extra.

Key

Can I use anything as a key?

Well, it depends on the storage (hence adapter) you will use. Why? It's all about what adapter can write as a key for it's storage. But most of the times any adapter will require it to be a string. What characters you'll use there is up to you - there is no limitation and stash-it relies on your common sense.

Keys are built

Yes. key is being built using buildKey public method.

Why? It is about having access to buildKey method's lifecycle methods. What for? To alter, if needed, the way how key is being built.

For instance, stash-it-plugin-prefixsuffix makes use of one of lifecycle methods of buildKey to add prefix and/or suffix to the value returned by that function.

Value

What type of values you can store?

Well, it solely depends on the adapter you use.

For instance, stash-it-adapter-memory is storing every data in a plain JavaScript object. So, whatever data JavaScript allows you to store there - so can you.

There is no validation of values. stash-it relies on your common sense.

Extra

extra is an object in which you can store any and all additional data in regards to the value you store. It is mostly used by plugins. But you're free to use it as well.

For instance, stash-it-plugin-ttl uses extra to store ttl data there (date crated, valid till, ttl value).

Item

Having learned what key, value and extra are, here is how the item object looks like:

{
    key: 'key',
    value: 'value',
    extra: {}
}

One may ask: will I always have to remember this structure when I will be creating and storing an item?

No. There is a helper function createItem in stash-it that will do that for you. Here's how you use it:

import { createItem } from 'stash-it';

const item = createItem('key', 'value', { optional: 'extra data' });

// and this is how newly created item will look like
{
    key: 'key',
    value: 'value',
    extra: {
        optional: 'extra data'
    }
}

Also, this function is used mostly (if not only) by adapters so you don't even have to know it exists at all. But if you'll want to create one (adapter) by yourself, this is what you should use to maintain cohesion with other adapters when returning an item from storage.