alchemy 2.0.0-beta.65 → 2.0.0-beta.66

package/lib/Cloudflare/Workers/Worker.d.ts

@@ -10,6 +10,7 @@ import { type MemoOptions } from "../../Command/Memo.ts";
 import type { Dependencies } from "../../Dependencies.ts";
 import type { InputProps } from "../../Input.ts";
 import type { Named, Tag } from "../../Named.ts";
+import type * as Output from "../../Output.ts";
 import { type Main, type MainRpc, type MakeShape, type PlatformProps, type PlatformServices } from "../../Platform.ts";
 import { Resource, type ResourceClassLike } from "../../Resource.ts";
 import type { Rpc } from "../../Rpc.ts";
@@ -126,12 +127,68 @@ export type WorkerEnv = Record<string, string | number | boolean | null | readon
 export type WorkerBindingProps = {
     [bindingName in string]: WorkerBindingResource | Effect.Effect<WorkerBindingResource, any, any>;
 };
+type Unwrap<T> = T extends Output.Output<infer A, infer _Req> ? A : T;
 export type NormalizedBindings<Bindings extends WorkerBindingProps = {}, AssetsConfig extends WorkerAssetsConfig | undefined = undefined> = {
-    [B in keyof Bindings]: Bindings[B] extends Effect.Effect<infer T extends WorkerBindingResource, any, any> ? T extends Redacted.Redacted<infer T> | Config.Config<infer T> ? T : T : Extract<Bindings[B], WorkerBindingResource>;
+    [B in keyof Bindings]: Bindings[B] extends Effect.Effect<infer T extends WorkerBindingResource, any, any> ? T extends Redacted.Redacted<infer V> | Config.Config<infer V> ? V : Unwrap<T> : Extract<Unwrap<Bindings[B]>, WorkerBindingResource>;
 } & (undefined extends AssetsConfig ? {} : {
     ASSETS: Assets;
 });
 export type WorkerAssetsConfig = string | AssetsProps | AssetsWithHash;
+/**
+ * Fine-grained control over the Worker's `workers.dev` surface. The two
+ * toggles are independent on the Cloudflare API.
+ */
+export interface WorkersDevConfig {
+    /**
+     * Serve the Worker at its stable `workers.dev` URL
+     * (`https://<worker-name>.<account-subdomain>.workers.dev`).
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Enable version preview URLs — a distinct
+     * `https://<version-prefix>-<worker-name>.<account-subdomain>.workers.dev`
+     * URL per uploaded version, plus stable aliased preview URLs
+     * (`https://<alias>-...`) for versions uploaded with an alias.
+     *
+     * When previews are enabled but {@link enabled} is `false`, the current
+     * version's preview URL becomes the Worker's primary `url` output.
+     * @default true
+     */
+    previewsEnabled?: boolean;
+}
+/**
+ * The Worker's custom-domain configuration: one canonical hostname, plus
+ * optional aliases that also serve the Worker and redirect hostnames that
+ * 301 to the canonical name.
+ */
+export interface WorkerDomainConfig {
+    /**
+     * The canonical hostname (e.g. `"example.com"`). Attached to the Worker
+     * as a Cloudflare custom domain — DNS record and edge certificate are
+     * managed automatically. The Cloudflare zone is inferred from the
+     * hostname and must already exist in the account.
+     *
+     * When set, `https://<name>` is the Worker's primary `url` output.
+     */
+    name: string;
+    /**
+     * Additional hostnames that serve the Worker (e.g. `"www.example.com"`,
+     * `"api.example.com"`). Each is attached as its own custom domain.
+     * Order matters: aliases follow `name` in the `urls` output.
+     */
+    aliases?: string[];
+    /**
+     * Hostnames that permanently redirect (HTTP 301, path and query
+     * preserved) to {@link name} — e.g. `"old.example.com"`. Each is
+     * attached as a custom domain (for DNS + TLS) with a redirect rule in
+     * the zone's `http_request_dynamic_redirect` phase, which runs before
+     * the Worker — redirected requests never invoke it. Redirect hostnames
+     * serve no content, so they appear in the `domain` output but never in
+     * `urls`.
+     */
+    redirects?: string[];
+}
 export interface WorkerRouteConfig {
     /**
      * URL pattern to match incoming requests against, e.g.
@@ -153,6 +210,185 @@ export interface WorkerRouteConfig {
      */
     zone?: ZoneReference;
 }
+/**
+ * Version-affinity configuration — keeps each user on one version for the
+ * duration of a gradual rollout.
+ *
+ * Percentages route each request independently, so one user can bounce
+ * between versions mid-rollout. Cloudflare pins a request to a version
+ * deterministically when it carries a `Cloudflare-Workers-Version-Key`
+ * header: the key is hashed and assigned a version from the current
+ * percentages, so equal keys always land on the same version, and pinned
+ * users only move forward as percentages rise.
+ *
+ * Setting `affinity` provisions that header as infrastructure: a `rewrite`
+ * Transform Rule in the `http_request_late_transform` phase of every zone
+ * the Worker serves on (custom domains and zone routes), scoped to the
+ * Worker's hostnames, filling the header from the configured source. The
+ * rule is updated in place as the config changes and removed when
+ * `affinity` is removed or the Worker is destroyed; other rules in the
+ * zone's shared entrypoint are left untouched.
+ *
+ * Exactly one of {@link cookie}, {@link header}, or {@link key} may be
+ * set; {@link ip} combines with `cookie`/`header` as a fallback or stands
+ * alone as the sole source.
+ *
+ * Transform Rules only see **zone traffic** — the Worker must have a
+ * `domain` or `routes` (or, with `version.parent`, the parent must).
+ * A workers.dev-only Worker fails the deploy with
+ * `WorkerVersionConfigError`; on the bare workers.dev URL clients must
+ * send the header themselves.
+ */
+export interface WorkerVersionAffinity {
+    /**
+     * Pin by the value of this request cookie (e.g. a session id). Requests
+     * without the cookie fall back to {@link ip} when set, otherwise they
+     * route independently by percentage.
+     */
+    cookie?: string;
+    /**
+     * Pin by the value of this request header (e.g. a tenant or user id
+     * your edge already stamps, or a stable auth claim forwarded as a
+     * header). Requests without the header fall back to {@link ip} when
+     * set, otherwise they route independently by percentage.
+     */
+    header?: string;
+    /**
+     * Pin by client IP. On its own (`{ ip: true }`) every request is keyed
+     * by `ip.src`; combined with {@link cookie} or {@link header} it is the
+     * fallback for requests missing the primary source (e.g. sticky by
+     * session cookie, falling back to sticky IP before the cookie is set).
+     */
+    ip?: boolean;
+    /**
+     * Escape hatch: a raw [Rules-language](https://developers.cloudflare.com/ruleset-engine/rules-language/)
+     * expression that computes the version key — e.g. a JWT claim via API
+     * Shield's `http.request.jwt.claims`, or any composite of request
+     * fields. Applied to every request on the Worker's hostnames; cannot be
+     * combined with the other sources.
+     */
+    key?: string;
+}
+/**
+ * Versioning configuration for a Worker deploy — controls Worker
+ * [versions and gradual deployments](https://developers.cloudflare.com/workers/configuration/versions-and-deployments/).
+ *
+ * Two modes, selected by {@link parent}:
+ *
+ * - **Version worker** (`parent` set): instead of creating its own script,
+ *   this Worker uploads an immutable *version* to the referenced parent
+ *   Worker's script. With `traffic: 0` (the default) the parent's live
+ *   deployment is untouched and the version is reachable only at its
+ *   preview URL (`<version-prefix>-<name>.<subdomain>.workers.dev`) —
+ *   the PR-preview use case. With `traffic > 0` the version becomes a
+ *   canary taking that percentage of the parent's traffic.
+ * - **Gradual rollout** (`parent` omitted): when this Worker deploys
+ *   itself, the newly uploaded version receives {@link traffic} percent
+ *   and the currently-live version keeps the remainder, instead of the
+ *   default 100% cutover.
+ *
+ * A gradual rollout carries only what a version can: code, bindings,
+ * compatibility settings, and cache configuration. Workers with static
+ * assets cannot roll out gradually (the versions API cannot carry assets),
+ * a deploy that changes Durable Object class migrations must go out at
+ * 100% (migrations cannot ride a rollout), and script-level settings
+ * (tags, observability, limits, placement, logpush) keep their live
+ * values until the next full deploy.
+ */
+export interface WorkerVersionOptions {
+    /**
+     * The Worker that owns the script this version is uploaded to. Accepts a
+     * Worker reference — typically `yield* Cloudflare.Worker.ref(id, { stage,
+     * stack })` for a Worker deployed in another stage/stack, or a
+     * locally-declared Worker — or a literal script name as an escape hatch.
+     *
+     * When set, this resource does not create a script of its own: it
+     * uploads a version (code + bindings + compatibility settings) to the
+     * parent's script. Script-level settings apply immediately to *all*
+     * versions of the parent, so they cannot be set on a version worker —
+     * `name`, `assets`, `namespace`, `crons`, `domain`, `routes`, `tags`,
+     * `logpush`, `observability`, `placement`, `limits`, and `subdomain` are
+     * rejected, as are locally-hosted Durable Object or Workflow classes
+     * (their migrations would mutate the parent).
+     *
+     * Changing the parent replaces the resource (a version belongs to
+     * exactly one script).
+     */
+    parent?: string | Worker;
+    /**
+     * Percentage of traffic (0–100) the newly uploaded version receives; the
+     * currently-live version keeps the remainder. Cloudflare deployments
+     * split between at most two versions, so one canary can be active per
+     * script at a time.
+     *
+     * With {@link parent} set, defaults to `0`: the version is
+     * preview-URL-only and the parent's live deployment is untouched.
+     * Without `parent`, defaults to `100` (today's full cutover); `0` means
+     * "upload the version without deploying it" (the equivalent of
+     * `wrangler versions upload`).
+     *
+     * Percentages replace the previous deployment, they never add. Each
+     * versioned deploy splits its new version against the *stable* version —
+     * the majority holder of the current deployment — so deploying at 10 and
+     * then at 20 yields the second version at 20% against the stable version
+     * at 80%, with the earlier 10% version dropped from routing entirely
+     * (still uploaded, but unreachable even via a version-override header).
+     * With unchanged code that replacement is exactly a ramp; with changed
+     * code it swaps canaries. The first deploy of a script always goes to
+     * 100%, since there is no previous version to split with.
+     *
+     * Note that a subsequent full deploy of the parent (or of this Worker
+     * itself, at the default 100) resets traffic to 100% of its own new
+     * version.
+     */
+    traffic?: number;
+    /**
+     * Preview-URL alias for the uploaded version. Aliased preview URLs
+     * (`<alias>-<name>.<subdomain>.workers.dev`) are stable — each upload
+     * with the same alias re-points the URL at the new version — which is
+     * what makes them useful as shareable PR-preview links and lets
+     * `Worker.URL` resolve before the version exists.
+     *
+     * For a version worker ({@link parent} set) an alias is derived
+     * automatically from the stack, stage, and logical id, so every version
+     * worker gets a stable preview URL out of the box; set this to override
+     * it. Must start with a lowercase letter, contain only lowercase
+     * letters, digits, and dashes, and `<alias>-<worker-name>` must fit in
+     * 63 characters (a DNS label).
+     */
+    alias?: string;
+    /**
+     * Keep each user on one version for the duration of the rollout by
+     * pinning them to a stable request property — a session cookie, a
+     * header, the client IP, or a raw Rules-language expression:
+     *
+     * ```typescript
+     * version: {
+     *   traffic: 10,
+     *   // sticky by session cookie, falling back to sticky IP
+     *   affinity: { cookie: "session_id", ip: true },
+     * }
+     * ```
+     *
+     * Provisions a Transform Rule that fills the
+     * `Cloudflare-Workers-Version-Key` header on the zones the Worker
+     * serves on — the Worker (or, with {@link parent}, the parent) must
+     * have a `domain` or `routes`. With `parent` set, the rule lands on the
+     * parent's zones, pinning users across the canary split. See
+     * {@link WorkerVersionAffinity}.
+     */
+    affinity?: WorkerVersionAffinity;
+    /**
+     * Human-readable annotation attached to the uploaded version, shown in
+     * the Cloudflare dashboard and `wrangler versions list`.
+     */
+    message?: string;
+    /**
+     * Machine-readable tag annotation attached to the uploaded version
+     * (e.g. a git commit SHA or PR number).
+     */
+    tag?: string;
+}
 export interface WorkerProps<Bindings extends WorkerBindingProps = any, Assets extends WorkerAssetsConfig | undefined = WorkerAssetsConfig | undefined> extends PlatformProps {
     /**
      * Worker name override. If omitted, Alchemy derives a deterministic physical
@@ -181,21 +417,38 @@ export interface WorkerProps<Bindings extends WorkerBindingProps = any, Assets e
      */
     namespace?: string | DispatchNamespace;
     /**
-     * Whether to enable a workers.dev URL for this worker
+     * Worker versions & gradual deployments. Set `version.parent` to upload
+     * this Worker as a preview/canary *version* of another Worker's script
+     * instead of creating its own; set `version.traffic` below 100 to
+     * gradually roll out a deploy of this Worker's own script. See
+     * {@link WorkerVersionOptions}.
+     */
+    version?: WorkerVersionOptions;
+    /**
+     * Controls the Worker's `workers.dev` surface.
+     *
+     * - `true` (the default) — serve the Worker at its stable `workers.dev`
+     *   URL and enable version preview URLs.
+     * - `false` — no `workers.dev` URLs at all.
+     * - An object — toggle the stable URL and version previews independently,
+     *   e.g. `{ enabled: false, previewsEnabled: true }` keeps the stable URL
+     *   off while each deployed version stays reachable at its preview URL.
+     *
      * @default true
      */
-    url?: boolean;
+    workersDev?: boolean | WorkersDevConfig;
     /**
      * Static assets to serve. Can be:
      * - A string path to the assets directory
      * - An AssetsProps object with directory and config
      * - An object with path and hash (e.g., from a Build resource)
+     *
+     * When neither {@link main} nor {@link script} is provided, the Worker is
+     * deployed **assets-only**: no script is uploaded at all and Cloudflare's
+     * asset layer serves every request, applying `htmlHandling` /
+     * `notFoundHandling` (including single-page-application fallback) itself.
      */
     assets?: Assets;
-    subdomain?: {
-        enabled?: boolean;
-        previewsEnabled?: boolean;
-    };
     /** @internal used by Cloudflare.Website.Vite resource */
     vite?: ViteOptions;
     logpush?: boolean;
@@ -232,7 +485,8 @@ export interface WorkerProps<Bindings extends WorkerBindingProps = any, Assets e
     tags?: string[];
     /**
      * Path to the Worker's entry module. Bundled with rolldown before
-     * upload. Mutually exclusive with {@link script} — provide exactly one.
+     * upload. Mutually exclusive with {@link script} — provide at most one.
+     * Omit both (with {@link assets} set) to deploy an assets-only Worker.
      *
      * A `.py` entry deploys a Python Worker instead: no bundling runs — the
      * entry plus every sibling `.py` file upload as Python modules, the
@@ -275,6 +529,11 @@ export interface WorkerProps<Bindings extends WorkerBindingProps = any, Assets e
      *   [Secrets & env](/cloudflare/security/secrets-env).
      * - Literal values — routed by shape: `Redacted<string>` →
      *   `secret_text`, `string` → `plain_text`, anything else → `json`.
+     * - `Output` values that resolve to a plain env value (e.g.
+     *   `Alchemy.makeRandom`) — classified at deploy time by their
+     *   resolved value using the literal rules above. Whole-resource
+     *   Outputs (`Output.of(bucket)`) are rejected at deploy time; bind
+     *   the resource itself instead.
      *
      * In Effect-native Workers you can alternatively `yield*` a
      * `Config` in the Init phase to register the binding implicitly;
@@ -295,11 +554,20 @@ export interface WorkerProps<Bindings extends WorkerBindingProps = any, Assets e
      */
     crons?: string[];
     /**
-     * One or more custom hostnames (e.g. `"app.example.com"`) to bind to this
-     * Worker. The Cloudflare Zone is inferred from the hostname — the zone must
-     * already exist in the account.
+     * The Worker's custom domain: one canonical hostname, plus optional
+     * `aliases` that also serve the Worker and `redirects` that 301 to the
+     * canonical name. A bare string is shorthand for `{ name }`. The
+     * Cloudflare zone is inferred from each hostname — the zone must already
+     * exist in the account.
+     *
+     * When set, `https://<name>` becomes the Worker's primary `url` output,
+     * ranking above the `workers.dev` URL. See {@link WorkerDomainConfig}.
+     *
+     * Omitting the prop leaves custom domains unmanaged — attachments made
+     * outside Alchemy are preserved. Pass `null` to explicitly detach every
+     * custom domain (and remove their redirect rules).
      */
-    domain?: string | string[];
+    domain?: string | WorkerDomainConfig | null;
     /**
      * Zone routes that map URL patterns to this Worker. Equivalent to Wrangler's
      * `routes` array — provide `zoneName` or `zoneId` (or `zone`) alongside each
@@ -379,6 +647,22 @@ export interface WorkerProps<Bindings extends WorkerBindingProps = any, Assets e
          * @default false
          */
         strictPort?: boolean;
+        /**
+         * Whether the local runtime's Cache API simulator
+         * (`caches.default` / `caches.open()`) stores responses. Set
+         * `false` to make every cache operation a no-op — matching
+         * production behaviour on `workers.dev` subdomains, where the
+         * Cache API silently does nothing.
+         * @default true
+         */
+        cache?: boolean;
+        /**
+         * Override the `request.cf` blob served to this Worker locally.
+         * Defaults to a static placeholder (Miniflare's Austin/DFW blob);
+         * pass e.g. `{ colo: "LHR", country: "GB" }` to simulate a
+         * different edge location.
+         */
+        cf?: Record<string, unknown>;
     } | {
         /**
          * Don't start a local Worker; an external dev server is running instead.
@@ -466,17 +750,81 @@ export type Worker<Bindings extends WorkerBindings = any> = Resource<WorkerTypeI
      */
     namespace: string | undefined;
     logpush: boolean | undefined;
+    /**
+     * The most significant URL the Worker is reachable at — always
+     * `urls[0]`, or `undefined` when the Worker is not reachable at any
+     * URL (e.g. a dispatch-namespace user worker). Ranking: the canonical
+     * custom domain, then aliases, then the stable `workers.dev` URL; a
+     * version worker's `url` is its aliased preview URL; under
+     * `alchemy dev` it is the local dev server's URL.
+     */
     url: string | undefined;
+    /**
+     * Every URL that serves this Worker, most significant first —
+     * `[https://<domain.name>?, ...aliases, <workers.dev URL>?,
+     * <version preview URLs>?]`, or the local dev server's
+     * `[localhost, ...LAN]` URLs under `alchemy dev`. Redirect hostnames
+     * never appear (they don't serve the Worker). Useful wholesale, e.g.
+     * as a CORS allow-list.
+     */
+    urls: string[];
+    /**
+     * The Worker's resolved custom-domain configuration — canonical
+     * `name`, `aliases`, and `redirects` as deployed — or `undefined`
+     * when no custom domain is configured.
+     */
+    domain: {
+        name: string;
+        aliases: string[];
+        redirects: string[];
+    } | undefined;
     tags: string[] | undefined;
     durableObjectNamespaces: Record<string, string>;
     accountId: string;
-    domains: string[];
     routes: {
         id: string;
         pattern: string;
         zoneId: string;
     }[];
     crons: string[];
+    /**
+     * The parent script name this Worker uploads versions to, when this
+     * resource is a version worker (`version.parent` set). `undefined` for
+     * a Worker that owns its own script — including one deploying with a
+     * gradual rollout. This is the discriminator `read`/`delete` use to
+     * avoid treating the parent's script as this resource's own.
+     */
+    versionOf?: string | undefined;
+    /**
+     * The id of the version uploaded by the most recent deploy. Only set
+     * when versioning is in play: always for a version worker
+     * (`version.parent`), and for a self-owned Worker when a gradual
+     * rollout (`version.traffic` < 100) deployed via the versions API.
+     */
+    versionId?: string | undefined;
+    /**
+     * The preview-URL alias attached to the uploaded version — the
+     * user-provided `version.alias`, or the auto-derived stable alias for
+     * a version worker. The aliased preview URL
+     * (`<alias>-<name>.<subdomain>.workers.dev`) is stable across
+     * deploys and is the version worker's primary `url`.
+     */
+    versionAlias?: string | undefined;
+    /**
+     * The id of the deployment created by the most recent deploy, when the
+     * deploy created one through the deployments API (a version with
+     * `traffic > 0`). Preview-only versions (`traffic: 0`) have no
+     * deployment.
+     */
+    deploymentId?: string | undefined;
+    /**
+     * The zone ids currently holding this resource's version-affinity
+     * Transform Rules (`version.affinity`) — the cleanup list consulted
+     * when affinity is removed or the resource is deleted. For a version
+     * worker these are the *parent's* zones. `undefined` when no affinity
+     * rules are deployed.
+     */
+    affinityZoneIds?: string[] | undefined;
     hash?: {
         assets: string | undefined;
         bundle: string | undefined;
@@ -498,7 +846,57 @@ export type Worker<Bindings extends WorkerBindings = any> = Resource<WorkerTypeI
     }[];
     crons?: string[];
     hyperdrives?: Record<string, Required<DevOrigin>>;
+    dev?: {
+        remote?: boolean;
+    };
 }, Providers>;
+/**
+ * Effect-native accessor for the Worker's own URL. The value is injected as an
+ * env binding that only exists at the *exec* phase on the deployed Worker, so
+ * reading it is deferred behind an Effect that requires {@link RuntimeContext}.
+ * Yield it inside a handler to obtain the URL string.
+ */
+export type URLAccessor = Effect.Effect<string, never, RuntimeContext>;
+/**
+ * The type of {@link URL} (`Worker.URL`).
+ *
+ * It is a real `Effect` — `yield* Worker.URL` inside a Worker init attaches
+ * the binding and resolves the deferred {@link URLAccessor} — but it also
+ * carries the `~alchemy/Kind` marker statically, so when it is declared on a
+ * Worker's `env` the binding machinery recognises it as a `self_url` binding
+ * (`isSelfUrl`) instead of running it.
+ *
+ * Defined in this module (not its own file): the effect closes over the
+ * `Worker` tag and `WorkerEnvironment`, and a separate module would form a
+ * value cycle with Worker.ts that the deploy bundler's scope hoisting turns
+ * into a startup crash.
+ */
+export interface URLEffect extends Effect.Effect<URLAccessor, never, WorkerEnvironment | Worker> {
+    "~alchemy/Kind": "Cloudflare.Workers.URL";
+}
+/**
+ * A Worker's own public URL, injected as a binding on that same Worker. At
+ * deploy time Alchemy resolves the URL the Worker will be served at (its first
+ * custom domain if any, otherwise its `workers.dev` URL) and injects it as a
+ * plain-text env binding, so the running Worker knows its own public address.
+ *
+ * Declare it on a Worker's `env` (it flows through `InferEnv` → `string`) or
+ * `yield*` it inside an Effect-native Worker to attach the binding and obtain
+ * a deferred {@link URLAccessor}. It is also exposed as
+ * `Cloudflare.Worker.URL`.
+ *
+ * Because the URL is resolved *before* the bundle is built, a `VITE_`-prefixed
+ * env key holding `Worker.URL` is inlined into the client bundle as
+ * `import.meta.env.VITE_*` — the canonical way to give a Vite frontend its own
+ * public URL.
+ */
+export declare const URL: URLEffect;
+/**
+ * Returns true when the value is the `Worker.URL` binding (keyed on the
+ * static `~alchemy/Kind` marker — the value is a real Effect, so every
+ * env-resolution site must check this before `Effect.isEffect`).
+ */
+export declare const isSelfUrl: (value: unknown) => value is URLEffect;
 /**
  * A Cloudflare Worker host with deploy-time binding support and runtime export
  * collection.
@@ -739,6 +1137,22 @@ export type Worker<Bindings extends WorkerBindings = any> = Resource<WorkerTypeI
  * }
  * ```
  *
+ * @example Assets-only Worker (static site)
+ * Omit `main` and `script` entirely to deploy a static site: no Worker
+ * code is uploaded — Cloudflare's asset layer serves every request and
+ * applies `htmlHandling` / `notFoundHandling` (including SPA fallback)
+ * itself, exactly like an assets-only `wrangler deploy`.
+ * ```typescript
+ * const site = yield* Cloudflare.Worker("Site", {
+ *   assets: {
+ *     directory: "./public",
+ *     htmlHandling: "drop-trailing-slash",
+ *     notFoundHandling: "404-page",
+ *   },
+ *   domain: "static.example.com",
+ * });
+ * ```
+ *
  * @example Zone routes
  * ```typescript
  * {
@@ -765,6 +1179,170 @@ export type Worker<Bindings extends WorkerBindings = any> = Resource<WorkerTypeI
  * }
  * ```
  *
+ * @section URLs & Domains
+ * Every URL that serves the Worker is collected in `worker.urls`, most
+ * significant first, and `worker.url` is always `urls[0]`. The ranking:
+ * the canonical custom domain (`domain.name`), then aliases in declared
+ * order, then the stable `workers.dev` URL, then version preview URLs.
+ * Under `alchemy dev`, `urls` is the local dev server's
+ * `[localhost, ...LAN]` addresses instead. Redirect hostnames never
+ * appear in `urls` — they serve no content.
+ *
+ * The `workersDev` prop controls the `workers.dev` surface (`true` by
+ * default = stable URL + version previews; `false` = neither; object form
+ * toggles independently), and the `domain` prop attaches custom domains —
+ * DNS records and edge certificates are managed automatically.
+ *
+ * @example Custom domain with aliases and redirects
+ * ```typescript
+ * const worker = yield* Cloudflare.Worker("Api", {
+ *   main: "./src/api.ts",
+ *   domain: {
+ *     name: "example.com",
+ *     aliases: ["www.example.com"],
+ *     redirects: ["old.example.com"], // 301 → https://example.com
+ *   },
+ * });
+ * // worker.url  === "https://example.com"
+ * // worker.urls === ["https://example.com", "https://www.example.com",
+ * //                  "https://<name>.<account>.workers.dev"]
+ * ```
+ *
+ * @example workers.dev toggles
+ * ```typescript
+ * // No workers.dev URLs at all:
+ * { main: "./src/api.ts", workersDev: false, domain: "api.example.com" }
+ *
+ * // Previews only — each deploy's version preview URL becomes worker.url:
+ * { main: "./src/api.ts", workersDev: { enabled: false, previewsEnabled: true } }
+ * ```
+ *
+ * @example All URLs as a CORS allow-list
+ * ```typescript
+ * const site = yield* Cloudflare.Worker("Site", {
+ *   main: "./src/site.ts",
+ *   domain: { name: "example.com", aliases: ["www.example.com"] },
+ * });
+ * const api = yield* Cloudflare.Worker("Api", {
+ *   main: "./src/api.ts",
+ *   env: { ALLOWED_ORIGINS: site.urls },
+ * });
+ * ```
+ *
+ * @section Versions & Gradual Deployments
+ * The `version` prop maps Cloudflare's
+ * [versions and gradual deployments](https://developers.cloudflare.com/workers/configuration/versions-and-deployments/)
+ * onto Alchemy stages. A Worker with `version.parent` set uploads an
+ * immutable *version* to the parent Worker's script instead of creating its
+ * own — by default with no traffic, reachable only at its preview URL
+ * (`worker.url`), which is the PR-preview workflow. Give it `traffic` to
+ * run it as a canary, or use `version.traffic` on a normal Worker to roll
+ * out its own deploys gradually.
+ *
+ * A version worker's `url` is its *aliased* preview URL
+ * (`<alias>-<name>.<subdomain>.workers.dev`) — the alias is derived from
+ * the stack, stage, and logical id (override with `version.alias`), so the
+ * URL is stable across deploys and always points at the latest uploaded
+ * version. The per-version URL (`<version-prefix>-...`) is also returned
+ * in `domains`. Because the aliased URL is known before the version
+ * exists, `Worker.URL` works on version workers and resolves to it.
+ *
+ * A version carries code, bindings, and compatibility settings. Script-level
+ * settings (routes, domains, crons, tags, observability, …) belong to the
+ * parent and are rejected on version workers, as are locally-hosted Durable
+ * Object or Workflow classes. Preview URLs require the parent's workers.dev
+ * subdomain to be enabled (the default).
+ *
+ * @example PR preview: a version of another stage's Worker
+ * ```typescript
+ * // The staging stage deploys the real Worker; a PR stage uploads its
+ * // code as a zero-traffic version of staging's script and gets back a
+ * // stable preview URL.
+ * const parent = yield* Cloudflare.Worker.ref("MyWorker", {
+ *   stage: "staging",
+ * });
+ * const preview = yield* Cloudflare.Worker("MyWorker", {
+ *   main: "./src/worker.ts",
+ *   version: { parent, message: `PR #${process.env.PR_NUMBER}` },
+ * });
+ * // preview.url -> https://<alias>-<name>.<subdomain>.workers.dev
+ * // (stable across deploys; re-points at each newly uploaded version)
+ * ```
+ *
+ * @example Canary: send 10% of the parent's traffic to a version
+ * ```typescript
+ * const parent = yield* Cloudflare.Worker.ref("MyWorker", { stage: "prod" });
+ * yield* Cloudflare.Worker("MyWorker", {
+ *   main: "./src/worker.ts",
+ *   version: { parent, traffic: 10 },
+ * });
+ * ```
+ *
+ * @example Gradual rollout of a Worker's own deploy
+ * ```typescript
+ * // The new version takes 25% of traffic; the previously-live version
+ * // keeps 75%. Bump traffic (or remove the prop) and re-deploy to promote.
+ * yield* Cloudflare.Worker("MyWorker", {
+ *   main: "./src/worker.ts",
+ *   version: { traffic: 25 },
+ * });
+ * ```
+ *
+ * @example Keep users on one version during the rollout
+ * ```typescript
+ * // Percentages route each request independently; affinity pins users by
+ * // filling the Cloudflare-Workers-Version-Key header on zone traffic —
+ * // here from the session cookie, falling back to the client IP. Requires
+ * // a `domain` or `routes` (with `parent`, the parent's).
+ * yield* Cloudflare.Worker("MyWorker", {
+ *   main: "./src/worker.ts",
+ *   domain: "api.example.com",
+ *   version: {
+ *     traffic: 25,
+ *     affinity: { cookie: "session_id", ip: true },
+ *   },
+ * });
+ * ```
+ *
+ * @section The Worker's own URL
+ * `Worker.URL` injects the URL a Worker is served at as a binding on that
+ * same Worker — the first custom `domain` if one is configured, otherwise
+ * its `workers.dev` URL, always equal to the resource's `url` attribute.
+ * Under `alchemy dev` it resolves to the local dev server's URL.
+ *
+ * @example Read the Worker's own URL inside a handler
+ * ```typescript
+ * Cloudflare.Worker(
+ *   "Api",
+ *   { main: import.meta.url },
+ *   Effect.gen(function* () {
+ *     // Attaches the binding and returns a deferred accessor.
+ *     const url = yield* Cloudflare.Worker.URL;
+ *
+ *     return {
+ *       fetch: Effect.gen(function* () {
+ *         const publicUrl = yield* url;
+ *         return Response.json({ url: publicUrl });
+ *       }),
+ *     };
+ *   }).pipe(Effect.provide(Cloudflare.Workers.URLBinding)),
+ * );
+ * ```
+ *
+ * @example Inject the URL into an async Worker's env
+ * `InferEnv` types the entry as `string`. A `VITE_`-prefixed key on a
+ * vite-built Worker is additionally inlined into the client bundle as
+ * `import.meta.env.VITE_PUBLIC_URL` at build time.
+ * ```typescript
+ * export const Worker = Cloudflare.Worker("Worker", {
+ *   main: "./src/worker.ts",
+ *   env: { PUBLIC_URL: Cloudflare.Worker.URL },
+ * });
+ *
+ * export type WorkerEnv = Cloudflare.InferEnv<typeof Worker>;
+ * //   { PUBLIC_URL: string }
+ * ```
+ *
  * @section Observability
  * Cloudflare Workers Observability is on by default — `logs.enabled` and
  * `logs.invocationLogs` are turned on if you don't pass an `observability`
@@ -1060,11 +1638,32 @@ export declare const Worker: ResourceClassLike<Worker> & Effect.Effect<Worker &
         <const Id extends string, Shape extends WorkerShape, Req extends WorkerServices | Container.Application<any> | PlatformServices | Tag>(id: Id, props: InputProps<WorkerProps>, impl: Effect.Effect<Shape, ConfigError, Req>): Effect.Effect<Worker & Rpc<Self>, never, Extract<Req, Container.Application<any>> | Providers> & Named<Id> & {
             new (): MakeShape<Shape, WorkerShape> & Named<Id> & Tag;
         };
+        /**
+         * Class form without an implementation — an external Worker (a plain
+         * bundled `main`, a raw `script`, or an assets-only Worker with no
+         * script at all):
+         *
+         * ```typescript
+         * export class Site extends Cloudflare.Worker<Site>()("Site", {
+         *   assets: { directory: "./public" },
+         * }) {}
+         * ```
+         */
+        <const Id extends string, Req = never>(id: Id, props: InputProps<WorkerProps> | Effect.Effect<InputProps<WorkerProps>, ConfigError, Req>): Effect.Effect<Worker & Rpc<{}>, never, Req | Providers> & Named<Id> & {
+            new (): Named<Id> & Tag;
+        };
     };
     <const Bindings extends WorkerBindingProps = {}, const Assets extends WorkerAssetsConfig | undefined = undefined, Req = never>(id: string, props: InputProps<WorkerProps<Bindings, Assets>> | Effect.Effect<InputProps<WorkerProps<Bindings, Assets>>, ConfigError, Req>): Effect.Effect<Worker<{
         [binding in keyof NormalizedBindings<Bindings, Assets>]: NormalizedBindings<Bindings, Assets>[binding];
     }> & Rpc<{}>, never, Req | Providers>;
     <const Id extends string, Shape extends WorkerShape, Req extends WorkerServices | Container.Application<any> | PlatformServices>(id: string, props: InputProps<WorkerProps>, impl: Effect.Effect<Shape, ConfigError, Req>): Effect.Effect<Worker & Rpc<Shape>, never, Extract<Req, Container.Application<any>> | Providers> & Named<Id>;
+    /**
+     * The Worker's own public URL, injected as a binding on that same Worker.
+     * Declare it on `env` (`env: { VITE_PUBLIC_URL: Worker.URL }`) or
+     * `yield*` it inside an Effect-native Worker to obtain a deferred
+     * accessor. See {@link URLEffect}.
+     */
+    readonly URL: URLEffect;
 };
 export {};
 //# sourceMappingURL=Worker.d.ts.map