Fix Queues docs code examples & types (#28192)

* fix(queues): update all code examples for type correctness and best practices

- Fix MessageSendRequest type to match @cloudflare/workers-types (contentType
  and delaySeconds are direct properties, not nested under options)
- Add readonly modifier to MessageBatch.messages in type definitions
- Use satisfies ExportedHandler<Env> pattern consistently across all examples
- Replace let with const where values are not reassigned
- Fix Error type issues: native Error objects are not structured-clone
  serializable, use serializable ErrorMessage interface instead
- Add proper error type narrowing in catch blocks (instanceof Error)
- Remove e: any catch annotations in favor of proper type narrowing
- Fix missing return statements in fetch handlers
- Fix Durable Objects example: use DurableObject base class instead of
  deprecated implements DurableObject pattern, add missing closing brace
- Replace Queue<any> with properly typed Queue<Message> throughout
- Use interface instead of type for Env declarations consistently
- Fix sendBatch example that unnecessarily JSON.stringified message bodies
- Update AI skill reference to match corrected MessageSendRequest type

* fix(queues): complete implicit snippets and add missing Env interfaces in how-queues-works

---------

Co-authored-by: opencode-agent[bot] <opencode-agent[bot]@users.noreply.github.com>

Author: ask-bonk[bot]

src/content/docs/queues/configuration/batching-retries.mdx

@@ -66,14 +66,14 @@ To explicitly acknowledge a message as delivered, call the `ack()` method on the
 <TypeScriptExample filename="index.ts" omitTabs={true}>
 ```ts
 export default {
-	async queue(batch: MessageBatch, env: Env, ctx: ExecutionContext) {
+	async queue(batch, env, ctx): Promise<void> {
 		for (const msg of batch.messages) {
 			// TODO: do something with the message
 			// Explicitly acknowledge the message as delivered
 			msg.ack();
 		}
 	},
-};
+} satisfies ExportedHandler<Env>;
 ```
 </TypeScriptExample>
 <TabItem label="Python" icon="seti:python">
@@ -96,13 +96,13 @@ You can also call `retry()` to explicitly force a message to be redelivered in a
 <TypeScriptExample filename="index.ts" omitTabs={true}>
 ```ts
 export default {
-	async queue(batch: MessageBatch, env: Env, ctx: ExecutionContext) {
+	async queue(batch, env, ctx): Promise<void> {
 		for (const msg of batch.messages) {
 			// TODO: do something with the message that fails
 			msg.retry();
 		}
 	},
-};
+} satisfies ExportedHandler<Env>;
 ```
 </TypeScriptExample>
 <TabItem label="Python" icon="seti:python">
@@ -210,14 +210,14 @@ To delay an individual message within a batch:
 <TypeScriptExample filename="index.ts" omitTabs={true}>
 ```ts
 export default {
-	async queue(batch: MessageBatch, env: Env, ctx: ExecutionContext) {
+	async queue(batch, env, ctx): Promise<void> {
 		for (const msg of batch.messages) {
 			// Mark for retry and delay a singular message
 			// by 3600 seconds (1 hour)
 			msg.retry({ delaySeconds: 3600 });
 		}
 	},
-};
+} satisfies ExportedHandler<Env>;
 ```
 </TypeScriptExample>
 <TabItem label="Python" icon="seti:python">
@@ -240,12 +240,12 @@ To delay a batch of messages:
 <TypeScriptExample filename="index.ts" omitTabs={true}>
 ```ts
 export default {
-	async queue(batch: MessageBatch, env: Env, ctx: ExecutionContext) {
+	async queue(batch, env, ctx): Promise<void> {
 		// Mark for retry and delay a batch of messages
 		// by 600 seconds (10 minutes)
 		batch.retryAll({ delaySeconds: 600 });
 	},
-};
+} satisfies ExportedHandler<Env>;
 ```
 </TypeScriptExample>
 <TabItem label="Python" icon="seti:python">
@@ -324,12 +324,12 @@ For example, to generate an [exponential backoff](https://en.wikipedia.org/wiki/
 <Tabs syncKey="workersExamples">
 <TypeScriptExample filename="index.ts" omitTabs={true}>
 ```ts
-const calculateExponentialBackoff = (
+function calculateExponentialBackoff(
 	attempts: number,
 	baseDelaySeconds: number,
-) => {
+): number {
 	return baseDelaySeconds ** attempts;
-};
+}
 ```
 </TypeScriptExample>
 <TabItem label="Python" icon="seti:python">
@@ -348,10 +348,9 @@ In your consumer, you then pass the value of `msg.attempts` and your desired del
 const BASE_DELAY_SECONDS = 30;
 
 export default {
-	async queue(batch: MessageBatch, env: Env, ctx: ExecutionContext) {
+	async queue(batch, env, ctx): Promise<void> {
 		for (const msg of batch.messages) {
-			// Mark for retry and delay a singular message
-			// by 3600 seconds (1 hour)
+			// Mark for retry with exponential backoff
 			msg.retry({
 				delaySeconds: calculateExponentialBackoff(
 					msg.attempts,
@@ -360,7 +359,7 @@ export default {
 			});
 		}
 	},
-};
+} satisfies ExportedHandler<Env>;
 ```
 </TypeScriptExample>
 <TabItem label="Python" icon="seti:python">

src/content/docs/queues/configuration/javascript-apis.mdx

@@ -26,20 +26,20 @@ An example of writing a single message to a Queue:
 <Tabs syncKey="workersExamples">
 <TypeScriptExample filename="index.ts" omitTabs={true}>
 ```ts
-type Environment = {
+interface Env {
   readonly MY_QUEUE: Queue;
-};
+}
 
 export default {
-  async fetch(req: Request, env: Environment): Promise<Response> {
+  async fetch(req, env, ctx): Promise<Response> {
     await env.MY_QUEUE.send({
       url: req.url,
       method: req.method,
       headers: Object.fromEntries(req.headers),
     });
-    return new Response('Sent!');
+    return new Response("Sent!");
   },
-};
+} satisfies ExportedHandler<Env>;
 ```
 </TypeScriptExample>
 <TabItem label="Python" icon="seti:python">
@@ -64,25 +64,24 @@ The Queues API also supports writing multiple messages at once:
 <Tabs syncKey="workersExamples">
 <TypeScriptExample filename="index.ts" omitTabs={true}>
 ```ts
-const sendResultsToQueue = async (results: Array<any>, env: Environment) => {
-  const batch: MessageSendRequest[] = results.map((value) => ({
-    body: JSON.stringify(value),
-  }));
-  await env.queue.sendBatch(batch);
+const sendResultsToQueue = async (results: Array<unknown>, env: Env) => {
+	const batch: MessageSendRequest[] = results.map((value) => ({
+		body: value,
+	}));
+	await env.MY_QUEUE.sendBatch(batch);
 };
 ```
 </TypeScriptExample>
 <TabItem label="Python" icon="seti:python">
 ```python
-import json
 from pyodide.ffi import to_js
 
 async def send_results_to_queue(results, env):
     batch = [
-        {"body": json.dumps(value)}
+        {"body": value}
         for value in results
     ]
-    await env.queue.sendBatch(to_js(batch))
+    await env.MY_QUEUE.sendBatch(to_js(batch))
 ```
 </TabItem>
 </Tabs>
@@ -105,9 +104,10 @@ interface Queue<Body = unknown> {
   * Sends a message to the Queue. The body can be any type supported by the [structured clone algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm#supported_types), as long as its size is less than 128 KB.
   * When the promise resolves, the message is confirmed to be written to disk.
 
-* `sendBatch(bodyIterable<MessageSendRequest<unknown>>)` <Type text="Promise<void>" />
+* `sendBatch(messagesIterable<MessageSendRequest<unknown>>, options?QueueSendBatchOptions)` <Type text="Promise<void>" />
 
   * Sends a batch of messages to the Queue. Each item in the provided [Iterable](https://www.typescriptlang.org/docs/handbook/iterators-and-generators.html) must be supported by the [structured clone algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm#supported_types). A batch can contain up to 100 messages, though items are limited to 128 KB each, and the total size of the array cannot exceed 256 KB.
+  * The optional `options` parameter can be used to apply settings (such as `delaySeconds`) to all messages in the batch. See [QueueSendBatchOptions](#queuesendbatchoptions).
   * When the promise resolves, the messages are confirmed to be written to disk.
 
 
@@ -117,10 +117,11 @@ interface Queue<Body = unknown> {
 A wrapper type used for sending message batches.
 
 ```ts
-type MessageSendRequest<Body = unknown> = {
+interface MessageSendRequest<Body = unknown> {
   body: Body;
-  options?: QueueSendOptions;
-};
+  contentType?: QueueContentType;
+  delaySeconds?: number;
+}
 ```
 
 
@@ -130,9 +131,15 @@ type MessageSendRequest<Body = unknown> = {
   * The body of the message.
   * The body can be any type supported by the [structured clone algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm#supported_types), as long as its size is less than 128 KB.
 
-* <code>options</code> <Type text="QueueSendOptions" />
+* <code>contentType</code> <Type text="QueueContentType" />
 
-  * Options to apply to the current message, including content type and message delay settings.
+  * The explicit content type of a message so it can be previewed correctly with the [List messages from the dashboard](/queues/examples/list-messages-from-dash/) feature. Optional argument.
+  * See [QueuesContentType](#queuescontenttype) for possible values.
+
+* <code>delaySeconds</code> <Type text="number" />
+
+  * The number of seconds to [delay a message](/queues/configuration/batching-retries/) for within the queue, before it can be delivered to a consumer.
+  * Must be an integer between 0 and 43200 (12 hours).
 
 
 
@@ -209,17 +216,17 @@ If the `queue()` function throws, or the promise returned by it or any of the pr
 <Tabs syncKey="workersExamples">
 <TypeScriptExample filename="index.ts" omitTabs={true}>
 ```ts
+interface Env {
+  // Add your bindings here
+}
+
 export default {
-  async queue(
-    batch: MessageBatch,
-    env: Environment,
-    ctx: ExecutionContext
-  ): Promise<void> {
+  async queue(batch, env, ctx): Promise<void> {
     for (const message of batch.messages) {
-      console.log('Received', message);
+      console.log("Received", message.body);
     }
   },
-};
+} satisfies ExportedHandler<Env>;
 ```
 </TypeScriptExample>
 <TabItem label="Python" icon="seti:python">
@@ -261,7 +268,7 @@ A batch of messages that are sent to a consumer Worker.
 ```ts
 interface MessageBatch<Body = unknown> {
   readonly queue: string;
-  readonly messages: Message<Body>[];
+  readonly messages: readonly Message<Body>[];
   ackAll(): void;
   retryAll(options?: QueueRetryOptions): void;
 }

src/content/docs/queues/examples/publish-to-a-queue-via-workers.mdx

@@ -54,25 +54,26 @@ interface Env {
 }
 
 export default {
-	async fetch(req, env): Promise<Response> {
+	async fetch(req, env, ctx): Promise<Response> {
 		// Validate the payload is JSON
 		// In a production application, we may more robustly validate the payload
 		// against a schema using a library like 'zod'
 		let messages;
 		try {
 			messages = await req.json();
-		} catch (e) {
+		} catch {
 			// Return a HTTP 400 (Bad Request) if the payload isn't JSON
-			return Response.json({ err: "payload not valid JSON" }, { status: 400 });
+			return Response.json({ error: "payload not valid JSON" }, { status: 400 });
 		}
 
 		// Publish to the Queue
 		try {
 			await env.YOUR_QUEUE.send(messages);
-		} catch (e: any) {
-			console.log(`failed to send to the queue: ${e}`);
+		} catch (e) {
+			const message = e instanceof Error ? e.message : "Unknown error";
+			console.error(`failed to send to the queue: ${message}`);
 			// Return a HTTP 500 (Internal Error) if our publish operation fails
-			return Response.json({ error: e.message }, { status: 500 });
+			return Response.json({ error: message }, { status: 500 });
 		}
 
 		// Return a HTTP 200 if the send succeeded!

src/content/docs/queues/examples/send-errors-to-r2.mdx

@@ -49,35 +49,44 @@ The following Worker will catch JavaScript errors and send them to a queue. The
 </WranglerConfig>
 
 ```ts
-type Environment = {
-	readonly ERROR_QUEUE: Queue<Error>;
+interface ErrorMessage {
+	message: string;
+	stack?: string;
+}
+
+interface Env {
+	readonly ERROR_QUEUE: Queue<ErrorMessage>;
 	readonly ERROR_BUCKET: R2Bucket;
-};
+}
 
 export default {
-  async fetch(req, env): Promise<Response> {
+  async fetch(req, env, ctx): Promise<Response> {
     try {
       return doRequest(req);
-    } catch (error) {
+    } catch (e) {
+      const error: ErrorMessage = {
+        message: e instanceof Error ? e.message : String(e),
+        stack: e instanceof Error ? e.stack : undefined,
+      };
       await env.ERROR_QUEUE.send(error);
       return new Response(error.message, { status: 500 });
     }
   },
-  async queue(batch, env): Promise<void> {
-    let file = '';
+  async queue(batch, env, ctx): Promise<void> {
+    let file = "";
     for (const message of batch.messages) {
       const error = message.body;
-      file += error.stack || error.message || String(error);
-      file += '\r\n';
+      file += error.stack ?? error.message;
+      file += "\r\n";
     }
     await env.ERROR_BUCKET.put(`errors/${Date.now()}.log`, file);
   },
-} satisfies ExportedHandler<Environment, Error>;
+} satisfies ExportedHandler<Env, ErrorMessage>;
 
-function doRequest(request: Request): Promise<Response> {
+function doRequest(request: Request): Response {
   if (Math.random() > 0.5) {
-    return new Response('Success!');
+    return new Response("Success!");
   }
-  throw new Error('Failed!');
+  throw new Error("Failed!");
 }
 ```

src/content/docs/queues/examples/use-queues-with-durable-objects.mdx

@@ -64,31 +64,33 @@ The following Worker script:
 2. Passes request data to the Durable Object.
 3. Publishes to a queue from within the Durable Object.
 
-The `constructor()` in the Durable Object makes your `Environment` available (in scope) on `this.env` to the [`fetch()` handler](/durable-objects/best-practices/create-durable-object-stubs-and-send-requests/) in the Durable Object.
+Extending the `DurableObject` base class makes your `Env` available on `this.env` and the Durable Object state available on `this.ctx` within the [`fetch()` handler](/durable-objects/best-practices/create-durable-object-stubs-and-send-requests/) in the Durable Object.
 
 ```ts
+import { DurableObject } from "cloudflare:workers";
+
 interface Env {
   YOUR_QUEUE: Queue;
-  YOUR_DO_CLASS: DurableObjectNamespace;
+  YOUR_DO_CLASS: DurableObjectNamespace<YourDurableObject>;
 }
 
 export default {
-  async fetch(req, env): Promise<Response> {
+  async fetch(req, env, ctx): Promise<Response> {
     // Assume each Durable Object is mapped to a userId in a query parameter
     // In a production application, this will be a userId defined by your application
     // that you validate (and/or authenticate) first.
-    let url = new URL(req.url)
-    let userIdParam = url.searchParams.get("userId")
+    const url = new URL(req.url);
+    const userIdParam = url.searchParams.get("userId");
 
     if (userIdParam) {
       // Get a stub that allows you to call that Durable Object
-      let durableObjectStub = env.YOUR_DO_CLASS.getByName(userIdParam);
+      const durableObjectStub = env.YOUR_DO_CLASS.getByName(userIdParam);
 
       // Pass the request to that Durable Object and await the response
       // This invokes the constructor once on your Durable Object class (defined further down)
       // on the first initialization, and the fetch method on each request.
       // We pass the original Request to the Durable Object's fetch method
-      let response = await durableObjectStub.fetch(req);
+      const response = await durableObjectStub.fetch(req);
 
       // This would return "wrote to queue", but you could return any response.
       return response;
@@ -97,17 +99,16 @@ export default {
   },
 } satisfies ExportedHandler<Env>;
 
-export class YourDurableObject implements DurableObject {
-  constructor(private state: DurableObjectState, private env: Env) {}
-
+export class YourDurableObject extends DurableObject<Env> {
   async fetch(req: Request): Promise<Response> {
     // Error handling elided for brevity.
     // Publish to your queue
     await this.env.YOUR_QUEUE.send({
-      id: this.state.id.toString() // Write the ID of the Durable Object to your queue
+      id: this.ctx.id.toString(), // Write the ID of the Durable Object to your queue
       // Write any other properties to your queue
     });
 
-    return new Response("wrote to queue")
+    return new Response("wrote to queue");
   }
+}
 ```