effect-cf 0.13.0 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "effect-cf",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Effect-native primitives for Cloudflare Workers and bindings.",
   "license": "MIT",
   "repository": {
@@ -39,9 +39,9 @@
     "prepublishOnly": "vp run build"
   },
   "devDependencies": {
-    "@cloudflare/vitest-pool-workers": "^0.15.0",
-    "@cloudflare/workers-types": "^4.20260421.1",
-    "@effect/platform-node": "4.0.0-beta.70",
+    "@cloudflare/vitest-pool-workers": "catalog:",
+    "@cloudflare/workers-types": "catalog:",
+    "@effect/platform-node": "4.0.0-beta.77",
     "@effect/sql-d1": "catalog:",
     "@effect/sql-pg": "catalog:",
     "@effect/sql-sqlite-do": "catalog:",
@@ -52,10 +52,10 @@
     "vitest": "catalog:"
   },
   "peerDependencies": {
-    "@effect/sql-d1": "^4.0.0-beta.70",
-    "@effect/sql-pg": "^4.0.0-beta.70",
-    "@effect/sql-sqlite-do": "^4.0.0-beta.70",
-    "effect": "^4.0.0-beta.70"
+    "@effect/sql-d1": "^4.0.0-beta.77",
+    "@effect/sql-pg": "^4.0.0-beta.77",
+    "@effect/sql-sqlite-do": "^4.0.0-beta.77",
+    "effect": "^4.0.0-beta.77"
   },
   "peerDependenciesMeta": {
     "@effect/sql-pg": {

package/src/AiGateway.ts

@@ -0,0 +1,284 @@
+import { Context, Data, Effect, type Layer } from "effect";
+import type { AiGateway as CloudflareAiGateway } from "@cloudflare/workers-types";
+
+import * as Binding from "./Binding";
+import type { WorkerEnvironment } from "./Environment";
+import { isWorkersAiBinding, type WorkersAiBinding } from "./WorkersAi";
+
+const expectedAiGatewayBinding = "Workers AI binding with gateway()";
+
+/** Error raised when an AI Gateway operation fails. */
+export class AiGatewayOperationError extends Data.TaggedError("AiGatewayOperationError")<{
+  readonly binding: string;
+  readonly operation: string;
+  readonly cause: unknown;
+}> {}
+
+/** Typed AI Gateway client definition. */
+export interface AiGatewayDefinition {
+  /** Binding name as configured in `wrangler.jsonc`. */
+  readonly binding: string;
+  /** Gateway id/name passed to `env.AI.gateway(id)`. */
+  readonly gatewayId: string;
+  /** Optional account id used by the HTTP-only helper. */
+  readonly accountId?: string;
+}
+
+export type AiGatewayBinding = CloudflareAiGateway;
+type AiGatewayRunData = Parameters<AiGatewayBinding["run"]>[0];
+export type AiGatewayPatchLog = Parameters<AiGatewayBinding["patchLog"]>[1];
+export type AiGatewayLog = Awaited<ReturnType<AiGatewayBinding["getLog"]>>;
+export type AiGatewayProvider = NonNullable<Parameters<AiGatewayBinding["getUrl"]>[0]>;
+export type AiGatewayUniversalRequest = Exclude<AiGatewayRunData, ReadonlyArray<unknown>>;
+export type AiGatewayHeaders = NonNullable<AiGatewayUniversalRequest["headers"]>;
+export type AiGatewayRunOptions = Parameters<CloudflareAiGateway["run"]>[1];
+
+export interface AiGatewayFetchOptions {
+  readonly provider?: AiGatewayProvider;
+  readonly path?: string;
+  readonly init?: RequestInit;
+}
+
+export interface AiGatewayClient {
+  readonly run: (
+    data: AiGatewayUniversalRequest | ReadonlyArray<AiGatewayUniversalRequest>,
+    options?: AiGatewayRunOptions,
+  ) => Effect.Effect<Response, AiGatewayOperationError>;
+  readonly getUrl: (provider?: AiGatewayProvider) => Effect.Effect<string, AiGatewayOperationError>;
+  readonly fetch: (
+    options: AiGatewayFetchOptions,
+  ) => Effect.Effect<Response, AiGatewayOperationError>;
+  readonly patchLog: (
+    logId: string,
+    data: AiGatewayPatchLog,
+  ) => Effect.Effect<void, AiGatewayOperationError>;
+  readonly getLog: (logId: string) => Effect.Effect<AiGatewayLog, AiGatewayOperationError>;
+  readonly unsafeRaw: Effect.Effect<AiGatewayBinding, AiGatewayOperationError>;
+  readonly definition: AiGatewayDefinition;
+}
+
+declare const AiGatewayServiceTypeId: unique symbol;
+
+/** Nominal service marker for AI Gateway services created with {@link make}. */
+export interface AiGatewayService<Id extends string> {
+  readonly [AiGatewayServiceTypeId]: {
+    readonly id: Id;
+  };
+}
+
+export type LayerOptions = {
+  readonly binding: string;
+  readonly gatewayId: string;
+  readonly accountId?: string;
+};
+
+export interface TagClass<Self, Id extends string> extends Context.ServiceClass<
+  Self,
+  Id,
+  AiGatewayClient
+> {
+  readonly id: Id;
+  readonly layer: (
+    options: LayerOptions,
+  ) => Layer.Layer<
+    Self,
+    Binding.BindingNotFoundError | Binding.BindingValidationError | AiGatewayOperationError,
+    WorkerEnvironment
+  >;
+}
+
+const aiGatewayError = (binding: string, operation: string, cause: unknown) =>
+  new AiGatewayOperationError({ binding, operation, cause });
+
+const tryAiGatewayPromise = <A>(
+  binding: string,
+  operation: string,
+  evaluate: () => Promise<A>,
+): Effect.Effect<A, AiGatewayOperationError> =>
+  Effect.tryPromise({
+    try: evaluate,
+    catch: (cause) => aiGatewayError(binding, operation, cause),
+  });
+
+const tryAiGatewaySync = <A>(
+  binding: string,
+  operation: string,
+  evaluate: () => A,
+): Effect.Effect<A, AiGatewayOperationError> =>
+  Effect.try({
+    try: evaluate,
+    catch: (cause) => aiGatewayError(binding, operation, cause),
+  });
+
+const providerUrl = (baseUrl: string, path = "") => {
+  const url = new URL(baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`);
+  const normalizedPath = path.replace(/^\/+/, "");
+  return normalizedPath === "" ? url : new URL(normalizedPath, url);
+};
+
+const gatewayUrl = (definition: { readonly accountId: string; readonly gatewayId: string }) =>
+  `https://gateway.ai.cloudflare.com/v1/${definition.accountId}/${definition.gatewayId}/`;
+
+export const isAiGatewayBinding = (value: unknown): value is WorkersAiBinding =>
+  isWorkersAiBinding(value);
+
+export const makeClient = (definition: AiGatewayDefinition, gateway: AiGatewayBinding) =>
+  ({
+    definition,
+    run: (data, options) =>
+      tryAiGatewayPromise(definition.binding, "run", () =>
+        gateway.run(
+          (Array.isArray(data) ? [...data] : data) as
+            | AiGatewayUniversalRequest
+            | Array<AiGatewayUniversalRequest>,
+          options,
+        ),
+      ),
+    getUrl: (provider) =>
+      tryAiGatewayPromise(definition.binding, "getUrl", () => gateway.getUrl(provider)),
+    fetch: (options) =>
+      Effect.gen(function* () {
+        const baseUrl = yield* tryAiGatewayPromise(definition.binding, "getUrl", () =>
+          gateway.getUrl(options.provider),
+        );
+        return yield* tryAiGatewayPromise(definition.binding, "fetch", () =>
+          fetch(providerUrl(baseUrl, options.path).href, options.init),
+        );
+      }),
+    patchLog: (logId, data) =>
+      tryAiGatewayPromise(definition.binding, "patchLog", () => gateway.patchLog(logId, data)),
+    getLog: (logId) =>
+      tryAiGatewayPromise(definition.binding, "getLog", () => gateway.getLog(logId)),
+    unsafeRaw: Effect.succeed(gateway),
+  }) satisfies AiGatewayClient;
+
+export const makeClientFromAi = (
+  definition: AiGatewayDefinition,
+  ai: WorkersAiBinding,
+): AiGatewayClient => {
+  const gateway = tryAiGatewaySync(definition.binding, "gateway", () =>
+    ai.gateway(definition.gatewayId),
+  );
+
+  const withGateway = <A>(
+    operation: (gateway: AiGatewayBinding) => Effect.Effect<A, AiGatewayOperationError>,
+  ) => gateway.pipe(Effect.flatMap(operation));
+
+  return {
+    definition,
+    run: (data, options) => withGateway((raw) => makeClient(definition, raw).run(data, options)),
+    getUrl: (provider) => withGateway((raw) => makeClient(definition, raw).getUrl(provider)),
+    fetch: (options) => withGateway((raw) => makeClient(definition, raw).fetch(options)),
+    patchLog: (logId, data) =>
+      withGateway((raw) => makeClient(definition, raw).patchLog(logId, data)),
+    getLog: (logId) => withGateway((raw) => makeClient(definition, raw).getLog(logId)),
+    unsafeRaw: gateway,
+  };
+};
+
+export const makeHttpClient = (
+  definition: Omit<AiGatewayDefinition, "binding"> & {
+    readonly accountId: string;
+    readonly binding?: string;
+  },
+  request: typeof fetch = fetch,
+): AiGatewayClient => {
+  const binding = definition.binding ?? "AI_GATEWAY";
+  const clientDefinition: AiGatewayDefinition = {
+    binding,
+    gatewayId: definition.gatewayId,
+    accountId: definition.accountId,
+  };
+
+  const getUrl = (provider?: AiGatewayProvider) =>
+    Effect.succeed(
+      provider === undefined
+        ? gatewayUrl(definition)
+        : providerUrl(gatewayUrl(definition), provider).href.replace(/\/$/, ""),
+    );
+  const extraHeaders = (options?: AiGatewayRunOptions): HeadersInit | undefined => {
+    if (
+      options?.extraHeaders === undefined ||
+      Array.isArray(options.extraHeaders) ||
+      options.extraHeaders instanceof Headers
+    ) {
+      return options?.extraHeaders as HeadersInit | undefined;
+    }
+
+    return Object.fromEntries(
+      Object.entries(options.extraHeaders).map(([key, value]) => [key, String(value)]),
+    );
+  };
+
+  return {
+    definition: clientDefinition,
+    run: (data, options) =>
+      tryAiGatewayPromise(binding, "run", () =>
+        request(gatewayUrl(definition), {
+          method: "POST",
+          body: JSON.stringify(data),
+          headers: new Headers({
+            "content-type": "application/json",
+            ...Object.fromEntries(new Headers(extraHeaders(options)).entries()),
+          }),
+          signal: options?.signal,
+        }),
+      ),
+    getUrl,
+    fetch: (options) =>
+      getUrl(options.provider).pipe(
+        Effect.flatMap((baseUrl) =>
+          tryAiGatewayPromise(binding, "fetch", () =>
+            request(providerUrl(baseUrl, options.path).href, options.init),
+          ),
+        ),
+      ),
+    patchLog: (logId, data) =>
+      tryAiGatewayPromise(binding, "patchLog", () =>
+        request(providerUrl(gatewayUrl(definition), `logs/${logId}`).href, {
+          method: "PATCH",
+          body: JSON.stringify(data),
+          headers: { "content-type": "application/json" },
+        }).then(() => undefined),
+      ),
+    getLog: (logId) =>
+      tryAiGatewayPromise(binding, "getLog", async () => {
+        const response = await request(providerUrl(gatewayUrl(definition), `logs/${logId}`).href);
+        return (await response.json()) as AiGatewayLog;
+      }),
+    unsafeRaw: Effect.fail(
+      aiGatewayError(
+        binding,
+        "unsafeRaw",
+        new TypeError("HTTP AI Gateway clients have no raw binding"),
+      ),
+    ),
+  };
+};
+
+export const layer = <Self>(
+  tag: Context.Service<Self, AiGatewayClient>,
+  definition: AiGatewayDefinition,
+) =>
+  Binding.layer(
+    tag,
+    definition.binding,
+    isAiGatewayBinding,
+    (ai) => makeClientFromAi(definition, ai),
+    { expected: expectedAiGatewayBinding },
+  );
+
+export const make = <Id extends string>(id: Id) => Tag<AiGatewayService<Id>>()<Id>(id);
+
+export const Tag =
+  <Self>() =>
+  <Id extends string>(id: Id) => {
+    const tag = Context.Service<Self, AiGatewayClient>()(id);
+
+    const makeLayer = (definition: LayerOptions) => layer(tag, definition);
+
+    return Object.assign(tag, {
+      id,
+      layer: makeLayer,
+    }) as TagClass<Self, Id>;
+  };

package/src/BrowserRendering.ts

@@ -0,0 +1,286 @@
+import { Context, Data, Effect, type Layer } from "effect";
+
+import * as Binding from "./Binding";
+import type { WorkerEnvironment } from "./Environment";
+
+const expectedBrowserRenderingBinding = "Browser Rendering binding resource";
+
+/** Error raised when a Browser Rendering operation fails. */
+export class BrowserRenderingOperationError extends Data.TaggedError(
+  "BrowserRenderingOperationError",
+)<{
+  readonly binding: string;
+  readonly operation: string;
+  readonly cause: unknown;
+}> {}
+
+/** Typed Browser Rendering binding definition. */
+export interface BrowserRenderingDefinition {
+  /** Binding name as configured in `wrangler.jsonc`. */
+  readonly binding: string;
+}
+
+export type BrowserRenderingBinding = object;
+export type BrowserRenderingLaunch<RawBinding, Browser, LaunchOptions = unknown> = (
+  binding: RawBinding,
+  options?: LaunchOptions,
+) => Promise<Browser>;
+export type BrowserRenderingConnect<RawBinding, Browser, ConnectOptions = unknown> = (
+  binding: RawBinding,
+  options?: ConnectOptions,
+) => Promise<Browser>;
+
+export interface BrowserRenderingBrowserLike<Page = BrowserRenderingPageLike> {
+  readonly newPage: () => Promise<Page>;
+  readonly close?: () => Promise<void>;
+  readonly disconnect?: () => void;
+  readonly version?: () => Promise<string>;
+}
+
+export interface BrowserRenderingPageLike {
+  readonly goto?: (url: string, options?: unknown) => Promise<unknown>;
+  readonly setContent?: (html: string, options?: unknown) => Promise<void>;
+  readonly content?: () => Promise<string>;
+  readonly screenshot?: (options?: unknown) => Promise<Uint8Array | string>;
+  readonly pdf?: (options?: unknown) => Promise<Uint8Array>;
+  readonly evaluate?: (pageFunction: unknown, ...args: ReadonlyArray<unknown>) => Promise<unknown>;
+  readonly close?: (options?: unknown) => Promise<void>;
+}
+
+export interface BrowserRenderingPageClient<Page extends BrowserRenderingPageLike> {
+  readonly raw: Page;
+  readonly goto: (
+    url: string,
+    options?: Parameters<NonNullable<Page["goto"]>>[1],
+  ) => Effect.Effect<
+    Awaited<ReturnType<NonNullable<Page["goto"]>>>,
+    BrowserRenderingOperationError
+  >;
+  readonly setContent: (
+    html: string,
+    options?: Parameters<NonNullable<Page["setContent"]>>[1],
+  ) => Effect.Effect<void, BrowserRenderingOperationError>;
+  readonly content: Effect.Effect<string, BrowserRenderingOperationError>;
+  readonly screenshot: <A = Uint8Array | string>(
+    options?: Parameters<NonNullable<Page["screenshot"]>>[0],
+  ) => Effect.Effect<A, BrowserRenderingOperationError>;
+  readonly pdf: <A = Uint8Array>(
+    options?: Parameters<NonNullable<Page["pdf"]>>[0],
+  ) => Effect.Effect<A, BrowserRenderingOperationError>;
+  readonly evaluate: <A = unknown>(
+    pageFunction: Parameters<NonNullable<Page["evaluate"]>>[0],
+    ...args: ReadonlyArray<unknown>
+  ) => Effect.Effect<A, BrowserRenderingOperationError>;
+  readonly close: (
+    options?: Parameters<NonNullable<Page["close"]>>[0],
+  ) => Effect.Effect<void, BrowserRenderingOperationError>;
+}
+
+export interface BrowserRenderingBrowserClient<
+  Browser extends BrowserRenderingBrowserLike<Page>,
+  Page extends BrowserRenderingPageLike,
+> {
+  readonly raw: Browser;
+  readonly newPage: Effect.Effect<BrowserRenderingPageClient<Page>, BrowserRenderingOperationError>;
+  readonly version: Effect.Effect<string, BrowserRenderingOperationError>;
+  readonly close: Effect.Effect<void, BrowserRenderingOperationError>;
+  readonly disconnect: Effect.Effect<void, BrowserRenderingOperationError>;
+}
+
+export interface BrowserRenderingClient<
+  RawBinding extends BrowserRenderingBinding = BrowserRenderingBinding,
+> {
+  readonly launchWith: <
+    Browser extends BrowserRenderingBrowserLike<Page>,
+    Page extends BrowserRenderingPageLike = BrowserRenderingPageLike,
+    LaunchOptions = unknown,
+  >(
+    launch: BrowserRenderingLaunch<RawBinding, Browser, LaunchOptions>,
+    options?: LaunchOptions,
+  ) => Effect.Effect<BrowserRenderingBrowserClient<Browser, Page>, BrowserRenderingOperationError>;
+  readonly connectWith: <
+    Browser extends BrowserRenderingBrowserLike<Page>,
+    Page extends BrowserRenderingPageLike = BrowserRenderingPageLike,
+    ConnectOptions = unknown,
+  >(
+    connect: BrowserRenderingConnect<RawBinding, Browser, ConnectOptions>,
+    options?: ConnectOptions,
+  ) => Effect.Effect<BrowserRenderingBrowserClient<Browser, Page>, BrowserRenderingOperationError>;
+  readonly unsafeRaw: Effect.Effect<RawBinding>;
+  readonly definition: BrowserRenderingDefinition;
+}
+
+declare const BrowserRenderingServiceTypeId: unique symbol;
+
+/** Nominal service marker for Browser Rendering services created with {@link make}. */
+export interface BrowserRenderingService<Id extends string> {
+  readonly [BrowserRenderingServiceTypeId]: {
+    readonly id: Id;
+  };
+}
+
+export type LayerOptions = {
+  readonly binding: string;
+};
+
+export interface TagClass<Self, Id extends string> extends Context.ServiceClass<
+  Self,
+  Id,
+  BrowserRenderingClient
+> {
+  readonly id: Id;
+  readonly layer: (
+    options: LayerOptions,
+  ) => Layer.Layer<
+    Self,
+    Binding.BindingNotFoundError | Binding.BindingValidationError,
+    WorkerEnvironment
+  >;
+}
+
+const browserRenderingError = (binding: string, operation: string, cause: unknown) =>
+  new BrowserRenderingOperationError({ binding, operation, cause });
+
+const tryBrowserRenderingPromise = <A>(
+  binding: string,
+  operation: string,
+  evaluate: () => Promise<A>,
+): Effect.Effect<A, BrowserRenderingOperationError> =>
+  Effect.tryPromise({
+    try: evaluate,
+    catch: (cause) => browserRenderingError(binding, operation, cause),
+  });
+
+const tryBrowserRenderingSync = <A>(
+  binding: string,
+  operation: string,
+  evaluate: () => A,
+): Effect.Effect<A, BrowserRenderingOperationError> =>
+  Effect.try({
+    try: evaluate,
+    catch: (cause) => browserRenderingError(binding, operation, cause),
+  });
+
+const missingMethod = (binding: string, operation: string) =>
+  Effect.fail(
+    browserRenderingError(
+      binding,
+      operation,
+      new TypeError(`Browser Rendering object does not expose ${operation}()`),
+    ),
+  );
+
+const wrapPage = <Page extends BrowserRenderingPageLike>(
+  binding: string,
+  page: Page,
+): BrowserRenderingPageClient<Page> => ({
+  raw: page,
+  goto: (url, options) =>
+    (page.goto === undefined
+      ? missingMethod(binding, "goto")
+      : tryBrowserRenderingPromise(binding, "goto", () =>
+          page.goto!(url, options),
+        )) as Effect.Effect<
+      Awaited<ReturnType<NonNullable<Page["goto"]>>>,
+      BrowserRenderingOperationError
+    >,
+  setContent: (html, options) =>
+    page.setContent === undefined
+      ? missingMethod(binding, "setContent")
+      : tryBrowserRenderingPromise(binding, "setContent", () => page.setContent!(html, options)),
+  content:
+    page.content === undefined
+      ? missingMethod(binding, "content")
+      : tryBrowserRenderingPromise(binding, "content", () => page.content!()),
+  screenshot: (options) =>
+    (page.screenshot === undefined
+      ? missingMethod(binding, "screenshot")
+      : tryBrowserRenderingPromise(binding, "screenshot", () =>
+          page.screenshot!(options),
+        )) as Effect.Effect<never, BrowserRenderingOperationError>,
+  pdf: (options) =>
+    (page.pdf === undefined
+      ? missingMethod(binding, "pdf")
+      : tryBrowserRenderingPromise(binding, "pdf", () => page.pdf!(options))) as Effect.Effect<
+      never,
+      BrowserRenderingOperationError
+    >,
+  evaluate: (pageFunction, ...args) =>
+    (page.evaluate === undefined
+      ? missingMethod(binding, "evaluate")
+      : tryBrowserRenderingPromise(binding, "evaluate", () =>
+          page.evaluate!(pageFunction, ...args),
+        )) as Effect.Effect<never, BrowserRenderingOperationError>,
+  close: (options) =>
+    page.close === undefined
+      ? Effect.void
+      : tryBrowserRenderingPromise(binding, "closePage", () => page.close!(options)),
+});
+
+const wrapBrowser = <
+  Browser extends BrowserRenderingBrowserLike<Page>,
+  Page extends BrowserRenderingPageLike,
+>(
+  binding: string,
+  browser: Browser,
+): BrowserRenderingBrowserClient<Browser, Page> => ({
+  raw: browser,
+  newPage: tryBrowserRenderingPromise(binding, "newPage", () => browser.newPage()).pipe(
+    Effect.map((page) => wrapPage(binding, page)),
+  ),
+  version:
+    browser.version === undefined
+      ? missingMethod(binding, "version")
+      : tryBrowserRenderingPromise(binding, "version", () => browser.version!()),
+  close:
+    browser.close === undefined
+      ? Effect.void
+      : tryBrowserRenderingPromise(binding, "closeBrowser", () => browser.close!()),
+  disconnect:
+    browser.disconnect === undefined
+      ? Effect.void
+      : tryBrowserRenderingSync(binding, "disconnect", () => browser.disconnect!()),
+});
+
+export const isBrowserRenderingBinding = (value: unknown): value is BrowserRenderingBinding =>
+  (typeof value === "object" || typeof value === "function") && value !== null;
+
+export const makeClient =
+  <RawBinding extends BrowserRenderingBinding = BrowserRenderingBinding>(
+    definition: BrowserRenderingDefinition,
+  ) =>
+  (binding: RawBinding): BrowserRenderingClient<RawBinding> => ({
+    definition,
+    launchWith: (launch, options) =>
+      tryBrowserRenderingPromise(definition.binding, "launch", () => launch(binding, options)).pipe(
+        Effect.map((browser) => wrapBrowser(definition.binding, browser)),
+      ),
+    connectWith: (connect, options) =>
+      tryBrowserRenderingPromise(definition.binding, "connect", () =>
+        connect(binding, options),
+      ).pipe(Effect.map((browser) => wrapBrowser(definition.binding, browser))),
+    unsafeRaw: Effect.succeed(binding),
+  });
+
+export const layer = <Self>(
+  tag: Context.Service<Self, BrowserRenderingClient>,
+  definition: BrowserRenderingDefinition,
+) =>
+  Binding.layer(tag, definition.binding, isBrowserRenderingBinding, makeClient(definition), {
+    expected: expectedBrowserRenderingBinding,
+  });
+
+export const make = <Id extends string>(id: Id) => Tag<BrowserRenderingService<Id>>()<Id>(id);
+
+export const Tag =
+  <Self>() =>
+  <Id extends string>(id: Id) => {
+    const tag = Context.Service<Self, BrowserRenderingClient>()(id);
+
+    const makeLayer = (definition: LayerOptions) => layer(tag, definition);
+
+    return Object.assign(tag, {
+      id,
+      layer: makeLayer,
+    }) as TagClass<Self, Id>;
+  };