@vercel/queue 0.0.0-alpha.3 → 0.0.0-alpha.5

package/README.md

@@ -39,16 +39,33 @@ Publishing and consuming messages on a queue
 
 ```typescript
 // index.ts
-import { createTopic, JsonTransport, QueueClient } from "@vercel/queue";
+import { send, receive } from "@vercel/queue";
 
-// Create a client - automatically authenticated using the OIDC token
-const client = await QueueClient.fromVercelFunction();
+type Message = {
+  message: string;
+  timestamp: number;
+};
+
+// Option 1: Using the send and receive helpers (simplest)
+// Automatically uses default client and JSON transport
+await send<Message>("my-topic", {
+  message: "Hello, World!",
+  timestamp: Date.now(),
+});
+
+// Consume a single message off the queue
+// (Often wrapped in a loop to keep polling messages off the queue)
+await receive<Message>("my-topic", "my-consumer-group", (m) => {
+  console.log(m.message);
+});
+
+// Option 2: Using createTopic for more control
+
+import { createTopic } from "@vercel/queue";
 
 // Create a topic with JSON serialization (default)
-const topic = createTopic<{ message: string; timestamp: number }>(
-  client,
-  "my-topic",
-);
+// Uses default QueueClient automatically authenticated from Vercel environment
+const topic = createTopic<Message>("my-topic");
 
 // Publish a message
 await topic.publish({
@@ -57,30 +74,29 @@ await topic.publish({
 });
 
 // Create a consumer group
-const consumer = topic.consumerGroup("my-processors");
-
-// Process messages continuously with cancellation support
-const controller = new AbortController();
+const consumer = topic.consumerGroup("my-consumer-group");
 
-// Start processing (blocks until aborted or error)
+// Process next available message (one-shot processing)
 try {
-  await consumer.subscribe(controller.signal, async (message) => {
-    console.log("Received:", message.payload.message);
-    console.log("Timestamp:", new Date(message.payload.timestamp));
+  await consumer.consume(async (message, metadata) => {
+    console.log("Received:", message.message);
+    console.log("Timestamp:", new Date(message.timestamp));
+    console.log("Message Metadata", metadata);
+    // => { messageId, deliveryCount, timestamp }
   });
 } catch (error) {
-  console.error("Processing stopped due to error:", error);
+  console.error("Processing error:", error);
 }
-
-// Stop processing from elsewhere in your code
-// controller.abort();
 ```
 
 Run the script
 
 ```bash
-# Using dotenv to load the OIDC token
-dotenv -e .env.local node index.ts
+# Install dotenv-cli and ts-node if you need it
+npm i -g dotenv-cli ts-node typescript
+
+# Run the script with the OIDC token
+dotenv -e .env.local ts-node index.ts
 ```
 
 ## Usage with Vercel
@@ -112,36 +128,75 @@ package export resolution:
 Create a new server function to publish messages
 
 ```typescript
-// app/action.ts
+// app/actions.ts
 "use server";
 
-import { createTopic, QueueClient } from "@vercel/queue";
+import { send } from "@vercel/queue";
 
 export async function publishTestMessage(message: string) {
-  // Initialize a queue client
-  const client = await QueueClient.fromVercelFunction();
-
-  // Create a topic with JSON serialization (default)
-  const topic = createTopic<{ message: string; timestamp: number }>(
-    client,
+  // Option 1: Using simple send shorthand
+  const { messageId } = await send(
     "my-topic",
+    { message, timestamp: Date.now() },
+    {
+      // Provide a callback URL to invoke a consumer when the message is ready to be processed
+      callback: {
+        url: getCallbackUrl() // implementation below
+      },
+    },
   );
 
+  console.log(`Published message ${messageId}`);
+}
+
+// Option 2: Customize the topic, transport, consumer groups, etc.
+import { createTopic } from "@vercel/queue";
+
+export async function publishTestMessage(message: string) {
+  // Create a topic with JSON serialization (default)
+  const topic = createTopic<{ message: string; timestamp: number }>("my-topic");
+
   // Publish the message
   const { messageId } = await topic.publish(
     { message, timestamp: Date.now() },
     {
-      // Provide a callback URL to invoke a consumer when the message is ready to be processed
+      // Provide multiple callback URLs to invoke multiple consumer groups
       callback: {
-        url: process.env.VERCEL_PROJECT_PRODUCTION_URL
-          ? `https://${process.env.VERCEL_PROJECT_PRODUCTION_URL}/api/queue/handle`
-          : "http://localhost:3000/api/queue/handle",
+        {
+          "consumer-group-1": {
+            url: getCallbackUrl()
+          },
+          "consumer-group-2": {
+            url: getCallbackUrl()
+            delay: 5 // Delay callback by 5 seconds
+          },
+        }
       },
     },
   );
 
   console.log(`Published message ${messageId}`);
 }
+
+// Helper function to generate a local callback URL
+function getCallbackUrl() {
+  const callbackUrl = new URL(
+    process.env.VERCEL_URL
+      ? `https://${process.env.VERCEL_URL}/api/queue/handle`
+      : "http://localhost:3000/api/queue/handle"
+  );
+
+  // Add Vercel automation bypass secret if available (for preview deployments)
+  if (process.env.VERCEL_AUTOMATION_BYPASS_SECRET) {
+    callbackUrl.searchParams.set(
+      "x-vercel-protection-bypass",
+      process.env.VERCEL_AUTOMATION_BYPASS_SECRET
+    );
+  }
+
+  return callbackUrl.toString();
+}
+
 ```
 
 Now wire up the server function to your app
@@ -151,12 +206,12 @@ Now wire up the server function to your app
 "use client";
 import { publishTestMessage } from "./actions";
 
-export default function Button() {
+export default function Page() {
   return (
     // ...
-    <Button onClick={() => publishTestMessage("Hello world")} >
+    <button onClick={() => publishTestMessage("Hello world")}>
       Publish Test Message
-    </a>
+    </button>
   );
 }
 ```
@@ -173,30 +228,30 @@ The `handleCallback` helper function simplifies queue callback handling in NextJ
 // app/api/queue/handle/route.ts
 import { handleCallback } from "@vercel/queue";
 
+// Option 1: Specify a single handler for the topic
 export const POST = handleCallback({
-  // Handle messages sent on the "new-users" topic (the consumer
-  // group "default" will be used)
   "my-topic": (message, metadata) => {
     console.log(`Received message:`, message, metadata);
     // metadata: { messageId, deliveryCount, timestamp }
   },
+
+  // .. more topic handlers can be provided here
 });
 
-// Or, specify separate handlers for separate consumer groups
+// This consumes messages on the "default" consumer group, which is used when no consumer groups
+// were specified in the publish `callback` earlierA
+
+// Option 2: Multiple consumer groups
 export const POST = handleCallback({
   // topic: "my-topic"
   "my-topic": {
     // consumer group: "compress"
-    compress: (message, metadata) => {
-      console.log("Compressing image:", message);
+    "consumer-group-1": (message, metadata) => {
+      console.log("Message:", message);
     },
     // consumer group: "resize"
-    resize: (message, metadata) => {
-      console.log("Resizing image:", message);
-    },
-    // consumer group: "watermark"
-    watermark: (message, metadata) => {
-      console.log("Adding watermark:", message);
+    "consume-group-2": (message, metadata) => {
+      console.log("Message", message);
     },
   },
 });
@@ -209,18 +264,16 @@ export const POST = handleCallback({
 Handle large files and data streams without loading them into memory:
 
 ```typescript
-import { StreamTransport } from "@vercel/queue";
+import { createTopic, StreamTransport } from "@vercel/queue";
 
 const videoTopic = createTopic<ReadableStream<Uint8Array>>(
-  client,
   "video-processing",
   new StreamTransport(),
 );
 
 // Process large video files efficiently
 const processor = videoTopic.consumerGroup("processors");
-await processor.subscribe(signal, async (message) => {
-  const videoStream = message.payload;
+await processor.consume(async (videoStream) => {
   // Process stream chunk by chunk
   const reader = videoStream.getReader();
   while (true) {
@@ -252,10 +305,10 @@ const webhooks = topic.consumerGroup("webhooks");
 - **Topics**: Named message channels with configurable serialization
 - **Consumer Groups**: Named groups of consumers that process messages in
   parallel
-  - `subscribe()`: Continuously process messages with automatic polling
-  - `receiveMessage()`: Process a specific message by ID
-  - `receiveNextMessage()`: Process the next available message (one-shot)
-  - `handleMessage()`: Process message metadata only (without payload)
+  - `consume()`: Process messages with flexible consumption patterns
+    - No options: Process next available message
+    - With `messageId`: Process specific message by ID
+    - With `skipPayload: true`: Process message metadata only (without payload)
 - **Transports**: Pluggable serialization/deserialization for different data
   types
 - **Streaming**: Memory-efficient processing of large payloads
@@ -288,13 +341,9 @@ memory.
 ```typescript
 import { createTopic, JsonTransport } from "@vercel/queue";
 
-const topic = createTopic<{ data: any }>(
-  client,
-  "json-topic",
-  new JsonTransport(),
-);
+const topic = createTopic<{ data: any }>("json-topic", new JsonTransport());
 // or simply (JsonTransport is the default):
-const topic = createTopic<{ data: any }>(client, "json-topic");
+const topic = createTopic<{ data: any }>("json-topic");
 ```
 
 #### BufferTransport
@@ -305,11 +354,7 @@ that fits in memory.
 ```typescript
 import { BufferTransport, createTopic } from "@vercel/queue";
 
-const topic = createTopic<Buffer>(
-  client,
-  "binary-topic",
-  new BufferTransport(),
-);
+const topic = createTopic<Buffer>("binary-topic", new BufferTransport());
 const binaryData = Buffer.from("Binary data", "utf8");
 await topic.publish(binaryData);
 ```
@@ -323,7 +368,6 @@ Ideal for large files and memory-efficient processing.
 import { createTopic, StreamTransport } from "@vercel/queue";
 
 const topic = createTopic<ReadableStream<Uint8Array>>(
-  client,
   "streaming-topic",
   new StreamTransport(),
 );
@@ -372,8 +416,12 @@ interface Transport<T = unknown> {
 ### QueueClient
 
 ```typescript
+// Simple usage - automatically gets OIDC token from Vercel environment
+const client = new QueueClient();
+
+// Or with options
 const client = new QueueClient({
-  token: string;
+  token?: string; // Optional - will auto-detect if not provided
   baseUrl?: string; // defaults to 'https://vqs.vercel.sh'
 });
 ```
@@ -381,7 +429,12 @@ const client = new QueueClient({
 ### Topic
 
 ```typescript
-const topic = createTopic<T>(client, topicName, transport?);
+// Simple usage with default client
+const topic = createTopic<T>(topicName, transport?);
+
+// For custom client configuration, use Topic constructor directly
+const customClient = new QueueClient({ baseUrl: "https://custom.vqs.vercel.sh" });
+const topic = new Topic<T>(customClient, topicName, transport?);
 
 // Publish a message (uses topic's transport)
 await topic.publish(payload, options?);
@@ -405,28 +458,59 @@ await topic.publish(payload, {
 const consumer = topic.consumerGroup<U>(groupName, options?);
 ```
 
-### ConsumerGroup
+### Send (Shorthand)
 
 ```typescript
-// Start continuous processing (blocks until signal is aborted or error occurs)
-await consumer.subscribe(signal, handler, options?);
+// Simple send - automatically uses default client and JSON transport
+await send<T>(topicName, payload);
+
+// Send with options including custom transport
+await send<T>(topicName, payload, {
+  transport?: Transport<T>;
+  idempotencyKey?: string;
+  retentionSeconds?: number;
+  callback?: Record<string, CallbackConfig> | CallbackConfig;
+});
 
-// Process a specific message by ID
-await consumer.receiveMessage(messageId, handler);
+// Examples:
+await send("notifications", { userId: "123", message: "Welcome!" });
 
-// Process the next available message
-await consumer.receiveNextMessage(handler);
+await send("images", imageBuffer, {
+  transport: new BufferTransport(),
+  callback: { url: "https://example.com/process-image" }
+});
 
-// Handle a specific message by ID without payload
-await consumer.handleMessage(messageId, handler);
+await send("events", eventData, {
+  idempotencyKey: "unique-key-123",
+  retentionSeconds: 3600,
+  callback: {
+    analytics: { url: "https://analytics.example.com/webhook" },
+    notifications: { url: "https://notifications.example.com/webhook", delay: 30 }
+  }
+});
+```
+
+### ConsumerGroup
+
+```typescript
+// Process next available message (simplest form)
+await consumer.consume(handler);
+
+// Process specific message by ID with payload
+await consumer.consume(handler, { messageId: "message-id" });
+
+// Process specific message by ID without payload (metadata only)
+// handler will be called with `undefined` as the payload
+await consumer.consume(handler, { messageId: "message-id", skipPayload: true });
 ```
 
 ### Message Handler
 
 ```typescript
 // Handler function signature
-type MessageHandler<T> = (
-  message: Message<T>,
+type MessageHandler<T = unknown> = (
+  message: T,
+  metadata: MessageMetadata,
 ) => Promise<MessageHandlerResult> | MessageHandlerResult;
 
 // Handler result types
@@ -435,6 +519,22 @@ type MessageHandlerResult = void | MessageTimeoutResult;
 interface MessageTimeoutResult {
   timeoutSeconds: number; // seconds before message becomes available again
 }
+
+// Message Metadata
+interface MessageMetadata {
+  messageId: string;
+  deliveryCount: number;
+  timestamp: string;
+}
+```
+
+### ConsumeOptions Interface
+
+```typescript
+interface ConsumeOptions {
+  messageId?: string; // Process specific message by ID
+  skipPayload?: boolean; // Skip payload download (requires messageId)
+}
 ```
 
 ### Transport Interface
@@ -462,24 +562,11 @@ interface CallbackMessageOptions {
 // Create a callback handler for NextJS route handlers
 function handleCallback(handlers: CallbackHandlers): (request: Request) => Promise<Response>;
 
-// Handler function signature for callbacks
-type Handler<T = unknown> = (
-  payload: T,
-  metadata: MessageMetadata
-) => Promise<MessageHandlerResult> | MessageHandlerResult;
-
-// Message metadata provided to handlers
-interface MessageMetadata {
-  messageId: string;
-  deliveryCount: number;
-  timestamp: string;
-}
-
 // Configuration object with handlers for different topics
 type CallbackHandlers = {
   [topicName: string]:
-    | Handler // Single handler (uses 'default' consumer group)
-    | { [consumerGroup: string]: Handler }; // Multiple consumer group handlers
+    | MessageHandler // Single handler (uses 'default' consumer group)
+    | { [consumerGroup: string]: MessageHandler }; // Multiple consumer group handlers
 };
 
 // Example usage:
@@ -511,7 +598,15 @@ interface UserEvent {
   timestamp: number;
 }
 
-const userTopic = createTopic<UserEvent>(client, "user-events");
+// Option 1: Using send shorthand
+await send<UserEvent>("user-events", {
+  userId: "123",
+  action: "login",
+  timestamp: Date.now(),
+});
+
+// Option 2: Using createTopic for consumers
+const userTopic = createTopic<UserEvent>("user-events");
 
 await userTopic.publish({
   userId: "123",
@@ -520,27 +615,21 @@ await userTopic.publish({
 });
 
 const consumer = userTopic.consumerGroup("processors");
-const controller = new AbortController();
 
+// Process next available message
 try {
-  await consumer.subscribe(controller.signal, async (message) => {
-    console.log(
-      `User ${message.payload.userId} performed ${message.payload.action}`,
-    );
+  await consumer.consume(async (message) => {
+    console.log(`User ${message.userId} performed ${message.action}`);
   });
 } catch (error) {
   console.error("Processing error:", error);
 }
-
-// Stop processing when needed
-// controller.abort();
 ```
 
 ### Processing Specific Messages by ID
 
 ```typescript
 const userTopic = createTopic<{ userId: string; action: string }>(
-  client,
   "user-events",
 );
 const consumer = userTopic.consumerGroup("processors");
@@ -549,12 +638,13 @@ const consumer = userTopic.consumerGroup("processors");
 const messageId = "01234567-89ab-cdef-0123-456789abcdef";
 
 try {
-  await consumer.receiveMessage(messageId, async (message) => {
-    console.log(`Processing specific message: ${message.messageId}`);
-    console.log(
-      `User ${message.payload.userId} performed ${message.payload.action}`,
-    );
-  });
+  await consumer.consume(
+    async (message, { messageId }) => {
+      console.log(`Processing specific message: ${messageId}`);
+      console.log(`User ${message.userId} performed ${message.action}`);
+    },
+    { messageId },
+  );
   console.log("Message processed successfully");
 } catch (error) {
   if (error.message.includes("not found or not available")) {
@@ -570,17 +660,14 @@ try {
 ### Processing Next Available Message
 
 ```typescript
-const workTopic = createTopic<{ taskType: string; data: any }>(
-  client,
-  "work-queue",
-);
+const workTopic = createTopic<{ taskType: string; data: any }>("work-queue");
 const worker = workTopic.consumerGroup("workers");
 
 // Process the next available message (one-shot processing)
 try {
-  await worker.receiveNextMessage(async (message) => {
-    console.log(`Processing task: ${message.payload.taskType}`);
-    await processTask(message.payload.taskType, message.payload.data);
+  await worker.consume(async (message) => {
+    console.log(`Processing task: ${message.taskType}`);
+    await processTask(message.taskType, message.data);
   });
   console.log("Message processed successfully");
 } catch (error) {
@@ -596,31 +683,37 @@ try {
   }
 }
 
-// You can also use it with timeout results
-await worker.receiveNextMessage(async (message) => {
-  if (!canProcessTaskType(message.payload.taskType)) {
+// Handle conditional timeouts
+await worker.consume(async (message) => {
+  if (!canProcessTaskType(message.taskType)) {
     // Return timeout to retry later
     return { timeoutSeconds: 60 };
   }
 
-  await processTask(message.payload.taskType, message.payload.data);
+  await processTask(message.taskType, message.data);
 });
+
+// Process specific message metadata only (no payload download)
+await worker.consume(
+  async (_, metadata) => {
+    console.log(`Message ID: ${metadata.messageId}`);
+    console.log(`Delivery count: ${metadata.deliveryCount}`);
+    console.log(`Timestamp: ${metadata.timestamp}`);
+    // _ is undefined - no payload was downloaded
+  },
+  { messageId: "specific-message-id", skipPayload: true },
+);
 ```
 
 ### Timing Out Messages
 
 ```typescript
-const workTopic = createTopic<{ taskType: string; data: any }>(
-  client,
-  "work-queue",
-);
+const workTopic = createTopic<{ taskType: string; data: any }>("work-queue");
 const worker = workTopic.consumerGroup("workers");
-const controller = new AbortController();
 
+// Process a message with conditional timeout
 try {
-  await worker.subscribe(controller.signal, async (message) => {
-    const { taskType, data } = message.payload;
-
+  await worker.consume(async ({ taskType, data }) => {
     // Check if we can process this task type right now
     if (taskType === "heavy-computation" && isSystemOverloaded()) {
       // Return timeout to retry later (5 minutes)
@@ -643,15 +736,12 @@ try {
 }
 
 // Example with exponential backoff
-const backoffController = new AbortController();
-
 try {
-  await worker.subscribe(backoffController.signal, async (message) => {
+  await worker.consume(async (message, { deliveryCount }) => {
     const maxRetries = 3;
-    const deliveryCount = message.deliveryCount;
 
     try {
-      await processMessage(message.payload);
+      await processMessage(message);
       // Successful processing - message will be deleted
     } catch (error) {
       if (deliveryCount < maxRetries) {
@@ -679,111 +769,97 @@ Here's a comprehensive example showing a video processing pipeline that
 processes videos with FFmpeg and stores the results in Vercel Blob:
 
 ```typescript
-import { createTopic, QueueClient, StreamTransport } from "@vercel/queue";
+import { createTopic, StreamTransport } from "@vercel/queue";
 import { spawn } from "child_process";
 import ffmpeg from "ffmpeg-static";
 import { put } from "@vercel/blob";
 
-const client = new QueueClient({
-  token: "your-vercel-oidc-token",
-});
-
 // Input topic with unoptimized videos
 const unoptimizedVideosTopic = createTopic<ReadableStream<Uint8Array>>(
-  client,
   "unoptimized-videos",
   new StreamTransport(),
 );
 
 // Output topic for optimized videos
 const optimizedVideosTopic = createTopic<ReadableStream<Uint8Array>>(
-  client,
   "optimized-videos",
   new StreamTransport(),
 );
 
 // Step 1: Process videos with FFmpeg
 const videoProcessor = unoptimizedVideosTopic.consumerGroup("processors");
-const processingController = new AbortController();
 
 try {
-  await videoProcessor.subscribe(
-    processingController.signal,
-    async (message) => {
-      const inputVideoStream = message.payload;
-      console.log("Processing video...");
-
-      if (!ffmpeg) {
-        throw new Error("FFmpeg not available");
-      }
+  await videoProcessor.consume(async (inputVideoStream) => {
+    console.log("Processing video...");
 
-      // Create optimized video stream using FFmpeg
-      const optimizedStream = new ReadableStream<Uint8Array>({
-        start(controller) {
-          const ffmpegProcess = spawn(
-            ffmpeg,
-            [
-              "-i",
-              "pipe:0", // Input from stdin
-              "-c:v",
-              "libvpx-vp9", // Video codec
-              "-c:a",
-              "libopus", // Audio codec
-              "-crf",
-              "23", // Quality
-              "-f",
-              "webm", // Output format
-              "pipe:1", // Output to stdout
-            ],
-            { stdio: ["pipe", "pipe", "pipe"] },
-          );
-
-          // Pipe input stream to FFmpeg
-          const reader = inputVideoStream.getReader();
-          const pipeInput = async () => {
-            while (true) {
-              const { done, value } = await reader.read();
-              if (done) {
-                ffmpegProcess.stdin?.end();
-                break;
-              }
-              ffmpegProcess.stdin?.write(value);
-            }
-          };
-          pipeInput();
-
-          // Stream FFmpeg output
-          ffmpegProcess.stdout?.on("data", (chunk) => {
-            controller.enqueue(new Uint8Array(chunk));
-          });
-
-          ffmpegProcess.on("close", (code) => {
-            if (code === 0) {
-              controller.close();
-            } else {
-              controller.error(new Error(`FFmpeg failed with code ${code}`));
+    if (!ffmpeg) {
+      throw new Error("FFmpeg not available");
+    }
+
+    // Create optimized video stream using FFmpeg
+    const optimizedStream = new ReadableStream<Uint8Array>({
+      start(controller) {
+        const ffmpegProcess = spawn(
+          ffmpeg,
+          [
+            "-i",
+            "pipe:0", // Input from stdin
+            "-c:v",
+            "libvpx-vp9", // Video codec
+            "-c:a",
+            "libopus", // Audio codec
+            "-crf",
+            "23", // Quality
+            "-f",
+            "webm", // Output format
+            "pipe:1", // Output to stdout
+          ],
+          { stdio: ["pipe", "pipe", "pipe"] },
+        );
+
+        // Pipe input stream to FFmpeg
+        const reader = inputVideoStream.getReader();
+        const pipeInput = async () => {
+          while (true) {
+            const { done, value } = await reader.read();
+            if (done) {
+              ffmpegProcess.stdin?.end();
+              break;
             }
-          });
-        },
-      });
+            ffmpegProcess.stdin?.write(value);
+          }
+        };
+        pipeInput();
+
+        // Stream FFmpeg output
+        ffmpegProcess.stdout?.on("data", (chunk) => {
+          controller.enqueue(new Uint8Array(chunk));
+        });
+
+        ffmpegProcess.on("close", (code) => {
+          if (code === 0) {
+            controller.close();
+          } else {
+            controller.error(new Error(`FFmpeg failed with code ${code}`));
+          }
+        });
+      },
+    });
 
-      // Publish optimized video to next topic
-      await optimizedVideosTopic.publish(optimizedStream);
-      console.log("Video optimized and published");
-    },
-  );
+    // Publish optimized video to next topic
+    await optimizedVideosTopic.publish(optimizedStream);
+    console.log("Video optimized and published");
+  });
 } catch (error) {
   console.error("Video processing error:", error);
 }
 
 // Step 2: Store optimized videos in Vercel Blob
 const blobUploader = optimizedVideosTopic.consumerGroup("blob-uploaders");
-const uploadController = new AbortController();
 
 try {
-  await blobUploader.subscribe(uploadController.signal, async (message) => {
-    const optimizedVideo = message.payload;
-
+  await blobUploader.consume(async (optimizedVideo) => {
     // Upload to Vercel Blob storage
     const filename = `optimized-${Date.now()}.webm`;
     const blob = await put(filename, optimizedVideo, {
@@ -796,12 +872,6 @@ try {
 } catch (error) {
   console.error("Blob upload error:", error);
 }
-
-// Graceful shutdown
-process.on("SIGINT", () => {
-  processingController.abort();
-  uploadController.abort();
-});
 ```
 
 ## Error Handling
@@ -813,18 +883,15 @@ The queue client provides specific error types for different failure scenarios:
 - **`QueueEmptyError`**: Thrown when attempting to receive messages from an
   empty queue (204 status)
 
-  - Only thrown when directly using `client.receiveMessages()`
-  - `ConsumerGroup.subscribe()` handles this error internally and continues
-    polling
+  - Thrown by `consume()` when no messages are available
+  - Also thrown when directly using `client.receiveMessages()`
 
 - **`MessageLockedError`**: Thrown when a message is temporarily locked (423
   status)
 
   - Contains optional `retryAfter` property with seconds to wait before retry
-  - For `receiveMessages()` on FIFO queues: the next message in sequence is
-    locked
-  - For `receiveMessageById()`: the requested message is locked
-  - `ConsumerGroup.subscribe()` handles this error internally when polling
+  - For `consume()` without options: the next message in FIFO sequence is locked
+  - For `consume()` with messageId: the requested message is locked
 
 - **`MessageNotFoundError`**: Message doesn't exist (404 status)
 
@@ -893,7 +960,7 @@ try {
 
 // Handle locked message with retry
 try {
-  await consumer.receiveMessage(messageId, handler);
+  await consumer.consume(handler, { messageId });
 } catch (error) {
   if (error instanceof MessageLockedError) {
     console.log("Message is locked by another consumer");