LazyLayersv8.0.0
Reference

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
}
MethodBehavior
getThe value, or null when the key is missing or expired.
mgetValues in key order; null for misses. On Durable Objects: one call per object holding some of the keys.
setWrites 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).
delDeletes keys; returns how many existed (expired keys do not count).
delIfEqualsDeletes the key only while it holds value. Use it to release a lock you own.
incrAdds 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.
pttlMilliseconds until expiry; -1 for no expiry, -2 for missing.
pingtrue when the backend answers (every shard on Durable Objects).
cacheTierThe 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)

namespace(DurableObjectNamespace)required

The binding of a class that answers exec(op, args) with createCoordinationObject.

shards(number)default: 4

Number of objects keys are spread over (hash(key) % shards). Keep it fixed once keys exist.

locationHint(string)

Passed to namespace.get(); put the objects near the callers (for example apac).

objectName((index: number) => string)default: index => `coordinator-${index}`

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.

cacheBytes(number)default: 33554432

Byte budget of this object's in-memory cache tier (LRU).

cleanupIntervalMs(number)default: 600000

How often expired keys are removed.

table(string)default: lazy_layers_coordination

SQLite table name.

Returns { core, exec(op, args), alarm() }. exec accepts only the coordination operations; anything else is rejected.

mongoCoordination(options)

collection(() => Collection)required

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 }).

now(() => number)default: Date.now

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 }
limit(number)required
Requests allowed per window.
windowMs(number)required
Window length; the first request starts the window.
cost(number)default: 1
How much this request counts.

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.

ready(() => Promise<unknown>)
Resolves when the database is connected; the stream starts after it.
retry({ minDelayMs?, maxDelayMs? })default: { minDelayMs: 500, maxDelayMs: 30000 }
Backoff for reopening the stream after an error.

Needs a replica set. On a standalone server it reports disconnected once and stops retrying.

On this page