0.3.3-u13.0 • Published 3 months ago

@agoric/cache v0.3.3-u13.0

Weekly downloads
-
License
Apache-2.0
Repository
github
Last release
3 months ago

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

import { makeCache, makeStoreCoordinator } from '@agoric/cache';
import { makeScalarBigMapStore } from '@agoric/vat-data';

const store = makeScalarBigMapStore('cache');
const coordinator = makeStoreCoordinator(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'


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

// You can also assert a pattern for the key.  If it doesn't match, then the cache returns a rejection.
await cache('foo', updater, 'nomatch'); // 'bar11'
await cache('foo', updater, 'bar11'); // 'bar111'
await cache('foo', updater, 'bar11'); // 'bar111'
await cache('foo'); // 'bar111'

// Specify a pattern of `undefined` for one-time initialisation.
await cache('frotz', 'default', undefined); // 'default'
await cache('frotz', 'ignored', undefined); // 'ignored'

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): Promise<recentValue> - get an eventually-consistent value for key
  • cache(key, (oldValue) => ERef<newValue>): Promise<newValue> - call the updater function transactionally with the current value of key, and update it to newValue. Rerun the updater function with a new value if the transaction is stale.
  • cache(key, (oldValue) => ERef<newValue>, guardPattern): Promise<newValue> - same as above, but only update the cache if guardPattern matches the current value. Return the updated value, or the value that matches guardPattern.

Cache coordinator

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

interface State {
  // State updates must include a generation counter exactly one
  // greater than the current state, or they are not applied.
  generation: bigint,
  // Any acceptable value supported by the cache.
  value: any,
};

// The default state for a key that has not yet been updated.
const GROUND_STATE = { generation: 0n, value: undefined };

interface Coordinator {
  /**
   * Read an eventually-consistent state for the specified key.
   */
  getRecentState: (key: unknown) => Promise<State>,
  /**
   * Attempt to update the key to the new state.  Returns the latest known
   * state after trying to apply the desiredState (may not match).
   */
  tryUpdateState: (key: unknown, desiredState: State, assertedMatch: Matcher) => Promise<State>,
}
0.3.3-u13.0

5 months ago

0.3.3-u12.0

6 months ago

0.3.3-dev-35576e9.0

10 months ago

0.3.3-dev-857e650.0

10 months ago

0.3.3-dev-f5f34f4.0

10 months ago

0.3.3-dev-b6b074d.0

10 months ago

0.3.3-dev-648d42f.0

10 months ago

0.3.3-u11wf.0

7 months ago

0.3.3-dev-6e5b422.0

10 months ago

0.3.3-dev-55ccfd2.0

10 months ago

0.3.3-dev-bcca849.0

10 months ago

0.3.3-dev-e96a12a.0

10 months ago

0.3.3-dev-aa8b3a1.0

10 months ago

0.3.3-dev-3c22e86.0

10 months ago

0.3.3-dev-22cbeb1.0

10 months ago

0.3.3-dev-af62279.0

10 months ago

0.3.3-dev-1303537.0

10 months ago

0.3.3-dev-e90f87b.0

10 months ago

0.3.3-dev-dfc712f.0

10 months ago

0.3.3-dev-bd1190d.0

10 months ago

0.3.3-dev-c50ca19.0

10 months ago

0.3.3-dev-ff1e301.0

10 months ago

0.3.3-dev-5382a55.0

10 months ago

0.3.3-u11.0

8 months ago

0.3.3-dev-284e2db.0

10 months ago

0.3.3-dev-6f740a4.0

10 months ago

0.3.3-dev-fb922d3.0

10 months ago

0.3.3-dev-afe8a6e.0

10 months ago

0.3.3-dev-6c6b5a0.0

10 months ago

0.3.3-dev-f010e07.0

10 months ago

0.3.3-dev-a6737cd.0

10 months ago

0.3.3-dev-b05c226.0

11 months ago

0.3.3-dev-696f0a8.0

11 months ago

0.3.3-dev-3a87a12.0

11 months ago

0.3.3-dev-657b621.0

11 months ago

0.3.3-dev-3ae8bfc.0

11 months ago

0.3.3-dev-3c781f6.0

11 months ago

0.3.1-dev-f9596b4.0

11 months ago

0.3.3-dev-b020abe.0

11 months ago

0.3.1-dev-13c169c.0

11 months ago

0.3.3-dev-ff36f02.0

11 months ago

0.3.3-dev-6bce049.0

10 months ago

0.3.3-dev-8c14632.0

11 months ago

0.3.1-dev-c2ae5c0.0

11 months ago

0.3.3-dev-779b73d.0

11 months ago

0.3.3-dev-c50674b.0

11 months ago

0.3.3-dev-2043349.0

11 months ago

0.3.3-dev-26028d4.0

11 months ago

0.3.2

11 months ago

0.3.1-dev-72b0aa9.0

11 months ago

0.3.3-dev-d589873.0

11 months ago

0.3.3-dev-3f11ae4.0

11 months ago

0.3.3-dev-2c5dd59.0

11 months ago

0.3.3-dev-4989f26.0

11 months ago

0.3.3-dev-51ee28f.0

11 months ago

0.3.3-dev-6fece09.0

11 months ago

0.3.1-dev-3b12eb6.0

11 months ago

0.3.3-dev-590740f.0

11 months ago

0.3.1-dev-80bdc60.0

11 months ago

0.3.3-dev-5736604.0

11 months ago

0.3.3-dev-2baa932.0

10 months ago

0.3.3-dev-046eb05.0

11 months ago

0.3.3-dev-39b1586.0

11 months ago

0.3.3-dev-dcddffd.0

10 months ago

0.3.3-dev-48da763.0

10 months ago

0.3.3-dev-13050c2.0

11 months ago

0.3.1-dev-acefd94.0

11 months ago

0.3.3-dev-3353509.0

11 months ago

0.3.3-dev-056a064.0

11 months ago

0.3.3-dev-f581a7e.0

11 months ago

0.3.3-dev-b8d6697.0

11 months ago

0.3.3-dev-9f34f9d.0

11 months ago

0.3.3-dev-4b79eb6.0

11 months ago

0.3.3-dev-69236fd.0

11 months ago

0.3.1-dev-d42f8d0.0

11 months ago

0.3.3-dev-dd19d79.0

11 months ago

0.3.3-dev-7632299.0

11 months ago

0.3.3-dev-8690eb0.0

11 months ago

0.3.1-dev-effbf7f.0

11 months ago

0.2.4-dev-09561e3.0

12 months ago

0.2.4-dev-a9d6a3b.0

12 months ago

0.2.4-dev-84f6373.0

12 months ago

0.3.1-dev-4a0bf28.0

11 months ago

0.2.4-dev-f5c3733.0

12 months ago

0.2.4-dev-cfa270b.0

12 months ago

0.2.4-dev-05bd95f.0

12 months ago

0.2.4-dev-35e5e30.0

12 months ago

0.2.4-dev-69003e6.0

12 months ago

0.3.1-dev-bf4b59f.0

12 months ago

0.2.4-dev-82bd133.0

12 months ago

0.2.4-dev-feb253e.0

12 months ago

0.2.4-dev-2788f8d.0

12 months ago

0.2.4-dev-3fa74c5.0

12 months ago

0.2.4-dev-76a3231.0

12 months ago

0.2.4-dev-f75cfb8.0

12 months ago

0.2.4-dev-acc2db2.0

12 months ago

0.2.4-dev-fa4a08d.0

12 months ago

0.2.4-dev-9cebd87.0

12 months ago

0.2.5-dev-800c2bb.0

12 months ago

0.2.5-dev-d32a66a.0

12 months ago

0.2.4-dev-6a45c15.0

12 months ago

0.3.1-dev-74a0763.0

11 months ago

0.2.4-dev-e9260d3.0

12 months ago

0.3.0

12 months ago

0.3.1

11 months ago

0.2.4-dev-ab7a341.0

12 months ago

0.2.4-dev-ffb9433.0

12 months ago

0.2.4-dev-fb9d18f.0

12 months ago

0.2.4-dev-c0b16c2.0

12 months ago

0.2.4-dev-606cbd2.0

12 months ago

0.2.4-dev-b1a7a3a.0

12 months ago

0.2.4-dev-f25bc81.0

12 months ago

0.2.4-dev-02e99df.0

12 months ago

0.2.4-dev-ab850a4.0

12 months ago

0.2.4-dev-eb9fb38.0

12 months ago

0.2.4-dev-8c6e4b2.0

12 months ago

0.2.4-dev-720a16f.0

12 months ago

0.2.4-dev-8d17cce.0

12 months ago

0.2.4-dev-09b993a.0

12 months ago

0.2.4-dev-c7c58c9.0

12 months ago

0.2.4-dev-0fc1914.0

12 months ago

0.2.4-dev-5a3d014.0

12 months ago

0.3.1-dev-fb2c249.0

11 months ago

0.2.4-dev-f6a48fd.0

12 months ago

0.2.4-dev-fa1e841.0

12 months ago

0.2.4-dev-dd5d004.0

12 months ago

0.3.1-dev-bf164a0.0

12 months ago

0.2.4-dev-eb0553c.0

12 months ago

0.2.4-dev-03d1e1c.0

12 months ago

0.2.4-dev-930595b.0

12 months ago

0.2.4-dev-ca22069.0

12 months ago

0.2.4-dev-177d1e6.0

12 months ago

0.2.4-dev-9d23380.0

12 months ago

0.2.4-dev-e816b60.0

12 months ago

0.2.4-dev-73ca139.0

12 months ago

0.2.4-dev-0a2843b.0

12 months ago

0.2.4-dev-0ce9545.0

12 months ago

0.2.4-dev-628de13.0

12 months ago

0.2.4

1 year ago

0.2.3

2 years ago

0.2.1

2 years ago

0.2.2

2 years ago

0.2.0

2 years ago