---
title: CoreCache
summary: The CoreCache class exposes the Compute Core Cache API, the same set of primitive operations used to build Fastly services. The Core Cache API puts the highest level of power in the hands of the user, but requires manual serialization of cache contents and explicit handling of request collapsing and revalidation control flow.
url: https://www.fastly.com/documentation/reference/compute/sdks/javascript/js-compute/cache/class.CoreCache/
---

**Kind:** Class  
**Module:** [cache](https://www.fastly.com/documentation/reference/compute/sdks/javascript/js-compute/cache/)  
**Package:** @fastly/js-compute 4.0.1  
**Since:** 3.9.0  
**Source:** https://github.com/fastly/js-compute-runtime/blob/70cf30af4e657879b2d1e7eafab880e39e3a3f7d/types/cache.d.ts#L232

The CoreCache class exposes the Compute Core Cache API, the same set of primitive operations used to build Fastly services.
The Core Cache API puts the highest level of power in the hands of the user, but requires manual serialization of cache contents and explicit handling of request collapsing and revalidation control flow.

## Methods

### insert

**Flags:** static  
**Source:** https://github.com/fastly/js-compute-runtime/blob/70cf30af4e657879b2d1e7eafab880e39e3a3f7d/types/cache.d.ts#L260

```javascript
static insert(key: string, options: InsertOptions): FastlyBody
```

Perform a non-transactional insertion into the cache, returning a `FastlyBody` instance for providing the cached object itself.
For the insertion to complete successfully, the object must be written into the returned `FastlyBody` instance, and then `FastlyBody.prototype.close` must be called.
If `FastlyBody.prototype.close` does not get called, the insertion is considered incomplete, and any concurrent lookups that may be reading from the object as it is streamed into the cache may encounter a streaming error.

Note: Like `CoreCache.lookup()`, `CoreCache.insert()` may race with concurrent lookups or insertions, and will unconditionally overwrite existing cached items rather than allowing for revalidation of an existing object.
The transactional equivalent of this function is `TransactionCacheEntry.insert()`, which may only be called following a `CoreCache.transactionLookup()` call and the returned `CacheEntry` when has a state where `CacheState.mustInsertOrUpdate()` returns true.

**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`: `InsertOptions` — A set of options to used whilst performing this insertion into the cache.

**Returns**

`FastlyBody`

**Throws**

- `TypeError` if the provided `key` is an empty string, cannot be coerced to a string, or is longer than 8,135 characters.

### lookup

**Flags:** static  
**Source:** https://github.com/fastly/js-compute-runtime/blob/70cf30af4e657879b2d1e7eafab880e39e3a3f7d/types/cache.d.ts#L246

```javascript
static lookup(key: string, options?: LookupOptions): CacheEntry | null
```

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.

**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`: `LookupOptions` (optional) — A set of options to used whilst performing this lookup into the cache.

**Returns**

`CacheEntry | null`

**Throws**

- `TypeError` if the provided `key` is an empty string, cannot be coerced to a string, or is longer than 8,135 characters.

### transactionLookup

**Flags:** static  
**Source:** https://github.com/fastly/js-compute-runtime/blob/70cf30af4e657879b2d1e7eafab880e39e3a3f7d/types/cache.d.ts#L282

```javascript
static transactionLookup(key: string, options?: LookupOptions): TransactionCacheEntry
```

Perform a transactional lookup into the cache, returning a `TransactionCacheEntry` instance.

Transactions coordinate between concurrent actions on the same cache key, incorporating concepts of [request collapsing](https://developer.fastly.com/learning/concepts/request-collapsing/) and [revalidation](https://developer.fastly.com/learning/concepts/stale/), though at a lower level that does not automatically interpret HTTP semantics.

Request Collapsing:
If there are multiple concurrent calls to `CoreCache.transactionLookup()` for the same item and that item is not present,
just one of the callers will be instructed to insert the item into the cache as part of the transaction.
The other callers will block until the metadata for the item has been inserted, and can then begin streaming its contents out of the cache at the same time that the inserting caller streams them into the cache.

Revalidation:
Similarly, if an item is usable but stale, and multiple callers attempt a `CoreCache.transactionLookup()` concurrently, they will all be given access to the stale item, but only one will be designated to perform an asynchronous update (or insertion) to freshen the item in the cache.

**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`: `LookupOptions` (optional) — A set of options to used whilst performing this lookup into the cache.

**Returns**

`TransactionCacheEntry`

**Throws**

- `TypeError` if the provided `key` is an empty string, cannot be coerced to a string, or is longer than 8,135 characters.

### transactionLookupAsync

**Flags:** static  
**Source:** https://github.com/fastly/js-compute-runtime/blob/70cf30af4e657879b2d1e7eafab880e39e3a3f7d/types/cache.d.ts#L300

```javascript
static transactionLookupAsync(key: string, options?: LookupOptions): PendingTransaction
```

Issue a transactional lookup into the cache without blocking, returning a `PendingTransaction`.

This behaves like `CoreCache.transactionLookup()` (the same request collapsing and
revalidation semantics apply), except that the lookup itself does not block: instead of
returning a `TransactionCacheEntry` directly, it returns a `PendingTransaction` which can
be polled via `PendingTransaction.prototype.pending`, or resolved via
`PendingTransaction.prototype.wait`, optionally bounded by a timeout.

**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`: `LookupOptions` (optional) — A set of options to used whilst performing this lookup into the cache.

**Returns**

`PendingTransaction`

**Throws**

- `TypeError` if the provided `key` is an empty string, cannot be coerced to a string, or is longer than 8,135 characters.