sproutboat 0.53.1 → 0.55.0

package/src/types-cmd.ts

@@ -0,0 +1,193 @@
+/**
+ * The `sproutboat types` command: its arguments, the file it writes, and `--check`.
+ *
+ * Wrangler's contract (`wrangler types [path]`): the positional is the declaration file to write, default
+ * `worker-configuration.d.ts`; `--env-interface`, `--strict-vars`, `--include-runtime`, `--include-env` and `--check`
+ * behave as there. Two differences are on purpose and said in the help: `--include-runtime` references the runtime
+ * types shipped with the CLI instead of copying them in, and there is no `--include-main-module` (nothing here reads
+ * `ctx.exports`).
+ *
+ * Earlier releases took a project directory as the one positional. A positional that is an existing directory is
+ * still read that way.
+ */
+import { existsSync, statSync } from "node:fs";
+import { readFile, rm, writeFile } from "node:fs/promises";
+import { dirname, relative, resolve, sep } from "node:path";
+import type { SproutboatConfig } from "./config";
+import {
+  exportedClasses,
+  generateTypes,
+  hashOf,
+  isCurrent,
+  LEGACY_TYPES_FILE,
+  LEGACY_TYPES_HEADER,
+  TYPES_FILE,
+  type TypesOptions,
+} from "./types-gen";
+
+export const TYPES_USAGE =
+  "types [path] [--env-interface <name>] [--no-strict-vars] [--no-include-runtime] [--no-include-env] [--check]";
+
+export type TypesArgs = {
+  /** The declaration file, as typed; or the project directory when it names an existing directory. */
+  positional?: string;
+  options: Omit<TypesOptions, "command" | "mainModule">;
+  check: boolean;
+};
+
+type BooleanOption = "strictVars" | "includeRuntime" | "includeEnv";
+const BOOLEAN_FLAGS = new Map<string, BooleanOption>([
+  ["--strict-vars", "strictVars"],
+  ["--include-runtime", "includeRuntime"],
+  ["--include-env", "includeEnv"],
+]);
+
+/** Parse what is left after the global flags and `checkOptions`, where `--flag=value` is already `--flag value`. */
+export function parseTypesArgs(args: readonly string[]): TypesArgs | { error: string } {
+  const out: TypesArgs = { options: {}, check: false };
+  for (let at = 0; at < args.length; at += 1) {
+    const arg = args[at]!;
+    if (arg === "--check") out.check = true;
+    else if (arg === "--env-interface") {
+      const value = args[(at += 1)];
+      if (value === undefined || value.startsWith("--")) return { error: "--env-interface needs a name" };
+      if (!/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(value)) return { error: `"${value}" is not a valid interface name` };
+      out.options.envInterface = value;
+    } else if (BOOLEAN_FLAGS.has(arg) || (arg.startsWith("--no-") && BOOLEAN_FLAGS.has(`--${arg.slice(5)}`))) {
+      const negated = !BOOLEAN_FLAGS.has(arg);
+      const key = BOOLEAN_FLAGS.get(negated ? `--${arg.slice(5)}` : arg)!;
+      if (negated) {
+        out.options[key] = false;
+        continue;
+      }
+      const next = args[at + 1];
+      // `--strict-vars=false` arrives as `--strict-vars false`; a bare `--strict-vars` means true.
+      if (next === "true" || next === "false") {
+        out.options[key] = next === "true";
+        at += 1;
+      } else if (next === undefined || next.startsWith("--")) out.options[key] = true;
+      else return { error: `${arg} takes true or false, not "${next}"` };
+    } else if (arg.startsWith("-")) return { error: `unknown option ${arg}` };
+    else if (out.positional === undefined) out.positional = arg;
+    else return { error: `unexpected argument "${arg}"` };
+  }
+  return out;
+}
+
+/** The command line as it is recorded in the generated file's header: the flags that differ from the defaults. */
+function commandLine(parsed: TypesArgs, path: string | undefined): string {
+  const { envInterface, strictVars, includeRuntime, includeEnv } = parsed.options;
+  return [
+    "sproutboat types",
+    ...(path ? [path] : []),
+    ...(envInterface && envInterface !== "Env" ? [`--env-interface=${envInterface}`] : []),
+    ...(strictVars === false ? ["--strict-vars=false"] : []),
+    ...(includeRuntime === false ? ["--include-runtime=false"] : []),
+    ...(includeEnv === false ? ["--include-env=false"] : []),
+  ].join(" ");
+}
+
+export type TypesPlan = {
+  /** Absolute path of the declaration file. */
+  path: string;
+  /** What `generateTypes` writes for it. */
+  text: string;
+  /** The positional was a project directory, which this release still reads (the file is then the default one). */
+  legacyDirectory: boolean;
+};
+
+/**
+ * The project directory and output file for a positional, and the file's text.
+ *
+ * `projectDirectory` is where `sproutboat.jsonc` is (already resolved from `-c` / `--cwd` and a directory
+ * positional); the output path is relative to the working directory, as in Wrangler.
+ */
+export async function planTypes(
+  parsed: TypesArgs,
+  config: SproutboatConfig,
+  projectDirectory: string,
+  cwd: string = process.cwd(),
+): Promise<TypesPlan> {
+  const positional = parsed.positional;
+  const asDirectory = positional !== undefined && isDirectory(resolve(cwd, positional));
+  const path =
+    positional === undefined || asDirectory ? resolve(projectDirectory, TYPES_FILE) : resolve(cwd, positional);
+
+  let mainModule: TypesOptions["mainModule"];
+  if (/\.(?:ts|mts|tsx)$/.test(config.main)) {
+    const entry = resolve(projectDirectory, config.main);
+    try {
+      const classes = exportedClasses(await readFile(entry, "utf8"));
+      if (classes.length) {
+        const rel = relative(dirname(path), entry.replace(/\.[^./\\]+$/, ""))
+          .split(sep)
+          .join("/");
+        mainModule = { importPath: rel.startsWith(".") ? rel : `./${rel}`, classes };
+      }
+    } catch {
+      // No entry file yet: the bindings are still worth typing.
+    }
+  }
+  const text = generateTypes(config, {
+    ...parsed.options,
+    mainModule,
+    command: commandLine(parsed, positional !== undefined && !asDirectory ? positional : undefined),
+  });
+  return { path, text, legacyDirectory: asDirectory };
+}
+
+/** `--check`: whether the file at `path` is the one `plan` would write. Missing or hand-written is not current. */
+export async function checkTypes(plan: TypesPlan): Promise<"current" | "stale" | "missing"> {
+  if (!existsSync(plan.path)) return "missing";
+  return isCurrent(await readFile(plan.path, "utf8"), plan.text) ? "current" : "stale";
+}
+
+function isDirectory(path: string): boolean {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/** Remove the file earlier releases wrote, when it is still exactly what they generated. */
+export async function removeLegacyTypes(projectDir: string): Promise<boolean> {
+  const legacy = resolve(projectDir, LEGACY_TYPES_FILE);
+  try {
+    if (!(await readFile(legacy, "utf8")).startsWith(LEGACY_TYPES_HEADER)) return false;
+    await rm(legacy);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Rewrite the generated types when the config has moved on, and only when the default file is the one a plain
+ * `sproutboat types` wrote. Called from `dev` and `deploy` so a binding added to sproutboat.jsonc cannot sit
+ * unreflected in the editor. It writes only when the content differs, which keeps it out of the way of git and of
+ * file watchers, and leaves a file made with other flags (or by hand) alone: Wrangler never touches it either.
+ * Returns what it did, for the caller to print.
+ */
+export async function refreshTypes(
+  projectDir: string,
+  config: SproutboatConfig,
+): Promise<{ wrote: boolean; removedLegacy: boolean }> {
+  const parsed = parseTypesArgs([]);
+  if ("error" in parsed) return { wrote: false, removedLegacy: false };
+  const plan = await planTypes(parsed, config, projectDir, projectDir);
+  let have: string | undefined;
+  try {
+    have = await readFile(plan.path, "utf8");
+  } catch {
+    // No file yet: only write one if the project already opted in with a tsconfig. A plain JavaScript project gets none.
+    if (!existsSync(resolve(projectDir, "tsconfig.json"))) return { wrote: false, removedLegacy: false };
+  }
+  if (have !== undefined) {
+    const customCommand = !(have.split("\n", 2)[1] ?? "").includes("`sproutboat types`");
+    if (hashOf(have) === undefined || customCommand || hashOf(have) === hashOf(plan.text))
+      return { wrote: false, removedLegacy: false };
+  }
+  await writeFile(plan.path, plan.text);
+  return { wrote: true, removedLegacy: await removeLegacyTypes(projectDir) };
+}

package/src/types-gen.ts

@@ -1,45 +1,66 @@
 /**
- * `sproutboat types` — the project's `env`, as TypeScript.
+ * `sproutboat types` — the project's `Env`, as TypeScript, the way `wrangler types` writes it.
  *
- * `env` remains available as a global in both compatibility modes. This file
- * gives it the project's binding names and types. From 2026-09-28 it is also
- * the second handler argument.
+ * The output is `worker-configuration.d.ts` (Wrangler's file name), a script file that declares an `Env` interface
+ * and `Cloudflare.Env` (what `import { env } from "cloudflare:workers"` reads) from `sproutboat.jsonc`, then
+ * references the ambient types shipped in `types/sproutboat.d.ts`. Binding *names* version with the project and
+ * binding *shapes* with the CLI. A handler is typed with `satisfies ExportedHandler<Env>`.
  *
- * The output declares `env` from `sproutboat.jsonc` and references the ambient
- * types shipped in `types/sproutboat.d.ts`, so binding *shapes* version with
- * the CLI and binding *names* version with the project.
- *
- * Names need no quoting: `parseConfig` already holds every binding and var to
- * /^[A-Z][A-Z0-9_]*$/, so all of them are plain identifiers.
+ * Names need no quoting: `parseConfig` already holds every binding and var to /^[A-Z][A-Z0-9_]*$/, so all of them
+ * are plain identifiers.
  */
+import { createHash } from "node:crypto";
 import { resourceRefs, type SproutboatConfig } from "./config";
 
-/** The file the generator writes, relative to the project directory. */
-export const TYPES_FILE = "sproutboat-env.d.ts";
+/** The file `sproutboat types` writes by default, relative to the project directory. */
+export const TYPES_FILE = "worker-configuration.d.ts";
 
-const HEADER = `// Generated by \`sproutboat types\`. Do not edit.
-//
-// Regenerated whenever sproutboat.jsonc is newer than this file, so a binding
-// added to the config shows up in the editor without asking. Commit it: it is
-// part of the project's type surface, like a schema.
-`;
+/** The file earlier releases wrote. It is only ever removed when it still carries its generated header. */
+export const LEGACY_TYPES_FILE = "sproutboat-env.d.ts";
+export const LEGACY_TYPES_HEADER = "// Generated by `sproutboat types`. Do not edit.";
+
+export type TypesOptions = {
+  /** Name of the interface (`--env-interface`). Default `Env`. */
+  envInterface?: string;
+  /** Literal types for `vars` (`--strict-vars`, default on); off, every var is a `string`. */
+  strictVars?: boolean;
+  /** Reference the runtime types shipped with the CLI (`--include-runtime`, default on). */
+  includeRuntime?: boolean;
+  /** Write the `Env` types (`--include-env`, default on). */
+  includeEnv?: boolean;
+  /** The command as typed, for the header. */
+  command?: string;
+  /**
+   * The entry module, so a Durable Object binding is typed with its class and `stub.method()` is checked.
+   * `importPath` is relative to the output file and has no extension; only a TypeScript entry is offered.
+   */
+  mainModule?: { importPath: string; classes: readonly string[] };
+};
 
 type Entry = { name: string; type: string; note?: string };
 
-/** Whether the binding's calls return Promises at the project's compatibility date. */
+const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+
+/** Whether a binding's calls return Promises at the project's compatibility date. */
 function asyncAt(config: SproutboatConfig, date: string): boolean {
   return config.compatibility_date >= date;
 }
 
-function entries(config: SproutboatConfig): Entry[] {
+/** `export class Name` declarations of an entry module, for typing Durable Object bindings. */
+export function exportedClasses(source: string): string[] {
+  return [...source.matchAll(/^\s*export\s+(?:abstract\s+)?class\s+([A-Za-z_$][A-Za-z0-9_$]*)/gm)].map(
+    (match) => match[1]!,
+  );
+}
+
+function entries(config: SproutboatConfig, options: TypesOptions): Entry[] {
   const out: Entry[] = [];
+  const strictVars = options.strictVars ?? true;
 
   for (const [name, value] of Object.entries(config.vars ?? {})) {
-    out.push({ name, type: "string", note: `vars: ${JSON.stringify(value)}` });
-  }
-  for (const name of config.secrets ?? []) {
-    out.push({ name, type: "string", note: "secret, set with `sproutboat secrets put`" });
+    out.push({ name, type: strictVars ? JSON.stringify(value) : "string" });
   }
+  for (const name of config.secrets ?? []) out.push({ name, type: "string", note: "secret" });
   for (const { binding } of resourceRefs(config.kv_namespaces))
     out.push({ name: binding, type: asyncAt(config, "2026-10-25") ? "KVNamespaceAsync" : "KVNamespace" });
   for (const { binding } of resourceRefs(config.d1_databases))
@@ -47,63 +68,78 @@ function entries(config: SproutboatConfig): Entry[] {
   for (const { binding } of resourceRefs(config.r2_buckets))
     out.push({ name: binding, type: asyncAt(config, "2026-10-26") ? "R2BucketAsync" : "R2Bucket" });
   for (const { binding } of resourceRefs(config.queues)) out.push({ name: binding, type: "Queue" });
-  for (const name of config.analytics_engine_datasets ?? []) {
-    out.push({ name, type: "AnalyticsEngineDataset" });
-  }
+  for (const name of config.analytics_engine_datasets ?? []) out.push({ name, type: "AnalyticsEngineDataset" });
   for (const [binding, className] of Object.entries(config.durable_objects ?? {})) {
-    out.push({ name: binding, type: "DurableObjectNamespace", note: `class ${className}` });
+    if (!asyncAt(config, "2026-10-28")) {
+      out.push({ name: binding, type: "DurableObjectNamespace", note: className });
+      continue;
+    }
+    const typed = options.mainModule?.classes.includes(className) && IDENTIFIER.test(className);
+    out.push({
+      name: binding,
+      type: typed
+        ? `DurableObjectNamespaceAsync<import(${JSON.stringify(options.mainModule!.importPath)}).${className}>`
+        : "DurableObjectNamespaceAsync",
+      note: typed ? undefined : className,
+    });
   }
   for (const service of config.services ?? []) {
-    out.push({ name: service.binding, type: "Fetcher", note: `service binding: ${service.service}` });
-  }
-  for (const rl of config.ratelimiters ?? []) {
-    out.push({ name: rl.binding, type: "RateLimit", note: `rate limit: ${rl.limit} per ${rl.period}s` });
+    out.push({
+      name: service.binding,
+      type: asyncAt(config, "2026-10-22") ? "FetcherAsync" : "Fetcher",
+      note: `service: ${service.service}`,
+    });
   }
+  for (const limiter of config.ratelimiters ?? []) out.push({ name: limiter.binding, type: "RateLimit" });
   if (config.assets?.binding) {
-    out.push({ name: config.assets.binding, type: "Fetcher", note: `static assets: ${config.assets.directory}` });
-  }
-  if (config.version_metadata) {
-    out.push({ name: config.version_metadata, type: "VersionMetadata" });
+    out.push({ name: config.assets.binding, type: asyncAt(config, "2026-10-22") ? "FetcherAsync" : "Fetcher" });
   }
+  if (config.version_metadata) out.push({ name: config.version_metadata, type: "VersionMetadata" });
   return out;
 }
 
+const sha = (text: string) => createHash("sha256").update(text).digest("hex").slice(0, 32);
+
+/** The hash a generated file carries in its first line, or `undefined` for anything else. */
+export function hashOf(file: string): string | undefined {
+  return /^\/\* eslint-disable \*\/\n\/\/ Generated by Sproutboat by running `[^\n]*` \(hash: ([0-9a-f]{32})\)\n/.exec(
+    file,
+  )?.[1];
+}
+
 /**
- * The contents of `sproutboat-env.d.ts` for `config`.
+ * The contents of `worker-configuration.d.ts` for `config`.
  *
- * Pure, so the test can assert on the text and `dev` can compare it against
- * what is already on disk without writing.
+ * Pure, so the tests can assert on the text and `dev` can compare it with what is on disk without writing.
  */
-export function generateTypes(config: SproutboatConfig): string {
-  const rows = entries(config);
-  const body = rows.length
-    ? rows
-        .map((entry) => `    ${entry.note ? `/** ${entry.note} */\n    ` : ""}${entry.name}: ${entry.type};`)
-        .join("\n")
-    : "    // No bindings declared in sproutboat.jsonc yet.";
-
-  const handlerNote =
-    config.compatibility_date >= "2026-09-28"
-      ? "The same object is passed as the second handler argument: fetch(request, env, ctx)."
-      : "The handler signature is fetch(request, ctx); env is only a global.";
+export function generateTypes(config: SproutboatConfig, options: TypesOptions = {}): string {
+  const name = options.envInterface ?? "Env";
+  if (!IDENTIFIER.test(name)) throw new Error(`"${name}" is not a valid interface name`);
+  const includeRuntime = options.includeRuntime ?? true;
+  const includeEnv = options.includeEnv ?? true;
+  const legacy = config.compatibility_date < "2026-09-28";
 
-  return `${HEADER}
-/// <reference types="sproutboat/types" />
-
-declare global {
-  /**
-   * Bindings from sproutboat.jsonc, for project "${config.name}".
-   *
-   * ${handlerNote}
-   * D1 (from 2026-10-24), KV (2026-10-25) and R2 (2026-10-26) return Promises, as on
-   * Workers, so a project at or after those dates gets the *Async types; before them
-   * the calls are synchronous. \`await\` works at every date.
-   */
-  const env: {
-${body}
-  };
+  const parts: string[] = [];
+  if (includeRuntime) parts.push('/// <reference types="sproutboat/types" />');
+  if (includeEnv) {
+    const rows = entries(config, options);
+    const base = `__Base${name}`;
+    const members = rows.map((row) => `\t${row.name}: ${row.type};${row.note ? ` /* ${row.note} */` : ""}`);
+    parts.push(
+      `interface ${base} {${members.length ? `\n${members.join("\n")}\n` : ""}}`,
+      `declare namespace Cloudflare {\n\tinterface Env extends ${base} {}\n}`,
+      `interface ${name} extends ${base} {}`,
+    );
+    // Before compatibility date 2026-09-28 the handler is `fetch(request, ctx)` and `env` is only a global.
+    if (legacy) parts.push(`declare const env: ${name};`);
+  }
+  const body = parts.join("\n") + "\n";
+  const command = options.command ?? "sproutboat types";
+  return `/* eslint-disable */\n// Generated by Sproutboat by running \`${command}\` (hash: ${sha(body)})\n${body}`;
 }
 
-export {};
-`;
+/** Whether `file` is what `generateTypes` would write for the same input, by the hash in its header. */
+export function isCurrent(file: string, wanted: string): boolean {
+  const have = hashOf(file);
+  return have !== undefined && have === hashOf(wanted);
 }

package/types/cloudflare-workers.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The `cloudflare:workers` module, as the runtime provides it: the base classes Workers code extends and the
+ * `env` import. A script file on purpose: an ambient `declare module` is only a declaration here, not an
+ * augmentation. `sproutboat.d.ts` references it, so the one reference a project's generated file carries is enough.
+ *
+ * `Cloudflare.Env` is declared by the project's `worker-configuration.d.ts`.
+ */
+/// <reference path="./sproutboat.d.ts" />
+
+declare module "cloudflare:workers" {
+  /** The bindings of this project, same object as the second handler argument. */
+  export const env: Cloudflare.Env;
+
+  /**
+   * A Durable Object class, from compatibility date 2026-10-29 (2026-10-28 for the Promise storage): `this.ctx` and
+   * `this.env` are set, and any method is callable as `await stub.method()`.
+   */
+  export abstract class DurableObject<Bindings = Cloudflare.Env> {
+    constructor(ctx: DurableObjectStateAsync, env: Bindings);
+    protected ctx: DurableObjectStateAsync;
+    protected env: Bindings;
+    fetch?(request: Request): Response | Promise<Response>;
+    /** Runs after `storage.setAlarm`, with no request in flight. */
+    alarm?(info?: { retryCount: number; isRetry: boolean }): void | Promise<void>;
+    webSocketMessage?(ws: WebSocket, message: string | ArrayBuffer): void | Promise<void>;
+    webSocketClose?(ws: WebSocket, code: number, reason: string, wasClean: boolean): void | Promise<void>;
+  }
+
+  /**
+   * A Worker as a class: `export default class extends WorkerEntrypoint<Env>`. Its methods are what a service
+   * binding calls over RPC (from compatibility date 2026-11-18).
+   */
+  export abstract class WorkerEntrypoint<Bindings = Cloudflare.Env> {
+    constructor(ctx: ExecutionContext, env: Bindings);
+    protected ctx: ExecutionContext;
+    protected env: Bindings;
+    fetch?(request: Request): Response | Promise<Response>;
+    scheduled?(controller: ScheduledController): void | Promise<void>;
+    queue?(batch: MessageBatch): void | Promise<void>;
+  }
+
+  export class RpcTarget {}
+}

package/types/sproutboat.d.ts

@@ -3,8 +3,8 @@
  *
  * Shipped with the CLI rather than as a separate package, so the types always
  * describe the runtime that the installed CLI compiles. `sproutboat types`
- * generates a project's `sproutboat-env.d.ts`, which references this file and
- * declares `env` with that project's bindings.
+ * generates a project's `worker-configuration.d.ts`, which references this file
+ * and declares `Env` with that project's bindings, as `wrangler types` does.
  *
  * KV, D1 and R2 are synchronous before the compatibility date that makes each one return a
  * Promise (D1 2026-10-24, KV 2026-10-25, R2 2026-10-26): `KVNamespace`, `D1Database` and
@@ -13,9 +13,24 @@
  * project's date. `await` works at every date. Before compatibility date 2026-09-28, `env` is a
  * global only and `ctx` is the second handler argument. From that date, `env`
  * is also passed as the second argument and `ctx` as the third.
+ *
+ * Durable Objects follow the same rule: from 2026-10-28 storage and `stub.fetch()` return Promises
+ * (`DurableObjectNamespaceAsync`, `DurableObjectStorageAsync`, `DurableObjectStateAsync`), from
+ * 2026-10-29 a class that extends `DurableObject` from "cloudflare:workers" is called over RPC, and from
+ * 2026-10-22 `fetch()` on a service or assets binding returns a Promise (`FetcherAsync`).
  */
 
+/// <reference path="./cloudflare-workers.d.ts" />
+
 declare global {
+  /**
+   * The project's bindings. Empty here; `sproutboat types` writes `interface Env extends ...` into
+   * `worker-configuration.d.ts`, which merges with this one, and `import { env } from "cloudflare:workers"` reads it.
+   */
+  namespace Cloudflare {
+    interface Env {}
+  }
+
   // ---------------------------------------------------------------- KV
 
   interface KVPutOptions {
@@ -262,6 +277,8 @@ declare global {
   }
 
   interface R2ObjectBodyAsync extends R2ObjectAsync {
+    /** Copies `httpMetadata` (content type, cache control, ...) onto `headers`, as on Workers. */
+    writeHttpMetadata(headers: Headers): void;
     body: ReadableStream;
     bodyUsed: boolean;
     arrayBuffer(): Promise<ArrayBuffer>;
@@ -419,6 +436,118 @@ declare global {
     getWebSocketAutoResponse(): WebSocketRequestResponsePair | null;
   }
 
+  // ------------------------------------- Durable Objects, from 2026-10-28
+
+  /** Workers RPC: the methods of a class, as Promise-returning stub methods. */
+  type RpcMethods<T> = {
+    [
+      K in keyof T as K extends
+        | "fetch"
+        | "alarm"
+        | "webSocketMessage"
+        | "webSocketClose"
+        | "webSocketError"
+        | "scheduled"
+        | "queue"
+        | "ctx"
+        | "env"
+        ? never
+        : T[K] extends (...args: never[]) => unknown
+          ? K
+          : never
+    ]: T[K] extends (...args: infer Args) => infer Result ? (...args: Args) => Promise<Awaited<Result>> : never;
+  };
+
+  /**
+   * What `namespace.get(id)` returns from 2026-10-28: `fetch()` is a Promise, and the methods of a
+   * class that extends `DurableObject` are callable as `await stub.method(...)` from 2026-10-29. Give
+   * the class as the type argument: `DurableObjectNamespaceAsync<Counter>`.
+   */
+  type DurableObjectStubAsync<T = undefined> = (T extends undefined ? unknown : RpcMethods<T>) & {
+    fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+    readonly id: DurableObjectId;
+    readonly name?: string;
+  };
+
+  interface DurableObjectNamespaceAsync<T = undefined> {
+    idFromName(name: string): DurableObjectId;
+    /** A 64-digit hex id, from `id.toString()`. */
+    idFromString(id: string): DurableObjectId;
+    newUniqueId(): DurableObjectId;
+    get(id: DurableObjectId): DurableObjectStubAsync<T>;
+    /** `get(idFromName(name))`, from 2026-10-29. */
+    getByName(name: string): DurableObjectStubAsync<T>;
+  }
+
+  interface DurableObjectListOptions {
+    prefix?: string;
+    start?: string;
+    startAfter?: string;
+    end?: string;
+    limit?: number;
+    reverse?: boolean;
+  }
+
+  interface DurableObjectTransaction {
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    put<T>(key: string, value: T): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    list<T = unknown>(options?: DurableObjectListOptions): Promise<Map<string, T>>;
+    rollback(): void;
+  }
+
+  type SqlStorageValue = ArrayBuffer | string | number | null;
+
+  interface SqlStorageCursor<T = Record<string, SqlStorageValue>> extends Iterable<T> {
+    readonly columnNames: string[];
+    readonly rowsRead: number;
+    readonly rowsWritten: number;
+    toArray(): T[];
+    one(): T;
+    raw<R extends SqlStorageValue[] = SqlStorageValue[]>(): IterableIterator<R>;
+    next(): IteratorResult<T>;
+  }
+
+  /** From 2026-10-29: each object has its own SQLite database. */
+  interface SqlStorage {
+    exec<T = Record<string, SqlStorageValue>>(query: string, ...bindings: unknown[]): SqlStorageCursor<T>;
+    readonly databaseSize: number;
+  }
+
+  /** Storage from 2026-10-28: every call returns a Promise, and an object keeps its own input gate. */
+  interface DurableObjectStorageAsync {
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    get<T = unknown>(keys: string[]): Promise<Map<string, T>>;
+    put<T>(key: string, value: T): Promise<void>;
+    put(entries: Record<string, unknown>): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    delete(keys: string[]): Promise<number>;
+    deleteAll(): Promise<void>;
+    list<T = unknown>(options?: DurableObjectListOptions): Promise<Map<string, T>>;
+    transaction<T>(closure: (txn: DurableObjectTransaction) => Promise<T>): Promise<T>;
+    /** Synchronous transaction over `sql`; rolls back if `closure` throws. */
+    transactionSync<T>(closure: () => T): T;
+    sync(): Promise<void>;
+    /** At most one alarm is pending per object; a later `setAlarm` replaces it. */
+    setAlarm(scheduledTime: number | Date): Promise<void>;
+    getAlarm(): Promise<number | null>;
+    deleteAlarm(): Promise<void>;
+    readonly sql: SqlStorage;
+  }
+
+  interface DurableObjectStateAsync {
+    readonly id: DurableObjectId;
+    readonly storage: DurableObjectStorageAsync;
+    /** Holds every other event out of the object until `callback` settles. Use it for start-up work. */
+    blockConcurrencyWhile<T>(callback: () => Promise<T>): Promise<T>;
+    waitUntil(promise: Promise<unknown>): void;
+    acceptWebSocket(ws: WebSocket, tags?: string[]): void;
+    getWebSockets(tag?: string): WebSocket[];
+    getTags(ws: WebSocket): string[];
+    setWebSocketAutoResponse(pair?: WebSocketRequestResponsePair): void;
+    getWebSocketAutoResponse(): WebSocketRequestResponsePair | null;
+  }
+
   // ---------------------------------------------------------- WebSockets
 
   /**
@@ -502,11 +631,20 @@ declare global {
 
   // ------------------------------------ Fetchers: services and assets
 
-  /** A service binding, and the shape of the static-asset binding. */
+  /** A service binding, and the shape of the static-asset binding, before 2026-10-22. */
   interface Fetcher {
     fetch(request: Request): Response;
   }
 
+  /**
+   * From 2026-10-22 `fetch()` on a service or assets binding returns a Promise. A service binding to a
+   * `WorkerEntrypoint` also exposes its methods over RPC from 2026-11-18: give the class as the type
+   * argument, `FetcherAsync<QuoteService>`, and `await env.PEER.random()` is checked.
+   */
+  type FetcherAsync<T = undefined> = (T extends undefined ? unknown : RpcMethods<T>) & {
+    fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+  };
+
   // --------------------------------------------------------- Handlers
 
   interface ScheduledEvent {
@@ -515,6 +653,15 @@ declare global {
     scheduledTime: number;
   }
 
+  /** What `scheduled(controller, env, ctx)` receives, from compatibility date 2026-09-28. */
+  interface ScheduledController {
+    /** The expression that fired, as written in `triggers.crons`. */
+    readonly cron: string;
+    readonly scheduledTime: number;
+    /** Do not retry this run if the handler throws. */
+    noRetry(): void;
+  }
+
   /** Work that outlives the response, drained in-process and capped at 25s. */
   interface ExecutionContext {
     waitUntil(promise: Promise<unknown>): void;
@@ -529,6 +676,16 @@ declare global {
     queue?(batch: MessageBatch<QueueBody>, ctx: ExecutionContext): void | Promise<void>;
   }
 
+  /**
+   * The default export of a Worker, as in Workers: `satisfies ExportedHandler<Env>`. Compatibility dates
+   * from 2026-09-28; `Env` comes from `sproutboat types`.
+   */
+  interface ExportedHandler<Bindings = unknown, QueueBody = unknown> {
+    fetch?(request: Request, env: Bindings, ctx: ExecutionContext): Response | Promise<Response>;
+    scheduled?(controller: ScheduledController, env: Bindings, ctx: ExecutionContext): void | Promise<void>;
+    queue?(batch: MessageBatch<QueueBody>, env: Bindings, ctx: ExecutionContext): void | Promise<void>;
+  }
+
   /** Handler signature for compatibility dates from 2026-09-28. */
   interface WorkersHandler<Bindings = Record<string, unknown>, QueueBody = unknown> {
     fetch(request: Request, env: Bindings, ctx: ExecutionContext): Response | Promise<Response>;