sproutboat 0.54.0 → 0.55.0

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>;