sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ Workers/ Cache.ts

import type * as cf from "@cloudflare/workers-types";
import * as Namespace from "alchemy/Namespace";
import type { RuntimeContext } from "alchemy/RuntimeContext";
import * as Effect from "effect/Effect";
import { Worker, WorkerExecutionContext, type CachePurgeError } from "./Worker.ts";

export interface CacheOptions {
  /**
   * Whether Workers Cache checks the cache before invoking the Worker.
   * @default true
   */
  enabled?: boolean;
  /**
   * Share cached responses across Worker versions. By default the cache is
   * scoped to a single version, so every deploy starts cold.
   * @default false
   */
  crossVersionCache?: boolean;
}

/**
 * Runtime client for Workers Cache, returned by `yield* Cloudflare.cache()`.
 */
export interface CacheClient {
  /**
   * Purge cached responses by `Cache-Tag`, path prefix, or everything.
   */
  purge(
    options: cf.CachePurgeOptions,
  ): Effect.Effect<cf.CachePurgeResult, CachePurgeError, RuntimeContext>;
}

/**
 * Enable [Workers Cache](https://blog.cloudflare.com/workers-cache/) on the
 * surrounding Worker and get the runtime cache client.
 *
 * Yielding `cache()` in an Effect-native Worker's init phase turns the cache
 * on at deploy time (the equivalent of setting `cache: { enabled: true }` on
 * the Worker's props) and returns a client whose `purge` drives the runtime
 * `ctx.cache` API from your handlers.
 *
 * What gets cached is controlled by standard response headers —
 * `Cache-Control` (including `stale-while-revalidate`), `Cache-Tag` for
 * tag-based purging, and `Vary` for content negotiation.
 *
 * For async (non-Effect) Workers, set the `cache` prop on the Worker
 * instead.
 *
 * **Example:** Example
 * ```typescript
 * Effect.gen(function* () {
 *   // init: enable Workers Cache on this Worker
 *   const { purge } = yield* Cloudflare.cache();
 *
 *   return {
 *     fetch: Effect.gen(function* () {
 *       const request = yield* HttpServerRequest;
 *       if (request.url.startsWith("/invalidate")) {
 *         yield* purge({ tags: ["products"] });
 *         return HttpServerResponse.text("purged");
 *       }
 *       return HttpServerResponse.text("hello", {
 *         headers: {
 *           "Cache-Control": "public, max-age=300",
 *           "Cache-Tag": "products",
 *         },
 *       });
 *     }),
 *   };
 * })
 * ```
 *
 * @binding
 * @product Workers
 * @category Workers & Compute
 */
export const cache = (options?: CacheOptions): Effect.Effect<CacheClient, never, Worker> =>
  Effect.gen(function* () {
    const host = yield* Worker;
    const exec = yield* WorkerExecutionContext;
    if (!globalThis.__ALCHEMY_RUNTIME__) {
      yield* Namespace.push(
        host.LogicalId,
        host.bind("Cache", {
          cache: {
            enabled: options?.enabled ?? true,
            crossVersionCache: options?.crossVersionCache,
          },
        }),
      );
    }
    return {
      // `exec` is the init-phase deferred context; purge resolves the live
      // per-event context from the calling handler's fiber.
      purge: (purgeOptions) => exec.cache.purge(purgeOptions),
    };
  });