@cloudflare/workers-utils 0.12.0 → 0.19.0

package/dist/index.d.mts

@@ -1,7 +1,9 @@
-import { B as Binding, R as RawConfig, C as Config, W as WorkerMetadataBinding } from './config-BQZJPwXe.mjs';
-export { am as AssetConfigMetadata, A as Assets, ar as BinaryFile, q as CacheOptions, H as CfAIBinding, a4 as CfAnalyticsEngineDataset, a9 as CfAssetsBinding, G as CfBrowserBinding, ac as CfCapnp, V as CfD1Database, L as CfDataBlobBindings, a5 as CfDispatchNamespace, M as CfDurableObject, ae as CfDurableObjectMigrations, _ as CfHelloWorld, a1 as CfHyperdrive, I as CfImagesBinding, x as CfKvNamespace, a7 as CfLogfwdr, a8 as CfLogfwdrBinding, a6 as CfMTlsCertificate, J as CfMediaBinding, v as CfModule, u as CfModuleType, aa as CfPipeline, af as CfPlacement, P as CfQueue, Q as CfR2Bucket, a0 as CfRateLimit, t as CfScriptFormat, Y as CfSecretsStoreSecrets, y as CfSendEmailBindings, a2 as CfService, ag as CfTailConsumer, F as CfTextBlobBindings, ad as CfUnsafe, ab as CfUnsafeBinding, ah as CfUserLimits, w as CfVars, X as CfVectorize, K as CfVersionMetadataBinding, a3 as CfVpcService, z as CfWasmModuleBindings, aj as CfWorkerContext, ai as CfWorkerInit, $ as CfWorkerLoader, ak as CfWorkerSourceMap, N as CfWorkflow, i as CloudchamberConfig, c as ConfigFields, o as ConfigModuleRuleType, j as ContainerApp, s as ContainerEngine, g as CustomDomainRoute, p as DispatchNamespaceOutbound, r as DockerConfiguration, k as DurableObjectBindings, D as DurableObjectMigration, av as ENVIRONMENT_TAG_PREFIX, E as Environment, m as EnvironmentNonInheritable, aq as File, at as INHERIT_SYMBOL, ax as JSON_CONFIG_FORMATS, al as Json, O as Observability, aw as PATH_TO_DEPLOY_CONFIG, b as RawDevConfig, d as RawEnvironment, a as RedirectedRawConfig, h as Route, n as Rule, au as SERVICE_TAG_PREFIX, ap as ServiceFetch, ao as ServiceMetadataRes, S as StreamingTailConsumer, T as TailConsumer, as as Trigger, U as UserLimits, an as WorkerMetadata, l as WorkflowBinding, Z as ZoneIdRoute, f as ZoneNameRoute, e as defaultWranglerConfig } from './config-BQZJPwXe.mjs';
+import { B as Binding, R as RawConfig, C as Config, W as WorkerMetadataBinding } from './config-CnJQHRQs.mjs';
+export { at as AssetConfigMetadata, A as Assets, ay as BinaryFile, q as CacheOptions, H as CfAIBinding, a0 as CfAISearch, $ as CfAISearchNamespace, ab as CfAnalyticsEngineDataset, a2 as CfArtifacts, ag as CfAssetsBinding, G as CfBrowserBinding, aj as CfCapnp, Y as CfD1Database, M as CfDataBlobBindings, ac as CfDispatchNamespace, N as CfDurableObject, al as CfDurableObjectMigrations, a4 as CfFlagship, a3 as CfHelloWorld, a7 as CfHyperdrive, I as CfImagesBinding, x as CfKvNamespace, ae as CfLogfwdr, af as CfLogfwdrBinding, ad as CfMTlsCertificate, J as CfMediaBinding, v as CfModule, u as CfModuleType, ah as CfPipeline, am as CfPlacement, V as CfQueue, X as CfR2Bucket, a6 as CfRateLimit, t as CfScriptFormat, a1 as CfSecretsStoreSecrets, y as CfSendEmailBindings, a8 as CfService, K as CfStreamBinding, an as CfTailConsumer, F as CfTextBlobBindings, ak as CfUnsafe, ai as CfUnsafeBinding, ao as CfUserLimits, w as CfVars, _ as CfVectorize, L as CfVersionMetadataBinding, aa as CfVpcNetwork, a9 as CfVpcService, z as CfWasmModuleBindings, aq as CfWorkerContext, ap as CfWorkerInit, a5 as CfWorkerLoader, ar as CfWorkerSourceMap, Q as CfWorkflow, i as CloudchamberConfig, c as ConfigFields, o as ConfigModuleRuleType, j as ContainerApp, s as ContainerEngine, g as CustomDomainRoute, p as DispatchNamespaceOutbound, r as DockerConfiguration, k as DurableObjectBindings, D as DurableObjectMigration, aC as ENVIRONMENT_TAG_PREFIX, E as Environment, m as EnvironmentNonInheritable, ax as File, aA as INHERIT_SYMBOL, aE as JSON_CONFIG_FORMATS, as as Json, O as Observability, aD as PATH_TO_DEPLOY_CONFIG, P as PreviewsConfig, b as RawDevConfig, d as RawEnvironment, a as RedirectedRawConfig, h as Route, n as Rule, aB as SERVICE_TAG_PREFIX, aw as ServiceFetch, av as ServiceMetadataRes, S as StreamingTailConsumer, T as TailConsumer, az as Trigger, U as UserLimits, au as WorkerMetadata, l as WorkflowBinding, Z as ZoneIdRoute, f as ZoneNameRoute, e as defaultWranglerConfig } from './config-CnJQHRQs.mjs';
 import * as jsoncParser from 'jsonc-parser';
 export { constructWranglerConfig } from './browser.mjs';
+export { Counter, MetricsRegistry } from './prometheus-metrics.mjs';
+import { ChildProcess } from 'node:child_process';
 import '@cloudflare/workers-shared';
 import 'cloudflare';
 
@@ -49,6 +51,8 @@ declare class Diagnostics {
     errors: string[];
     warnings: string[];
     children: Diagnostics[];
+    /** Set to true when an unexpected/unknown field is encountered during validation. */
+    hasUnexpectedFields: boolean;
     /**
      * Create a new Diagnostics object.
      * @param description A general description of this collection of messages.
@@ -60,6 +64,8 @@ declare class Diagnostics {
     addChild(diagnostics: Diagnostics): void;
     /** Does this or any of its children have errors. */
     hasErrors(): boolean;
+    /** Does this or any of its children have unexpected fields. */
+    hasUnexpectedFieldsInTree(): boolean;
     /** Render the errors of this and all its children. */
     renderErrors(): string;
     /** Does this or any of its children have warnings. */
@@ -83,7 +89,7 @@ declare const bucketFormatMessage = "Bucket names must begin and end with an alp
  * Config field names for bindings (e.g., "kv_namespaces", "d1_databases").
  * These are the keys used in Wrangler's config file
  */
-type ConfigBindingFieldName = "data_blobs" | "durable_objects" | "kv_namespaces" | "send_email" | "queues" | "d1_databases" | "vectorize" | "hyperdrive" | "r2_buckets" | "logfwdr" | "services" | "analytics_engine_datasets" | "text_blobs" | "browser" | "ai" | "images" | "media" | "version_metadata" | "unsafe" | "vars" | "wasm_modules" | "dispatch_namespaces" | "mtls_certificates" | "workflows" | "pipelines" | "secrets_store_secrets" | "ratelimits" | "assets" | "unsafe_hello_world" | "worker_loaders" | "vpc_services";
+type ConfigBindingFieldName = "data_blobs" | "durable_objects" | "kv_namespaces" | "send_email" | "queues" | "d1_databases" | "vectorize" | "ai_search_namespaces" | "ai_search" | "hyperdrive" | "r2_buckets" | "logfwdr" | "services" | "analytics_engine_datasets" | "text_blobs" | "browser" | "ai" | "images" | "stream" | "media" | "version_metadata" | "unsafe" | "vars" | "wasm_modules" | "dispatch_namespaces" | "mtls_certificates" | "workflows" | "pipelines" | "secrets_store_secrets" | "artifacts" | "ratelimits" | "assets" | "unsafe_hello_world" | "flagship" | "worker_loaders" | "vpc_services" | "vpc_networks";
 /**
  * @deprecated new code should use getBindingTypeFriendlyName() instead
  */
@@ -133,6 +139,8 @@ declare function normalizeAndValidateConfig(rawConfig: RawConfig, configPath: st
  */
 declare function isDockerfile(imagePath: string, configPath: string | undefined): boolean;
 
+type ConfigBindingOptions = Pick<Config, "ai" | "browser" | "d1_databases" | "dispatch_namespaces" | "durable_objects" | "queues" | "r2_buckets" | "services" | "kv_namespaces" | "mtls_certificates" | "vectorize" | "workflows" | "vpc_services">;
+
 declare function configFormat(configPath: string | undefined): "json" | "jsonc" | "toml" | "none";
 declare function configFileName(configPath: string | undefined): "wrangler.json" | "wrangler.jsonc" | "wrangler.toml" | "Wrangler configuration";
 declare function formatConfigSnippet(snippet: RawConfig, configPath: Config["configPath"], formatted?: boolean): string;
@@ -174,7 +182,11 @@ declare class PatchConfigError extends Error {
  * Set to `true` to duplicate `message`.
  *  */
 type TelemetryMessage = {
-    telemetryMessage?: string | true;
+    telemetryMessage: string | boolean;
+};
+type UserErrorOptions = ErrorOptions & TelemetryMessage;
+type FatalErrorOptions = UserErrorOptions & {
+    code?: number;
 };
 /**
  * Base class for errors where the user has done something wrong. These are not
@@ -184,14 +196,14 @@ type TelemetryMessage = {
  */
 declare class UserError extends Error {
     telemetryMessage: string | undefined;
-    constructor(message?: string | undefined, options?: (ErrorOptions & TelemetryMessage) | undefined);
+    constructor(message: string, options: UserErrorOptions);
 }
 declare class DeprecationError extends UserError {
-    constructor(message: string, options?: TelemetryMessage);
+    constructor(message: string, options: TelemetryMessage);
 }
 declare class FatalError extends UserError {
-    readonly code?: number | undefined;
-    constructor(message?: string, code?: number | undefined, options?: TelemetryMessage);
+    readonly code: number | undefined;
+    constructor(message: string, options: FatalErrorOptions);
 }
 declare class CommandLineArgsError extends UserError {
 }
@@ -200,12 +212,12 @@ declare class CommandLineArgsError extends UserError {
  *
  * To use, pass stringify'd json into the constructor like so:
  * ```js
- * throw new JsonFriendlyFatalError(JSON.stringify({ error: messageToDisplay });
+ * throw new JsonFriendlyFatalError(JSON.stringify({ error: messageToDisplay }), {
+ *   telemetryMessage: false,
+ * });
  * ```
  */
 declare class JsonFriendlyFatalError extends FatalError {
-    readonly code?: number | undefined;
-    constructor(message?: string, code?: number | undefined, options?: TelemetryMessage);
 }
 declare class MissingConfigError extends Error {
     telemetryMessage: string | undefined;
@@ -216,14 +228,15 @@ declare class MissingConfigError extends Error {
  *
  * If `isJson` is true, then the `message` is JSON stringified.
  */
-declare function createFatalError(message: unknown, isJson: boolean, code?: number, telemetryMessage?: TelemetryMessage): Error;
+declare function createFatalError(message: unknown, isJson: boolean, options: FatalErrorOptions): Error;
 
 type Message = {
     text: string;
     location?: Location;
     notes?: Message[];
     kind?: "warning" | "error";
-} & TelemetryMessage;
+};
+type MessageInit = Message & TelemetryMessage;
 type Location = ParseFile & {
     line: number;
     column: number;
@@ -243,15 +256,16 @@ declare class ParseError extends UserError implements Message {
     readonly notes: Message[];
     readonly location?: Location;
     readonly kind: "warning" | "error";
-    constructor({ text, notes, location, kind, telemetryMessage }: Message);
+    constructor({ text, notes, location, kind, telemetryMessage }: MessageInit);
 }
 declare class APIError extends ParseError {
     #private;
     code?: number;
     accountTag?: string;
-    constructor({ status, ...rest }: Message & {
+    constructor({ status, ...rest }: MessageInit & {
         status?: number;
     });
+    get status(): number | undefined;
     isGatewayError(): boolean;
     isRetryable(): boolean;
     get reportable(): boolean;
@@ -432,6 +446,8 @@ type VariableNames =
  | "CLOUDFLARE_ENV"
 /** Custom directory for Wrangler's cache files (overrides `node_modules/.cache/wrangler`). */
  | "WRANGLER_CACHE_DIR"
+/** Custom path to cloudflared binary (overrides automatic binary management). */
+ | "CLOUDFLARED_PATH"
 /** Set to "staging" to use staging APIs instead of production. */
  | "WRANGLER_API_ENVIRONMENT"
 /** Custom auth domain (usually auto-configured). */
@@ -446,8 +462,14 @@ type VariableNames =
  | "WRANGLER_REVOKE_URL"
 /** Direct authorization token for API requests. */
  | "WRANGLER_CF_AUTHORIZATION_TOKEN"
+/** Cloudflare Access Service Token Client ID. Used to authenticate with Access-protected domains in non-interactive environments (e.g. CI). */
+ | "CLOUDFLARE_ACCESS_CLIENT_ID"
+/** Cloudflare Access Service Token Client Secret. Used with CLOUDFLARE_ACCESS_CLIENT_ID. */
+ | "CLOUDFLARE_ACCESS_CLIENT_SECRET"
 /** Enable the local explorer UI at /cdn-cgi/explorer (experimental, default: false). */
  | "X_LOCAL_EXPLORER"
+/** Open the browser in headful (visible) mode when using the Browser Run API in local dev (default: false). */
+ | "X_BROWSER_HEADFUL"
 /** Override command used by `wrangler init` (default: "create cloudflare"). */
  | "WRANGLER_C3_COMMAND"
 /** Enable/disable telemetry data collection. */
@@ -694,9 +716,23 @@ declare const getCloudflareEnv: () => string | undefined;
 declare const getOpenNextDeployFromEnv: () => string | undefined;
 /**
  * `X_LOCAL_EXPLORER` enables the local explorer UI at /cdn-cgi/explorer.
- * This is an experimental feature flag. Defaults to false when not set.
  */
 declare const getLocalExplorerEnabledFromEnv: () => boolean;
+/**
+ * `X_BROWSER_HEADFUL` opens the browser in headful (visible) mode when using the
+ * Browser Run API in local development.
+ *
+ * Set to "true" to enable:
+ *
+ * ```sh
+ * X_BROWSER_HEADFUL=true vite dev
+ * ```
+ *
+ * Note: when using `@cloudflare/playwright`, two Chrome windows may appear — the initial blank
+ * page and the one created by `browser.newPage()`. This is expected due to how Playwright handles
+ * browser contexts via CDP.
+ */
+declare const getBrowserRenderingHeadfulFromEnv: () => boolean;
 /**
  * `CLOUDFLARE_CF_FETCH_ENABLED` controls whether Miniflare fetches the `cf.json` file
  * containing request.cf properties from workers.cloudflare.com.
@@ -733,6 +769,13 @@ declare const getCfFetchPathFromEnv: () => string | undefined;
  * Useful for Yarn PnP or projects without node_modules.
  */
 declare const getWranglerCacheDirFromEnv: () => string | undefined;
+/**
+ * `CLOUDFLARED_PATH` specifies a custom path to a cloudflared binary.
+ *
+ * If set, Wrangler will use this cloudflared binary instead of downloading one.
+ * The path must point to an existing executable file.
+ */
+declare const getCloudflaredPathFromEnv: () => string | undefined;
 
 declare function getGlobalWranglerConfigPath(): string;
 
@@ -743,24 +786,6 @@ type DD = `${number}${number}`;
  * Represents a valid compatibility date, a string such as `2025-09-27`
  */
 type CompatDate = `${YYYY}-${MM}-${DD}`;
-type GetCompatDateOptions = {
-    projectPath?: string;
-};
-type GetCompatDateResult = {
-    date: CompatDate;
-    source: "workerd" | "fallback";
-};
-/**
- * Gets the compatibility date of the locally installed workerd package.
- *
- * If the package is not found the fallback date of 2025-09-27 is returned instead.
- *
- * Additionally, if the workerd date is set to the future then the current date is returned instead.
- *
- * @param options.projectPath the path to the project
- * @returns an object including the compatibility date and its source
- */
-declare function getLocalWorkerdCompatibilityDate({ projectPath, }?: GetCompatDateOptions): GetCompatDateResult;
 /**
  * Discern whether a string represents a compatibility date (`YYYY-MM-DD`)
  *
@@ -769,12 +794,9 @@ declare function getLocalWorkerdCompatibilityDate({ projectPath, }?: GetCompatDa
  */
 declare function isCompatDate(str: string): str is CompatDate;
 /**
- * Returns the date formatted as a compatibility date
- *
- * @param date The target date to convert
- * @returns The date as a CompatDate string (a string following the format `YYYY-MM-DD`)
+ * Returns today's date as a compatibility date string (`YYYY-MM-DD`).
  */
-declare function formatCompatibilityDate(date: Date): CompatDate;
+declare function getTodaysCompatDate(): CompatDate;
 
 /**
  * Returns whether the given path is a directory
@@ -815,4 +837,54 @@ declare function removeDir(dirPath: string, options?: {
  */
 declare function removeDirSync(dirPath: string): void;
 
-export { APIError, Binding, COMPLIANCE_REGION_CONFIG_PUBLIC, COMPLIANCE_REGION_CONFIG_UNKNOWN, CommandLineArgsError, type CompatDate, type ComplianceConfig, Config, type ConfigBindingFieldName, DeprecationError, FatalError, JsonFriendlyFatalError, type Location, type Message, MissingConfigError, type NormalizeAndValidateConfigArgs, type PackageJSON, ParseError, type ParseFile, PatchConfigError, RawConfig, type ResolveConfigPathOptions, type TelemetryMessage, UserError, WorkerMetadataBinding, assertNever, bucketFormatMessage, configFileName, configFormat, createFatalError, experimental_patchConfig, experimental_readRawConfig, findWranglerConfig, formatCompatibilityDate, formatConfigSnippet, friendlyBindingNames, getBindingTypeFriendlyName, getBooleanEnvironmentVariableFactory, getBuildConditionsFromEnv, getBuildPlatformFromEnv, getC3CommandFromEnv, getCIGeneratePreviewAlias, getCIMatchTag, getCIOverrideName, getCIOverrideNetworkModeHost, getCfFetchEnabledFromEnv, getCfFetchPathFromEnv, getCloudflareApiBaseUrl, getCloudflareApiEnvironmentFromEnv, getCloudflareComplianceRegion, getCloudflareEnv, getCloudflareIncludeProcessEnvFromEnv, getCloudflareLoadDevVarsFromDotEnv, getComplianceRegionSubdomain, getD1ExtraLocationChoices, getDisableConfigWatching, getDockerPath, getEnvironmentVariableFactory, getGlobalWranglerConfigPath, getLocalExplorerEnabledFromEnv, getLocalWorkerdCompatibilityDate, getOpenNextDeployFromEnv, getOutputFileDirectoryFromEnv, getOutputFilePathFromEnv, getRegistryPath, getSanitizeLogs, getSubdomainMixedStateCheckDisabled, getTraceHeader, getWorkersCIBranchName, getWranglerCacheDirFromEnv, getWranglerHideBanner, getWranglerSendErrorReportsFromEnv, getWranglerSendMetricsFromEnv, hasProperty, indexLocation, isCompatDate, isDirectory, isDockerfile, isOptionalProperty, isPagesConfig, isRequiredProperty, isValidR2BucketName, mapWorkerMetadataBindings, normalizeAndValidateConfig, parseByteSize, parseHumanDuration, parseJSON, parseJSONC, parseNonHyphenedUuid, parsePackageJSON, parseTOML, readFileSync, readFileSyncToBuffer, removeDir, removeDirSync, resolveWranglerConfigPath, searchLocation, validatePagesConfig };
+/**
+ * cloudflared binary management for Wrangler tunnel commands.
+ *
+ * This module handles downloading, caching, and running the cloudflared binary.
+ * It uses the Cloudflare update worker (update.argotunnel.com) to resolve
+ * the latest version and download URL, matching cloudflared's own update mechanism.
+ */
+
+interface Logger {
+    log: typeof console.log;
+    warn: typeof console.warn;
+    debug: typeof console.debug;
+}
+/**
+ * Spawn cloudflared process with automatic binary management
+ */
+declare function spawnCloudflared(args: string[], options?: {
+    stdio?: "inherit" | "pipe";
+    env?: Record<string, string>;
+    skipVersionCheck?: boolean;
+    confirmDownload?: (message: string) => Promise<boolean>;
+    logger?: Logger;
+}): Promise<ChildProcess>;
+
+interface TunnelResult {
+    publicUrl: URL;
+}
+interface Tunnel {
+    ready: () => Promise<TunnelResult>;
+    dispose: () => void;
+    extendExpiry: (ms?: number) => void;
+}
+interface TunnelOptions {
+    origin: URL;
+    timeoutMs?: number;
+    expiryMs?: number;
+    reminderIntervalMs?: number;
+    extendHint?: string;
+    logger?: Logger;
+}
+/**
+ * Start a Cloudflare Quick Tunnel for a local dev origin.
+ *
+ * Spawns `cloudflared tunnel --url <origin>` and waits for the public URL
+ * to appear in its stderr output. Returns a controller with a `ready()`
+ * promise that resolves once the tunnel URL is available, and a `dispose()`
+ * function to stop the tunnel.
+ */
+declare function startTunnel(options: TunnelOptions): Tunnel;
+
+export { APIError, Binding, COMPLIANCE_REGION_CONFIG_PUBLIC, COMPLIANCE_REGION_CONFIG_UNKNOWN, CommandLineArgsError, type CompatDate, type ComplianceConfig, Config, type ConfigBindingFieldName, type ConfigBindingOptions, DeprecationError, Diagnostics, FatalError, JsonFriendlyFatalError, type Location, type Message, MissingConfigError, type NormalizeAndValidateConfigArgs, type PackageJSON, ParseError, type ParseFile, PatchConfigError, RawConfig, type ResolveConfigPathOptions, type TelemetryMessage, type Tunnel, type TunnelOptions, UserError, WorkerMetadataBinding, assertNever, bucketFormatMessage, configFileName, configFormat, createFatalError, experimental_patchConfig, experimental_readRawConfig, findWranglerConfig, formatConfigSnippet, friendlyBindingNames, getBindingTypeFriendlyName, getBooleanEnvironmentVariableFactory, getBrowserRenderingHeadfulFromEnv, getBuildConditionsFromEnv, getBuildPlatformFromEnv, getC3CommandFromEnv, getCIGeneratePreviewAlias, getCIMatchTag, getCIOverrideName, getCIOverrideNetworkModeHost, getCfFetchEnabledFromEnv, getCfFetchPathFromEnv, getCloudflareApiBaseUrl, getCloudflareApiEnvironmentFromEnv, getCloudflareComplianceRegion, getCloudflareEnv, getCloudflareIncludeProcessEnvFromEnv, getCloudflareLoadDevVarsFromDotEnv, getCloudflaredPathFromEnv, getComplianceRegionSubdomain, getD1ExtraLocationChoices, getDisableConfigWatching, getDockerPath, getEnvironmentVariableFactory, getGlobalWranglerConfigPath, getLocalExplorerEnabledFromEnv, getOpenNextDeployFromEnv, getOutputFileDirectoryFromEnv, getOutputFilePathFromEnv, getRegistryPath, getSanitizeLogs, getSubdomainMixedStateCheckDisabled, getTodaysCompatDate, getTraceHeader, getWorkersCIBranchName, getWranglerCacheDirFromEnv, getWranglerHideBanner, getWranglerSendErrorReportsFromEnv, getWranglerSendMetricsFromEnv, hasProperty, indexLocation, isCompatDate, isDirectory, isDockerfile, isOptionalProperty, isPagesConfig, isRequiredProperty, isValidR2BucketName, mapWorkerMetadataBindings, normalizeAndValidateConfig, parseByteSize, parseHumanDuration, parseJSON, parseJSONC, parseNonHyphenedUuid, parsePackageJSON, parseTOML, readFileSync, readFileSyncToBuffer, removeDir, removeDirSync, resolveWranglerConfigPath, searchLocation, spawnCloudflared, startTunnel, validatePagesConfig };