@vercel/queue 0.0.0-alpha.6 → 0.0.0-alpha.8

package/README.md

@@ -46,8 +46,7 @@ type Message = {
   timestamp: number;
 };
 
-// Option 1: Using the send and receive helpers (simplest)
-// Automatically uses default client and JSON transport
+// Send a message to a topic
 await send<Message>("my-topic", {
   message: "Hello, World!",
   timestamp: Date.now(),
@@ -55,38 +54,12 @@ await send<Message>("my-topic", {
 
 // 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);
+await receive<Message>("my-topic", "my-consumer-group", (message, metadata) => {
+  console.log("Received:", message.message);
+  console.log("Timestamp:", new Date(message.timestamp));
+  console.log("Message Metadata", metadata);
+  // => { messageId, deliveryCount, timestamp }
 });
-
-// Option 2: Using createTopic for more control
-
-import { createTopic } from "@vercel/queue";
-
-// Create a topic with JSON serialization (default)
-// Uses default QueueClient automatically authenticated from Vercel environment
-const topic = createTopic<Message>("my-topic");
-
-// Publish a message
-await topic.publish({
-  message: "Hello, World!",
-  timestamp: Date.now(),
-});
-
-// Create a consumer group
-const consumer = topic.consumerGroup("my-consumer-group");
-
-// Process next available message (one-shot processing)
-try {
-  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 error:", error);
-}
 ```
 
 ## Usage with Vercel
@@ -124,31 +97,13 @@ Create a new server function to publish messages
 import { send } from "@vercel/queue";
 
 export async function publishTestMessage(message: string) {
-  // Option 1: Using simple send shorthand
-  const { messageId } = await send(
-    "my-topic",
-    { message, timestamp: Date.now() },
-    },
-  );
-
-  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() },
-  );
+  const { messageId } = await send("my-topic", {
+    message,
+    timestamp: Date.now(),
+  });
 
   console.log(`Published message ${messageId}`);
 }
-
 ```
 
 Now wire up the server function to your app
@@ -330,14 +285,15 @@ Multiple consumers can process messages from the same topic in parallel:
 
 ```typescript
 // Multiple workers in the same group - they share/split messages
-const worker1 = topic.consumerGroup("workers");
-const worker2 = topic.consumerGroup("workers"); // Same group name
-// worker1 and worker2 will receive different messages (load balancing)
+// Using the same consumer group name means they will load balance messages
+await receive("my-topic", "workers", handler1);
+await receive("my-topic", "workers", handler2);
+// handler1 and handler2 will receive different messages (load balancing)
 
 // Different consumer groups - each gets copies of ALL messages
-const analytics = topic.consumerGroup("analytics");
-const webhooks = topic.consumerGroup("webhooks");
-// analytics and webhooks will both receive every message
+await receive("my-topic", "analytics", analyticsHandler);
+await receive("my-topic", "webhooks", webhooksHandler);
+// analyticsHandler and webhooksHandler will both receive every message
 ```
 
 ## Architecture
@@ -345,8 +301,8 @@ const webhooks = topic.consumerGroup("webhooks");
 - **Topics**: Named message channels with configurable serialization
 - **Consumer Groups**: Named groups of consumers that process messages in
   parallel
-  - `consume()`: Process messages with flexible consumption patterns
-    - No options: Process next available message
+  - `receive()`: Process messages with flexible consumption patterns
+    - Basic usage: 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
@@ -368,8 +324,7 @@ The multipart parser is optimized for high-throughput scenarios:
 
 The queue client supports customizable serialization through the `Transport`
 interface with **streaming support** for memory-efficient processing. Transport
-can be configured at the **topic level** when creating a topic, or at the
-**consumer group level** when creating a consumer group.
+can be configured using the `transport` option when calling `send()` or `receive()`.
 
 ### Built-in Transports
 
@@ -379,11 +334,15 @@ Buffers data for JSON parsing - suitable for structured data that fits in
 memory.
 
 ```typescript
-import { createTopic, JsonTransport } from "@vercel/queue";
-
-const topic = createTopic<{ data: any }>("json-topic", new JsonTransport());
-// or simply (JsonTransport is the default):
-const topic = createTopic<{ data: any }>("json-topic");
+import { send, JsonTransport } from "@vercel/queue";
+
+// JsonTransport is the default, so these are equivalent:
+await send("json-topic", { data: "example" });
+await send(
+  "json-topic",
+  { data: "example" },
+  { transport: new JsonTransport() },
+);
 ```
 
 #### BufferTransport
@@ -413,37 +372,7 @@ interface.
 
 ## API Reference
 
-### QueueClient
-
-```typescript
-// Simple usage - automatically gets OIDC token from Vercel environment
-const client = new QueueClient();
-
-// Or with options
-const client = new QueueClient({
-  token?: string; // Optional - will auto-detect if not provided
-  baseUrl?: string; // defaults to 'https://vqs.vercel.sh'
-});
-```
-
-### Topic
-
-```typescript
-// 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?);
-
-// Create a consumer group (can override transport)
-const consumer = topic.consumerGroup<U>(groupName, options?);
-```
-
-### Send (Shorthand)
+### Send Function
 
 ```typescript
 // Simple send - automatically uses default client and JSON transport
@@ -469,18 +398,23 @@ await send("events", eventData, {
 });
 ```
 
-### ConsumerGroup
+### Receive Function
 
 ```typescript
 // Process next available message (simplest form)
-await consumer.consume(handler);
+await receive("topic-name", "consumer-group", handler);
 
 // Process specific message by ID with payload
-await consumer.consume(handler, { messageId: "message-id" });
+await receive("topic-name", "consumer-group", 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 });
+await receive("topic-name", "consumer-group", handler, {
+  messageId: "message-id",
+  skipPayload: true,
+});
 ```
 
 ### Message Handler
@@ -507,12 +441,16 @@ interface MessageMetadata {
 }
 ```
 
-### ConsumeOptions Interface
+### Receive Options
 
 ```typescript
-interface ConsumeOptions {
+// Options for the receive function
+interface ReceiveOptions<T = unknown> {
   messageId?: string; // Process specific message by ID
   skipPayload?: boolean; // Skip payload download (requires messageId)
+  transport?: Transport<T>; // Custom transport (defaults to JsonTransport)
+  visibilityTimeoutSeconds?: number; // Message visibility timeout
+  refreshInterval?: number; // Refresh interval for long-running operations
 }
 ```
 
@@ -566,27 +504,16 @@ interface UserEvent {
   timestamp: number;
 }
 
-// Option 1: Using send shorthand
+// Send a message
 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",
-  action: "login",
-  timestamp: Date.now(),
-});
-
-const consumer = userTopic.consumerGroup("processors");
-
-// Process next available message
+// Receive and process a message
 try {
-  await consumer.consume(async (message) => {
+  await receive<UserEvent>("user-events", "processors", async (message) => {
     console.log(`User ${message.userId} performed ${message.action}`);
   });
 } catch (error) {
@@ -597,16 +524,13 @@ try {
 ### Processing Specific Messages by ID
 
 ```typescript
-const userTopic = createTopic<{ userId: string; action: string }>(
-  "user-events",
-);
-const consumer = userTopic.consumerGroup("processors");
-
 // Process a specific message if you know its ID
 const messageId = "01234567-89ab-cdef-0123-456789abcdef";
 
 try {
-  await consumer.consume(
+  await receive<{ userId: string; action: string }>(
+    "user-events",
+    "processors",
     async (message, { messageId }) => {
       console.log(`Processing specific message: ${messageId}`);
       console.log(`User ${message.userId} performed ${message.action}`);
@@ -626,15 +550,16 @@ try {
 ### Processing Next Available Message
 
 ```typescript
-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.consume(async (message) => {
-    console.log(`Processing task: ${message.taskType}`);
-    await processTask(message.taskType, message.data);
-  });
+  await receive<{ taskType: string; data: any }>(
+    "work-queue",
+    "workers",
+    async (message) => {
+      console.log(`Processing task: ${message.taskType}`);
+      await processTask(message.taskType, message.data);
+    },
+  );
   console.log("Message processed successfully");
 } catch (error) {
   if (error instanceof QueueEmptyError) {
@@ -650,17 +575,23 @@ try {
 }
 
 // Handle conditional timeouts
-await worker.consume(async (message) => {
-  if (!canProcessTaskType(message.taskType)) {
-    // Return timeout to retry later
-    return { timeoutSeconds: 60 };
-  }
+await receive<{ taskType: string; data: any }>(
+  "work-queue",
+  "workers",
+  async (message) => {
+    if (!canProcessTaskType(message.taskType)) {
+      // Return timeout to retry later
+      return { timeoutSeconds: 60 };
+    }
 
-  await processTask(message.taskType, message.data);
-});
+    await processTask(message.taskType, message.data);
+  },
+);
 
 // Process specific message metadata only (no payload download)
-await worker.consume(
+await receive<{ taskType: string; data: any }>(
+  "work-queue",
+  "workers",
   async (_, metadata) => {
     console.log(`Message ID: ${metadata.messageId}`);
     console.log(`Delivery count: ${metadata.deliveryCount}`);
@@ -674,56 +605,64 @@ await worker.consume(
 ### Timing Out Messages
 
 ```typescript
-const workTopic = createTopic<{ taskType: string; data: any }>("work-queue");
-const worker = workTopic.consumerGroup("workers");
-
 // Process a message with conditional timeout
 try {
-  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)
-      return { timeoutSeconds: 300 };
-    }
+  await receive<{ taskType: string; data: any }>(
+    "work-queue",
+    "workers",
+    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)
+        return { timeoutSeconds: 300 };
+      }
 
-    // Check if we have required resources
-    if (taskType === "external-api" && !isExternalServiceAvailable()) {
-      // Return timeout to retry in 1 minute
-      return { timeoutSeconds: 60 };
-    }
+      // Check if we have required resources
+      if (taskType === "external-api" && !isExternalServiceAvailable()) {
+        // Return timeout to retry in 1 minute
+        return { timeoutSeconds: 60 };
+      }
 
-    // Process the message normally
-    console.log(`Processing ${taskType} task`);
-    await processTask(taskType, data);
-    // Message will be automatically deleted on successful completion
-  });
+      // Process the message normally
+      console.log(`Processing ${taskType} task`);
+      await processTask(taskType, data);
+      // Message will be automatically deleted on successful completion
+    },
+  );
 } catch (error) {
   console.error("Worker processing error:", error);
 }
 
 // Example with exponential backoff
 try {
-  await worker.consume(async (message, { deliveryCount }) => {
-    const maxRetries = 3;
-
-    try {
-      await processMessage(message);
-      // Successful processing - message will be deleted
-    } catch (error) {
-      if (deliveryCount < maxRetries) {
-        // Exponential backoff: 2^deliveryCount minutes
-        const timeoutSeconds = Math.pow(2, deliveryCount) * 60;
-        console.log(
-          `Retrying message in ${timeoutSeconds} seconds (attempt ${deliveryCount})`,
-        );
-        return { timeoutSeconds: timeoutSeconds };
-      } else {
-        // Max retries reached, let the message fail and be deleted
-        console.error("Max retries reached, message will be discarded:", error);
-        throw error;
+  await receive<{ taskType: string; data: any }>(
+    "work-queue",
+    "workers",
+    async (message, { deliveryCount }) => {
+      const maxRetries = 3;
+
+      try {
+        await processMessage(message);
+        // Successful processing - message will be deleted
+      } catch (error) {
+        if (deliveryCount < maxRetries) {
+          // Exponential backoff: 2^deliveryCount minutes
+          const timeoutSeconds = Math.pow(2, deliveryCount) * 60;
+          console.log(
+            `Retrying message in ${timeoutSeconds} seconds (attempt ${deliveryCount})`,
+          );
+          return { timeoutSeconds: timeoutSeconds };
+        } else {
+          // Max retries reached, let the message fail and be deleted
+          console.error(
+            "Max retries reached, message will be discarded:",
+            error,
+          );
+          throw error;
+        }
       }
-    }
-  });
+    },
+  );
 } catch (error) {
   console.error("Backoff processing error:", error);
 }
@@ -738,15 +677,14 @@ The queue client provides specific error types for different failure scenarios:
 - **`QueueEmptyError`**: Thrown when attempting to receive messages from an
   empty queue (204 status)
 
-  - Thrown by `consume()` when no messages are available
-  - Also thrown when directly using `client.receiveMessages()`
+  - Thrown by `receive()` when no messages are available
 
 - **`MessageLockedError`**: Thrown when a message is temporarily locked (423
   status)
 
   - Contains optional `retryAfter` property with seconds to wait before retry
-  - For `consume()` without options: the next message is locked
-  - For `consume()` with messageId: the requested message is locked
+  - For `receive()` without options: the next message is locked
+  - For `receive()` with messageId: the requested message is locked
 
 - **`MessageNotFoundError`**: Message doesn't exist (404 status)
 
@@ -775,7 +713,6 @@ The queue client provides specific error types for different failure scenarios:
 ```typescript
 import {
   BadRequestError,
-
   ForbiddenError,
   InternalServerError,
   MessageLockedError,
@@ -785,9 +722,10 @@ import {
 
 // Handle empty queue or locked messages
 try {
-  for await (const message of client.receiveMessages(options, transport)) {
-    // Process messages
-  }
+  await receive("my-topic", "my-consumer", async (message) => {
+    // Process message
+    console.log("Processing message:", message);
+  });
 } catch (error) {
   if (error instanceof QueueEmptyError) {
     console.log("Queue is empty, retry later");
@@ -801,7 +739,7 @@ try {
 
 // Handle locked message with retry
 try {
-  await consumer.consume(handler, { messageId });
+  await receive("my-topic", "my-consumer", handler, { messageId });
 } catch (error) {
   if (error instanceof MessageLockedError) {
     console.log("Message is locked by another consumer");
@@ -809,12 +747,12 @@ try {
       console.log(`Retry after ${error.retryAfter} seconds`);
       setTimeout(() => retry(), error.retryAfter * 1000);
     }
-
+  }
 }
 
 // Handle authentication and authorization errors
 try {
-  await topic.publish(payload);
+  await send("my-topic", payload);
 } catch (error) {
   if (error instanceof UnauthorizedError) {
     console.log("Invalid token - refresh authentication");