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

import type { Rpc } from "@cloudflare/workers-types";
import type { Input } from "alchemy/Input";
import { isResourceOfType } from "alchemy/Resource";
import type { Worker } from "./Worker.ts";
import { WorkerTypeId } from "./WorkerRuntime.ts";

type WorkerEntrypointTypeId = "Cloudflare.WorkerEntrypoint";
const WorkerEntrypointTypeId: WorkerEntrypointTypeId = "Cloudflare.WorkerEntrypoint";

export interface WorkerEntrypointOptions {
  /**
   * Named entrypoint on the target Worker — the exported
   * `WorkerEntrypoint` class the binding calls. Omitted → the default
   * entrypoint (equivalent to binding the Worker directly, but with
   * {@link props} support).
   */
  entrypoint?: string;
  /**
   * Properties exposed to the target entrypoint via workerd's
   * `ctx.props`. Values accept `Output` references and resolve at deploy
   * time.
   *
   * Local dev (`alchemy dev`) delivers these today. On deployed Workers
   * the Cloudflare API's binding schema does not carry `props` yet, so
   * they are typed and plumbed but dropped at upload until the distilled
   * `workers` service adds the field.
   */
  props?: Record<string, Input<unknown>>;
}

/**
 * A service binding to an entrypoint of another Worker or of this Worker —
 * the value form accepted in an async Worker's `env`. See
 * {@link WorkerEntrypoint}.
 */
export interface WorkerEntrypointBinding<
  Entrypoint extends Rpc.WorkerEntrypointBranded | undefined = undefined,
> {
  /** Brand discriminating entrypoint bindings in `env` classification. */
  readonly kind: WorkerEntrypointTypeId;
  /** The target Worker resource, or `undefined` for this Worker itself. */
  readonly worker: Worker | undefined;
  /** Named entrypoint on the target, or `undefined` for the default. */
  readonly entrypoint: string | undefined;
  /** `ctx.props` delivered to the target entrypoint. */
  readonly props: Record<string, Input<unknown>> | undefined;
  /** Entry-point instance type used by `InferEnv`; absent at runtime. */
  readonly "~alchemy/entrypoint"?: Entrypoint;
}

/**
 * Bind an entrypoint of another Worker or of this Worker.
 *
 * Binding a Worker directly in `env` (`env: { TARGET: worker }`) targets
 * its *default* entrypoint. A Worker that exposes additional
 * `WorkerEntrypoint` classes — workerd treats every named class export of
 * an entry module as an entrypoint — is bound with `WorkerEntrypoint`,
 * which selects the class by name and can deliver `ctx.props` to it.
 *
 * ### Defining the Target Entrypoint
 * Export a class extending Cloudflare's native `WorkerEntrypoint` from
 * the target Worker's module. This `Api` class defines the RPC methods
 * that callers can invoke through a named service binding.
 *
 * **Example:** Export the Api class
 * ```typescript
 * // target/src/worker.ts
 * import { WorkerEntrypoint } from "cloudflare:workers";
 *
 * export class Api extends WorkerEntrypoint {
 *   async greet(name: string): Promise<string> {
 *     return `hello ${name}`;
 *   }
 * }
 *
 * export default {
 *   async fetch() {
 *     return new Response("ok");
 *   },
 * };
 * ```
 *
 * ### Binding a Named Entrypoint
 * Import the exported `Api` class as a type and select its named export
 * with `"Api"`. Pass its instance type (`Api`, not `typeof Api`) to get
 * Cloudflare's native `Service<Api>` RPC client. Without a type argument,
 * the binding is a bare `Fetcher`; the entrypoint name alone cannot
 * identify the class's type.
 *
 * **Example:** Bind and call the exported Api
 * ```typescript
 * // alchemy.run.ts
 * import * as Cloudflare from "@alchemy.run/cloudflare";
 * import type { Api } from "./target/src/worker.ts";
 *
 * const target = yield* Cloudflare.Worker("Target", {
 *   main: "./target/src/worker.ts",
 * });
 *
 * const caller = yield* Cloudflare.Worker("Caller", {
 *   main: "./caller/src/worker.ts",
 *   env: {
 *     API: Cloudflare.WorkerEntrypoint<Api>(target, "Api"),
 *   },
 * });
 * ```
 *
 * ```typescript
 * // caller/src/worker.ts
 * import type { CallerEnv } from "../../alchemy.run.ts";
 *
 * export default {
 *   async fetch(request: Request, env: CallerEnv) {
 *     return new Response(await env.API.greet("alice"));
 *   },
 * };
 * ```
 *
 * ### Binding This Worker's Own Entrypoints
 * Leave out the Worker to bind an entrypoint of the Worker that declares
 * the binding (Wrangler's `services: [{ binding, service: <this worker>,
 * entrypoint }]`). With no name, it binds the default export, the same as
 * `Cloudflare.Workers.Self`.
 *
 * **Example:** Bind this Worker's McpEntrypoint and default export
 * ```typescript
 * // alchemy.run.ts
 * import type { McpEntrypoint } from "./src/worker.ts";
 *
 * const api = yield* Cloudflare.Worker("Api", {
 *   main: "./src/worker.ts",
 *   env: {
 *     MCP: Cloudflare.WorkerEntrypoint<McpEntrypoint>("McpEntrypoint"),
 *     SELF: Cloudflare.WorkerEntrypoint(),
 *   },
 * });
 * ```
 *
 * ```typescript
 * // src/worker.ts
 * export class McpEntrypoint extends WorkerEntrypoint {
 *   async fetch() {
 *     return new Response("mcp");
 *   }
 * }
 *
 * export default {
 *   fetch: (request: Request, env: WorkerEnv) => env.MCP.fetch(request),
 * };
 * ```
 *
 * ### Delivering ctx.props
 * The options form attaches properties the target reads from
 * `this.ctx.props` — workerd's per-binding configuration channel. `Output`
 * values resolve at deploy time. An Effect Worker reads them with
 * `yield* ctx.props` on `Cloudflare.WorkerExecutionContext`.
 *
 * **Example:** Entrypoint binding with props
 * ```typescript
 * env: {
 *   VENDOR: Cloudflare.WorkerEntrypoint(vendorWorker, {
 *     entrypoint: "Vendor",
 *     props: { baseUrl: site.url },
 *   }),
 * }
 * ```
 *
 * @resource
 * @product Workers
 * @category Workers & Compute
 */
export interface WorkerEntrypointFunction {
  /** An entrypoint of this Worker: its default export, or the named class. */
  <Entrypoint extends Rpc.WorkerEntrypointBranded | undefined = undefined>(
    entrypointOrOptions?: string | WorkerEntrypointOptions,
  ): WorkerEntrypointBinding<NoInfer<Entrypoint>>;
  /** An entrypoint of another Worker: its default export, or the named class. */
  <Entrypoint extends Rpc.WorkerEntrypointBranded | undefined = undefined>(
    worker: Worker,
    entrypointOrOptions?: string | WorkerEntrypointOptions,
  ): WorkerEntrypointBinding<NoInfer<Entrypoint>>;
}

export const WorkerEntrypoint: WorkerEntrypointFunction = (
  workerOrEntrypoint?: Worker | string | WorkerEntrypointOptions,
  entrypointOrOptions?: string | WorkerEntrypointOptions,
) => {
  // A Worker resource carries its `Type`; a bare name or options object
  // names an entrypoint of this Worker. A `Worker.ref(...)` is a callable
  // Output proxy (`typeof` is "function"), so match on `Type` rather than
  // on the value's shape.
  const targetsWorker = isResourceOfType(workerOrEntrypoint, WorkerTypeId);
  const worker = targetsWorker ? (workerOrEntrypoint as Worker) : undefined;
  const entrypoint = targetsWorker
    ? entrypointOrOptions
    : (workerOrEntrypoint as string | WorkerEntrypointOptions | undefined);
  const options = typeof entrypoint === "string" ? { entrypoint } : (entrypoint ?? {});
  return {
    kind: WorkerEntrypointTypeId,
    worker,
    entrypoint: options.entrypoint,
    props: options.props,
  };
};

/** Structural guard for {@link WorkerEntrypointBinding} `env` values. */
export const isWorkerEntrypoint = (value: unknown): value is WorkerEntrypointBinding<any> =>
  typeof value === "object" &&
  value !== null &&
  (value as { kind?: unknown }).kind === WorkerEntrypointTypeId;