# Cache API reference

> Current emitted signatures and options for @db3.ai/app/cache.

- Package: `@db3.ai/app/cache`
- Canonical page: [https://db3.ai/docs/cache-api](https://db3.ai/docs/cache-api)
- Markdown: [https://db3.ai/docs/cache-api.md](https://db3.ai/docs/cache-api.md)
- Framework source of truth: `packages/app/src/cache/README.md`

<a id="start"></a>

## Imports and examples

Import supported APIs from `@db3.ai/app/cache`. These signatures come from the staged package used by consumers. Relative filenames in declarations describe type dependencies; they are not extra supported deep imports.

Use the guide for setup, executable examples, failure handling and ownership. A signature is not proof that every deployment or provider has been exercised.

- [Guide, examples and testing](https://db3.ai/docs/cache.md)

<a id="cache"></a>

## Cache service

### Cache service

```typescript
import type * as cache from './contracts/index.js';
/**
 * Application cache service exposed through `app().cache`.
 *
 * The framework owns cache naming and lifecycle while Cache Manager currently
 * supplies storage behavior through memory and Redis Keyv adapters.
 *
 * @example
     * const summary = await app().cache.getOrSet(`notes:v1:${ownerId}:summary`, async () => {
     * 	return { count: await Note.where('owner', ownerId).count() };
 * }, {
 * 	ttl: 60_000,
 * });
 */
export declare class Cache implements cache.CacheDriver {
    #private;
    /**
     * Creates the configured cache service.
     *
     * @param options - Named cache-store configuration.
     * @param driver - Optional concrete driver used by focused tests or providers.
     */
    constructor(options?: cache.CacheOptions, driver?: cache.CacheDriver);
    /**
     * Retrieves a cached value.
     *
     * @param key - Stable application cache key.
     * @returns Cached value or undefined after a miss.
     */
    get<TValue>(key: string): Promise<TValue | undefined>;
    /**
     * Stores one defined cache value.
     *
     * @param key - Stable application cache key.
     * @param value - Defined value to retain.
     * @param options - Optional per-write TTL.
     * @returns The stored value.
     */
    set<TValue>(key: string, value: TValue, options?: cache.CacheSetOptions): Promise<TValue>;
    /**
     * Returns a cached value or computes and stores it after a miss.
     *
     * Cache Manager coalesces concurrent misses for the same key within this
     * process, so the factory runs once while other callers await its result.
     *
     * @param key - Stable application cache key.
     * @param factory - Value producer invoked after a cache miss.
     * @param options - TTL and optional background-refresh controls.
     * @returns Cached or newly resolved value.
     */
    getOrSet<TValue>(key: string, factory: cache.CacheValueFactory<TValue>, options?: cache.CacheGetOrSetOptions<TValue>): Promise<TValue>;
    /**
     * Removes one cache key.
     *
     * @param key - Cache key to remove.
     * @returns True when the driver accepted the deletion.
     */
    forget(key: string): Promise<boolean>;
    /**
     * Removes every key owned by the configured store.
     */
    clear(): Promise<void>;
    /**
     * Releases resources held by the configured cache driver.
     */
    close(): Promise<void>;
}
```

<a id="options"></a>

## Named store options

### Named store options

```typescript
/**
 * Bounded in-process cache store configuration.
 */
export interface MemoryCacheStoreOptions {
    /** Cache driver selected for this named store. */
    driver: 'memory';
    /** Default time-to-live in milliseconds. Omit for no default expiry. */
    ttl?: number;
    /** Maximum entries retained by the least-recently-used cache. Defaults to 1,000. */
    maxEntries?: number;
    /** Whether values are cloned when stored and retrieved. Defaults to true. */
    clone?: boolean;
}
/**
 * Redis cache store configuration using the official Keyv adapter.
 */
export interface RedisCacheStoreOptions {
    /** Cache driver selected for this named store. */
    driver: 'redis';
    /** Redis connection URL including credentials and database when required. */
    url: string;
    /**
     * Prefix isolating application cache keys from other Redis data.
     *
     * A namespace is required so clearing the cache cannot affect unrelated keys.
     */
    namespace: string;
    /** Default time-to-live in milliseconds. Omit for no default expiry. */
    ttl?: number;
    /** Milliseconds allowed for the initial Redis connection attempt. */
    connectionTimeoutMs?: number;
    /** Number of namespaced keys removed in each cache-clear batch. */
    clearBatchSize?: number;
    /** Whether Redis connection failures should reject cache operations. */
    throwOnConnectError?: boolean;
    /** Whether Redis command errors should reject cache operations. */
    throwOnErrors?: boolean;
}
/**
 * Supported framework cache store configurations.
 */
export type CacheStoreOptions = MemoryCacheStoreOptions | RedisCacheStoreOptions;
/**
 * Named cache-store configuration resolved from the application config.
 */
export interface CacheOptions {
    /** Named store used by `app().cache`. Defaults to `memory`. */
    default?: string;
    /** Cache stores available to the application. */
    stores?: Record<string, CacheStoreOptions>;
}
```

<a id="operations"></a>

## TTL and factory options

### TTL and factory options

```typescript
/**
 * Per-write cache options.
 */
export interface CacheSetOptions {
    /** Time-to-live in milliseconds, overriding the configured store default. */
    ttl?: number;
}
/**
 * Options controlling one cache-through lookup.
 */
export interface CacheGetOrSetOptions<TValue> {
    /**
     * Time-to-live in milliseconds or a function deriving it from the resolved value.
     */
    ttl?: number | ((value: TValue) => number);
    /**
     * Remaining TTL threshold that triggers a background refresh.
     *
     * The stale value is returned while the factory refreshes it.
     */
    refreshThreshold?: number | ((value: TValue) => number);
}
/**
 * Factory that computes a value after a cache miss.
 */
export type CacheValueFactory<TValue> = () => TValue | Promise<TValue>;
```

<a id="repository"></a>

## Repository contract

### Repository contract

```typescript
import type { CacheGetOrSetOptions, CacheSetOptions, CacheValueFactory } from './CacheOperations.js';
/**
 * Application-facing cache operations shared by framework and app code.
 */
export interface CacheRepository {
    /**
     * Retrieves a cached value.
     *
     * @param key - Stable application cache key.
     * @returns Cached value or undefined when the key is absent or expired.
     */
    get<TValue>(key: string): Promise<TValue | undefined>;
    /**
     * Stores one defined cache value.
     *
     * @param key - Stable application cache key.
     * @param value - Defined value to retain.
     * @param options - Optional per-write TTL.
     * @returns The stored value.
     */
    set<TValue>(key: string, value: TValue, options?: CacheSetOptions): Promise<TValue>;
    /**
     * Returns a cached value or computes and stores it after a miss.
     *
     * Concurrent lookups for the same key share one in-flight factory execution
     * within the current process.
     *
     * @param key - Stable application cache key.
     * @param factory - Value producer invoked after a cache miss.
     * @param options - TTL and optional background-refresh controls.
     * @returns Cached or newly resolved value.
     */
    getOrSet<TValue>(key: string, factory: CacheValueFactory<TValue>, options?: CacheGetOrSetOptions<TValue>): Promise<TValue>;
    /**
     * Removes one cache key.
     *
     * @param key - Cache key to remove.
     * @returns True when the underlying cache accepted the deletion.
     */
    forget(key: string): Promise<boolean>;
    /**
     * Removes every key owned by the configured cache store.
     */
    clear(): Promise<void>;
}
```

<a id="driver"></a>

## Driver lifecycle

### Driver lifecycle

```typescript
import type { CacheRepository } from './CacheRepository.js';
/**
 * Cache backend boundary owned by the framework cache service.
 */
export interface CacheDriver extends CacheRepository {
    /**
     * Releases connections and other resources held by the cache backend.
     */
    close(): Promise<void>;
}
```

## Related documentation
- [Cache an expensive lookup](https://db3.ai/docs/cache.md): Cache a note summary, keep account keys separate and invalidate it after a write.

## Guidance for AI tools
Use the documented public import `@db3.ai/app/cache` and its exported types. Prefer the source-backed examples and behavioural outcomes above over invented APIs or source-relative internal imports.