# @agoric/cache

> Agoric's simple cache interface

Latest version **0.4.0** (published 2026-04-08) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @agoric/cache
pnpm add @agoric/cache
yarn add @agoric/cache
bun add @agoric/cache
```

## Health

**Score 55/100 (C)** — status: active.

Positive: esm support; no vulnerabilities; high maintenance score.

Warnings: low downloads; no types; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.4.0 |
| Published | 2026-04-08 |
| First published | 2022-06-08 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Node | ^20.9 \|\| ^22.11 |
| Dependencies | 6 |
| Unpacked size | 37.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 357 |
| Author | Agoric |
| Maintainers | warner, erights, mhofman, michaelfig, kriskowal, agoricbot, mujahidkay, gibson042, jimlarson, samsiegart |

## Links

- npm: https://www.npmjs.com/package/@agoric/cache
- Repository: https://github.com/Agoric/agoric-sdk
- npm.io page: https://npm.io/package/@agoric/cache

## Dependencies (6)

- [@endo/far](https://npm.io/package/@endo/far.md) ^1.1.14
- [@agoric/store](https://npm.io/package/@agoric/store.md) 0.10.0
- [@endo/marshal](https://npm.io/package/@endo/marshal.md) ^1.8.0
- [@agoric/internal](https://npm.io/package/@agoric/internal.md) 0.4.0
- [@agoric/notifier](https://npm.io/package/@agoric/notifier.md) 0.7.0
- [@agoric/vat-data](https://npm.io/package/@agoric/vat-data.md) 0.6.0

## Recent versions

- 0.4.0 (latest) — 2026-04-08
- 0.3.3-dev-8656b52.0.8656b52 (dev) — 2026-09-09
- 0.5.0-upgrade-23-dev-224776f.0.224776f (upgrade-23-dev) — 2026-08-12
- 0.5.0-u23.1 (agoric-upgrade-23) — 2026-07-20
- 0.4.1-upgrade-22-dev-0922d04.0.0922d04 (upgrade-22-dev) — 2026-04-08
- 0.3.3-other-dev-d15096d.0.d15096d (other-dev) — 2025-11-13
- 0.4.0-u22.2 (agoric-upgrade-22) — 2025-09-09
- 0.3.3-u21.0.1 (agoric-upgrade-21) — 2025-07-29
- 0.3.3-ymax-v0.2-alpha-dev-8e37faa.0 (ymax-v0.2-alpha-dev) — 2025-07-21
- 0.3.3-upgrade-21-dev-16519b2.0 (upgrade-21-dev) — 2025-06-19
- 0.3.3-u21.0 (community-dev) — 2025-06-19
- 0.3.3-upgrade-19-devnet-dev-5428c4d.0 (upgrade-19-devnet-dev) — 2025-04-24
- 0.3.3-upgrade-20-dev-ef71cfd.0 (upgrade-20-dev) — 2025-04-17
- 0.3.3-u20.0 (agoric-upgrade-20) — 2025-04-17
- 0.3.3-upgrade-19-dev-5428c4d.0 (upgrade-19-dev) — 2025-03-13
- … 2994 more at https://npm.io/package/@agoric/cache/versions

## README

# Agoric Cache

This cache mechanism allows a cache client function to synchronize with a cache
backend.  Any passable object can be a cache key or a cache value.

## Demo

```js
import { makeCache, makeScalarStoreCoordinator } from '@agoric/cache';
import { M } from '@agoric/store';
import { makeScalarBigMapStore } from '@agoric/vat-data';

const store = makeScalarBigMapStore('cache');
const coordinator = makeScalarStoreCoordinator(store);
const cache = makeCache(coordinator);

// Direct value manipulation.
await cache('baz'); // undefined
await cache('baz', 'barbosa'); // 'barbosa'

// Match-and-set.
await cache('baz', 'babaloo', undefined); // 'barbosa'
await cache('baz', 'babaloo', 'barbosa'); // 'babaloo'

// One-time initialization.
await cache('frotz', 'default'); // 'default'
await cache('frotz', 'ignored'); // 'default'

// Update the `'foo'` entry, using its old value (initially `undefined`).
await cache('foo'); // `undefined`
const updater = (oldValue = 'bar') => `${oldValue}1`;
await cache('foo', updater, M.any()); // 'bar1'
await cache('foo', updater, M.any()); // 'bar11'
await cache('foo'); // 'bar11'

// You can also specify a guard pattern for the value to update.  If it
// doesn't match the latest value, then the cache isn't updated.
await cache('foo', updater, 'nomatch'); // 'bar11'
await cache('foo', updater, 'bar11'); // 'bar111'
await cache('foo', updater, 'bar11'); // 'bar111'
await cache('foo'); // 'bar111'
```

## Cache client

The client-side API is normally exposed as a single function named `cache`.  You
can create a cache client function by running `makeCache(coordinator,
follower)`.  If not specified, the default coordinator is just a local in-memory
map without persistence.

- the ground state for a cache key value is `undefined`.  It is impossible to distinguish a set value of `undefined` from an unset key
- `cache(key, (oldValue) => ERef<newValue>, guardPattern?): Promise<newValue>` -
  transactionally updates the value of `key` from a value matched by `guardPattern`
  to the results of sanitizing the result of calling the updater function with
  that value. Retries all three steps (read current value, attempt match, call updater),
  if the transaction is stale. `guardPattern` defaults to matching only `undefined`.
  Returns the current value after any resulting update.
- `cache(key, passable, guardPattern?): Promise<newValue>` -
  same as above with an updater function that ignores arguments and returns
  `passable` (e.g., `() => passable`).

## Cache coordinator

The cache coordinator must implement the `Coordinator` interface, which supports
eventual consistency with optimistic updates:

```ts
interface Updater {
  /**
   * Calculate the newValue for a given oldValue
   */
  update: (oldValue: Passable) => unknown
}

interface Coordinator {
  /**
   * Read an eventually-consistent value for the specified key.
   */
  getRecentValue: (key: Passable) => Promise<Passable>,
  /**
   * Update a cache value to newValue, but only if guardPattern matches the current value.
   */
  setCacheValue: (key: Passable, newValue: Passable, guardPattern: Pattern) => Promise<Passable>,
  /**
   * Update a cache value via an updater calculation of newValue, but only if guardPattern
   * matches the current value.
   */
  updateCacheValue: (key: Passable, updater: ERef<Updater>, assertedMatch: Matcher) => Promise<Passable>,
}
```

---
_Source: https://npm.io/package/@agoric/cache · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._