Coordination
lazy-layers-cache/coordination: shared keys, locks, counters, rate limits, a shared cache tier and invalidation buses without Redis.
import {
durableObjectCoordination, mongoCoordination, localCoordination,
createCoordinationObject, createCoordinationCore, memoryCoordinationStorage, sqliteCoordinationStorage,
consumeRateLimit, RemoteCacheStore, BroadcastEventBus, MongoChangeStreamEventBus,
} from 'lazy-layers-cache/coordination'Available in ESM and CommonJS from 0.7.0. The entry point loads no Redis, NATS, RabbitMQ or native codec code. For when to use which backend, see Without Redis.
The Coordination API
Every backend returns an object with this interface. All methods are asynchronous and atomic.
interface Coordination {
readonly backend: string // 'durable-objects' | 'mongo' | 'memory'
get(key: string): Promise<string | null>
mget(keys: string[]): Promise<(string | null)[]>
set(key: string, value: string, options?: { ttlMs?: number; ifAbsent?: boolean }): Promise<boolean>
del(keys: string[]): Promise<number>
delIfEquals(key: string, value: string): Promise<boolean>
incr(key: string, options?: { by?: number; ttlMs?: number }): Promise<{ value: number; expiresAt: number | null }>
pttl(key: string): Promise<number>
ping(): Promise<boolean>
cacheTier(): CoordinationCacheTier | null
}| Method | Behavior |
|---|---|
get | The value, or null when the key is missing or expired. |
mget | Values in key order; null for misses. On Durable Objects: one call per object holding some of the keys. |
set | Writes the value. With ttlMs the key expires; without it, it never does. With ifAbsent: true it writes only if the key does not exist and returns false otherwise (a lock). |
del | Deletes keys; returns how many existed (expired keys do not count). |
delIfEquals | Deletes the key only while it holds value. Use it to release a lock you own. |
incr | Adds by (default 1, a safe integer) to an integer key. A missing or expired key starts at 0 and takes ttlMs as its expiry; an existing key keeps its expiry. Rejects a non-integer value. |
pttl | Milliseconds until expiry; -1 for no expiry, -2 for missing. |
ping | true when the backend answers (every shard on Durable Objects). |
cacheTier | The shared byte cache (Durable Objects and memory), or null (MongoDB). |
Values are strings. Store JSON with JSON.stringify when you need structure.
Backends
durableObjectCoordination(options)
The binding of a class that answers exec(op, args) with createCoordinationObject.
Number of objects keys are spread over (hash(key) % shards). Keep it fixed once keys exist.
Passed to namespace.get(); put the objects near the callers (for example apac).
Object names per shard.
Reads (get, mget, pttl, cache reads, ping) are retried once after a retryable Durable Object error. Writes are not retried, because a failed write may still have been applied.
createCoordinationObject(ctx, options)
The inside of the Durable Object class. Keys are stored in ctx.storage.sql (a SQLite-backed class is required). An alarm removes expired keys every cleanupIntervalMs while any key can expire.
Byte budget of this object's in-memory cache tier (LRU).
How often expired keys are removed.
SQLite table name.
Returns { core, exec(op, args), alarm() }. exec accepts only the coordination operations; anything else is rejected.
mongoCoordination(options)
The collection of { _id: key, v, exp } documents. Called on every operation, so it may throw while the database is not connected. Create a TTL index: createIndex({ exp: 1 }, { expireAfterSeconds: 0 }).
Clock, for tests.
Locks use a conditional upsert (a live key makes the insert collide on _id). Counters use one pipeline findOneAndUpdate; concurrent first increments of the same key are retried. There is no cache tier.
localCoordination(core) · createCoordinationCore(storage, options)
createCoordinationCore is the synchronous engine every backend shares. localCoordination wraps it as an asynchronous Coordination for one process or for tests. Storage adapters: memoryCoordinationStorage() and sqliteCoordinationStorage(sql, table?).
consumeRateLimit(coordination, key, options)
Fixed-window rate limiting with one atomic increment per call.
const result = await consumeRateLimit(coordination, `rl:login:${ip}`, { limit: 5, windowMs: 60_000 })
// { allowed, count, limit, remaining, resetAt }RemoteCacheStore
A CacheStore on a CoordinationCacheTier, for LazyLayersCache's l2. Values use the portable serializer, as the Cloudflare KV stores do.
new RemoteCacheStore(coordination.cacheTier(), { ttlMs: 30_000 })Event buses
Both implement the EventBus contract, report subscribed / disconnected through onStatus, and deliver at most once. An event that cannot be decoded makes LazyLayers reconcile L1.
BroadcastEventBus
new BroadcastEventBus({ send: (payload: Uint8Array) => Promise<void>, transport?: string })publish(event) encodes the event and calls send(payload). Your transport delivers the bytes to the other instances, which call bus.deliver(payload). Durable Object RPC between shards is the intended transport.
MongoChangeStreamEventBus
new MongoChangeStreamEventBus({ collection, ready?, source?, retry?, onError? })publish(event) inserts { payload, source, at }. Every instance watches the collection and receives the other instances' events. Give the collection a TTL index on at.
Needs a replica set. On a standalone server it reports disconnected once and stops retrying.