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

import type * as cf from "@cloudflare/workers-types";
import type { RuntimeContext } from "alchemy/RuntimeContext";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Stream from "effect/Stream";
import * as Binding from "../Workers/Binding.ts";
import type { ImagesBinding } from "./ImagesBinding.ts";

const TypeId = "Cloudflare.Images.Images" as const;
type TypeId = typeof TypeId;

export class ImagesError extends Data.TaggedError("ImagesError")<{
  message: string;
  code?: number;
  cause: unknown;
}> {}

/**
 * A Cloudflare Images binding for image transformation inside Workers — a
 * Worker-only binding with no backing cloud resource.
 *
 * `Images` is a single value that is at once the `Binding.Service` tag, the
 * callable that produces an {@link ImagesBinding}, and the type. Declare it on a
 * Worker's `env` (it flows through `InferEnv` → `cf.ImagesBinding`) or `yield*`
 * it inside an Effect-native Worker to attach the binding and obtain the
 * {@link ImagesClient}.
 *
 * ### Effect-style Worker (recommended)
 * **Example:** Read image format and dimensions from the request body
 * ```typescript
 * import { HttpServerRequest } from "effect/http/HttpServerRequest";
 *
 * Cloudflare.Worker("ImageWorker", { main: import.meta.url },
 *   Effect.gen(function* () {
 *     const images = yield* Cloudflare.Images.Images("PIPELINE");
 *     return {
 *       fetch: Effect.gen(function* () {
 *         const request = yield* HttpServerRequest;
 *         const info = yield* images.info(request.stream);
 *         return yield* HttpServerResponse.json(info);
 *       }),
 *     };
 *   }).pipe(Effect.provide(Cloudflare.Images.ImagesBinding)),
 * );
 * ```
 *
 * ### Binding to a Worker (declarative)
 * **Example:** Example
 * ```typescript
 * export const Worker = Cloudflare.Worker("Worker", {
 *   main: "./src/worker.ts",
 *   env: { MEDIA: Cloudflare.Images.Images("PIPELINE") },
 * });
 *
 * export type WorkerEnv = Cloudflare.InferEnv<typeof Worker>;
 * //   { MEDIA: ImagesBinding }
 * ```
 *
 * ### Local development
 * **Example:** Proxy to the real Images service in dev
 * ```typescript
 * // Default: transforms run locally via Sharp under `alchemy dev` and
 * // hosted images are stored on disk. Alchemy.remote() opts the binding
 * // into the real Images service instead — in an Effect-native Worker:
 * const images = yield* Cloudflare.Images.Images("IMAGES").pipe(Alchemy.remote());
 *
 * // or declared on an async Worker's env:
 * env: { IMAGES: Cloudflare.Images.Images("IMAGES").pipe(Alchemy.remote()) }
 * ```
 *
 * @see https://developers.cloudflare.com/images/transform-images/bindings/
 *
 * @binding
 * @product Images
 * @category Media
 */
export interface Images extends Binding.Service<Images, TypeId, ImagesClient> {
  /**
   * @param name Binding name (logical id) — the `env` key it resolves to.
   * @default "IMAGES"
   */
  (name?: string): ImagesBinding;
}

export const Images = Binding.Service<Images>({
  id: TypeId,
  defaultName: "IMAGES",
  toWorkerBinding: (binding) => ({
    type: "images",
    name: binding.name,
  }),
});

export const isImages = (value: unknown): value is ImagesBinding =>
  Binding.isBinding(value) && value.kind === TypeId;

/**
 * Effect-native client for a Cloudflare Images binding. Wraps the runtime
 * {@link cf.ImagesBinding} so each method returns an Effect tagged with
 * {@link ImagesError}.
 */
export interface ImagesClient {
  /** Effect resolving to the raw Cloudflare runtime binding. */
  raw: Effect.Effect<cf.ImagesBinding, never, RuntimeContext>;
  /**
   * Read image format and dimensions from a stream of bytes. Fails with
   * {@link ImagesError} (code 9412) if the input is not a recognized image.
   */
  info<E = never, R = never>(
    stream: Stream.Stream<Uint8Array, E, R>,
    options?: cf.ImageInputOptions,
  ): Effect.Effect<cf.ImageInfoResponse, ImagesError, RuntimeContext | R>;
  /**
   * Begin a transformation pipeline. Subsequent `.transform()` / `.draw()`
   * calls are pure; `.output(opts)` runs the pipeline.
   */
  input<E = never, R = never>(
    stream: Stream.Stream<Uint8Array, E, R>,
    options?: cf.ImageInputOptions,
  ): Effect.Effect<ImageTransformer, never, RuntimeContext | R>;
}

/**
 * Effect-native handle to the result of `input(...).output(...)`. Mirrors the
 * runtime `ImageTransformationResult` but exposes side effects as sync effects.
 */
export interface ImageTransformationResult {
  raw: cf.ImageTransformationResult;
  response: Effect.Effect<cf.Response>;
  contentType: Effect.Effect<string>;
  image(
    options?: cf.ImageTransformationOutputOptions,
  ): Effect.Effect<cf.ReadableStream<Uint8Array>>;
}

/**
 * Effect-native chainable transformer. `transform`/`draw` are pure; `output` is
 * the only step that crosses into Cloudflare's runtime and returns an Effect.
 */
export interface ImageTransformer {
  raw: cf.ImageTransformer;
  transform(transform: cf.ImageTransform): ImageTransformer;
  draw<E = never, R = never>(
    image: Stream.Stream<Uint8Array, E, R> | ImageTransformer,
    options?: cf.ImageDrawOptions,
  ): Effect.Effect<ImageTransformer, never, R>;
  output(options: cf.ImageOutputOptions): Effect.Effect<ImageTransformationResult, ImagesError>;
}