Skip to content
AstilbaCache
Sponsor

Implementation status

Check which Astilba Cache methods, helpers, drivers, and adapters work in the current unreleased source build.

Astilba Cache is unreleased. The portable correctness kernel and the main Workers source path are active. React Router now provides scope-aware L3 dependency collection and response tags, while elapsed-time policy, CDN purge delivery, several convenience methods, and production release gates remain incomplete.

Use this page as the preview ledger. “Implemented” means behavior exists on public main and is exercised by the repository’s test lanes. It does not mean the package has an npm installation or production support commitment.

Use API reference for exact exported shapes. When another page and this ledger appear to differ, follow this page and report the stale page.

Configuration requirements

Section titled “Configuration requirements”
Requirement Current boundary
namespace, clock, rng Required by raw createCache(). createWorkersCache() supplies Clock and Rng.
l2 Required when a read must run its factory. Without L2, a fill throws NotImplementedError.
l1 Optional. Required if principal-derived, L1-only values should survive beyond the current call. The Workers factory supplies bounded memory().
registry Required by expire(), delete(), and clear().
registry + bus + l2 Required for coordinated read validation and mirror recovery. Registry plus Bus without L2 throws at construction.
Workers bindings createWorkersCache() requires a stable name, KV namespace, and Coordinator Durable Object namespace. The Coordinator separately requires the same KV namespace under REGISTRY_KV.

Implemented in the root API

Section titled “Implemented in the root API”
Surface Current behavior
createCache() Builds the cache facade, optional invalidation reader and poller, and retention registration from supplied drivers.
getOrSet() Reads L1 then L2 or fills a value with compatible in-isolate singleflight. A terminal fenced fill throws FencedError.
getOrSetEntry() Adds skip() and returns value, tier, stale, durability, skip, age, and optional error-serve metadata.
Strong reads and fills Live-check stored entries and pre-check strong misses when coordinated invalidation is configured. A verified mid-fill hard purge can trigger a bounded re-mint and refetch.
expire(), delete(), clear() Apply soft, hard, and namespace invalidation through a supplied Registry.
collect() Records explicit dependencies and decides scope, timing, and byte/count budget eligibility at header commit. React Router binds it per request so served hits and fills contribute tags and scope evidence automatically.
explain() Witnesses a default-public key in L1 then L2, its stored identity, current local invalidation verdict and reader state, and any request-scoped render attribution. Missing, undecodable, or codec-incompatible entries are reportable misses.
Factory dependency tags setTags() replaces the call-level base and dependsOn() adds memberships. The validated settle-time union is stored and used by render collection and write-back fencing.
memory() Provides a bounded per-instance LRU Store. It enforces maxEntries, UTF-8 maxBytes, and Store-level expiry when constructed with a Clock.
t, compound() Build branded tags. t validates the complete final grammar and byte budget; compound() provides positional delimiter escaping.
duration() Builds computed duration strings and rejects non-positive, non-finite, fractional-millisecond, or unsafe products with InvalidDurationError.
httpError(), isRetriableHttp() Preserve HTTP status information and implement the default stale-on-error classifier.
Custom Codec and Lock Participate in decode safety, fill identity, cross-isolate exclusion, and write arbitration when supplied.
Telemetry Uses the exported TELEMETRY_EVENTS catalog, emits plain events or HMAC-pseudonymizes hosted string fields, and isolates sink throws or rejections with optional onSinkError.

Scope resolution, negative-entry safety, serve-time stale revalidation, codec identity checks, classified L2 write failures, eventual fail-closed behavior, snapshot-capable recovery, and write-back fencing are also implemented.

Implemented source adapters

Section titled “Implemented source adapters”
Entry point Current behavior
@astilba/cache/cloudflare Exports createWorkersCache, cloudflareKV, Coordinator, doRegistry, doBus, redialingDoBus, and their public configuration types.
@astilba/cache/react-router Exports root server middleware, typed Cache context, current request access, default L3 budget and ineligibility event constants, and the observable poll-tick event and interval constants.
Recovery poller Observes pointer liveness, runs bounded delta and snapshot recovery, and backs baseline polling off on failure. React Router drives it with request-piggyback ticks.

These subpaths are present in the source and publish export map, but no package has been published.

Partial or provisional behavior

Section titled “Partial or provisional behavior”
Surface Current boundary
TTL, grace, and age Duration builders work, but stored timing fields are zero, elapsed expiry is not enforced, and entry age is always zero. Defaults for TTL and grace are not applied.
Default consistency Per-call consistency works. defaults.consistency is declared but not consumed by the raw read path, so an omitted call option remains eventual.
notFoundTtl Its presence opts an HttpError 404 into a negative write, but the duration is not enforced. Negative entries remain excluded from grace and stale-on-error.
Eventual stale refresh The stale value is returned, but refresh work is currently awaited before that response resolves. Background adoption, queue retry, and latency decoupling are incomplete.
Factory cancellation and grace context The factory receives a fresh AbortSignal, but the kernel does not abort it on a cache deadline. ctx.graced is not populated.
Entry durability metadata Origin fills report private or suppressed L2 writes as durable: false. Existing L1/L2 hit paths report true unconditionally, so hit-level durability is not proof that a shared copy exists.
Unknown error posture unknownPolicy: “error” and takedownSensitive select an error resolution, but the read path still continues as a miss. RegistryUnavailableError is exported but not emitted.
compound() validation Positional escaping works, but compound parts do not receive t’s remaining character or 256-byte validation in current main. Keep parts grammar-safe.
React Router response caching Automatic dependency and scope collection, Cache-Tag emission, safe private demotion, immutable-response rebuilding, and an overridable 16 KB / 1,000-occurrence budget work. The middleware never invents public or s-maxage; the application must opt into shared caching.
Factory response qualifier FactoryCtx.dependsOn(tag, { l3: false }) throws until stored per-tag emission metadata exists. The same qualifier works on RenderCollector.dependsOn().
Explain scope and authority explain(key) addresses only the default public canonical key. It uses current local knowledge and performs no live check, resync, or L1 hydration.
Telemetry catalog registry_degraded and state_stale are reserved names with no emit sites. The Workers factory does not expose telemetry for its internally constructed memory L1.
Purge result matchedHint is always “unknown”; flushed() and edgePurged() resolve without tracking the promised completion boundaries.
Key invalidation { key } targets the contextless public canonical key only. Use dependency tags for tenant or principal-derived variants.
Scope-qualified tag selectors The selector type accepts scope, but Registry tag resolution ignores it. A tag purge affects every entry carrying that tag.
Lock option lock: true uses a configured Lock; without one it silently continues without cross-isolate locking. No production Lock adapter is exported.
Coordinator journal Durable and replayable, but append-only without production checkpointing or truncation.
Workers measurements Workerd lanes cover behavior, but deployed consistency and caching measurements are still pending.

defaults.maxEntryRetention, maxSyncLag, and heartbeatInterval are consumed. maxSyncLag tunes the attached recovery poller; heartbeatInterval tunes the reader’s silence threshold and must be coordinated separately with the Coordinator deployment variable.

Throwing placeholders

Section titled “Throwing placeholders”

These exports or paths currently throw NotImplementedError:

  • globalTag()
  • expireAll() and deleteAll()
  • FactoryCtx.reuseGraced()
  • FactoryCtx.setTtl()
  • FactoryCtx.dependsOn(tag, { l3: false })
  • a factory fill with no L2 Store
  • expire(), delete(), or clear() without a Registry

Declared but inert surfaces

Section titled “Declared but inert surfaces”

These APIs currently return normally or exist in the types but do not apply their intended behavior:

  • CacheConfig.cdn and the cdn mode on delete() do not invoke a CDN driver.
  • defaults.graceBackoff and defaults.onUnavailable are not consumed.
  • Tier includes “l1.5”, but the current read path does not emit it.

expireAll() and deleteAll() still require their explicit origin-load guard at the type level, but the methods do not run yet.

Integrations not present

Section titled “Integrations not present”

There is no Redis or Valkey adapter, production Lock, CDN purge path, chaos demo, or deployed-probe package. React Router is the only shared-response adapter, and its fixture plus the Cloudflare integration Worker are tests, not templates.

Section titled “Related”