sailfork / t3code-github / .repos/ alchemy-effect/ packages/ frontend-frameworks/ src/ vinext/ cache/ kv-runtime.ts

/**
 * vinext data-cache adapter backed by a Cloudflare KV namespace.
 * Default export is the factory `virtual:vinext-cache-adapters` calls as
 * `({ env, options }) => CacheHandler`.
 *
 * Reads `env[binding]` (default `VINEXT_KV_CACHE`). Same codec as Redis
 * and S3 via {@link makeDataCacheHandler}. Prerender pairs are uploaded
 * at `alchemy deploy` — this runtime does not walk the filesystem.
 */
import { makeDataCacheHandler, type DataCacheStore } from "./handler.ts";

export interface KvAdapterOptions extends Record<string, unknown> {
  /** Worker binding name. @default "VINEXT_KV_CACHE" */
  readonly binding?: string;
  readonly appPrefix?: string;
  readonly ttlSeconds?: number;
  readonly tagCacheTtlMs?: number;
}

const DEFAULT_BINDING = "VINEXT_KV_CACHE";
/** Cloudflare KV rejects expirationTtl below 60 seconds. */
const MIN_KV_TTL_SECONDS = 60;

interface KvNamespaceLike {
  get(key: string): Promise<string | null>;
  put(key: string, value: string, options?: { expirationTtl?: number }): Promise<void>;
  delete(key: string): Promise<void>;
}

const isKvNamespace = (value: unknown): value is KvNamespaceLike =>
  typeof value === "object" &&
  value !== null &&
  typeof (value as KvNamespaceLike).get === "function" &&
  typeof (value as KvNamespaceLike).put === "function" &&
  typeof (value as KvNamespaceLike).delete === "function";

const kvStore = (ns: KvNamespaceLike): DataCacheStore => ({
  async getText(key) {
    return (await ns.get(key)) ?? undefined;
  },
  async putText(key, value, ttlMs) {
    const expirationTtl =
      ttlMs !== undefined && ttlMs > 0
        ? Math.max(MIN_KV_TTL_SECONDS, Math.ceil(ttlMs / 1000))
        : undefined;
    await ns.put(key, value, expirationTtl !== undefined ? { expirationTtl } : undefined);
  },
  async delete(key) {
    await ns.delete(key);
  },
});

const createKvDataCacheAdapter = ({
  env,
  options,
}: {
  env?: Record<string, unknown>;
  options?: KvAdapterOptions;
}) => {
  const binding = options?.binding ?? DEFAULT_BINDING;
  const ns = env?.[binding];
  if (!isKvNamespace(ns)) {
    throw new Error(`[vinext] The KV data cache adapter requires Worker binding \`${binding}\`.`);
  }
  return makeDataCacheHandler(kvStore(ns), options);
};

export default createKvDataCacheAdapter;