Skip to main content
Version: 3.27.2

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 : object

    • headers : 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 within TransactionInsertOptions.
      • 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.

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