Implementation:Helicone Helicone Cache Provider Interface

Knowledge Sources	Helicone
Domains	Caching, Infrastructure, Abstraction
Last Updated	2026-02-14 06:32 GMT

Overview

An abstract cache provider interface that enables dependency injection of caching implementations across packages, supporting atomic get-or-generate operations with dynamic TTL.

Description

The cache/provider.ts module defines the CacheProvider interface, the core abstraction for cross-package caching in Helicone. The interface exposes a single method, getAndStoreToken, that atomically checks the cache for a key, calls a generator function on cache miss, and stores the result with a dynamic TTL determined by the generator's return value.

The module also defines TokenWithTTL<T>, which wraps a cached value with its ttl (in seconds) and expiresAt (Unix timestamp in milliseconds) metadata. A local Result<T, E> type is defined for cache operation results.

This interface enables packages like the cost/auth module to accept a cache provider via dependency injection without being coupled to a specific implementation (such as Redis or in-memory caching).

Usage

Implement the CacheProvider interface with a concrete caching backend (e.g., Redis, KV store) and pass it to functions that support cached operations, such as getGoogleAccessToken in the GCP auth module.

Code Reference

Source Location

• Repository: Helicone
• File: packages/common/cache/provider.ts

Signature

export interface Result<T, E> {
  data: T | null;
  error: E | null;
}

export interface TokenWithTTL<T> {
  value: T;
  ttl: number;       // TTL in seconds
  expiresAt: number;  // Unix timestamp in milliseconds
}

export interface CacheProvider {
  getAndStoreToken<T, K>(
    key: string,
    fn: () => Promise<Result<TokenWithTTL<T>, K>>
  ): Promise<Result<T, K>>;
}

Import

import {
  CacheProvider,
  Result,
  TokenWithTTL,
} from "@helicone/common/cache/provider";

I/O Contract

Interface	Method	Parameters	Returns	Description
CacheProvider	getAndStoreToken	key: string, fn: () => Promise<Result<TokenWithTTL<T>, K>>	Promise<Result<T, K>>	Atomically checks cache, generates on miss, stores with dynamic TTL

Type	Fields	Description
TokenWithTTL<T>	value: T, ttl: number, expiresAt: number	Wraps a cached value with TTL and absolute expiration time
Result<T, E>	null, error: E | null	Simple result type for cache operations

Usage Examples

import { CacheProvider, Result, TokenWithTTL } from "@helicone/common/cache/provider";

// Example implementation with a Redis-like store
class RedisCacheProvider implements CacheProvider {
  async getAndStoreToken<T, K>(
    key: string,
    fn: () => Promise<Result<TokenWithTTL<T>, K>>
  ): Promise<Result<T, K>> {
    // Check cache first
    const cached = await redis.get(key);
    if (cached) {
      return { data: JSON.parse(cached), error: null };
    }

    // Generate on miss
    const result = await fn();
    if (result.error) {
      return { data: null, error: result.error };
    }

    // Store with TTL
    await redis.set(key, JSON.stringify(result.data!.value), "EX", result.data!.ttl);
    return { data: result.data!.value, error: null };
  }
}

// Use with GCP auth
import { getGoogleAccessToken } from "@helicone/cost/auth/gcpServiceAccountAuth";

const cache = new RedisCacheProvider();
const token = await getGoogleAccessToken(serviceAccountJson, orgId, scopes, cache);

Related Pages

• Principle:Helicone_Helicone_Cache_Abstraction