PersistentCache(useLocalCache, bucketopt, prefixopt, s3Endpointopt, accessKeyIdopt, secretAccessKeyopt)

A cache implementation.

See the get, put and delete methods for more details.

Constructor

new PersistentCache(useLocalCache, bucketopt, prefixopt, s3Endpointopt, accessKeyIdopt, secretAccessKeyopt)

Initialize this cache module.

Project code should never need to call this. The SSR Server provides an instance of this class.

Parameters:
Name Type Attributes Description
useLocalCache Boolean

true to use a local disk cache, false to use a remote (S3) cache. A deployed SSR Server will use the remote S3 cache. The local development server will use the local disk cache.

bucket String <optional>

for a remote cache, the name of the S3 bucket to use.

prefix String <optional>

for a remote cache, a prefix for the cache, within the S3 bucket.

s3Endpoint String <optional>

for a remote cache, the S3 endpoint to use (allows for testing).

accessKeyId String <optional>

for testing, override AWS access key id

secretAccessKey String <optional>

for testing, override AWS secret key

Methods

delete(key, namespaceopt) → {Promise.<*>}

Remove a single entry from the cache.

Parameters:
Name Type Attributes Description
key String

the cache key

namespace String | Array.<String> <optional>

the cache namespace

Returns:

resolves when delete is complete

Type
Promise.<*>

get(namespaceopt, key) → {Promise.<*>}

Get a JavaScript object from the cache.

The returned Promise will resolve either to null if there is no match in the cache, or to an object with the following properties: 'found' is a boolean that is true if the item was found in the cache, 'false' if not, 'data' is the data for the object (or undefined if the object was not found), 'metadata' is the metadata object passed to put() (or undefined if the object was not found), 'expiration' is a JS date/timestamp representing the time at which the item will expire from the cache, 'key' is the item's cache key, and 'namespace' is the item's cache namespace.

If the value passed to 'put' was a Buffer, then 'data' will be a Buffer. If the value passed to 'put' was anything else, it will have been deserialized from JSON, and will be whatever type was originally passed in.

If an object is in the cache under the given key, each call to this method will return a separate copy of the object.

If the object is NOT in the cache, this method will return an object with 'found' set to false. This allows a then() handler to use object deconstruction on the result.

Within the cache, items under the same key but in different namespaces are distinct. The default namespace is undefined.

Parameters:
Name Type Attributes Description
namespace String | Array.<String> <optional>

the cache namespace

key String

the cache key

Returns:

A Promise that will resolve to the cache result, or null if there is no match in the cache.

Type
Promise.<*>

put(key, namespaceopt, data, metadataopt, expirationopt) → {Promise.<*>}

Store a JavaScript object in the cache.

If the data to be stored is a Buffer, it's stored as-is. If it's any other type, it's serialized to JSON and the JSON is stored. If the data is not JSON-serializable, then this method will throw an error.

A primary use-case for this cache is storing HTTP responses, which include a status code, headers and a body. The body is typically most efficiently stored as a Buffer. Passing an object to 'data' that has a Buffer value will result in the Buffer being JSON-encoded, which is slow and takes up much more space than the origin data. The recommended way to store a response is to include the status and headers in the item's metadata, and to pass the body as a Buffer.

If an expiration date/timestamp is given, the data will expire from the cache at that time. If no date/timestamp is given, the default expiration is one year from the time that the data is stored.

Within the cache, items under the same key but in different namespaces are distinct. The default namespace is undefined.

If put() is called to store metdata but no data, you should pass undefined for 'data'.

Parameters:
Name Type Attributes Description
key String

the cache key.

namespace String | Array.<String> <optional>

the cache namespace

data Buffer | *

the data to be stored.

metadata Object <optional>

a simple JS object with keys and values for metadata. This object MUST be JSON-seralizable.

expiration Number <optional>

the expiration date/time for the data, as a JS date/timestamp (the result of Date.getTime). If the expiration is less than PersistentCache.DELTA_THRESHOLD (midnight on January 1st, 1980) it is interpreted as a delta number of mS to be added to the current time. This allows for deltas up to ten years.

Returns:

resolves when data has been stored, or rejects on an error

Type
Promise.<*>