@samveys/cache

# cache Function

The `@samveys/cache` plugin: binds `'cache'` (the {@link CacheManager}); stores open on first use.

function cache(config: CacheConfig): import("@samveys/core").Plugin<CacheConfig<string>>;

Exported from packages/cache/src/plugin.ts

# createCacheManager Function

Builds the `'cache'` binding from a configuration. Stores are created on first use.

function createCacheManager(config: CacheConfig): CacheManager;

Exported from packages/cache/src/manager.ts

# createDatabaseStore Function

A store in a SQL table (`key` primary, `value` JSON text, `expires_at` ms). The table is created on first use. `add` is an INSERT and a unique violation means "exists", so locks work across processes sharing the database. Every read-modify-write is a compare-and-swap on the stored text, so no statement depends on dialect-specific SQL.

function createDatabaseStore(options: DatabaseStoreOptions): CacheStore;

Exported from packages/cache/src/stores.ts

# createFailoverStore Function

Tries each store in order; the first that answers wins. When all fail: SVS_E097.

function createFailoverStore(stores: readonly CacheStore[]): CacheStore;

Exported from packages/cache/src/stores.ts

# createFunnel Function

Creates a funnel: at most `limit` concurrent runs, each holding one of `limit` slot locks.

function createFunnel(store: CacheStore, name: string, options: FunnelOptions): Funnel;

Exported from packages/cache/src/manager.ts

# createLock Function

Creates a lock on `store`. Each call has a fresh owner token, so only the acquirer can release.

function createLock(store: CacheStore, name: string, ttlMs: number): Lock;

Exported from packages/cache/src/manager.ts

# createMemoryStore Function

An in-process store: a `Map` with expiry. Values are structured-cloned on the way in and out.

function createMemoryStore(): CacheStore;

Exported from packages/cache/src/stores.ts

# databaseStore Function

Config for a SQL-table store; share the table between processes to share locks.

function databaseStore(options: DatabaseStoreOptions): StoreConfig;

Exported from packages/cache/src/stores.ts

# defineCacheConfig Function

Identity helper that types the store names of a cache configuration.

function defineCacheConfig<const Stores extends Readonly<Record<string, StoreConfig>>>(config: {

Exported from packages/cache/src/manager.ts

# failoverStore Function

Config for a failover chain of other stores, by configured name or inline config.

function failoverStore(stores: readonly (string | StoreConfig)[]): StoreConfig;

Exported from packages/cache/src/stores.ts

# memoryStore Function

Config for an in-process store.

function memoryStore(): StoreConfig;

Exported from packages/cache/src/stores.ts

# CacheConfig Interface

Configuration of `cache()`.

interface CacheConfig<Names extends string = string> {
    /** The store used by `cache.get()`, `cache.lock()` and friends. */
    readonly default: Names;
    readonly stores: Readonly<Record<Names, StoreConfig>>;
}

Exported from packages/cache/src/contracts.ts

# CacheManager Interface

The `'cache'` container binding.

interface CacheManager extends CacheStore {
    /** The names of the configured stores. */
    readonly names: readonly string[];
    /** A configured store by name (the default store when omitted). */
    store(name?: string): CacheStore;
    /** Returns the cached value, or computes, stores and returns it. Concurrent callers each compute. */
    remember<T>(key: string, ttlMs: number | undefined, compute: () => Promise<T> | T): Promise<T>;

Exported from packages/cache/src/contracts.ts

# CacheStore Interface

A cache backend. TTLs are in milliseconds; a missing or `undefined` TTL means "never expires".

interface CacheStore {
    /** Returns the stored value, or `undefined` when the key is missing or expired. */
    get<T = unknown>(key: string): Promise<T | undefined>;
    /** Stores a value (JSON-compatible or structured-cloneable for the memory store). */
    put(key: string, value: unknown, ttlMs?: number): Promise<void>;
    /** Removes a key. Returns true when a live key was removed. */
    forget(key: string): Promise<boolean>;
    /**
     * Atomically adds `by` to a numeric key (a missing or expired key starts at 0) and returns the
     * new value. `ttlMs` applies only when the key is created, so a counter keeps a fixed window.
  …

interface CacheStore {
    /** Returns the stored value, or `undefined` when the key is missing or expired. */
    get<T = unknown>(key: string): Promise<T | undefined>;
    /** Stores a value (JSON-compatible or structured-cloneable for the memory store). */
    put(key: string, value: unknown, ttlMs?: number): Promise<void>;
    /** Removes a key. Returns true when a live key was removed. */
    forget(key: string): Promise<boolean>;
    /**
     * Atomically adds `by` to a numeric key (a missing or expired key starts at 0) and returns the
     * new value. `ttlMs` applies only when the key is created, so a counter keeps a fixed window.
     */
    increment(key: string, by?: number, ttlMs?: number): Promise<number>;
    /** Atomic put-if-absent. Returns true when the key was written, false when a live key exists. */
    add(key: string, value: unknown, ttlMs?: number): Promise<boolean>;
    /** Removes every key of this store. */
    flush(): Promise<void>;
    /**
     * Deletes `key` only when it holds exactly `value`. Used by locks to release only by owner token.
     * Returns true when a key was deleted.
     */
    forgetIfEquals(key: string, value: unknown): Promise<boolean>;
    /** Releases resources the store opened. Optional. */
    close?(): Promise<void>;
}

Exported from packages/cache/src/contracts.ts

# DatabaseStoreOptions Interface

Options of {@link DatabaseStoreOptions}-based stores.

interface DatabaseStoreOptions {
    /** Resolves the database lazily, so the store can be configured before the database plugin boots. */
    readonly database: () => Database;

Exported from packages/cache/src/contracts.ts

# Funnel Interface

A concurrency limiter built from {@link FunnelOptions}.

interface Funnel {
    /**
     * Runs `fn` once a slot is free, releasing the slot afterwards (also when `fn` throws).
     * @throws SamveysError SVS_E096 when no slot became free within `waitMs`.
     */
    run<T>(fn: () => Promise<T> | T, options?: {
        readonly waitMs?: number;
    }): Promise<T>;

Exported from packages/cache/src/contracts.ts

# FunnelOptions Interface

Options of {@link CacheManager.funnel}.

interface FunnelOptions {
    /** Maximum concurrent runs across every process sharing the store. */
    readonly limit: number;
    /** How long one slot is held at most before it expires (crash safety), in ms. */
    readonly ttlMs: number;
}

Exported from packages/cache/src/contracts.ts

# Lock Interface

A named mutual-exclusion lock, held by an owner token.

interface Lock {
    /** The lock name. */
    readonly name: string;
    /** The random owner token this handle acquires and releases with. */
    readonly owner: string;
    /** Tries once. Returns true when this handle now holds the lock. */
    acquire(): Promise<boolean>;
    /** Releases the lock only when this handle's token owns it. Returns true when released. */
    release(): Promise<boolean>;
    /**
  …

interface Lock {
    /** The lock name. */
    readonly name: string;
    /** The random owner token this handle acquires and releases with. */
    readonly owner: string;
    /** Tries once. Returns true when this handle now holds the lock. */
    acquire(): Promise<boolean>;
    /** Releases the lock only when this handle's token owns it. Returns true when released. */
    release(): Promise<boolean>;
    /**
     * Polls until the lock is acquired, up to `waitMs`.
     * @throws SamveysError SVS_E096 when the wait time elapsed.
     */
    block(waitMs: number): Promise<void>;
}

Exported from packages/cache/src/contracts.ts

# StoreConfig Interface

Configuration of one store. Build with `memoryStore()`, `databaseStore()` or `failoverStore()`.

interface StoreConfig {
    /** Creates the store. Called once per manager, lazily. */
    readonly create: (resolve: (name: string) => CacheStore) => CacheStore;

Exported from packages/cache/src/contracts.ts