@btravstack/cache

---

@btravstack/cache / index

index

Classes

Cache

Defined in: packages/cache/src/cache.ts:91

The port an application depends on.

Keys are plain strings and the caller composes them, tenant included: a namespace parameter would put a tenancy model in a package with no business holding one. A value is unknown in both directions, encoded by the adapter, and claiming what came back is the caller's.

Extends

• PortInstance<"Cache", CacheService>

Constructors

Constructor

new Cache(): Cache;

Defined in: packages/di/dist/index.d.mts:16

Returns

Cache

Inherited from

Port("Cache")<CacheService>.constructor

Properties

Property	Modifier	Type	Inherited from	Defined in
[ID]	readonly	"Cache"	Port("Cache").[ID]	packages/di/dist/index.d.mts:12
[SERVICE]	readonly	CacheService	Port("Cache").[SERVICE]	packages/di/dist/index.d.mts:13
portId	readonly	"Cache"	Port("Cache").portId	packages/di/dist/index.d.mts:17

---

CacheBackend

Defined in: packages/cache/src/cache.ts:101

The port every adapter provides, and the one an application never depends on.

di allows one provider per port per graph, so an instrumented composition cannot layer over a module that already provides Cache: an adapter provides this instead, and cache() is what turns it into Cache. Exported because a spec substituting an adapter overrides this port by name.

Extends

• PortInstance<"CacheBackend", CacheBackendService>

Constructors

Constructor

new CacheBackend(): CacheBackend;

Defined in: packages/di/dist/index.d.mts:16

Returns

CacheBackend

Inherited from

Port("CacheBackend")<CacheBackendService>.constructor

Properties

Property	Modifier	Type	Inherited from	Defined in
[ID]	readonly	"CacheBackend"	Port("CacheBackend").[ID]	packages/di/dist/index.d.mts:12
[SERVICE]	readonly	CacheBackendService	Port("CacheBackend").[SERVICE]	packages/di/dist/index.d.mts:13
portId	readonly	"CacheBackend"	Port("CacheBackend").portId	packages/di/dist/index.d.mts:17

---

CacheUnavailable

Defined in: packages/cache/src/cache.ts:16

The adapter could not answer. Modeled rather than thrown away, because whether an unreachable cache degrades to a miss or fails the request is the CALLER's decision.

Extends

• TaggedErrorInstance<"CacheUnavailable", { key: string; operation: "get" | "set" | "delete"; }>

Constructors

Constructor

new CacheUnavailable(args): CacheUnavailable;

Defined in: node_modules/.pnpm/unthrown@5.8.0/node_modules/unthrown/dist/index.d.mts:2034

Parameters

Parameter	Type
args	object & object

Returns

CacheUnavailable

Inherited from

TaggedError("CacheUnavailable")<{
  readonly operation: "get" | "set" | "delete";
  readonly key: string;
}>.constructor

Properties

Property	Modifier	Type	Inherited from	Defined in
_tag	readonly	"CacheUnavailable"	TaggedError("CacheUnavailable")._tag	node_modules/.pnpm/unthrown@5.8.0/node_modules/unthrown/dist/index.d.mts:2011
cause?	public	unknown	TaggedError("CacheUnavailable").cause	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es2022.error.d.ts:24
key	readonly	string	TaggedError("CacheUnavailable").key	packages/cache/src/cache.ts:18
message	public	string	TaggedError("CacheUnavailable").message	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1075
name	public	string	TaggedError("CacheUnavailable").name	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1074
operation	readonly	"get" | "set" | "delete"	TaggedError("CacheUnavailable").operation	packages/cache/src/cache.ts:17
stack?	public	string	TaggedError("CacheUnavailable").stack	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1076

Type Aliases

CacheBackendService

type CacheBackendService = object;

Defined in: packages/cache/src/cache.ts:22

What an adapter implements: the three operations, and nothing derived.

Properties

Property	Modifier	Type	Description	Defined in
delete	readonly	(key) => AsyncResult<void, CacheUnavailable>	Deleting a key nobody set is Ok: delete is idempotent.	packages/cache/src/cache.ts:31
get	readonly	(key) => AsyncResult<CacheHit | undefined, CacheUnavailable>	A miss is Ok(undefined): absence is the cache working, not failing.	packages/cache/src/cache.ts:24
set	readonly	(key, value, options?) => AsyncResult<void, CacheUnavailable>	-	packages/cache/src/cache.ts:25

---

CacheHit

type CacheHit = object;

Defined in: packages/cache/src/cache.ts:9

What a get answers when the key is there — a one-field record rather than the value, because a cached null and a key nobody set are different facts and undefined can only carry one of them.

Properties

Property	Modifier	Type	Defined in
value	readonly	unknown	packages/cache/src/cache.ts:9

---

CacheOptions

type CacheOptions<E, N> = object;

Defined in: packages/cache/src/module.ts:8

Type Parameters

Type Parameter
E
N

Properties

Property	Modifier	Type	Description	Defined in
adapter	readonly	Module<CacheBackend, E, N>	The adapter module: memoryCache() from this entry point, redisCache() from @btravstack/cache/redis, or one an application wrote itself over CacheBackend.	packages/cache/src/module.ts:14

---

CacheService

type CacheService = CacheBackendService & object;

Defined in: packages/cache/src/cache.ts:38

What an application reads: the adapter's three, plus the read-through every caller was writing by hand.

Type Declaration

Name	Type	Description	Defined in
getOrSet()	<T, E>(key, loader, options?) => AsyncResult<T, E>	Answer from the cache, or run loader and store what it produced. The degradation policy is decided here, once: an unavailable cache is a miss, so the loader runs and the caller sees the answer; a failed write is best effort, so the caller sees the value rather than the cache's problem. That is why CacheUnavailable is absent from the error channel — what is left is the loader's own E. A hit comes back as T by cast: the port stores unknown, and the caller owning the key's meaning is the same claim it was making at every call site before this method existed — made once, here.	packages/cache/src/cache.ts:52

---

MemoryCacheOptions

type MemoryCacheOptions = object;

Defined in: packages/cache/src/memory.ts:7

Properties

Property	Modifier	Type	Description	Defined in
clock?	readonly	Clock	What ttlMs is measured against. Defaults to the kernel's systemClock; a spec passes createFakeClock() so an expiry is asserted without a real wait.	packages/cache/src/memory.ts:13

Functions

cache()

function cache<E, N>(__namedParameters): Module<Cache | HealthChecks, E, N>;

Defined in: packages/cache/src/module.ts:38

The cache starter: an adapter, and Cache provided from it.

cache({ adapter: redisCache() });

Two ports, because di allows one provider per port per graph: the port an application depends on must not be the port an adapter provides, or the observed form could only be a layer over the plain one. CacheBackend is what an adapter targets, Cache what an application reads, and this function is the seam — which is also what a spec overrides to swap an adapter.

There is no instrumented flag, and that is the point. Every call is handed to whatever contributed to Observers; a graph that composed no observability has only this module's own no-op member, so it costs a call per operation and nothing else. What the observers do with it — a span carrying the key, a count whose result tells a hit from a miss, an error line — belongs to @btravstack/observability rather than here. Keys ride the attributes; values never do.

Type Parameters

Type Parameter
E
N

Parameters

Parameter	Type
__namedParameters	CacheOptions<E, N>

Returns

Module<Cache | HealthChecks, E, N>

---

memoryCache()

function memoryCache(options?): Module<CacheBackend, never, never>;

Defined in: packages/cache/src/memory.ts:65

The adapter as a module, which is the shape cache({ adapter }) takes.

Parameters

Parameter	Type
options	MemoryCacheOptions

Returns

Module<CacheBackend, never, never>

---

memoryCacheBackend()

function memoryCacheBackend(options?): CacheBackendService;

Defined in: packages/cache/src/memory.ts:30

The in-memory adapter's service, so a spec can drive it without a graph.

Expiry is lazy, checked on read rather than swept on a timer: a timer would keep the event loop alive, which a kernel built around a process that can end has no business doing. Nothing is serialised — the value comes back as the same reference, which is the honest difference from the Redis adapter rather than a deep-cloning fake that would hide a mutation bug.

ponytail: no eviction and no maximum size, so a process caching unbounded keys grows unbounded. The upgrade path is the Redis adapter.

Parameters

Parameter	Type
options	MemoryCacheOptions

Returns

CacheBackendService

---

memoryCacheProvider()

function memoryCacheProvider(options?): Provider<CacheBackend, never, never> & object;

Defined in: packages/cache/src/memory.ts:61

The adapter as a provider, which is the shape @btravstack/testing's overridden takes: a spec substitutes this for the Redis one under the application's real root, and every sibling provider still constructs.

Parameters

Parameter	Type
options	MemoryCacheOptions

Returns

Provider<CacheBackend, never, never> & object