@btravstack/cache / index
index
Classes
Cache
Defined in: packages/cache/src/cache.ts:136
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:15
Returns
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:11 |
[SERVICE] | readonly | CacheService | Port("Cache").[SERVICE] | packages/di/dist/index.d.mts:12 |
portId | static readonly | "Cache" | Port("Cache").portId | packages/di/dist/index.d.mts:16 |
CacheBackend
Defined in: packages/cache/src/cache.ts:146
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:15
Returns
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:11 |
[SERVICE] | readonly | CacheBackendService | Port("CacheBackend").[SERVICE] | packages/di/dist/index.d.mts:12 |
portId | static readonly | "CacheBackend" | Port("CacheBackend").portId | packages/di/dist/index.d.mts:16 |
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.12.1/node_modules/unthrown/dist/index.d.mts:2386
Parameters
| Parameter | Type |
|---|---|
args | object & object |
Returns
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.12.1/node_modules/unthrown/dist/index.d.mts:2363 |
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:36 |
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> | An adapter reached through Cache is handed whole milliseconds or nothing — readThrough reads ttlMs once for every adapter, so none of them has to decide what a zero, a fraction or a NaN means. | packages/cache/src/cache.ts:30 |
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:43
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. A ttlMs that is not at least a whole millisecond means the value is not stored — see readThrough — so the loader's answer still reaches the caller. 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:60 |
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
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