effect-cf 0.33.0 → 0.35.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "effect-cf",
-  "version": "0.33.0",
+  "version": "0.35.0",
   "description": "Effect-native primitives for Cloudflare Workers and bindings.",
   "license": "MIT",
   "repository": {

package/src/AiGateway.ts

@@ -8,7 +8,6 @@ import * as ErrorMessage from "./internal/ErrorMessage";
 
 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;
@@ -19,13 +18,9 @@ export class AiGatewayOperationError extends Data.TaggedError("AiGatewayOperatio
   }
 }
 
-/** 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;
 }
 
@@ -104,7 +99,6 @@ export interface AiGatewayClient {
 
 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;

package/src/AnalyticsEngine.ts

@@ -65,7 +65,6 @@ export const AnalyticsEngineDataPointSchema = S.Struct({
 const decodeQueryResponse = S.decodeUnknownEffect(queryResponseSchema);
 const decodeDataPoint = S.decodeUnknownEffect(AnalyticsEngineDataPointSchema);
 
-/** Error raised when an Analytics Engine operation fails. */
 export class AnalyticsEngineOperationError extends Data.TaggedError(
   "AnalyticsEngineOperationError",
 )<{
@@ -85,7 +84,6 @@ export interface AnalyticsEngineWriteViolation {
   readonly actual?: number;
 }
 
-/** Error raised when an Analytics Engine write input violates Cloudflare limits. */
 export class AnalyticsEngineWriteValidationError extends Data.TaggedError(
   "AnalyticsEngineWriteValidationError",
 )<{
@@ -99,7 +97,6 @@ export class AnalyticsEngineWriteValidationError extends Data.TaggedError(
   }
 }
 
-/** Error raised when an Analytics Engine SQL API query fails. */
 export class AnalyticsEngineQueryError extends Data.TaggedError("AnalyticsEngineQueryError")<{
   readonly operation: string;
   readonly accountId: string;
@@ -109,9 +106,7 @@ export class AnalyticsEngineQueryError extends Data.TaggedError("AnalyticsEngine
   readonly cause?: unknown;
 }> {}
 
-/** Typed Analytics Engine dataset binding definition. */
 export interface AnalyticsEngineDefinition {
-  /** Binding name as configured in `wrangler.jsonc`. */
   readonly binding: string;
 }
 
@@ -142,11 +137,9 @@ export interface AnalyticsEngineQueryResult<Row = AnalyticsEngineQueryRow> {
 }
 
 export interface AnalyticsEngineQueryDefinition {
-  /** Cloudflare account id that owns the Analytics Engine datasets. */
   readonly accountId: string;
   /** API token with Account Analytics Read permission. */
   readonly apiToken: Redacted.Redacted<string>;
-  /** Base Cloudflare API URL. Defaults to `https://api.cloudflare.com/client/v4`. */
   readonly apiBaseUrl?: string | URL;
 }
 
@@ -202,14 +195,12 @@ export interface AnalyticsEngineQueryClient {
 declare const AnalyticsEngineServiceTypeId: unique symbol;
 declare const AnalyticsEngineQueryServiceTypeId: unique symbol;
 
-/** Nominal service marker for Analytics Engine services created with {@link make}. */
 export interface AnalyticsEngineService<Id extends string> {
   readonly [AnalyticsEngineServiceTypeId]: {
     readonly id: Id;
   };
 }
 
-/** Nominal service marker for Analytics Engine query services created with {@link makeQuery}. */
 export interface AnalyticsEngineQueryService<Id extends string> {
   readonly [AnalyticsEngineQueryServiceTypeId]: {
     readonly id: Id;
@@ -581,7 +572,14 @@ const executeQueryRequest = (
   options?: AnalyticsEngineQueryOptions,
 ) =>
   Effect.gen(function* () {
-    const response = yield* httpClient.execute(queryRequest(definition, sql, options)).pipe(
+    const request = yield* Effect.try({
+      try: () => queryRequest(definition, sql, options),
+      catch: (cause) =>
+        analyticsEngineQueryError(definition, "query", "Invalid Analytics Engine SQL API URL", {
+          cause,
+        }),
+    });
+    const response = yield* httpClient.execute(request).pipe(
       Effect.mapError((cause) =>
         analyticsEngineQueryError(definition, "query", "Analytics Engine SQL API request failed", {
           cause,

package/src/Artifacts.ts

@@ -18,7 +18,6 @@ const expectedArtifactsBinding =
 const expectedArtifactsRepo =
   "Artifacts repo handle with createToken(), listTokens(), revokeToken(), fork(), log(), readCommit(), and readTree()";
 
-/** Artifacts operation represented by {@link ArtifactsOperationError}. */
 export type ArtifactsOperation =
   | "createClient"
   | "create"
@@ -37,7 +36,6 @@ export type ArtifactsOperation =
   | "readTree"
   | "cli";
 
-/** Documented string error codes returned by Cloudflare Artifacts. */
 export const artifactsErrorCodes = [
   "ALREADY_EXISTS",
   "NOT_FOUND",
@@ -53,7 +51,6 @@ export const artifactsErrorCodes = [
   "INTERNAL_ERROR",
 ] as const satisfies ReadonlyArray<CloudflareArtifactsErrorCode>;
 
-/** Documented numeric error codes returned by Cloudflare Artifacts. */
 export const artifactsErrorNumericCodes = {
   ALREADY_EXISTS: 10201,
   NOT_FOUND: 10200,
@@ -69,17 +66,13 @@ export const artifactsErrorNumericCodes = {
   INTERNAL_ERROR: 10400,
 } as const satisfies Readonly<Record<CloudflareArtifactsErrorCode, number>>;
 
-/** A documented Cloudflare Artifacts string error code. */
 export type ArtifactsErrorCode = CloudflareArtifactsErrorCode;
 
-/** Error raised when a Cloudflare Artifacts operation fails. */
 export class ArtifactsOperationError extends Data.TaggedError("ArtifactsOperationError")<{
   readonly binding: string;
   readonly operation: ArtifactsOperation;
   readonly cause: unknown;
-  /** Cloudflare string error code, when retained by the runtime. */
   readonly code?: ArtifactsErrorCode | (string & {});
-  /** Cloudflare REST-compatible numeric error code, when retained by the runtime. */
   readonly numericCode?: number;
 }> {
   override get message(): string {
@@ -89,16 +82,12 @@ export class ArtifactsOperationError extends Data.TaggedError("ArtifactsOperatio
   }
 }
 
-/** Typed Cloudflare Artifacts binding definition. */
 export interface ArtifactsDefinition {
-  /** Binding name from an `artifacts` entry in `wrangler.jsonc`. */
   readonly binding: string;
 }
 
-/** Repository name containing alphanumeric characters, dots, hyphens, or underscores. */
 export type RepoName = string;
 
-/** Cursor used by repository list pagination. */
 export type Cursor = string;
 
 /** Scope granted to a repository token. */
@@ -107,21 +96,16 @@ export type ArtifactsTokenScope = "read" | "write";
 /** Lifecycle state of a repository token. */
 export type ArtifactsTokenState = "active" | "expired" | "revoked";
 
-/** Lifecycle state included with repositories returned by `list()`. */
 export type ArtifactsRepoStatus = "ready" | "importing" | "forking";
 
-/** Stable repository metadata returned by Cloudflare Artifacts. */
 export type ArtifactsRepoInfo = CloudflareArtifactsRepoInfo;
 
-/** Result of creating, importing, or forking a repository. */
 export type ArtifactsCreateRepoResult = Readonly<CloudflareArtifactsCreateRepoResult>;
 
-/** Repository metadata returned by `list()`. */
 export interface ArtifactsRepoListEntry extends ArtifactsRepoInfo {
   readonly status: ArtifactsRepoStatus;
 }
 
-/** Cursor-paginated repository list result. */
 export interface ArtifactsRepoListResult {
   readonly repos: ReadonlyArray<ArtifactsRepoListEntry>;
   readonly total: number;
@@ -151,13 +135,10 @@ export interface ArtifactsCommit {
   readonly author: ArtifactsCommitIdentity;
   readonly committer: ArtifactsCommitIdentity;
   readonly parents: ReadonlyArray<string>;
-  /** Unix timestamp in seconds. */
   readonly authoredAt: number;
-  /** Unix timestamp in seconds. */
   readonly committedAt: number;
 }
 
-/** Bare commit array returned by `log()`. */
 export type ArtifactsLogResult = ReadonlyArray<ArtifactsCommit>;
 
 /**
@@ -170,20 +151,14 @@ export interface ArtifactsTree<Field = unknown> {
   readonly [field: string]: Field;
 }
 
-/** Options for `Artifacts.create()`. */
 export interface ArtifactsCreateOptions {
-  /** Prevent pushes to the repository. */
   readonly readOnly?: boolean;
   readonly description?: string;
-  /** Initial default branch name. */
   readonly setDefaultBranch?: string;
 }
 
-/** Options for cursor-paginating `Artifacts.list()`. */
 export interface ArtifactsListOptions {
-  /** Page size from 1 through 200. Defaults to 50. */
   readonly limit?: number;
-  /** Cursor returned by a previous list result. */
   readonly cursor?: Cursor;
 }
 
@@ -191,47 +166,37 @@ export interface ArtifactsListOptions {
 export interface ArtifactsImportSource {
   /** Full HTTPS URL of the Git repository. */
   readonly url: string;
-  /** Source branch. Defaults to the remote's default branch. */
   readonly branch?: string;
-  /** Shallow clone depth. */
   readonly depth?: number;
 }
 
-/** Options for the target of `Artifacts.import()`. */
 export interface ArtifactsImportTargetOptions {
   readonly description?: string;
   readonly readOnly?: boolean;
 }
 
-/** Target repository used by `Artifacts.import()`. */
 export interface ArtifactsImportTarget {
   readonly name: RepoName;
   readonly opts?: ArtifactsImportTargetOptions;
 }
 
-/** Parameters for `Artifacts.import()`. */
 export interface ArtifactsImportParams {
   readonly source: ArtifactsImportSource;
   readonly target: ArtifactsImportTarget;
 }
 
-/** Options for `ArtifactsRepoClient.fork()`. */
 export interface ArtifactsForkOptions {
   readonly description?: string;
   readonly readOnly?: boolean;
-  /** Only copy the default branch. Defaults to `true`. */
   readonly defaultBranchOnly?: boolean;
 }
 
-/** Options for `ArtifactsRepoClient.log()`. */
 export interface ArtifactsLogOptions {
-  /** Branch, tag, or commit hash. */
   readonly ref?: string;
   readonly limit?: number;
   readonly offset?: number;
 }
 
-/** Runtime repository handle, including methods absent from current shipped Workers types. */
 export interface ArtifactsRepoBinding extends Partial<ArtifactsRepoInfo> {
   /**
    * Read repository metadata.
@@ -262,7 +227,6 @@ export interface ArtifactsRepoBinding extends Partial<ArtifactsRepoInfo> {
   readonly readTree: (hash: string) => Promise<ArtifactsTree>;
 }
 
-/** Cloudflare Artifacts namespace binding. */
 export interface ArtifactsBinding {
   readonly create: (
     name: RepoName,
@@ -274,14 +238,7 @@ export interface ArtifactsBinding {
   readonly delete: (name: RepoName) => Promise<boolean>;
 }
 
-/**
- * Effect wrapper around a repository handle returned by `Artifacts.get()`.
- *
- * The inherited metadata is the snapshot read while resolving the client.
- * Use `info()` to refresh it from the repository handle.
- */
 export interface ArtifactsRepoClient extends ArtifactsRepoInfo {
-  /** Read and validate the repository's current metadata. */
   readonly info: () => Effect.Effect<ArtifactsRepoInfo, ArtifactsOperationError>;
   /**
    * Create a Git token for the repository.
@@ -307,7 +264,6 @@ export interface ArtifactsRepoClient extends ArtifactsRepoInfo {
   readonly raw: ArtifactsRepoBinding;
 }
 
-/** Effect wrapper around a Cloudflare Artifacts namespace binding. */
 export interface ArtifactsClient {
   readonly create: (
     name: RepoName,
@@ -327,7 +283,6 @@ export interface ArtifactsClient {
 
 declare const ArtifactsServiceTypeId: unique symbol;
 
-/** Nominal service marker for Artifacts services created with {@link make}. */
 export interface ArtifactsService<Id extends string> {
   readonly [ArtifactsServiceTypeId]: {
     readonly id: Id;
@@ -440,7 +395,6 @@ const readRepoInfo = (
   );
 };
 
-/** Tests whether a value exposes the complete documented Artifacts repo handle API. */
 export const isArtifactsRepoBinding = <Candidate>(
   value: Candidate,
 ): value is Candidate & ArtifactsRepoBinding =>
@@ -452,7 +406,6 @@ export const isArtifactsRepoBinding = <Candidate>(
   hasFunction(value, "readCommit") &&
   hasFunction(value, "readTree");
 
-/** Tests whether a value exposes the complete documented Artifacts namespace API. */
 export const isArtifactsBinding = <Candidate>(
   value: Candidate,
 ): value is Candidate & ArtifactsBinding =>

package/src/Binding.ts

@@ -2,10 +2,8 @@ import { Context, Data, Effect, Layer, Predicate } from "effect";
 
 import { WorkerEnvironment, type WorkerEnv } from "./Environment";
 
-/** Internal type id marker used by binding helper services. */
 export const TypeId = "~effect-cf/Binding" as const;
 
-/** Internal type id marker used by binding helper services. */
 export type TypeId = typeof TypeId;
 
 /** Error raised when a configured binding does not exist on `env`. */
@@ -171,12 +169,6 @@ const getBinding = <Resource>(
     return resource;
   });
 
-/**
- * Creates a Context tag + layer for reading and validating a Cloudflare binding.
- *
- * The Context key is namespaced as `effect-cf/Binding/<id>`; `id` stays the
- * bare user-supplied identifier.
- */
 export interface BindingService<Self, Id extends string, Service> extends Context.ServiceClass<
   Self,
   `effect-cf/Binding/${Id}`,

package/src/BrowserRendering.ts

@@ -6,7 +6,6 @@ import * as ErrorMessage from "./internal/ErrorMessage";
 
 const expectedBrowserRenderingBinding = "Browser Rendering binding resource";
 
-/** Error raised when a Browser Rendering operation fails. */
 export class BrowserRenderingOperationError extends Data.TaggedError(
   "BrowserRenderingOperationError",
 )<{
@@ -19,9 +18,7 @@ export class BrowserRenderingOperationError extends Data.TaggedError(
   }
 }
 
-/** Typed Browser Rendering binding definition. */
 export interface BrowserRenderingDefinition {
-  /** Binding name as configured in `wrangler.jsonc`. */
   readonly binding: string;
 }
 
@@ -132,7 +129,6 @@ export interface BrowserRenderingClient<
 
 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;

package/src/Cache.ts

@@ -8,16 +8,12 @@ import { Context, Data, Effect, Layer, Option } from "effect";
 
 import * as ErrorMessage from "./internal/ErrorMessage";
 
-/** Request key accepted by Cloudflare's Cache API. */
 export type CacheRequest = CloudflareRequestInfo | URL;
 
-/** Query options supported by Cloudflare's Cache API. */
 export type CacheQueryOptions = CloudflareCacheQueryOptions;
 
-/** Cache operation represented by {@link CacheOperationError}. */
 export type CacheOperation = "open" | "match" | "put" | "delete";
 
-/** Error raised when a Cloudflare Cache API operation fails. */
 export class CacheOperationError extends Data.TaggedError("CacheOperationError")<{
   readonly cache: string;
   readonly operation: CacheOperation;
@@ -28,40 +24,29 @@ export class CacheOperationError extends Data.TaggedError("CacheOperationError")
   }
 }
 
-/** Effect wrapper around one Cloudflare `Cache` instance. */
 export interface CacheClient {
-  /** Cache name (`default` for `caches.default`). */
   readonly name: string;
-  /** Finds a cached response, mapping cache misses to `Option.none()`. */
   readonly match: (
     request: CacheRequest,
     options?: CacheQueryOptions,
   ) => Effect.Effect<Option.Option<Response>, CacheOperationError>;
-  /** Stores a response under the request key. */
   readonly put: (
     request: CacheRequest,
     response: Response,
   ) => Effect.Effect<void, CacheOperationError>;
-  /** Deletes a cached response and reports whether it existed. */
   readonly delete: (
     request: CacheRequest,
     options?: CacheQueryOptions,
   ) => Effect.Effect<boolean, CacheOperationError>;
-  /** Access to the native Cloudflare `Cache` instance. */
   readonly rawUnsafe: Effect.Effect<CloudflareCache>;
 }
 
-/** Effect wrapper around Cloudflare's global `caches` object. */
 export interface CacheStorageClient {
-  /** Cloudflare's shared default cache. */
   readonly default: CacheClient;
-  /** Opens a named cache. */
   readonly open: (name: string) => Effect.Effect<CacheClient, CacheOperationError>;
-  /** Access to the native Cloudflare `CacheStorage` instance. */
   readonly rawUnsafe: Effect.Effect<CloudflareCacheStorage>;
 }
 
-/** Service for Cloudflare's global Cache API. */
 export class CacheStorage extends Context.Service<CacheStorage, CacheStorageClient>()(
   "effect-cf/CacheStorage",
 ) {}
@@ -83,7 +68,6 @@ const spanOptions = (cache: string, operation: CacheOperation) => ({
   attributes: { cache, operation },
 });
 
-/** Wraps a native Cloudflare `Cache` instance. */
 export const makeCacheClient = (cache: CloudflareCache, name = "default"): CacheClient => ({
   name,
   match: Effect.fn(
@@ -109,7 +93,6 @@ export const makeCacheClient = (cache: CloudflareCache, name = "default"): Cache
   rawUnsafe: Effect.succeed(cache),
 });
 
-/** Wraps a native Cloudflare `CacheStorage` instance. */
 export const makeClient = (storage: CloudflareCacheStorage): CacheStorageClient => ({
   default: makeCacheClient(storage.default),
   open: (name) =>
@@ -120,9 +103,7 @@ export const makeClient = (storage: CloudflareCacheStorage): CacheStorageClient
   rawUnsafe: Effect.succeed(storage),
 });
 
-/** Provides Cache API services from an explicit native `CacheStorage` instance. */
 export const layerFrom = (storage: CloudflareCacheStorage): Layer.Layer<CacheStorage> =>
   Layer.succeed(CacheStorage, makeClient(storage));
 
-/** Provides Cache API services from Cloudflare's global `caches` object. */
 export const layer: Layer.Layer<CacheStorage> = Layer.sync(CacheStorage, () => makeClient(caches));

package/src/CloudflareOtlp.ts

@@ -1,28 +1,8 @@
 /**
- * OTLP telemetry layers for Cloudflare Workers and Durable Objects.
- *
- * Every layer exposes {@link OtlpExporter.Flusher}, which drains buffered
- * telemetry on demand. Cloudflare isolates can freeze before the periodic
- * export interval fires. Effect-backed Worker fetch handlers, Worker or
- * Durable Object native RPC handlers, and Durable Object alarm handlers
- * schedule this flusher automatically. These automatic flushes are capped at
- * two seconds and silently discard timeouts and failures so telemetry cannot
- * extend or fail the user event, or recursively log through an unhealthy
- * exporter.
- *
- * Other entrypoint lifecycles, including queue handlers, do not flush
- * automatically. Applications can flush explicitly or hand the flush to their
- * `waitUntil` mechanism, and own the timeout and failure policy at that call
- * site:
- *
- * ```ts
- * const flusher = yield* OtlpExporter.Flusher;
- *
- * yield* flusher.flush.pipe(
- *   Effect.timeoutOption("2 seconds"),
- *   Effect.ignoreCause,
- * );
- * ```
+ * Worker fetch/queue/RPC and Durable Object alarm/RPC handlers schedule a
+ * best-effort flusher. It settles within two seconds; other lifecycles must
+ * flush explicitly. Scheduled flush failures cannot fail user events. Exporter
+ * layer finalizers run separately and follow their configured shutdown timeout.
  */
 import { ConfigProvider, Effect, Layer, Option } from "effect";
 import type * as Tracer from "effect/Tracer";
@@ -76,32 +56,18 @@ export interface LayerOptions {
   readonly signals?: ReadonlyArray<Signal>;
   /** OTLP payload serialization. Defaults to protobuf. */
   readonly serialization?: Serialization;
-  /** Resource metadata forwarded to Effect's OTLP resource resolver. */
   readonly resource?: ResourceOptions;
-  /**
-   * Explicit headers for every selected signal.
-   *
-   * When omitted, Effect reads `OTEL_EXPORTER_OTLP_HEADERS` and the
-   * signal-specific `OTEL_EXPORTER_OTLP_*_HEADERS` variables.
-   */
   readonly headers?: Headers.Input;
-  /** Exclude log records emitted for spans when exporting logs. */
   readonly loggerExcludeLogSpans?: boolean;
-  /** Merge the OTLP logger with existing loggers instead of replacing them. */
   readonly loggerMergeWithExisting?: boolean;
-  /** Custom trace context lookup used by the Effect OTLP tracer. */
   readonly tracerContext?: <X>(primitive: Tracer.EffectPrimitive<X>, span: Tracer.AnySpan) => X;
 }
 
-/** Resource metadata specific to Cloudflare Workers. */
 export interface WorkerLayerOptions extends LayerOptions {
-  /** Cloudflare Worker name to attach as `cloudflare.worker.name`. */
   readonly workerName?: string;
 }
 
-/** Resource metadata specific to Cloudflare Durable Objects. */
 export interface DurableObjectLayerOptions extends LayerOptions {
-  /** Durable Object class name to attach as `cloudflare.durable_object.class`. */
   readonly className?: string;
   /**
    * Include the Durable Object id as `cloudflare.durable_object.id`.
@@ -154,7 +120,6 @@ const serializationLayer = (serialization: Serialization | undefined) =>
 
 type SignalLayer = ReturnType<typeof OtlpLogger.layerFromConfig>;
 
-/** Merges a non-empty signal layer list; callers handle the empty case. */
 const mergeSignalLayers = (layers: ReadonlyArray<SignalLayer>): SignalLayer => {
   let merged = layers[0]!;
 
@@ -243,6 +208,8 @@ export const layerProtobuf = (
  *
  * Provide this layer at runtime scope for long-lived metrics aggregation, or at
  * handler scope when traces/logs should flush as the Cloudflare event finishes.
+ * A handler-scoped exporter can delay scope closure while its own finalizer
+ * flushes; the two-second background flush limit does not bound layer shutdown.
  */
 export const layerWorker = (options: WorkerLayerOptions = {}): Layer.Layer<OtlpExporter.Flusher> =>
   makeLayer(options, {

package/src/ComputerArtifacts.ts

@@ -35,7 +35,6 @@ export type ComputerArtifactsCliResult = Readonly<CloudflareComputerArtifactsCli
 
 /** Options used when wrapping a session-scoped Artifacts client. */
 export interface ComputerArtifactsClientOptions {
-  /** Binding name attached to errors and tracing spans. Defaults to `ARTIFACTS`. */
   readonly binding?: string;
 }
 
@@ -136,7 +135,6 @@ const spanOptions = (
   operation: Artifacts.ArtifactsOperation,
 ) => ({ attributes: { binding, sessionId, operation } });
 
-/** Wraps an already-created upstream session client. */
 export const fromClient = (
   client: CloudflareComputerArtifactClient,
   options: ComputerArtifactsClientOptions = {},