CoreCache.lookup
Perform a non-transactional lookup into the cache, returning a CacheEntry if a usable cached item was found. A cached item is usable if its age is less than the sum of its TTL and its stale-while-revalidate period. Items beyond that age are unusably stale.
Note: A non-transactional lookup will not attempt to coordinate with any concurrent cache lookups.
If two instances of the service perform a lookup at the same time for the same cache key, and the item is not yet cached, they will both return null
.
Without further coordination, they may both end up performing the work needed to insert() the item (which usually involves origin requests and/or computation) and racing with each other to insert.
To resolve such races between concurrent lookups, use CoreCache.transactionLookup()
instead.
Syntax
lookup(key, options)
Parameters
key
: string- A cache key which is a string with a length of up to 8,135 that identify a cached item.
- The cache key may not uniquely identify an item; headers can be used to augment the key when multiple items are associated with the same key.
options
: objectheaders
: HeadersInit optional- The headers act as additional factors in object selection, and the choice of which headers to factor in is determined during insertion, via the
vary
property withinTransactionInsertOptions
. - A lookup will succeed when there is at least one cached item that matches lookup’s
key
, and all of the lookup’s headers included in the cache items’vary
list match the corresponding headers in that cached item. - A typical example is a cached HTTP response, where the request had an "Accept-Encoding" header. In that case, the origin server may or may not decide on a given encoding, and whether that same response is suitable for a request with a different (or missing) Accept-Encoding header is determined by whether Accept-Encoding is listed in Vary header in the origin’s response.
- Note: These headers are narrowly useful for implementing cache lookups incorporating the semantics of the HTTP Vary header.
- The headers act as additional factors in object selection, and the choice of which headers to factor in is determined during insertion, via the
Return value
Returns CacheEntry
if a usable cached item was found, otherwise returns null
.
Exceptions
TypeError
- If the provided
key
:- Is an empty string
- Cannot be coerced to a string
- Is longer than 8135 characters
- If the provided