cache

io.cache provides an application-level cache, so a client-side code may control and clear cache depending on application logic.

Don't forget to consult the cookbook to see working snippets solving simple real-world problems.

Logic

If options object has a Boolean property cache, it tells the cache service to process or to ignore a request. Otherwise, a default algorithm is used described in Service documentation.

If options object has a property bust (see bust), and it is truthy, it ignores the value of cache assuming that this request should not be cached.

When cache retrieves a piece of information, it constructs a fake XHR object, which mimics the real XMLHttpRequest. In most cases, there is no difference in an application in which one is used.

Exposed properties

Like any service, io.cache works transparently with io, but it exposes some helpers.

io.cache.save(options, result)

This function stores a result for an I/O request described by options. The result object can be:

• An instance of io.Result. In this case, its xhr property is used to store all pertinent details.
• A JSON-compatible object or value.

io.cache.remove(options)

This function removes a cached object, which corresponds to options.

(As of 1.5.0) If options is a function, it will be called for every cache key (without a prefix usually specified by io.prefix). If it returns a truthy value the corresponding cache object will be removed.

(As of 1.3.0) If options is a regular expression object, it will be applied to all cached resources, which URL satisfies the regular expression. For example, /^https/ will delete all cached resources starting with 'https' like 'https:/example.com/', but not '/https' nor '/abc?q=https'.

(As of 1.5.0) If options is a string or an object, it will be processed first by io.processOptions(). Then its url property will be inspected as described below.

(As of 1.3.0) If options is a string, which ends with '*', it is assumed to be a wildcard and all cached resources with a URL prefixed by options (sans '*'). For example, '/abc*' will delete cached resources for '/abc', '/abc?q=x', '/abc/xyz', and '/abcd'.

When attempting to remove an entry keep in mind that a URL is used as it is supplied to io without a normalization usually done by a browser. For example, if you didn't supply a domain name, a browser will resolve it to use the current domain, but io will use the URL without changes.

Another important point is that otherwise the URL will be sanitized, all prohibited characters will be properly encoded and a query is sanitized and appended as well (if there is one).

Generally, only GET requests are cached, but potentially it is possible to override it. The wildcard ignores a verb when matching cache items, while regular expressions and functions can take it into account.

io.cache.saveByKey(key, result)

This function is similar to io.cache.save(), but uses a unique key instead of options. It is used to implement io.cache.save(), and exposed mostly for efficiency.

io.cache.storage

This is a cache object, which is used to store and retrieve cached data. It has the following properties:

• store(key, data) — stores data using a unique string key. Data is assumed to be a JSON-compatible object or value.
• retrieve(key) — returns data by its string key, or undefined, if not found.
• remove(key) — deletes data by its string key.
• clear() — deletes all data in the cache.

An application rarely, if ever, needs to use io.cache.storage directly. But it can assign this object to implement custom caches.

io.cache.makeStorage(type)

This function creates a cache storage object, which can be assigned to io.cache.storage directly. type should be a string. Two values are valid:

• 'sessionStorage' — create a cache based on sessionStorage.
• 'localStorage' — create a cache based on localStorage.

This is a helper function, which is used internally.

Standard service properties

See Service documentation for more details.