Skip to content
AstilbaCache
Sponsor

API status

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

Astilba Cache is unreleased. The portable correctness kernel is active, while time-based expiry, convenience helpers, completion tracking, and production integrations remain incomplete.

Use this page as the preview ledger. “Implemented” means the behavior exists in the public source and is exercised by its test lanes; it does not mean the package has a supported installation or production runtime.

Use API reference for the complete exported surface. This page records implementation status and exceptions.

Configuration requirements

Section titled “Configuration requirements”
Requirement Current boundary
namespace, clock, rng Required by createCache().
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.
registry Required by expire(), delete(), and clear().
registry + bus Required together to build coordinated read validation. Supplying only one does not build the invalidation reader. L2 separately enables durable delta replay and remains required when a factory runs.

Implemented in the kernel

Section titled “Implemented in the kernel”
Surface Current behavior
createCache() Builds the cache facade, optional invalidation state, and retention registration from application-supplied drivers.
getOrSet() Reads L1 then L2 or fills a value with compatible in-isolate singleflight. A fenced terminal miss throws FencedError.
getOrSetEntry() Adds skip() and returns value, tier, stale, durability, skip, age, and optional error-serve metadata.
expire(), delete(), clear() Apply soft, hard, and namespace invalidation through a supplied Registry.
collect() Records required L3 tags and decides late-tag or byte/count budget eligibility at header commit. No supported framework adapter feeds it automatically.
compound() Produces unambiguous positional tags and rejects reserved user-tag prefixes at the cache boundary.
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.
Telemetry Emits plain events or HMAC-pseudonymizes hosted string fields when a salt is configured.

Scope resolution, negative-entry safety, serve-time stale revalidation, codec identity checks, classified L2 write failures, strong live checks on stored entries, eventual fail-closed behavior, and write-back fencing are also implemented.

Partial or provisional behavior

Section titled “Partial or provisional behavior”
Surface Current boundary
TTL, grace, and age Options and types exist, 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, so an omitted call option remains eventual.
notFoundTtl Its presence opts an HttpError with status 404 into a negative write, but the declared 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. 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 currently 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 in configuration, but the current read path still continues as a miss. RegistryUnavailableError is exported but not emitted.
collect() The standalone budget decision works. Cache hits do not automatically contribute tags, and no supported request adapter owns header commit.
Purge result matchedHint is always “unknown”; flushed() and edgePurged() resolve without tracking real completion.
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 the current 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.
Replication recovery Suspect reads can reactively replay contiguous L2 delta batches. The documented snapshot has no periodic poller and does not bridge a missing delta with a snapshot.
Cloudflare adapters KV, Coordinator, DO Registry, and mirror writes are implemented internally and tested under workerd, but are not supported package entry points.
Coordinator journal Durable and replayable, but still append-only without production checkpointing or truncation.

Throwing placeholders

Section titled “Throwing placeholders”

These value exports or methods currently throw NotImplementedError:

  • memory(), t, globalTag(), and duration()
  • expireAll(), deleteAll(), and explain()
  • FactoryCtx.reuseGraced()
  • 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:

  • FactoryCtx.dependsOn(), setTags(), and setTtl() are no-ops.
  • 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 supported Memory, Redis, CDN, production Bus, React Router, demo, or deployed-probe package path. The internal Cloudflare test worker is not an application template.

Section titled “Related”