All Symbols - cache documentation

Examples

Basic usage

import { Cache, createInMemory } from "@anabranch/cache";

const cache = await Cache.connect(createInMemory()).run();

await cache.set("user:1", { name: "Alice" }, { ttl: 60_000 }).run();
const user = await cache.get<{ name: string }>("user:1").run();

Cache-aside pattern

const user = await cache.getOrSet<User>(
  `user:${id}`,
  () => db.query("SELECT * FROM users WHERE id = ?", [id]),
  { ttl: 60_000 },
).run();

Classes

c

Cache(adapter: CacheAdapter)

Cache wrapper with Task semantics for composable error handling.

close(): Task<void, CacheCloseFailed>
Release the connection.
connect(connector: CacheConnector): Task<Cache, CacheConnectionFailed>
Connect to a cache via a connector.
delete(key: string): Task<void, CacheDeleteFailed>
Remove a key. No error if the key does not exist.
get<T>(key: string): Task<T | null, CacheGetFailed>
Retrieve a value by key. Returns null on cache miss.
getOrSet<T>(
key: string,
fn: () => Promisable<T>,
options?: SetOptions
): Task<T, CacheGetFailed | CacheSetFailed>
Get a value, or compute and store it on cache miss.
has(key: string): Task<boolean, CacheGetFailed>
Check whether a key exists.
set(
key: string,
value: unknown,
options?: SetOptions
): Task<void, CacheSetFailed>
Store a value with an optional TTL.

c

CacheCloseFailed(

message: string,

cause?: unknown

)

Close operation failed.

c

CacheConnectionFailed(

message: string,

cause?: unknown

)

Connection establishment failed.

c

CacheDeleteFailed(

Delete operation failed.

c

CacheError(message: string)

Base error for all cache-related failures.

c

CacheGetFailed(

Get operation failed.

c

CacheSetFailed(

Set operation failed.

Functions

f

createInMemory(): InMemoryConnector

Creates an in-memory cache connector for testing and development.

Interfaces

I

CacheAdapter

Cache adapter interface for cache-agnostic operations.

close(): Promise<void>
Release any resources held by this adapter instance.
delete(key: string): Promise<void>
Remove a key. No error if the key does not exist.
get(key: string): Promise<unknown | null>
Retrieve a value by key. Returns null if the key does not exist or has expired.
has(key: string): Promise<boolean>
Check whether a key exists and has not expired.
set(
key: string,
value: unknown,
options?: SetOptions
): Promise<void>
Store a value with an optional TTL in milliseconds.

I

CacheConnector

Connector that produces connected CacheAdapter instances.

connect(signal?: AbortSignal): Promise<CacheAdapter>
Acquire a connected adapter.
end(): Promise<void>
Close all connections and clean up resources.

I

InMemoryConnector

In-memory cache connector.

I

SetOptions

Options for set operations.

ttl: number
Time-to-live in milliseconds. When omitted the entry does not expire.