@vercel/queue 0.0.0-alpha.37 → 0.0.0-alpha.39

package/README.md

@@ -5,12 +5,13 @@ A TypeScript client library for interacting with the Vercel Queue Service API, d
 ## Features
 
 - **Automatic Queue Triggering**: Vercel automatically triggers your API routes when messages are ready
-- **Next.js Integration**: Built-in support for Next.js API routes and Server Actions
+- **Next.js Integration**: Built-in support for Next.js App Router and Pages Router
 - **Generic Payload Support**: Send and receive any type of data with type safety
 - **Pub/Sub Pattern**: Topic-based messaging with consumer groups
 - **Type Safety**: Full TypeScript support with generic types
 - **Streaming Support**: Handle large payloads efficiently
 - **Customizable Serialization**: Use built-in transports (JSON, Buffer, Stream) or create your own
+- **Framework Adapters**: Web API, Next.js App Router, and Pages Router support
 
 ## Installation
 
@@ -39,6 +40,8 @@ vc env pull
 
 The library reads your `vercel.json` configuration, discovers your queue handlers, and triggers them automatically when messages are sent.
 
+> **Note:** Local dev mode is enabled when `NODE_ENV=development`. Most frameworks (Next.js, etc.) set this automatically when running `npm run dev`.
+
 ### Example Workflow
 
 ```bash
@@ -48,18 +51,6 @@ npm run dev
 # Send messages - they process locally automatically!
 ```
 
-### TypeScript Configuration
-
-Update your `tsconfig.json` to use `"bundler"` module resolution for proper package export resolution:
-
-```json
-{
-  "compilerOptions": {
-    "moduleResolution": "bundler"
-  }
-}
-```
-
 ### Publishing Messages
 
 The `send` function can be used anywhere in your codebase to publish messages to a queue:
@@ -109,126 +100,107 @@ Messages are consumed using API routes that Vercel automatically triggers when m
 
 #### 1. Create API Routes
 
-##### App Router (Recommended)
+##### Web API (`@vercel/queue/web`)
+
+The `handleCallback` from `@vercel/queue/web` returns a standard `(Request) => Promise<Response>` handler. It works with any framework that uses the Web API `Request`/`Response` types, including Next.js App Router, Hono, and others.
 
-The recommended approach is to handle multiple topics and consumers in a single API route to keep your `vercel.json` configuration simple:
+**Next.js App Router:**
 
 ```typescript
-// app/api/queue/route.ts
-import { handleCallback } from "@vercel/queue";
-
-export const POST = handleCallback({
-  // Single topic with one consumer
-  "my-topic": {
-    "my-consumer": async (message, metadata) => {
-      // metadata includes: { messageId, deliveryCount, createdAt, topicName, consumerGroup }
-      console.log("Processing message:", message);
-
-      // If this throws an error, the message will be automatically retried
-      await processMessage(message);
-    },
-  },
+// app/api/queue/my-topic/route.ts
+import { handleCallback } from "@vercel/queue/web";
 
-  // Multiple consumers for different purposes
-  "order-events": {
-    fulfillment: async (order, metadata) => {
-      await processOrder(order);
-    },
-    analytics: async (order, metadata) => {
-      await trackOrder(order);
-    },
-  },
+export const POST = handleCallback(async (message, metadata) => {
+  // metadata includes: { messageId, deliveryCount, createdAt, topicName, consumerGroup }
+  console.log("Processing message:", message);
+
+  // If this throws an error, the message will be automatically retried
+  await processMessage(message);
 });
 ```
 
-While you can split handlers into separate routes if needed (e.g., for code organization or deployment flexibility), consolidating them in one route is recommended for simpler configuration.
+**Hono:**
 
-##### Pages Router
+```typescript
+import { Hono } from "hono";
+import { handleCallback } from "@vercel/queue/web";
+
+const app = new Hono();
+
+app.post(
+  "/api/queue",
+  handleCallback(async (message, metadata) => {
+    console.log("Processing:", message);
+  }),
+);
 
-For Next.js Pages Router, import from `@vercel/queue/nextjs/pages` to get a handler compatible with the Pages Router API (`NextApiRequest`/`NextApiResponse`):
+export default app;
+```
+
+For multiple topics/consumers, create separate route files:
 
 ```typescript
-// pages/api/queue.ts
-import { handleCallback } from "@vercel/queue/nextjs/pages";
+// app/api/queue/orders/fulfillment/route.ts
+import { handleCallback } from "@vercel/queue/web";
 
-export default handleCallback({
-  "my-topic": {
-    "my-consumer": async (message, metadata) => {
-      console.log("Processing message:", message);
-      await processMessage(message);
-    },
-  },
-  "order-events": {
-    fulfillment: async (order, metadata) => {
-      await processOrder(order);
-    },
-    analytics: async (order, metadata) => {
-      await trackOrder(order);
-    },
-  },
+export const POST = handleCallback(async (order, metadata) => {
+  await processOrder(order);
 });
 ```
 
-The `/nextjs/pages` subpath export automatically adapts the handler to work with the Pages Router API.
+```typescript
+// app/api/queue/orders/analytics/route.ts
+import { handleCallback } from "@vercel/queue/web";
 
-#### 2. Configure vercel.json
+export const POST = handleCallback(async (order, metadata) => {
+  await trackOrder(order);
+});
+```
 
-Configure which topics and consumers your API route handles.
+##### Pages Router (`@vercel/queue/nextjs/pages`)
 
-**For App Router:**
+For Next.js Pages Router, import from `@vercel/queue/nextjs/pages`. This returns a `(req, res) => Promise<void>` handler:
 
-```json
-{
-  "functions": {
-    "app/api/queue/route.ts": {
-      "experimentalTriggers": [
-        {
-          "type": "queue/v1beta",
-          "topic": "my-topic",
-          "consumer": "my-consumer",
-          "retryAfterSeconds": 60,
-          "initialDelaySeconds": 0
-        },
-        {
-          "type": "queue/v1beta",
-          "topic": "order-events",
-          "consumer": "fulfillment"
-        },
-        {
-          "type": "queue/v1beta",
-          "topic": "order-events",
-          "consumer": "analytics",
-          "retryAfterSeconds": 300
-        }
-      ]
-    }
-  }
-}
+```typescript
+// pages/api/queue/my-topic.ts
+import { handleCallback } from "@vercel/queue/nextjs/pages";
+
+export default handleCallback(async (message, metadata) => {
+  console.log("Processing message:", message);
+  await processMessage(message);
+});
 ```
 
-**For Pages Router:**
+#### 2. Configure vercel.json
+
+Configure which topics and consumers your API routes handle.
 
 ```json
 {
   "functions": {
-    "pages/api/queue.ts": {
+    "app/api/queue/my-topic/route.ts": {
       "experimentalTriggers": [
         {
-          "type": "queue/v1beta",
+          "type": "queue/v2beta",
           "topic": "my-topic",
-          "consumer": "my-consumer",
           "retryAfterSeconds": 60,
           "initialDelaySeconds": 0
-        },
+        }
+      ]
+    },
+    "app/api/queue/orders/fulfillment/route.ts": {
+      "experimentalTriggers": [
         {
-          "type": "queue/v1beta",
-          "topic": "order-events",
-          "consumer": "fulfillment"
-        },
+          "type": "queue/v2beta",
+          "topic": "order-events"
+        }
+      ]
+    },
+    "app/api/queue/orders/analytics/route.ts": {
+      "experimentalTriggers": [
         {
-          "type": "queue/v1beta",
+          "type": "queue/v2beta",
           "topic": "order-events",
-          "consumer": "analytics",
           "retryAfterSeconds": 300
         }
       ]
@@ -246,47 +218,48 @@ Configure which topics and consumers your API route handles.
 - **Automatic Triggering**: Vercel triggers your API routes when messages are available
 - **Message Processing**: Your API routes receive message metadata via headers
 - **Configuration**: The `vercel.json` file tells Vercel which routes handle which topics/consumers
+- **Delivery Modes**: The server uses CloudEvents binary content mode to deliver messages. For small messages, the full payload and receipt handle are pushed directly in the HTTP body and headers, avoiding an extra API fetch. For large messages, only the message ID is sent and the SDK fetches the payload.
 
 ## Advanced Features
 
-### Client Class
+### Custom Client Configuration
 
-For custom configuration (tokens, headers, etc.), use the `Client` class:
+For custom configuration (tokens, headers, transport), create a `QueueClient` and pass it via options:
 
 ```typescript
-import { Client } from "@vercel/queue";
+import { QueueClient, send } from "@vercel/queue";
+import { handleCallback } from "@vercel/queue/web";
 
-const client = new Client({
-  token: "my-token", // Optional: custom auth token
-  headers: { "X-Custom": "header" }, // Optional: custom headers
-  pinToDeployment: false, // Optional: disable deployment pinning (default: true)
+const client = new QueueClient({
+  token: "my-token",
+  headers: { "X-Custom": "header" },
 });
 
-// Send a message
-await client.send("my-topic", { hello: "world" });
+// Send with custom client
+await send("my-topic", { hello: "world" }, { client });
 
-// Handle callbacks using the same client
-export const POST = client.handleCallback({
-  "my-topic": {
-    "my-group": async (msg, meta) => console.log(msg),
-  },
+// Handle callbacks with custom client
+export const POST = handleCallback(async (msg, meta) => console.log(msg), {
+  client,
 });
 ```
 
-### Parsing Callback Requests
+### Core Handler (Framework Agnostic)
 
-For custom webhook handling, use `parseCallback` to extract queue information from CloudEvent requests:
+For custom framework integration, use the core `handleCallback` from `@vercel/queue`. It takes parsed request data and throws on errors:
 
 ```typescript
-import { parseCallback } from "@vercel/queue";
+import { handleCallback, parseRawCallback } from "@vercel/queue";
 
-export async function POST(request: Request) {
-  const { queueName, consumerGroup, messageId } = await parseCallback(request);
-
-  // Use the parsed information for custom processing...
-  await myWorkflow.handleWebhook(queueName, consumerGroup, messageId);
-
-  return Response.json({ status: "success" });
+// In your framework handler:
+const parsed = parseRawCallback(body, headers);
+try {
+  await handleCallback(async (msg, meta) => {
+    console.log("Processing:", msg);
+  }, parsed);
+  // success
+} catch (error) {
+  // handle error → 500
 }
 ```
 
@@ -332,11 +305,41 @@ await send("json-topic", { data: "example" }, { transport });
 | Large payloads     | StreamTransport       | Very Low     | Medium      |
 | Real-time streams  | StreamTransport       | Very Low     | High        |
 
+## Handling Empty Queues
+
+When no messages are available in the queue, the handler receives `null` for both the message and metadata parameters. This allows graceful handling without exceptions:
+
+```typescript
+await receive("my-topic", "my-consumer", async (message, metadata) => {
+  if (!message) {
+    console.log("No message received - queue is empty");
+    return;
+  }
+
+  // Process the message
+  console.log("Processing:", message);
+  console.log("Message ID:", metadata.messageId);
+});
+```
+
+The same pattern works with `handleCallback`:
+
+```typescript
+import { handleCallback } from "@vercel/queue/web";
+
+export const POST = handleCallback(async (message, metadata) => {
+  if (!message) {
+    // No message available - handle gracefully
+    return;
+  }
+  await processMessage(message);
+});
+```
+
 ## Error Handling
 
 The queue client provides specific error types:
 
-- **`QueueEmptyError`**: No messages available in the queue
 - **`MessageLockedError`**: Message is being processed by another consumer
 - **`MessageNotFoundError`**: Message doesn't exist or has expired
 - **`MessageNotAvailableError`**: Message exists but cannot be claimed
@@ -399,26 +402,32 @@ The following environment variables can be used to configure the queue client:
 ```typescript
 import { receive } from "@vercel/queue";
 
-// Process next available message
-await receive<T>(topicName, consumerGroup, handler);
+// Process next available message (or null if queue is empty)
+await receive<T>(topicName, consumerGroup, async (message, metadata) => {
+  if (!message) {
+    console.log("Queue is empty");
+    return;
+  }
+  // Process message
+});
 
-// Process specific message by ID
+// Batch processing: fetch up to 10 messages in one request
 await receive<T>(topicName, consumerGroup, handler, {
-  messageId: "message-id",
+  limit: 10, // Default: 1, Min: 1, Max: 10
 });
 
-// Process message with options
+// Process specific message by ID
 await receive<T>(topicName, consumerGroup, handler, {
-  messageId: "message-id", // Optional: process specific message by ID
-  transport: new JsonTransport(), // Optional: custom transport (defaults to JsonTransport)
-  visibilityTimeoutSeconds: 30, // Optional: message visibility timeout
-  visibilityRefreshInterval: 10, // Optional: how often to refresh the lock
+  messageId: "message-id",
 });
 
+// Note: limit and messageId are mutually exclusive options
+
 // Handler function signature
+// When queue is empty, both message and metadata are null
 type MessageHandler<T = unknown> = (
-  message: T,
-  metadata: MessageMetadata,
+  message: T | null,
+  metadata: MessageMetadata | null,
 ) => Promise<void> | void;
 
 // MessageMetadata type
@@ -437,7 +446,7 @@ interface MessageMetadata {
 
 | Limit                       | Value                 | Notes                               |
 | --------------------------- | --------------------- | ----------------------------------- |
-| Message throughput          | 10,000s msg/sec/topic | Scales horizontally                 |
+| Message throughput          | 10,000+ msg/sec/topic | Scales horizontally                 |
 | Payload size                | 1 GB                  | Smaller messages have lower latency |
 | Number of topics            | Unlimited             | No hard limit                       |
 | Consumer groups per message | ~4,000                | Per-message limit                   |
@@ -495,9 +504,8 @@ Topic patterns support wildcards for flexible routing:
     "app/api/queue/route.ts": {
       "experimentalTriggers": [
         {
-          "type": "queue/v1beta",
-          "topic": "user-*",
-          "consumer": "processor"
+          "type": "queue/v2beta",
+          "topic": "user-*"
         }
       ]
     }
@@ -514,12 +522,28 @@ Topic patterns support wildcards for flexible routing:
 
 ## API Reference
 
-### Client Configuration
+### Export Structure
+
+| Import Path                  | `handleCallback`                                                 |
+| ---------------------------- | ---------------------------------------------------------------- |
+| `@vercel/queue`              | Core async function: `(handler, parsed, opts?) => Promise<void>` |
+| `@vercel/queue/web`          | Returns `(request: Request) => Promise<Response>`                |
+| `@vercel/queue/nextjs/pages` | Returns `(req, res) => Promise<void>`                            |
+
+Additional exports from `@vercel/queue`:
+
+| Export                    | Description                                                   |
+| ------------------------- | ------------------------------------------------------------- |
+| `parseCallback`           | Parse a Web API `Request` into a `ParsedCallbackRequest`      |
+| `parseRawCallback`        | Parse a pre-parsed body + headers (e.g. Pages Router)         |
+| `CLOUD_EVENT_TYPE_V2BETA` | `"com.vercel.queue.v2beta"` — binary CloudEvent type constant |
+
+### QueueClient Configuration
 
 ```typescript
-import { Client } from "@vercel/queue";
+import { QueueClient } from "@vercel/queue";
 
-const client = new Client({
+const client = new QueueClient({
   // Base URL for the queue service
   // Default: "https://vercel-queue.com"
   // Env: VERCEL_QUEUE_BASE_URL
@@ -544,6 +568,10 @@ const client = new Client({
   // Default: true
   pinToDeployment: true,
 });
+
+// Pass to any function via options
+await send("my-topic", payload, { client });
+export const POST = handleCallback(handler, { client });
 ```
 
 ### Send Options
@@ -569,62 +597,70 @@ await send("my-topic", payload, {
 
 ### Receive Options
 
+The `receive` function supports two mutually exclusive modes:
+
 ```typescript
+// Batch mode: receive multiple messages
 await receive("my-topic", "my-consumer", handler, {
-  // Specific message ID to consume (optional)
-  messageId: "0-1",
+  // Maximum messages to retrieve in a single request
+  // Default: 1, Min: 1, Max: 10
+  limit: 10,
 
   // Message lock duration in seconds
-  // Default: 30, Min: 0, Max: 3600
+  // Default: 300, Min: 30, Max: 3600
   visibilityTimeoutSeconds: 60,
-
-  // How often to refresh the lock during processing
-  // Default: visibilityTimeoutSeconds / 3
-  visibilityRefreshInterval: 15,
-
-  // Custom deserializer (default: JsonTransport)
-  transport: new JsonTransport(),
 });
-```
 
-### Receive Options (Advanced)
-
-```typescript
+// By-ID mode: receive a specific message
 await receive("my-topic", "my-consumer", handler, {
-  // Payload deserializer
-  // Default: JsonTransport
-  transport: new JsonTransport(),
+  // Specific message ID to consume
+  messageId: "0-1",
 
-  // Message lock duration
-  // Default: 30, Min: 0, Max: 3600
+  // Message lock duration in seconds
+  // Default: 300, Min: 30, Max: 3600
   visibilityTimeoutSeconds: 60,
-
-  // How often to refresh the lock during processing
-  // Default: visibilityTimeoutSeconds / 3
-  visibilityRefreshInterval: 20,
 });
 ```
 
+> **Note**: `limit` and `messageId` cannot be used together - they are mutually exclusive options.
+
 ### handleCallback Options
 
 ```typescript
+import { handleCallback } from "@vercel/queue/web";
+
 export const POST = handleCallback(
-  {
-    "my-topic": {
-      "my-consumer": async (message, metadata) => {
-        await processMessage(message);
-      },
-    },
+  async (message, metadata) => {
+    await processMessage(message);
   },
   {
     // Message lock duration for long-running handlers
-    // Default: 30, Min: 0, Max: 3600
-    // visibilityRefreshInterval defaults to visibilityTimeoutSeconds / 3
+    // Default: 300, Min: 30, Max: 3600
     visibilityTimeoutSeconds: 300, // 5 minutes
   },
 );
 ```
 
+### Core handleCallback
+
+The core `handleCallback` is an async function that takes already-parsed request data. Use it to build custom framework integrations:
+
+```typescript
+import { handleCallback, parseCallback, parseRawCallback } from "@vercel/queue";
+
+// Web API Request
+const parsed = await parseCallback(request);
+
+// Or, for frameworks that pre-parse the body (e.g. Pages Router)
+const parsed = parseRawCallback(req.body, req.headers);
+
+try {
+  await handleCallback(handler, parsed);
+} catch (error) {
+  // handle error → 500
+}
+```
+
 ## License
 
 MIT