Cache API

Generated public TypeScript reference for @relkit/cache.

Common APIs

• defineCache

For configuration and examples, read define, organization, rate limits.

For a complete workflow, follow 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.

client-abort.ts

runAbortableEffect

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

Example

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

Signature

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

client-effects.ts

deleteCacheEffect

Deletes one key.

Example

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

Signature

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

Source

getCacheEffect

Reads a decoded cache value.

Example

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

Signature

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

Source

getOrSetCacheEffect

Reads or produces and stores one value through the provider.

Example

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

Signature

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

Source

hasCacheEffect

Checks key presence.

Example

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

Signature

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

Source

setCacheEffect

Writes a validated key and value.

Example

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

Signature

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

Source

client-errors.ts

CacheCapabilityError (class)

The provider lacks a declared cache capability.

Example

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

Signature

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

Source

code (property)

Signature

readonly code: "RELKIT_CACHE_CAPABILITY_UNSUPPORTED"

Source

CacheDependencyError (class)

A function used an undeclared cache.

Example

new CacheDependencyError("prices");

Signature

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

Source

code (property)

Signature

readonly code: "RELKIT_CACHE_DEPENDENCY_UNDECLARED"

Source

CacheIncrementUnsupportedError (class)

Increment needs a numeric value contract.

Example

new CacheIncrementUnsupportedError();

Signature

declare class CacheIncrementUnsupportedError {
  constructor();
}

Source

code (property)

Signature

readonly code: "RELKIT_CACHE_INCREMENT_UNSUPPORTED"

Source

CacheOperationCancelledError (class)

Caller cancellation of an operation.

Example

new CacheOperationCancelledError();

Signature

declare class CacheOperationCancelledError {
  constructor();
}

Source

code (property)

Signature

readonly code: "ABORT_ERR"

Source

CacheOperationTimeoutError (class)

Deadline expiration of an operation.

Example

new CacheOperationTimeoutError();

Signature

declare class CacheOperationTimeoutError {
  constructor();
}

Source

code (property)

Signature

readonly code: "ETIMEDOUT"

Source

CacheProviderError (class)

The provider omits an operation.

Example

new CacheProviderError("get");

Signature

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

Source

code (property)

Signature

readonly code: "RELKIT_CACHE_PROVIDER_UNAVAILABLE"

Source

CacheProviderFailureError (class)

Provider rejection with its original cause retained.

Example

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

Signature

declare class CacheProviderFailureError

Source

CacheSchemaValidationError (class)

A tagged schema failure retaining its legacy TypeError classification.

Example

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

Signature

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

Source

_tag (property)

Signature

readonly _tag: "CacheSchemaValidationError"

Source

code (property)

Signature

readonly code: "RELKIT_CACHE_SCHEMA_VALIDATION"

Source

CacheTtlPolicyError (class)

A tagged TTL violation retaining its legacy RangeError classification.

Example

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

Signature

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

Source

_tag (property)

Signature

readonly _tag: "CacheTtlPolicyError"

Source

code (property)

Signature

readonly code: "RELKIT_CACHE_TTL_POLICY"

Source

reason (property)

Signature

readonly reason: string

Source

CacheValidationError (class)

Invalid non-schema input or provider result.

Example

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

Signature

declare class CacheValidationError

Source

client-increment.ts

incrementCacheEffect

Increments a numeric cache value.

Example

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

Signature

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

Source

client-observability.ts

CacheTelemetry (class)

Injectable telemetry for cache Effect operations.

Example

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

Signature

declare class CacheTelemetry

Source

CacheTelemetryLive

Default spans and bounded Effect metrics.

Example

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

Signature

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

Source

observeCache

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

Example

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

Signature

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

Source

client-observability.types.ts

CacheObservedEdge (interface)

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

Example

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

Signature

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

Source

CacheObservedOperation (type alias)

Names of observed public cache operations.

Example

const operation: CacheObservedOperation = "get";

Signature

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

Source

CacheOperationObservation (interface)

One operation outcome with bounded, input-free fields.

Example

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

Signature

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

Source

CacheTelemetryService (interface)

Replaceable telemetry boundary for cache Effect calls.

Example

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

Signature

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

client-operation.ts

invokeProvider

Invokes an optional provider method in the typed error channel.

Example

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

Signature

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

Source

runCacheOperation

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

Example

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

Signature

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

Source

client-operation.types.ts

CacheCapabilities (interface)

Provider-declared feature support.

Example

const capabilities: CacheCapabilities = { increment: true };

Signature

export interface CacheCapabilities {
  readonly increment?: boolean;
}

Source

CacheCapability (type alias)

Provider feature negotiated before executing an operation.

Example

const capability: CacheCapability = "increment";

Signature

type CacheCapability = "increment";

Source

CacheInvocation (interface)

Provider invocation and its typed Effect work.

Example

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

Signature

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

CacheOperation (type alias)

Fixed cache method names used for spans and metrics.

Example

const operation: CacheOperation = "get";

Signature

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

Source

CacheOperationContext (interface)

Cancellation and deadline data passed to a provider call.

Example

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

Signature

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

Source

CacheOperationOptions (interface)

Optional write or increment TTL in milliseconds.

Example

const options: CacheOperationOptions = { ttlMs: 1000 };

Signature

export interface CacheOperationOptions {
  readonly ttlMs?: number;
}

Source

CacheOperationOutcome (type alias)

Stable operation outcomes for RELKIT observations.

Example

const outcome: CacheOperationOutcome = "success";

Signature

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

Source

CacheProvider (interface)

Optional provider methods; missing methods fail with CacheProviderError.

Example

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

Signature

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

client-runtime.ts

CacheRuntime (class)

Substitutable provider and invocation configuration.

Example

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

Signature

declare class CacheRuntime

Source

asProviderEffect

Validates the provider source in Effect.

Example

Effect.runSync(asProviderEffect(undefined));

Signature

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

Source

cacheRuntimeLayer

Creates the live provider Layer from client options.

Example

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

Signature

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

Source

client-runtime.types.ts

CacheBridgeOptions (interface)

Metadata sent to an invocation bridge.

Example

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

Signature

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

Source

CacheInvocationBridge (interface)

Existing invocation bridge contract.

Example

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

Signature

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

CacheRuntimeService (interface)

Provider and options supplied to cache Effect operations.

Example

const runtime: CacheRuntimeService = { options, provider };

Signature

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

Source

client-validation-effect.ts

normalizeTtlEffect

Normalizes a requested TTL against the configured policy.

Example

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

Signature

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

Source

validateBooleanEffect

Validates a provider has result.

Example

Effect.runSync(validateBooleanEffect(true));

Signature

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

Source

validateClientIdentityEffect

Validates client identity before a provider is acquired.

Example

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

Signature

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

Source

validateClientPolicyEffect

Validates schemas and TTL policy after the provider source.

Example

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

Signature

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

Source

validateIncrementDeltaEffect

Validates a finite increment delta.

Example

Effect.runSync(validateIncrementDeltaEffect(2));

Signature

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

Source

validatePolicyEffect

Validates configured policy numbers.

Example

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

Signature

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

Source

validateSchemaEffect

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

Example

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

Signature

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

Source

client.ts

“./client.types.js” (namespace export)

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

Signature

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

Source

CacheCapabilityError

Signature

declare const CacheCapabilityError: typeof CacheCapabilityError;

Source

CacheDependencyError

Signature

declare const CacheDependencyError: typeof CacheDependencyError;

Source

CacheIncrementUnsupportedError

Signature

declare const CacheIncrementUnsupportedError: typeof CacheIncrementUnsupportedError;

Source

CacheOperationCancelledError

Signature

declare const CacheOperationCancelledError: typeof CacheOperationCancelledError;

Source

CacheOperationTimeoutError

Signature

declare const CacheOperationTimeoutError: typeof CacheOperationTimeoutError;

Source

CacheProviderError

Signature

declare const CacheProviderError: typeof CacheProviderError;

Source

CacheProviderFailureError

Signature

declare const CacheProviderFailureError: typeof CacheProviderFailureError;

Source

CacheRuntime

Signature

declare const CacheRuntime: typeof CacheRuntime;

Source

CacheSchemaValidationError

Signature

declare const CacheSchemaValidationError: typeof CacheSchemaValidationError;

Source

CacheTelemetry

Signature

declare const CacheTelemetry: typeof CacheTelemetry;

Source

CacheTelemetryLive

Signature

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

Source

CacheTtlPolicyError

Signature

declare const CacheTtlPolicyError: typeof CacheTtlPolicyError;

Source

CacheValidationError

Signature

declare const CacheValidationError: typeof CacheValidationError;

Source

cacheRuntimeLayer

Signature

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

Source

createCacheClient

Constructs the existing Promise cache client from its Effect implementation.

Throws

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

Example

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

Signature

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

createCacheClientEffect

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

Example

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

Signature

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

deleteCacheEffect

Signature

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

Source

getCacheEffect

Signature

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

Source

getOrSetCacheEffect

Signature

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

Source

hasCacheEffect

Signature

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

Source

incrementCacheEffect

Signature

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

Source

setCacheEffect

Signature

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

Source

client.types.ts

CacheBridgeOptions

Signature

declare const CacheBridgeOptions: CacheBridgeOptions;

Source

CacheCapabilities

Signature

declare const CacheCapabilities: CacheCapabilities;

Source

CacheCapability

Signature

declare const CacheCapability: "increment";

Source

CacheClient (type alias)

Promise client with increment exposed only for numeric value types.

Example

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

Signature

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

Source

CacheClientBase (interface)

Promise methods retained for existing callers.

Example

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

Signature

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

CacheClientOptions (interface)

Client configuration and advisory observation hooks.

Example

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

Signature

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

CacheDescriptorPolicy (interface)

Descriptor schema and TTL defaults used by a client.

Example

const policy: CacheDescriptorPolicy = { defaultTtlMs: 1000 };

Signature

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

Source

CacheEffectClient (interface)

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

Example

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

Signature

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

CacheInvocationBridge

Signature

declare const CacheInvocationBridge: CacheInvocationBridge;

Source

CacheNumericClient (type alias)

Increment method exposed for numeric value contracts.

Example

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

Signature

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

CacheObservedEdge

Signature

declare const CacheObservedEdge: CacheObservedEdge;

Source

CacheOperation

Signature

declare const CacheOperation: CacheOperation;

Source

CacheOperationContext

Signature

declare const CacheOperationContext: CacheOperationContext;

Source

CacheOperationError (type alias)

Expected failures from a cache Effect operation.

Example

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

Signature

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

Source

CacheOperationObservation

Signature

declare const CacheOperationObservation: CacheOperationObservation;

Source

CacheOperationOptions

Signature

declare const CacheOperationOptions: CacheOperationOptions;

Source

CacheOperationOutcome

Signature

declare const CacheOperationOutcome: CacheOperationOutcome;

Source

CacheProvider

Signature

declare const CacheProvider: CacheProvider;

Source

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

runDescriptor(Effect.succeed(1));

Signature

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

Source

define-cache-error.ts

CacheDescriptorError (class)

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

Example

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

Signature

declare class CacheDescriptorError

Source

define-cache.ts

defineCache

Defines a typed cache contract with existing synchronous behavior.

Throws

TypeError for invalid options and IDs.

Example

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

Signature

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

Since v0.1.0

CacheDescriptor

Signature

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

Source

CacheDescriptorAny

Signature

declare const CacheDescriptorAny: CacheDescriptorAny;

Source

CacheDescriptorError

Signature

declare const CacheDescriptorError: typeof CacheDescriptorError;

Source

DefineCacheOptions

Signature

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

Source

assertCacheDescriptor

Asserts a cache descriptor synchronously.

Throws

TypeError when the candidate is invalid.

Example

assertCacheDescriptor(value);

Signature

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

Source

assertCacheDescriptorEffect

Asserts a cache descriptor in Effect.

Example

Effect.runSync(assertCacheDescriptorEffect(value));

Signature

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

Source

defineCacheEffect

Defines a typed, frozen cache contract in Effect.

Example

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

Signature

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

isCacheDescriptor

Checks a possible cache descriptor synchronously.

Example

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

Signature

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

Source

isCacheDescriptorEffect

Checks a possible descriptor without throwing.

Example

Effect.runSync(isCacheDescriptorEffect(value));

Signature

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

Source

define-cache.types.ts

CacheDescriptor (interface)

Frozen cache descriptor with phantom key and value types.

Example

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

Signature

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

CacheDescriptorAny (type alias)

Any cache descriptor when schema type parameters are not known.

Example

const value: CacheDescriptorAny = defineCache(options);

Signature

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

Source

DefineCacheOptions (interface)

Inputs used to define one typed cache contract.

Example

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

Signature

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

index.ts

“./client.js” (namespace export)

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

Signature

export * from "./client.js";

Source

“./define-cache.js” (namespace export)

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

Signature

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

Source