# Cache API

Every export of kitr/cache, with its signature.

Every export of `kitr/cache`, `kitr/cache/provider`, read from the published type definitions. The [guide](/packages/cache) shows them in use.

## kitr/cache

### cached

```ts
function cached<Args extends unknown[], T>(cache: Cache, fn: (...args: Args) => Promise<T> | T, options: RememberOptions & {
  key: (...args: Args) => string;
}): (...args: Args) => Promise<T>;
```

Wrap a function so each distinct argument list is remembered under `key(...args)`.

### createCache

```ts
function createCache(config?: CacheConfig): Cache;
```

Build a cache without an app: what the provider binds, and what tests and scripts call directly.

### createMemoryCacheDriver

```ts
function createMemoryCacheDriver(): CacheDriver;
```

In-process cache with TTLs and tags. The default; fine for one server, wrong for several.

### useCache

```ts
function useCache(app: KitrApp): Cache;
```

The app's cache, from the container. Pass `ctx.app` in a controller; throws if the cache provider is not registered.

### defineConfig

```ts
const defineConfig: <const C extends CacheConfig>(config: C) => C;
```

Type the default export of `config/cache.ts`. Returns its argument unchanged.

### Cache

```ts
interface Cache {
  /** The parsed value, or `undefined` on a miss or after expiry. */
  get<T>(key: string): Promise<T | undefined>;
  /** Store a value as JSON (`undefined` is stored as `null`), with an optional ttl and tags. */
  set<T>(key: string, value: T, options?: RememberOptions): Promise<void>;
  /** Whether a live entry exists, including one holding `null`. */
  has(key: string): Promise<boolean>;
  /** Remove one entry. */
  delete(key: string): Promise<void>;
  /** Return the cached value, or run `fn`, store its result and return it. Concurrent calls share one run. */
  remember<T>(key: string, fn: () => Promise<T> | T, options?: RememberOptions): Promise<T>;
  /** Remove every entry tagged with any of `tags`, whatever its key. */
  invalidateTags(...tags: string[]): Promise<void>;
  /** Remove every entry from the driver. */
  clear(): Promise<void>;
  /** The driver underneath, for its `name` or a raw read. */
  readonly driver: CacheDriver;
}
```

The cache service bound as `cache` in the container: JSON values over a driver, with TTLs and tags.

### CacheConfig

```ts
interface CacheConfig {
  /** Where entries live. Default: `createMemoryCacheDriver()`. */
  driver?: CacheDriver;
  /** Prepended to every key, so several apps can share one Redis. */
  prefix?: string;
  /** Seconds, when `remember()` is called without a ttl. Default 300. */
  defaultTtl?: number;
}
```

The options in `config/cache.ts`, also accepted by `createCache()`.

### CacheDriver

```ts
interface CacheDriver {
  /** Shown in devtools and logs, e.g. `memory` or `redis`. */
  name: string;
  /** The stored string, or `undefined` when the key is missing or expired. */
  get(key: string): Promise<string | undefined>;
  /** `ttl` in seconds; `undefined` keeps the entry until deleted. */
  set(key: string, value: string, ttl?: number): Promise<void>;
  /** Remove one key and forget its tags. */
  delete(key: string): Promise<void>;
  /** Remove every key tagged with any of `tags`. */
  invalidateTags(tags: string[]): Promise<void>;
  /** Record the tags of a key so `invalidateTags` can find it. */
  tag(key: string, tags: string[]): Promise<void>;
  /** Remove every key and every tag. */
  clear(): Promise<void>;
}
```

What a cache backend implements: six async methods over string keys and string values.
Values arrive already serialised to JSON by the cache, and keys already carry the prefix.

### RememberOptions

```ts
interface RememberOptions {
  /** Seconds the entry lives. Default: the cache's `defaultTtl`. */
  ttl?: number;
  /** Labels to clear the entry by later with `invalidateTags()`. */
  tags?: string[];
}
```

Per-entry options for `set()`, `remember()` and `cached()`.

## kitr/cache/provider

### cacheProvider

```ts
const cacheProvider: import("@kitr/core").KitrProvider;
```

Binds `cache` from `config/cache.ts` (memory driver by default) on the server; does nothing in the browser.

<!-- GENERATED by scripts/api-docs.mjs from the type definitions. Do not edit. -->