---
title: Cache API
description: Generated public TypeScript reference for @relkit/cache.
search:
  exclude: true
sidebar:
  icon: braces
---

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

## Common APIs

- [defineCache](/docs/api/cache#definecache)

For configuration and examples, read [define](/docs/modules/caching/define), [organization](/docs/modules/service/organization), [rate limits](/docs/modules/http/rate-limits).

For a complete workflow, follow [cache product prices](/guides/caching/cache-product-prices).

## Public imports

- `@relkit/cache` — 50 exports

## All exported APIs

Names link to their complete contracts. Re-exports share their original contract; legacy exports keep their separate identity. Examples link to the API's inline sample, a maintained repository usage, or the shared module walkthrough.

| API                                                                                    | Kind  | Import from     | Example                                                             |
| -------------------------------------------------------------------------------------- | ----- | --------------- | ------------------------------------------------------------------- |
| [assertCacheDescriptor](/docs/api/cache#assertcachedescriptor)                         | Value | `@relkit/cache` | [API example](/docs/api/cache#assertcachedescriptor)                |
| [assertCacheDescriptorEffect](/docs/api/cache#assertcachedescriptoreffect)             | Value | `@relkit/cache` | [API example](/docs/api/cache#assertcachedescriptoreffect)          |
| [CacheBridgeOptions](/docs/api/cache#cachebridgeoptions-interface)                     | Type  | `@relkit/cache` | [API example](/docs/api/cache#cachebridgeoptions-interface)         |
| [CacheCapabilities](/docs/api/cache#cachecapabilities-interface)                       | Type  | `@relkit/cache` | [API example](/docs/api/cache#cachecapabilities-interface)          |
| [CacheCapability](/docs/api/cache#cachecapability-type-alias)                          | Type  | `@relkit/cache` | [API example](/docs/api/cache#cachecapability-type-alias)           |
| [CacheCapabilityError](/docs/api/cache#cachecapabilityerror-class)                     | Value | `@relkit/cache` | [API example](/docs/api/cache#cachecapabilityerror-class)           |
| [CacheClient](/docs/api/cache#cacheclient-type-alias)                                  | Type  | `@relkit/cache` | [API example](/docs/api/cache#cacheclient-type-alias)               |
| [CacheClientBase](/docs/api/cache#cacheclientbase-interface)                           | Type  | `@relkit/cache` | [API example](/docs/api/cache#cacheclientbase-interface)            |
| [CacheClientOptions](/docs/api/cache#cacheclientoptions-interface)                     | Type  | `@relkit/cache` | [API example](/docs/api/cache#cacheclientoptions-interface)         |
| [CacheDependencyError](/docs/api/cache#cachedependencyerror-class)                     | Value | `@relkit/cache` | [API example](/docs/api/cache#cachedependencyerror-class)           |
| [CacheDescriptor](/docs/api/cache#cachedescriptor-interface)                           | Type  | `@relkit/cache` | [API example](/docs/api/cache#cachedescriptor-interface)            |
| [CacheDescriptorAny](/docs/api/cache#cachedescriptorany-type-alias)                    | Type  | `@relkit/cache` | [API example](/docs/api/cache#cachedescriptorany-type-alias)        |
| [CacheDescriptorError](/docs/api/cache#cachedescriptorerror-class)                     | Value | `@relkit/cache` | [API example](/docs/api/cache#cachedescriptorerror-class)           |
| [CacheDescriptorPolicy](/docs/api/cache#cachedescriptorpolicy-interface)               | Type  | `@relkit/cache` | [API example](/docs/api/cache#cachedescriptorpolicy-interface)      |
| [CacheEffectClient](/docs/api/cache#cacheeffectclient-interface)                       | Type  | `@relkit/cache` | [API example](/docs/api/cache#cacheeffectclient-interface)          |
| [CacheIncrementUnsupportedError](/docs/api/cache#cacheincrementunsupportederror-class) | Value | `@relkit/cache` | [API example](/docs/api/cache#cacheincrementunsupportederror-class) |
| [CacheInvocationBridge](/docs/api/cache#cacheinvocationbridge-interface)               | Type  | `@relkit/cache` | [API example](/docs/api/cache#cacheinvocationbridge-interface)      |
| [CacheNumericClient](/docs/api/cache#cachenumericclient-type-alias)                    | Type  | `@relkit/cache` | [API example](/docs/api/cache#cachenumericclient-type-alias)        |
| [CacheObservedEdge](/docs/api/cache#cacheobservededge-interface)                       | Type  | `@relkit/cache` | [API example](/docs/api/cache#cacheobservededge-interface)          |
| [CacheOperation](/docs/api/cache#cacheoperation-type-alias)                            | Type  | `@relkit/cache` | [API example](/docs/api/cache#cacheoperation-type-alias)            |
| [CacheOperationCancelledError](/docs/api/cache#cacheoperationcancellederror-class)     | Value | `@relkit/cache` | [API example](/docs/api/cache#cacheoperationcancellederror-class)   |
| [CacheOperationContext](/docs/api/cache#cacheoperationcontext-interface)               | Type  | `@relkit/cache` | [API example](/docs/api/cache#cacheoperationcontext-interface)      |
| [CacheOperationError](/docs/api/cache#cacheoperationerror-type-alias)                  | Type  | `@relkit/cache` | [API example](/docs/api/cache#cacheoperationerror-type-alias)       |
| [CacheOperationObservation](/docs/api/cache#cacheoperationobservation-interface)       | Type  | `@relkit/cache` | [API example](/docs/api/cache#cacheoperationobservation-interface)  |
| [CacheOperationOptions](/docs/api/cache#cacheoperationoptions-interface)               | Type  | `@relkit/cache` | [API example](/docs/api/cache#cacheoperationoptions-interface)      |
| [CacheOperationOutcome](/docs/api/cache#cacheoperationoutcome-type-alias)              | Type  | `@relkit/cache` | [API example](/docs/api/cache#cacheoperationoutcome-type-alias)     |
| [CacheOperationTimeoutError](/docs/api/cache#cacheoperationtimeouterror-class)         | Value | `@relkit/cache` | [API example](/docs/api/cache#cacheoperationtimeouterror-class)     |
| [CacheProvider](/docs/api/cache#cacheprovider-interface)                               | Type  | `@relkit/cache` | [API example](/docs/api/cache#cacheprovider-interface)              |
| [CacheProviderError](/docs/api/cache#cacheprovidererror-class)                         | Value | `@relkit/cache` | [API example](/docs/api/cache#cacheprovidererror-class)             |
| [CacheProviderFailureError](/docs/api/cache#cacheproviderfailureerror-class)           | Value | `@relkit/cache` | [API example](/docs/api/cache#cacheproviderfailureerror-class)      |
| [CacheRuntime](/docs/api/cache#cacheruntime-class)                                     | Value | `@relkit/cache` | [API example](/docs/api/cache#cacheruntime-class)                   |
| [cacheRuntimeLayer](/docs/api/cache#cacheruntimelayer)                                 | Value | `@relkit/cache` | [API example](/docs/api/cache#cacheruntimelayer)                    |
| [CacheSchemaValidationError](/docs/api/cache#cacheschemavalidationerror-class)         | Value | `@relkit/cache` | [API example](/docs/api/cache#cacheschemavalidationerror-class)     |
| [CacheTelemetry](/docs/api/cache#cachetelemetry-class)                                 | Value | `@relkit/cache` | [API example](/docs/api/cache#cachetelemetry-class)                 |
| [CacheTelemetryLive](/docs/api/cache#cachetelemetrylive)                               | Value | `@relkit/cache` | [API example](/docs/api/cache#cachetelemetrylive)                   |
| [CacheTtlPolicyError](/docs/api/cache#cachettlpolicyerror-class)                       | Value | `@relkit/cache` | [API example](/docs/api/cache#cachettlpolicyerror-class)            |
| [CacheValidationError](/docs/api/cache#cachevalidationerror-class)                     | Value | `@relkit/cache` | [API example](/docs/api/cache#cachevalidationerror-class)           |
| [createCacheClient](/docs/api/cache#createcacheclient)                                 | Value | `@relkit/cache` | [API example](/docs/api/cache#createcacheclient)                    |
| [createCacheClientEffect](/docs/api/cache#createcacheclienteffect)                     | Value | `@relkit/cache` | [API example](/docs/api/cache#createcacheclienteffect)              |
| [defineCache](/docs/api/cache#definecache)                                             | Value | `@relkit/cache` | [API example](/docs/api/cache#definecache)                          |
| [defineCacheEffect](/docs/api/cache#definecacheeffect)                                 | Value | `@relkit/cache` | [API example](/docs/api/cache#definecacheeffect)                    |
| [DefineCacheOptions](/docs/api/cache#definecacheoptions-interface)                     | Type  | `@relkit/cache` | [API example](/docs/api/cache#definecacheoptions-interface)         |
| [deleteCacheEffect](/docs/api/cache#deletecacheeffect)                                 | Value | `@relkit/cache` | [API example](/docs/api/cache#deletecacheeffect)                    |
| [getCacheEffect](/docs/api/cache#getcacheeffect)                                       | Value | `@relkit/cache` | [API example](/docs/api/cache#getcacheeffect)                       |
| [getOrSetCacheEffect](/docs/api/cache#getorsetcacheeffect)                             | Value | `@relkit/cache` | [API example](/docs/api/cache#getorsetcacheeffect)                  |
| [hasCacheEffect](/docs/api/cache#hascacheeffect)                                       | Value | `@relkit/cache` | [API example](/docs/api/cache#hascacheeffect)                       |
| [incrementCacheEffect](/docs/api/cache#incrementcacheeffect)                           | Value | `@relkit/cache` | [API example](/docs/api/cache#incrementcacheeffect)                 |
| [isCacheDescriptor](/docs/api/cache#iscachedescriptor)                                 | Value | `@relkit/cache` | [API example](/docs/api/cache#iscachedescriptor)                    |
| [isCacheDescriptorEffect](/docs/api/cache#iscachedescriptoreffect)                     | Value | `@relkit/cache` | [API example](/docs/api/cache#iscachedescriptoreffect)              |
| [setCacheEffect](/docs/api/cache#setcacheeffect)                                       | Value | `@relkit/cache` | [API example](/docs/api/cache#setcacheeffect)                       |

## `client-abort.ts`

### runAbortableEffect

Guards provider work with a scoped abort listener and an absolute deadline.

**Example**

```ts
Effect.runPromise(runAbortableEffect(new AbortController().signal, undefined, Effect.succeed(1)));
```

**Signature**

```ts
declare const runAbortableEffect: <A, E, R>(
  signal: AbortSignal,
  deadlineMs: number | undefined,
  work: Effect.Effect<A, E, R>,
) => Effect.Effect<A, E | CacheOperationCancelledError | CacheOperationTimeoutError, R>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-abort.ts#L10)

## `client-effects.ts`

### deleteCacheEffect

Deletes one key.

**Example**

```ts
Effect.provide(deleteCacheEffect("sku"), cacheRuntimeLayer(options));
```

**Signature**

```ts
declare const deleteCacheEffect: (
  key: unknown,
) => Effect.Effect<void, CacheOperationError, CacheRuntime>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-effects.ts#L77)

### getCacheEffect

Reads a decoded cache value.

**Example**

```ts
Effect.provide(getCacheEffect("sku"), cacheRuntimeLayer(options));
```

**Signature**

```ts
declare const getCacheEffect: (
  key: unknown,
) => Effect.Effect<unknown, CacheOperationError, CacheRuntime>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-effects.ts#L17)

### getOrSetCacheEffect

Reads or produces and stores one value through the provider.

**Example**

```ts
Effect.provide(
  getOrSetCacheEffect("sku", () => 1),
  cacheRuntimeLayer(options),
);
```

**Signature**

```ts
declare const getOrSetCacheEffect: (
  key: unknown,
  produce: () => MaybePromise<unknown>,
  settings?: { ttlMs?: number } | undefined,
) => Effect.Effect<unknown, CacheOperationError, CacheRuntime>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-effects.ts#L126)

### hasCacheEffect

Checks key presence.

**Example**

```ts
Effect.provide(hasCacheEffect("sku"), cacheRuntimeLayer(options));
```

**Signature**

```ts
declare const hasCacheEffect: (
  key: unknown,
) => Effect.Effect<boolean, CacheOperationError, CacheRuntime>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-effects.ts#L100)

### setCacheEffect

Writes a validated key and value.

**Example**

```ts
Effect.provide(setCacheEffect("sku", 1), cacheRuntimeLayer(options));
```

**Signature**

```ts
declare const setCacheEffect: (
  key: unknown,
  value: unknown,
  settings?: { ttlMs?: number } | undefined,
) => Effect.Effect<void, CacheOperationError, CacheRuntime>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-effects.ts#L46)

## `client-errors.ts`

### CacheCapabilityError (class)

The provider lacks a declared cache capability.

**Example**

```ts
new CacheCapabilityError("increment", "increment");
```

**Signature**

```ts
declare class CacheCapabilityError {
  constructor(capability: CacheCapability, operation: CacheOperation);
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-errors.ts#L9)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_CACHE_CAPABILITY_UNSUPPORTED"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-errors.ts#L13)

### CacheDependencyError (class)

A function used an undeclared cache.

**Example**

```ts
new CacheDependencyError("prices");
```

**Signature**

```ts
declare class CacheDependencyError {
  constructor(cacheId: string);
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-errors.ts#L25)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_CACHE_DEPENDENCY_UNDECLARED"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-errors.ts#L29)

### CacheIncrementUnsupportedError (class)

Increment needs a numeric value contract.

**Example**

```ts
new CacheIncrementUnsupportedError();
```

**Signature**

```ts
declare class CacheIncrementUnsupportedError {
  constructor();
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-errors.ts#L86)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_CACHE_INCREMENT_UNSUPPORTED"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-errors.ts#L90)

### CacheOperationCancelledError (class)

Caller cancellation of an operation.

**Example**

```ts
new CacheOperationCancelledError();
```

**Signature**

```ts
declare class CacheOperationCancelledError {
  constructor();
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-errors.ts#L101)

### code (property)

**Signature**

```ts
readonly code: "ABORT_ERR"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-errors.ts#L105)

### CacheOperationTimeoutError (class)

Deadline expiration of an operation.

**Example**

```ts
new CacheOperationTimeoutError();
```

**Signature**

```ts
declare class CacheOperationTimeoutError {
  constructor();
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-errors.ts#L119)

### code (property)

**Signature**

```ts
readonly code: "ETIMEDOUT"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-errors.ts#L123)

### CacheProviderError (class)

The provider omits an operation.

**Example**

```ts
new CacheProviderError("get");
```

**Signature**

```ts
declare class CacheProviderError {
  constructor(operation: CacheOperation);
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-errors.ts#L41)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_CACHE_PROVIDER_UNAVAILABLE"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-errors.ts#L45)

### CacheProviderFailureError (class)

Provider rejection with its original cause retained.

**Example**

```ts
new CacheProviderFailureError({ operation: "get", cause: "offline" });
```

**Signature**

```ts
declare class CacheProviderFailureError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-errors.ts#L138)

### CacheSchemaValidationError (class)

A tagged schema failure retaining its legacy TypeError classification.

**Example**

```ts
new CacheSchemaValidationError("key", [{ message: "Invalid key" }]);
```

**Signature**

```ts
declare class CacheSchemaValidationError { constructor(
    readonly phase: "key" | "value",
    readonly issues: readonly StandardIssue[],
  ) }
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-errors.ts#L58)

### \_tag (property)

**Signature**

```ts
readonly _tag: "CacheSchemaValidationError"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-errors.ts#L59)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_CACHE_SCHEMA_VALIDATION"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-errors.ts#L60)

### CacheTtlPolicyError (class)

A tagged TTL violation retaining its legacy RangeError classification.

**Example**

```ts
new CacheTtlPolicyError("Cache ttlMs must be a positive integer");
```

**Signature**

```ts
declare class CacheTtlPolicyError {
  constructor(message: string);
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-errors.ts#L73)

### \_tag (property)

**Signature**

```ts
readonly _tag: "CacheTtlPolicyError"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-errors.ts#L74)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_CACHE_TTL_POLICY"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-errors.ts#L75)

### reason (property)

**Signature**

```ts
readonly reason: string
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-errors.ts#L76)

### CacheValidationError (class)

Invalid non-schema input or provider result.

**Example**

```ts
new CacheValidationError({ reason: "Cache has must return a boolean" });
```

**Signature**

```ts
declare class CacheValidationError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-errors.ts#L146)

## `client-increment.ts`

### incrementCacheEffect

Increments a numeric cache value.

**Example**

```ts
Effect.provide(incrementCacheEffect("sku", 2), cacheRuntimeLayer(options));
```

**Signature**

```ts
declare const incrementCacheEffect: (
  key: unknown,
  delta?: any,
  settings?: { ttlMs?: number } | undefined,
) => Effect.Effect<number, CacheOperationError, CacheRuntime>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-increment.ts#L19)

## `client-observability.ts`

### CacheTelemetry (class)

Injectable telemetry for cache Effect operations.

**Example**

```ts
Effect.provide(getCacheEffect("sku"), CacheTelemetryLive);
```

**Signature**

```ts
declare class CacheTelemetry
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-observability.ts#L9)

### CacheTelemetryLive

Default spans and bounded Effect metrics.

**Example**

```ts
Effect.provide(getCacheEffect("sku"), CacheTelemetryLive);
```

**Signature**

```ts
declare const CacheTelemetryLive: Layer.Layer<CacheTelemetry, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-observability.ts#L15)

### observeCache

Observes an operation through an optional test Layer or default telemetry.

**Example**

```ts
observeCache("get", Effect.succeed(undefined));
```

**Signature**

```ts
declare const observeCache: <A, E, R>(
  operation: CacheObservedOperation,
  effect: Effect.Effect<A, E, R>,
) => Effect.Effect<A, E, R>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-observability.ts#L27)

## `client-observability.types.ts`

### CacheObservedEdge (interface)

A declared dependency edge observed without any cache key or value.

**Example**

```ts
const edge: CacheObservedEdge = { relationship: "uses-cache", from: "orders", to: "prices" };
```

**Signature**

```ts
export interface CacheObservedEdge {
  readonly relationship: "uses-cache";
  readonly from: string;
  readonly to: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-observability.types.ts#L12)

### CacheObservedOperation (type alias)

Names of observed public cache operations.

**Example**

```ts
const operation: CacheObservedOperation = "get";
```

**Signature**

```ts
type CacheObservedOperation =
  CacheOperation | "define" | "isDescriptor" | "assertDescriptor" | "createClient";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-observability.types.ts#L7)

### CacheOperationObservation (interface)

One operation outcome with bounded, input-free fields.

**Example**

```ts
const event: CacheOperationObservation = {
  capability: "cache",
  operation: "get",
  ownerId: "orders",
  cacheId: "prices",
  outcome: "success",
};
```

**Signature**

```ts
export interface CacheOperationObservation {
  readonly capability: "cache";
  readonly operation: CacheOperation;
  readonly ownerId: string;
  readonly cacheId: string;
  readonly outcome: CacheOperationOutcome;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-observability.types.ts#L20)

### CacheTelemetryService (interface)

Replaceable telemetry boundary for cache Effect calls.

**Example**

```ts
const telemetry: CacheTelemetryService = { observe: (_name, effect) => effect };
```

**Signature**

```ts
export interface CacheTelemetryService {
  /** Wraps an operation with tracing and metrics.
   * @param operation - Stable operation name.
   * @param effect - Work to observe.
   * @returns The same Effect success and error channels.
   * @example telemetry.observe("get", Effect.succeed(undefined));
   */
  readonly observe: <A, E, R>(
    operation: CacheObservedOperation,
    effect: Effect.Effect<A, E, R>,
  ) => Effect.Effect<A, E, R>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-observability.types.ts#L30)

## `client-operation.ts`

### invokeProvider

Invokes an optional provider method in the typed error channel.

**Example**

```ts
Effect.runPromise(invokeProvider("get", async () => 1, ["sku"]));
```

**Signature**

```ts
declare const invokeProvider: <A>(
  operation: CacheOperation,
  method: ((...args: any[]) => A | PromiseLike<A>) | undefined,
  args: Array<unknown>,
) => Effect.Effect<Awaited<A>, CacheOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-operation.ts#L30)

### runCacheOperation

Executes provider work with injectable runtime, bridge, cancellation, and hooks.

**Example**

```ts
Effect.provide(
  runCacheOperation({ operation: "get", input: {}, work: () => Effect.succeed(1) }),
  layer,
);
```

**Signature**

```ts
declare const runCacheOperation: <A>(
  invocation: CacheInvocation<A>,
) => Effect.Effect<A, CacheOperationError, CacheRuntime>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-operation.ts#L50)

## `client-operation.types.ts`

### CacheCapabilities (interface)

Provider-declared feature support.

**Example**

```ts
const capabilities: CacheCapabilities = { increment: true };
```

**Signature**

```ts
export interface CacheCapabilities {
  readonly increment?: boolean;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-operation.types.ts#L34)

### CacheCapability (type alias)

Provider feature negotiated before executing an operation.

**Example**

```ts
const capability: CacheCapability = "increment";
```

**Signature**

```ts
type CacheCapability = "increment";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-operation.types.ts#L11)

### CacheInvocation (interface)

Provider invocation and its typed Effect work.

**Example**

```ts
const invocation: CacheInvocation<number> = {
  operation: "get",
  input: {},
  work: () => Effect.succeed(1),
};
```

**Signature**

```ts
export interface CacheInvocation<A> {
  readonly operation: CacheOperation;
  readonly input: unknown;
  readonly capability?: "increment";
  /** Builds validated provider work inside the cache runtime.
   * @param provider - Injected provider.
   * @param context - Cancellation and deadline context.
   * @returns Effect of the operation result or a typed cache failure.
   * @example invocation.work(provider, context);
   */
  readonly work: (
    provider: CacheProvider,
    context: CacheOperationContext,
  ) => Effect.Effect<A, CacheOperationError>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-operation.types.ts#L112)

### CacheOperation (type alias)

Fixed cache method names used for spans and metrics.

**Example**

```ts
const operation: CacheOperation = "get";
```

**Signature**

```ts
type CacheOperation = "get" | "set" | "delete" | "has" | "getOrSet" | "increment";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-operation.types.ts#L7)

### CacheOperationContext (interface)

Cancellation and deadline data passed to a provider call.

**Example**

```ts
const context: CacheOperationContext = { operation: "get", signal: new AbortController().signal };
```

**Signature**

```ts
export interface CacheOperationContext {
  readonly operation: CacheOperation;
  readonly signal: AbortSignal;
  readonly deadlineMs?: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-operation.types.ts#L26)

### CacheOperationOptions (interface)

Optional write or increment TTL in milliseconds.

**Example**

```ts
const options: CacheOperationOptions = { ttlMs: 1000 };
```

**Signature**

```ts
export interface CacheOperationOptions {
  readonly ttlMs?: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-operation.types.ts#L20)

### CacheOperationOutcome (type alias)

Stable operation outcomes for RELKIT observations.

**Example**

```ts
const outcome: CacheOperationOutcome = "success";
```

**Signature**

```ts
type CacheOperationOutcome =
  "success" | "provider-failure" | "cancelled" | "timeout" | "unsupported" | "validation-error";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-operation.types.ts#L15)

### CacheProvider (interface)

Optional provider methods; missing methods fail with CacheProviderError.

**Example**

```ts
const provider: CacheProvider = { get: async () => undefined };
```

**Signature**

```ts
export interface CacheProvider {
  readonly capabilities?: CacheCapabilities | readonly CacheCapability[];
  /** Reads one key.
   * @param key - Provider key.
   * @param context - Cancellation and deadline context.
   * @returns Stored value or undefined.
   * @example await provider.get?.("sku", context);
   */
  readonly get?: (
    key: unknown,
    context?: CacheOperationContext,
  ) => MaybePromise<unknown | undefined>;
  /** Writes one entry.
   * @param key - Provider key.
   * @param value - Validated value.
   * @param options - Optional TTL.
   * @param context - Cancellation and deadline context.
   * @returns Completion.
   * @example await provider.set?.("sku", 1);
   */
  readonly set?: (
    key: unknown,
    value: unknown,
    options?: CacheOperationOptions,
    context?: CacheOperationContext,
  ) => MaybePromise<void>;
  /** Deletes one key.
   * @param key - Provider key.
   * @param context - Cancellation and deadline context.
   * @returns Completion.
   * @example await provider.delete?.("sku");
   */
  readonly delete?: (key: unknown, context?: CacheOperationContext) => MaybePromise<void>;
  /** Tests key presence.
   * @param key - Provider key.
   * @param context - Cancellation and deadline context.
   * @returns Presence.
   * @example await provider.has?.("sku");
   */
  readonly has?: (key: unknown, context?: CacheOperationContext) => MaybePromise<boolean>;
  /** Reads or fills a key.
   * @param key - Provider key.
   * @param produce - Miss producer.
   * @param options - Optional TTL.
   * @param context - Cancellation and deadline context.
   * @returns Stored or produced value.
   * @example await provider.getOrSet?.("sku", () => 1);
   */
  readonly getOrSet?: (
    key: unknown,
    produce: () => MaybePromise<unknown>,
    options?: CacheOperationOptions,
    context?: CacheOperationContext,
  ) => MaybePromise<unknown>;
  /** Increments a numeric entry.
   * @param key - Provider key.
   * @param delta - Finite increment.
   * @param options - Optional TTL.
   * @param context - Cancellation and deadline context.
   * @returns Updated numeric value.
   * @example await provider.increment?.("sku", 2);
   */
  readonly increment?: (
    key: unknown,
    delta: number,
    options?: CacheOperationOptions,
    context?: CacheOperationContext,
  ) => MaybePromise<unknown>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-operation.types.ts#L40)

## `client-runtime.ts`

### CacheRuntime (class)

Substitutable provider and invocation configuration.

**Example**

```ts
Effect.provide(
  getCacheEffect("sku"),
  cacheRuntimeLayer({ ownerId: "orders", cacheId: "prices", source: {} }),
);
```

**Signature**

```ts
declare class CacheRuntime
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-runtime.ts#L12)

### asProviderEffect

Validates the provider source in Effect.

**Example**

```ts
Effect.runSync(asProviderEffect(undefined));
```

**Signature**

```ts
declare const asProviderEffect: (
  value: unknown,
) => Effect.Effect<CacheProvider, CacheProviderError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-runtime.ts#L36)

### cacheRuntimeLayer

Creates the live provider Layer from client options.

**Example**

```ts
cacheRuntimeLayer({ ownerId: "orders", cacheId: "prices", source: {} });
```

**Signature**

```ts
declare const cacheRuntimeLayer: (
  options: CacheClientOptions,
) => Layer.Layer<
  CacheRuntime,
  CacheProviderError | CacheTtlPolicyError | CacheValidationError,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-runtime.ts#L20)

## `client-runtime.types.ts`

### CacheBridgeOptions (interface)

Metadata sent to an invocation bridge.

**Example**

```ts
const options: CacheBridgeOptions = {
  name: "cache.get",
  attributes: {},
  signal: new AbortController().signal,
};
```

**Signature**

```ts
export interface CacheBridgeOptions {
  readonly name: string;
  readonly attributes: Readonly<Record<string, unknown>>;
  readonly signal: AbortSignal;
  readonly input?: unknown;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-runtime.types.ts#L7)

### CacheInvocationBridge (interface)

Existing invocation bridge contract.

**Example**

```ts
const bridge: CacheInvocationBridge = { run: async (operation) => operation() };
```

**Signature**

```ts
export interface CacheInvocationBridge {
  /** Runs one operation in the existing invocation boundary.
   * @param operation - Deferred operation callback.
   * @param options - Span metadata, signal, and input.
   * @returns Operation value or rejection.
   * @example bridge.run(() => Promise.resolve(1));
   */
  readonly run: <A>(operation: () => MaybePromise<A>, options?: CacheBridgeOptions) => Promise<A>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-runtime.types.ts#L16)

### CacheRuntimeService (interface)

Provider and options supplied to cache Effect operations.

**Example**

```ts
const runtime: CacheRuntimeService = { options, provider };
```

**Signature**

```ts
export interface CacheRuntimeService {
  readonly options: CacheClientOptions;
  readonly provider: CacheProvider;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-runtime.types.ts#L28)

## `client-validation-effect.ts`

### normalizeTtlEffect

Normalizes a requested TTL against the configured policy.

**Example**

```ts
Effect.runSync(normalizeTtlEffect(undefined, 1000, 5000));
```

**Signature**

```ts
declare const normalizeTtlEffect: (
  value: unknown,
  defaultTtlMs: number | undefined,
  maxTtlMs: number | undefined,
) => Effect.Effect<{ ttlMs: number } | undefined, CacheTtlPolicyError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-validation-effect.ts#L91)

### validateBooleanEffect

Validates a provider has result.

**Example**

```ts
Effect.runSync(validateBooleanEffect(true));
```

**Signature**

```ts
declare const validateBooleanEffect: (
  value: unknown,
) => Effect.Effect<boolean, CacheValidationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-validation-effect.ts#L125)

### validateClientIdentityEffect

Validates client identity before a provider is acquired.

**Example**

```ts
Effect.runSync(validateClientIdentityEffect({ ownerId: "orders", cacheId: "prices", source: {} }));
```

**Signature**

```ts
declare const validateClientIdentityEffect: (
  options: CacheClientOptions<
    StandardSchemaV1<unknown, unknown>,
    StandardSchemaV1<unknown, unknown>
  >,
) => Effect.Effect<undefined, CacheValidationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-validation-effect.ts#L14)

### validateClientPolicyEffect

Validates schemas and TTL policy after the provider source.

**Example**

```ts
Effect.runSync(validateClientPolicyEffect({ ownerId: "orders", cacheId: "prices", source: {} }));
```

**Signature**

```ts
declare const validateClientPolicyEffect: (
  options: CacheClientOptions<
    StandardSchemaV1<unknown, unknown>,
    StandardSchemaV1<unknown, unknown>
  >,
) => Effect.Effect<undefined, CacheTtlPolicyError | CacheValidationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-validation-effect.ts#L27)

### validateIncrementDeltaEffect

Validates a finite increment delta.

**Example**

```ts
Effect.runSync(validateIncrementDeltaEffect(2));
```

**Signature**

```ts
declare const validateIncrementDeltaEffect: (
  value: unknown,
) => Effect.Effect<number, CacheValidationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-validation-effect.ts#L135)

### validatePolicyEffect

Validates configured policy numbers.

**Example**

```ts
Effect.runSync(validatePolicyEffect(1000, "defaultTtlMs"));
```

**Signature**

```ts
declare const validatePolicyEffect: (
  value: number | undefined,
  name: string,
) => Effect.Effect<undefined, CacheTtlPolicyError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-validation-effect.ts#L113)

### validateSchemaEffect

Validates a value through Standard Schema in the typed error channel.

**Example**

```ts
Effect.runPromise(validateSchemaEffect(undefined, "sku", "key"));
```

**Signature**

```ts
declare const validateSchemaEffect: (
  schema: StandardSchemaV1<unknown, unknown> | undefined,
  value: unknown,
  phase: "value" | "key",
) => Effect.Effect<unknown, CacheSchemaValidationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-validation-effect.ts#L69)

## `client.ts`

### "./client.types.js" (namespace export)

Re-exports all named exports from the "./client.types.js" module.

**Signature**

```ts
export * from "./client.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.ts#L31)

### CacheCapabilityError

**Signature**

```ts
declare const CacheCapabilityError: typeof CacheCapabilityError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.ts#L20)

### CacheDependencyError

**Signature**

```ts
declare const CacheDependencyError: typeof CacheDependencyError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.ts#L21)

### CacheIncrementUnsupportedError

**Signature**

```ts
declare const CacheIncrementUnsupportedError: typeof CacheIncrementUnsupportedError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.ts#L22)

### CacheOperationCancelledError

**Signature**

```ts
declare const CacheOperationCancelledError: typeof CacheOperationCancelledError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.ts#L23)

### CacheOperationTimeoutError

**Signature**

```ts
declare const CacheOperationTimeoutError: typeof CacheOperationTimeoutError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.ts#L24)

### CacheProviderError

**Signature**

```ts
declare const CacheProviderError: typeof CacheProviderError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.ts#L25)

### CacheProviderFailureError

**Signature**

```ts
declare const CacheProviderFailureError: typeof CacheProviderFailureError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.ts#L26)

### CacheRuntime

**Signature**

```ts
declare const CacheRuntime: typeof CacheRuntime;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.ts#L40)

### CacheSchemaValidationError

**Signature**

```ts
declare const CacheSchemaValidationError: typeof CacheSchemaValidationError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.ts#L27)

### CacheTelemetry

**Signature**

```ts
declare const CacheTelemetry: typeof CacheTelemetry;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.ts#L41)

### CacheTelemetryLive

**Signature**

```ts
declare const CacheTelemetryLive: Layer.Layer<CacheTelemetry, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.ts#L41)

### CacheTtlPolicyError

**Signature**

```ts
declare const CacheTtlPolicyError: typeof CacheTtlPolicyError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.ts#L28)

### CacheValidationError

**Signature**

```ts
declare const CacheValidationError: typeof CacheValidationError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.ts#L29)

### cacheRuntimeLayer

**Signature**

```ts
declare const cacheRuntimeLayer: (
  options: CacheClientOptions,
) => Layer.Layer<
  CacheRuntime,
  CacheProviderError | CacheTtlPolicyError | CacheValidationError,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.ts#L40)

### createCacheClient

Constructs the existing Promise cache client from its Effect implementation.

**Throws**

TypeError for invalid configuration, or a tagged cache policy/provider error.

**Example**

```ts
createCacheClient({ ownerId: "orders", cacheId: "prices", source: {} });
```

**Signature**

```ts
declare const createCacheClient: <
  const KeySchema extends StandardSchemaV1 = StandardSchemaV1<unknown, unknown>,
  const ValueSchema extends StandardSchemaV1 = StandardSchemaV1<unknown, unknown>,
>(
  options: CacheClientOptions<KeySchema, ValueSchema>,
) => CacheClient<InferInput<KeySchema>, InferOutput<ValueSchema>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.ts#L92)

### createCacheClientEffect

Constructs an Effect-first cache client with a validated provider.

**Example**

```ts
Effect.runSync(createCacheClientEffect({ ownerId: "orders", cacheId: "prices", source: {} }));
```

**Signature**

```ts
declare const createCacheClientEffect: <
  const KeySchema extends StandardSchemaV1 = StandardSchemaV1<unknown, unknown>,
  const ValueSchema extends StandardSchemaV1 = StandardSchemaV1<unknown, unknown>,
>(
  options: CacheClientOptions<KeySchema, ValueSchema>,
) => Effect.Effect<
  CacheEffectClient<InferInput<KeySchema>, InferOutput<ValueSchema>>,
  CacheProviderError | CacheTtlPolicyError | CacheValidationError,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.ts#L47)

### deleteCacheEffect

**Signature**

```ts
declare const deleteCacheEffect: (
  key: unknown,
) => Effect.Effect<void, CacheOperationError, CacheRuntime>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.ts#L33)

### getCacheEffect

**Signature**

```ts
declare const getCacheEffect: (
  key: unknown,
) => Effect.Effect<unknown, CacheOperationError, CacheRuntime>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.ts#L34)

### getOrSetCacheEffect

**Signature**

```ts
declare const getOrSetCacheEffect: (
  key: unknown,
  produce: () => MaybePromise<unknown>,
  settings?: { ttlMs?: number } | undefined,
) => Effect.Effect<unknown, CacheOperationError, CacheRuntime>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.ts#L35)

### hasCacheEffect

**Signature**

```ts
declare const hasCacheEffect: (
  key: unknown,
) => Effect.Effect<boolean, CacheOperationError, CacheRuntime>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.ts#L36)

### incrementCacheEffect

**Signature**

```ts
declare const incrementCacheEffect: (
  key: unknown,
  delta?: any,
  settings?: { ttlMs?: number } | undefined,
) => Effect.Effect<number, CacheOperationError, CacheRuntime>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.ts#L39)

### setCacheEffect

**Signature**

```ts
declare const setCacheEffect: (
  key: unknown,
  value: unknown,
  settings?: { ttlMs?: number } | undefined,
) => Effect.Effect<void, CacheOperationError, CacheRuntime>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.ts#L37)

## `client.types.ts`

### CacheBridgeOptions

**Signature**

```ts
declare const CacheBridgeOptions: CacheBridgeOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.types.ts#L162)

### CacheCapabilities

**Signature**

```ts
declare const CacheCapabilities: CacheCapabilities;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.types.ts#L21)

### CacheCapability

**Signature**

```ts
declare const CacheCapability: "increment";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.types.ts#L20)

### CacheClient (type alias)

Promise client with increment exposed only for numeric value types.

**Example**

```ts
const value = await client.get("sku");
```

**Signature**

```ts
type CacheClient<Key, Value> = CacheClientBase<Key, Value> &
  ([Value] extends [number] ? CacheNumericClient<Key, Value> : object);
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.types.ts#L87)

### CacheClientBase (interface)

Promise methods retained for existing callers.

**Example**

```ts
const value = await client.get("sku");
```

**Signature**

```ts
export interface CacheClientBase<Key, Value> {
  /** Reads one decoded value.
   * @param key - Cache key.
   * @returns Value or undefined, or a rejected cache error.
   * @example await client.get("sku");
   */
  get(key: Key): Promise<Value | undefined>;
  /** Writes a value.
   * @param key - Cache key.
   * @param value - Value to store.
   * @param options - Optional TTL.
   * @returns Completion or a rejected cache error.
   * @example await client.set("sku", 1);
   */
  set(key: Key, value: Value, options?: CacheOperationOptions): Promise<void>;
  /** Removes one entry.
   * @param key - Cache key.
   * @returns Completion or a rejected cache error.
   * @example await client.delete("sku");
   */
  delete(key: Key): Promise<void>;
  /** Tests whether a key exists.
   * @param key - Cache key.
   * @returns Presence or a rejected cache error.
   * @example await client.has("sku");
   */
  has(key: Key): Promise<boolean>;
  /** Reads or produces one value.
   * @param key - Cache key.
   * @param produce - Called only on a cache miss.
   * @param options - Optional TTL.
   * @returns Value or a rejected cache error.
   * @example await client.getOrSet("sku", () => 1);
   */
  getOrSet(
    key: Key,
    produce: () => MaybePromise<Value>,
    options?: CacheOperationOptions,
  ): Promise<Value>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.types.ts#L31)

### CacheClientOptions (interface)

Client configuration and advisory observation hooks.

**Example**

```ts
const options: CacheClientOptions = { ownerId: "orders", cacheId: "prices", source: {} };
```

**Signature**

```ts
export interface CacheClientOptions<
  KeySchema extends StandardSchemaV1 = StandardSchemaV1,
  ValueSchema extends StandardSchemaV1 = StandardSchemaV1,
> {
  readonly ownerId: string;
  readonly cacheId: string;
  readonly source: unknown;
  readonly keySchema?: KeySchema;
  readonly valueSchema?: ValueSchema;
  readonly key?: KeySchema;
  readonly value?: ValueSchema;
  readonly descriptor?: CacheDescriptorPolicy;
  readonly defaultTtlMs?: number;
  readonly maxTtlMs?: number;
  readonly bridge?: CacheInvocationBridge;
  readonly signal?: () => AbortSignal;
  readonly deadline?: () => number | undefined;
  readonly declared?: boolean;
  readonly onObservedEdge?: (edge: CacheObservedEdge) => void;
  readonly onOperation?: (operation: CacheOperationObservation) => void;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.types.ts#L176)

### CacheDescriptorPolicy (interface)

Descriptor schema and TTL defaults used by a client.

**Example**

```ts
const policy: CacheDescriptorPolicy = { defaultTtlMs: 1000 };
```

**Signature**

```ts
export interface CacheDescriptorPolicy {
  readonly key?: StandardSchemaV1;
  readonly value?: StandardSchemaV1;
  readonly defaultTtlMs?: number;
  readonly maxTtlMs?: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.types.ts#L167)

### CacheEffectClient (interface)

Effect-first cache operations; each call can be composed or provided with a test Layer.

**Example**

```ts
const value = await Effect.runPromise(client.get("sku"));
```

**Signature**

```ts
export interface CacheEffectClient<Key, Value> {
  /** Reads a key.
   * @param key - Cache key.
   * @returns Effect of value, undefined, or CacheOperationError.
   * @example client.get("sku");
   */
  get(key: Key): Effect.Effect<Value | undefined, CacheOperationError>;
  /** Writes a value.
   * @param key - Cache key.
   * @param value - Value to store.
   * @param options - Optional TTL.
   * @returns Effect of void or CacheOperationError.
   * @example client.set("sku", 1);
   */
  set(
    key: Key,
    value: Value,
    options?: CacheOperationOptions,
  ): Effect.Effect<void, CacheOperationError>;
  /** Deletes one key.
   * @param key - Cache key.
   * @returns Effect of void or CacheOperationError.
   * @example client.delete("sku");
   */
  delete(key: Key): Effect.Effect<void, CacheOperationError>;
  /** Tests for a key.
   * @param key - Cache key.
   * @returns Effect of boolean or CacheOperationError.
   * @example client.has("sku");
   */
  has(key: Key): Effect.Effect<boolean, CacheOperationError>;
  /** Reads or produces a value.
   * @param key - Cache key.
   * @param produce - Miss producer.
   * @param options - Optional TTL.
   * @returns Effect of value or CacheOperationError.
   * @example client.getOrSet("sku", () => 1);
   */
  getOrSet(
    key: Key,
    produce: () => MaybePromise<Value>,
    options?: CacheOperationOptions,
  ): Effect.Effect<Value, CacheOperationError>;
  /** Increments a numeric value.
   * @param key - Cache key.
   * @param delta - Finite increment.
   * @param options - Optional TTL.
   * @returns Effect of number or CacheOperationError.
   * @example client.increment("sku", 2);
   */
  increment(
    key: Key,
    delta?: number,
    options?: CacheOperationOptions,
  ): Effect.Effect<number, CacheOperationError>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.types.ts#L106)

### CacheInvocationBridge

**Signature**

```ts
declare const CacheInvocationBridge: CacheInvocationBridge;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.types.ts#L162)

### CacheNumericClient (type alias)

Increment method exposed for numeric value contracts.

**Example**

```ts
await numericClient.increment("sku", 2);
```

**Signature**

```ts
type CacheNumericClient<Key, Value extends number> = {
  /** Increments a numeric value.
   * @param key - Cache key.
   * @param delta - Finite increment.
   * @param options - Optional TTL.
   * @returns Updated value or a rejected cache error.
   * @example await numericClient.increment("sku", 2);
   */
  increment(key: Key, delta?: number, options?: CacheOperationOptions): Promise<Value>;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.types.ts#L74)

### CacheObservedEdge

**Signature**

```ts
declare const CacheObservedEdge: CacheObservedEdge;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.types.ts#L163)

### CacheOperation

**Signature**

```ts
declare const CacheOperation: CacheOperation;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.types.ts#L22)

### CacheOperationContext

**Signature**

```ts
declare const CacheOperationContext: CacheOperationContext;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.types.ts#L23)

### CacheOperationError (type alias)

Expected failures from a cache Effect operation.

**Example**

```ts
Effect.catchTag("CacheProviderError", (error) => Effect.log(error.message));
```

**Signature**

```ts
type CacheOperationError =
  | CacheCapabilityError
  | CacheDependencyError
  | CacheIncrementUnsupportedError
  | CacheOperationCancelledError
  | CacheOperationTimeoutError
  | CacheProviderError
  | CacheProviderFailureError
  | CacheSchemaValidationError
  | CacheTtlPolicyError
  | CacheValidationError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.types.ts#L92)

### CacheOperationObservation

**Signature**

```ts
declare const CacheOperationObservation: CacheOperationObservation;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.types.ts#L163)

### CacheOperationOptions

**Signature**

```ts
declare const CacheOperationOptions: CacheOperationOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.types.ts#L24)

### CacheOperationOutcome

**Signature**

```ts
declare const CacheOperationOutcome: CacheOperationOutcome;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.types.ts#L25)

### CacheProvider

**Signature**

```ts
declare const CacheProvider: CacheProvider;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.types.ts#L26)

## `define-cache-compat.ts`

### runDescriptor

Runs a descriptor Effect and restores established synchronous errors.

**Throws**

The original shared-contract error or TypeError for invalid input.

**Example**

```ts
runDescriptor(Effect.succeed(1));
```

**Signature**

```ts
declare const runDescriptor: <A>(effect: Effect.Effect<A, CacheDescriptorError>) => A;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/define-cache-compat.ts#L10)

## `define-cache-error.ts`

### CacheDescriptorError (class)

Invalid descriptor input, with its original cause when a dependency threw.

**Example**

```ts
new CacheDescriptorError({ reason: "Invalid cache descriptor" });
```

**Signature**

```ts
declare class CacheDescriptorError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/define-cache-error.ts#L6)

## `define-cache.ts`

### defineCache

Defines a typed cache contract with existing synchronous behavior.

**Throws**

TypeError for invalid options and IDs.

**Example**

```ts
import { defineCache } from "@relkit/cache";
import { z } from "@relkit/schema";
const prices = defineCache({ id: "prices", key: z.string(), value: z.number() });
```

**Signature**

```ts
declare const defineCache: <
  const Id extends string,
  const KeySchema extends StandardSchemaV1,
  const ValueSchema extends StandardSchemaV1,
>(
  options: DefineCacheOptions<Id, KeySchema, ValueSchema>,
) => CacheDescriptor<Id, InferInput<KeySchema>, InferOutput<ValueSchema>, KeySchema, ValueSchema>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/define-cache.ts#L94)

Since v0.1.0

### CacheDescriptor

**Signature**

```ts
declare const CacheDescriptor: CacheDescriptor<Id, Key, Value, KeySchema, ValueSchema>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/define-cache.ts#L13)

### CacheDescriptorAny

**Signature**

```ts
declare const CacheDescriptorAny: CacheDescriptorAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/define-cache.ts#L14)

### CacheDescriptorError

**Signature**

```ts
declare const CacheDescriptorError: typeof CacheDescriptorError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/define-cache.ts#L17)

### DefineCacheOptions

**Signature**

```ts
declare const DefineCacheOptions: DefineCacheOptions<Id, KeySchema, ValueSchema>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/define-cache.ts#L15)

### assertCacheDescriptor

Asserts a cache descriptor synchronously.

**Throws**

TypeError when the candidate is invalid.

**Example**

```ts
assertCacheDescriptor(value);
```

**Signature**

```ts
declare const assertCacheDescriptor: (value: unknown) => asserts value is CacheDescriptorAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/define-cache.ts#L142)

### assertCacheDescriptorEffect

Asserts a cache descriptor in Effect.

**Example**

```ts
Effect.runSync(assertCacheDescriptorEffect(value));
```

**Signature**

```ts
declare const assertCacheDescriptorEffect: (
  value: unknown,
) => Effect.Effect<undefined, CacheDescriptorError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/define-cache.ts#L127)

### defineCacheEffect

Defines a typed, frozen cache contract in Effect.

**Example**

```ts
Effect.runSync(defineCacheEffect({ id: "prices", key: z.string(), value: z.number() }));
```

**Signature**

```ts
declare const defineCacheEffect: <
  const Id extends string,
  const KeySchema extends StandardSchemaV1,
  const ValueSchema extends StandardSchemaV1,
>(
  options: DefineCacheOptions<Id, KeySchema, ValueSchema>,
) => Effect.Effect<
  CacheDescriptor<Id, InferInput<KeySchema>, InferOutput<ValueSchema>, KeySchema, ValueSchema>,
  CacheDescriptorError,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/define-cache.ts#L23)

### isCacheDescriptor

Checks a possible cache descriptor synchronously.

**Example**

```ts
if (isCacheDescriptor(value)) console.log(value.id);
```

**Signature**

```ts
declare const isCacheDescriptor: (value: unknown) => value is CacheDescriptorAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/define-cache.ts#L119)

### isCacheDescriptorEffect

Checks a possible descriptor without throwing.

**Example**

```ts
Effect.runSync(isCacheDescriptorEffect(value));
```

**Signature**

```ts
declare const isCacheDescriptorEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/define-cache.ts#L108)

## `define-cache.types.ts`

### CacheDescriptor (interface)

Frozen cache descriptor with phantom key and value types.

**Example**

```ts
const descriptor = defineCache({ id: "prices", key: z.string(), value: z.number() });
```

**Signature**

```ts
export interface CacheDescriptor<
  Id extends string,
  Key,
  Value,
  KeySchema extends StandardSchemaV1 = StandardSchemaV1,
  ValueSchema extends StandardSchemaV1 = StandardSchemaV1,
> extends DescriptorBase<"cache", Id> {
  readonly profile?: string;
  readonly key: KeySchema;
  readonly value: ValueSchema;
  readonly defaultTtlMs?: number;
  readonly maxTtlMs?: number;
  readonly __key?: Key;
  readonly __value?: Value;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/define-cache.types.ts#L6)

### CacheDescriptorAny (type alias)

Any cache descriptor when schema type parameters are not known.

**Example**

```ts
const value: CacheDescriptorAny = defineCache(options);
```

**Signature**

```ts
type CacheDescriptorAny = CacheDescriptor<string, unknown, unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/define-cache.types.ts#L24)

### DefineCacheOptions (interface)

Inputs used to define one typed cache contract.

**Example**

```ts
const options: DefineCacheOptions<"prices", typeof key, typeof value> = {
  id: "prices",
  key,
  value,
};
```

**Signature**

```ts
export interface DefineCacheOptions<
  Id extends string,
  KeySchema extends StandardSchemaV1,
  ValueSchema extends StandardSchemaV1,
> extends DescriptorMetadata {
  readonly id: Id;
  readonly profile?: string;
  readonly key: KeySchema;
  readonly value: ValueSchema;
  readonly defaultTtlMs?: number;
  readonly maxTtlMs?: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/define-cache.types.ts#L28)

## `index.ts`

### "./client.js" (namespace export)

Re-exports all named exports from the "./client.js" module.

**Signature**

```ts
export * from "./client.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/index.ts#L2)

### "./define-cache.js" (namespace export)

Re-exports all named exports from the "./define-cache.js" module.

**Signature**

```ts
export * from "./define-cache.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/index.ts#L1)