@vercel/queue 0.0.2 → 0.1.0

package/dist/index.d.ts

@@ -37,12 +37,11 @@ interface Transport<T = unknown> {
  * @example
  * ```typescript
  * // Default (JsonTransport is used automatically)
- * const queue = new QueueClient({ region: process.env.QUEUE_REGION! });
+ * const queue = new QueueClient();
  * await queue.send("topic", { data: "example" });
  *
  * // With custom serialization
  * const queue = new QueueClient({
- *   region: process.env.QUEUE_REGION!,
  *   transport: new JsonTransport({
  *     replacer: (key, value) => key === "password" ? undefined : value,
  *     reviver: (key, value) => key === "date" ? new Date(value) : value,
@@ -75,7 +74,7 @@ declare class JsonTransport<T = unknown> implements Transport<T> {
  *
  * @example
  * ```typescript
- * const queue = new QueueClient({ region: "iad1", transport: new BufferTransport() });
+ * const queue = new QueueClient({ transport: new BufferTransport() });
  * await queue.send("binary-topic", myBuffer);
  * ```
  */
@@ -95,13 +94,13 @@ declare class BufferTransport implements Transport<Buffer> {
  *
  * @example
  * ```typescript
- * const queue = new QueueClient({ region: "iad1", transport: new StreamTransport() });
- *
  * // Sending a stream
+ * const queue = new QueueClient({ transport: new StreamTransport() });
  * await queue.send("large-file", myReadableStream);
  *
  * // Receiving - cleanup handled automatically
- * await queue.receive("large-file", "processor", async (stream, meta) => {
+ * const poller = new PollingQueueClient({ region: "iad1", transport: new StreamTransport() });
+ * await poller.receive("large-file", "processor", async (stream, meta) => {
  *   const reader = stream.getReader();
  *   // Process chunks...
  * });
@@ -155,15 +154,17 @@ interface QueueClientOptions {
      * Requests are sent to the regional endpoint resolved by
      * {@link BaseUrlResolver} (default: `https://${region}.vercel-queue.com`).
      *
-     * Use a `QUEUE_REGION` env var set to `${VERCEL_REGION}` in production
-     * and a fixed region (e.g. `"iad1"`) in development.
+     * When omitted, the region is auto-detected from the `VERCEL_REGION`
+     * environment variable (set automatically on Vercel). If not available,
+     * defaults to `"iad1"` with a console warning.
      *
      * @example
      * ```ts
-     * new QueueClient({ region: process.env.QUEUE_REGION! })
+     * new QueueClient()                         // auto-detect, falls back to "iad1"
+     * new QueueClient({ region: "iad1" })       // explicit
      * ```
      */
-    region: VercelRegion;
+    region?: VercelRegion;
     /**
      * Custom resolver that maps a region code to a base {@link URL}.
      *
@@ -205,6 +206,28 @@ interface QueueClientOptions {
      */
     transport?: Transport;
 }
+/**
+ * Options for creating a {@link PollingQueueClient}.
+ *
+ * Identical to {@link QueueClientOptions} except `region` is **required**
+ * because messages can only be received from the region they were sent to.
+ * Using a fixed region (e.g. `"iad1"`) ensures that `send` and `receive`
+ * target the same endpoint.
+ */
+interface PollingQueueClientOptions extends QueueClientOptions {
+    /**
+     * Vercel region code for API routing — **required** for polling.
+     *
+     * Messages can only be received from the region they were sent to.
+     * Use a fixed region (e.g. `"iad1"`) for both sending and receiving.
+     *
+     * @example
+     * ```ts
+     * new PollingQueueClient({ region: "iad1" })
+     * ```
+     */
+    region: VercelRegion;
+}
 /**
  * Options for sending messages.
  */
@@ -496,14 +519,37 @@ declare class ConsumerRegistryNotConfiguredError extends Error {
     constructor(message?: string);
 }
 
+/**
+ * Queue client for push-based (callback) workflows.
+ *
+ * Use this client when Vercel delivers messages to your route handlers.
+ * Provides {@link send}, {@link handleCallback}, and {@link handleNodeCallback}.
+ *
+ * Region is resolved automatically:
+ * 1. Explicit `region` option (highest priority)
+ * 2. `VERCEL_REGION` environment variable (set automatically on Vercel)
+ * 3. Falls back to `"iad1"` with a console warning
+ *
+ * The constructor never throws — `new QueueClient()` always works.
+ *
+ * For manual polling workflows, use {@link PollingQueueClient} instead.
+ *
+ * @example
+ * ```typescript
+ * import { QueueClient } from "@vercel/queue";
+ *
+ * const queue = new QueueClient();
+ * export const { send, handleCallback, handleNodeCallback } = queue;
+ * ```
+ */
 declare class QueueClient {
-    constructor(options: QueueClientOptions);
+    constructor(options?: QueueClientOptions);
     /**
      * Send a message to a topic.
      *
      * This is an arrow function property so it can be destructured:
      * ```typescript
-     * const { send } = new QueueClient({ region: process.env.QUEUE_REGION! });
+     * const { send } = new QueueClient();
      * await send("my-topic", payload);
      * ```
      *
@@ -514,28 +560,6 @@ declare class QueueClient {
      *   the message for deferred processing (no ID available yet)
      */
     send: <T = unknown>(topicName: string, payload: T, options?: SendOptions) => Promise<SendResult>;
-    /**
-     * Receive and process messages from a topic.
-     *
-     * Each message is automatically locked, kept alive via periodic visibility
-     * extensions during processing, and acknowledged upon successful handler completion.
-     * The handler is not called when the queue is empty — check `result.ok` instead.
-     *
-     * This is an arrow function property so it can be destructured:
-     * ```typescript
-     * const { receive } = new QueueClient({ region: process.env.QUEUE_REGION! });
-     * const result = await receive("my-topic", "my-group", handler);
-     * if (!result.ok) console.log(result.reason);
-     * ```
-     *
-     * @param topicName - Name of the topic (pattern: `[A-Za-z0-9_-]+`)
-     * @param consumerGroup - Name of the consumer group (pattern: `[A-Za-z0-9_-]+`)
-     * @param handler - Function to process each message payload and metadata.
-     *                  Not called when the queue is empty.
-     * @param options - Optional receive options (visibilityTimeoutSeconds, limit, or messageId)
-     * @returns Discriminated result: `{ ok: true }` on success, `{ ok: false, reason }` otherwise
-     */
-    receive: <T = unknown>(topicName: string, consumerGroup: string, handler: MessageHandler<T>, options?: ReceiveOptions) => Promise<ReceiveResult>;
     /**
      * Create a Web API route handler for processing queue callback messages.
      *
@@ -544,7 +568,7 @@ declare class QueueClient {
      *
      * This is an arrow function property so it can be destructured:
      * ```typescript
-     * const { handleCallback } = new QueueClient({ region: process.env.QUEUE_REGION! });
+     * const { handleCallback } = new QueueClient();
      * export const POST = handleCallback(handler);
      * ```
      *
@@ -568,7 +592,7 @@ declare class QueueClient {
      *
      * This is an arrow function property so it can be destructured:
      * ```typescript
-     * const { handleNodeCallback } = new QueueClient({ region: process.env.QUEUE_REGION! });
+     * const { handleNodeCallback } = new QueueClient();
      * app.post("/api/queue", handleNodeCallback(handler));
      * ```
      *
@@ -594,6 +618,67 @@ declare class QueueClient {
         end(): void;
     }) => Promise<void>);
 }
+/**
+ * Queue client for poll-based (manual receive) workflows.
+ *
+ * Use this client when you manually poll for messages with {@link receive}.
+ * Also provides {@link send} for publishing messages.
+ *
+ * Region is **required** because messages can only be received from the
+ * region they were sent to. Use a fixed region (e.g. `"iad1"`) for both
+ * sending and receiving.
+ *
+ * For push-based (callback) workflows on Vercel, use {@link QueueClient} instead.
+ *
+ * @example
+ * ```typescript
+ * import { PollingQueueClient } from "@vercel/queue";
+ *
+ * const queue = new PollingQueueClient({ region: "iad1" });
+ * export const { send, receive } = queue;
+ * ```
+ */
+declare class PollingQueueClient {
+    constructor(options: PollingQueueClientOptions);
+    /**
+     * Send a message to a topic.
+     *
+     * This is an arrow function property so it can be destructured:
+     * ```typescript
+     * const { send } = new PollingQueueClient({ region: "iad1" });
+     * await send("my-topic", payload);
+     * ```
+     *
+     * @param topicName - Name of the topic (pattern: `[A-Za-z0-9_-]+`)
+     * @param payload - The data to send (serialized via the configured transport)
+     * @param options - Optional send options (idempotencyKey, retentionSeconds, delaySeconds, headers)
+     * @returns `{ messageId }` — `messageId` is `null` when the server accepted
+     *   the message for deferred processing (no ID available yet)
+     */
+    send: <T = unknown>(topicName: string, payload: T, options?: SendOptions) => Promise<SendResult>;
+    /**
+     * Receive and process messages from a topic.
+     *
+     * Each message is automatically locked, kept alive via periodic visibility
+     * extensions during processing, and acknowledged upon successful handler completion.
+     * The handler is not called when the queue is empty — check `result.ok` instead.
+     *
+     * This is an arrow function property so it can be destructured:
+     * ```typescript
+     * const { receive } = new PollingQueueClient({ region: "iad1" });
+     * const result = await receive("my-topic", "my-group", handler);
+     * if (!result.ok) console.log(result.reason);
+     * ```
+     *
+     * @param topicName - Name of the topic (pattern: `[A-Za-z0-9_-]+`)
+     * @param consumerGroup - Name of the consumer group (pattern: `[A-Za-z0-9_-]+`)
+     * @param handler - Function to process each message payload and metadata.
+     *                  Not called when the queue is empty.
+     * @param options - Optional receive options (visibilityTimeoutSeconds, limit, or messageId)
+     * @returns Discriminated result: `{ ok: true }` on success, `{ ok: false, reason }` otherwise
+     */
+    receive: <T = unknown>(topicName: string, consumerGroup: string, handler: MessageHandler<T>, options?: ReceiveOptions) => Promise<ReceiveResult>;
+}
 
 /**
  * Core queue callback utilities for handling incoming webhook payloads
@@ -668,4 +753,4 @@ declare function parseRawCallback(body: unknown, headers: Record<string, string
  */
 declare function parseCallback(request: Request): Promise<ParsedCallbackRequest>;
 
-export { BadRequestError, type BaseUrlResolver, BufferTransport, CLOUD_EVENT_TYPE_V1BETA, CLOUD_EVENT_TYPE_V2BETA, ConsumerDiscoveryError, ConsumerRegistryNotConfiguredError, DuplicateMessageError, ForbiddenError, InternalServerError, InvalidLimitError, JsonTransport, type Message, MessageAlreadyProcessedError, MessageCorruptedError, type MessageHandler, MessageLockedError, type MessageMetadata, MessageNotAvailableError, MessageNotFoundError, type ParsedCallbackRequest, type ParsedCallbackV1, type ParsedCallbackV2, QueueClient, type QueueClientOptions, QueueEmptyError, type ReceiveBatchOptions, type ReceiveByIdOptions, type ReceiveOptions, type ReceiveResult, type RetryDirective, type RetryHandler, type SendOptions, type SendResult, StreamTransport, type Transport, UnauthorizedError, type VercelRegion, parseCallback, parseRawCallback };
+export { BadRequestError, type BaseUrlResolver, BufferTransport, CLOUD_EVENT_TYPE_V1BETA, CLOUD_EVENT_TYPE_V2BETA, ConsumerDiscoveryError, ConsumerRegistryNotConfiguredError, DuplicateMessageError, ForbiddenError, InternalServerError, InvalidLimitError, JsonTransport, type Message, MessageAlreadyProcessedError, MessageCorruptedError, type MessageHandler, MessageLockedError, type MessageMetadata, MessageNotAvailableError, MessageNotFoundError, type ParsedCallbackRequest, type ParsedCallbackV1, type ParsedCallbackV2, PollingQueueClient, type PollingQueueClientOptions, QueueClient, type QueueClientOptions, QueueEmptyError, type ReceiveBatchOptions, type ReceiveByIdOptions, type ReceiveOptions, type ReceiveResult, type RetryDirective, type RetryHandler, type SendOptions, type SendResult, StreamTransport, type Transport, UnauthorizedError, type VercelRegion, parseCallback, parseRawCallback };

package/dist/index.js

@@ -46,6 +46,7 @@ __export(index_exports, {
   MessageLockedError: () => MessageLockedError,
   MessageNotAvailableError: () => MessageNotAvailableError,
   MessageNotFoundError: () => MessageNotFoundError,
+  PollingQueueClient: () => PollingQueueClient,
   QueueClient: () => QueueClient,
   QueueEmptyError: () => QueueEmptyError,
   StreamTransport: () => StreamTransport,
@@ -1079,7 +1080,7 @@ var ApiClient = class _ApiClient {
       return;
     }
     throw new Error(
-      'No deployment ID available. VERCEL_DEPLOYMENT_ID is not set.\n\nThis usually means the code is running outside a Vercel deployment (e.g. during build or in a non-Vercel environment).\n\nTo fix this, create a new QueueClient with an explicit deploymentId:\n  new QueueClient({ region: "iad1", deploymentId: "dpl_xxx" })\nOr explicitly opt out of deployment pinning:\n  new QueueClient({ region: "iad1", deploymentId: null })'
+      'No deployment ID available. VERCEL_DEPLOYMENT_ID is not set.\n\nThis usually means the code is running outside a Vercel deployment (e.g. during build or in a non-Vercel environment).\n\nTo fix this, create a client with an explicit deploymentId:\n  new QueueClient({ deploymentId: "dpl_xxx" })\nOr explicitly opt out of deployment pinning:\n  new QueueClient({ deploymentId: null })'
     );
   }
   getSendDeploymentId() {
@@ -1137,7 +1138,7 @@ var ApiClient = class _ApiClient {
       }
       console.debug("[VQS Debug] Request:", JSON.stringify(logData, null, 2));
     }
-    init.headers.set("User-Agent", `@vercel/queue/${"0.0.2"}`);
+    init.headers.set("User-Agent", `@vercel/queue/${"0.1.0"}`);
     init.headers.set("Vqs-Client-Ts", (/* @__PURE__ */ new Date()).toISOString());
     const response = await fetch(url, init);
     if (isDebugEnabled()) {
@@ -1473,23 +1474,37 @@ var ApiClient = class _ApiClient {
 
 // src/client.ts
 var apiClients = /* @__PURE__ */ new WeakMap();
-function getApiClient(client) {
+function getApi(client) {
   const api = apiClients.get(client);
   if (!api) {
-    throw new Error("QueueClient not initialized");
+    throw new Error("Client not initialized");
   }
   return api;
 }
+function getApiClient(client) {
+  return getApi(client);
+}
+var DEFAULT_REGION = "iad1";
+function resolveRegion(region) {
+  if (region) return region;
+  const fromEnv = process.env.VERCEL_REGION;
+  if (fromEnv) return fromEnv;
+  console.warn(
+    `[QueueClient] Region not detected \u2014 defaulting to "${DEFAULT_REGION}". On Vercel this is set automatically via VERCEL_REGION. To silence this warning, pass region explicitly: new QueueClient({ region: "iad1" })`
+  );
+  return DEFAULT_REGION;
+}
 var QueueClient = class {
-  constructor(options) {
-    apiClients.set(this, new ApiClient(options));
+  constructor(options = {}) {
+    const region = resolveRegion(options.region);
+    apiClients.set(this, new ApiClient({ ...options, region }));
   }
   /**
    * Send a message to a topic.
    *
    * This is an arrow function property so it can be destructured:
    * ```typescript
-   * const { send } = new QueueClient({ region: process.env.QUEUE_REGION! });
+   * const { send } = new QueueClient();
    * await send("my-topic", payload);
    * ```
    *
@@ -1500,7 +1515,7 @@ var QueueClient = class {
    *   the message for deferred processing (no ID available yet)
    */
   send = async (topicName, payload, options) => {
-    const api = getApiClient(this);
+    const api = getApi(this);
     const result = await api.sendMessage({
       queueName: topicName,
       payload,
@@ -1519,75 +1534,6 @@ var QueueClient = class {
     }
     return { messageId: result.messageId };
   };
-  /**
-   * Receive and process messages from a topic.
-   *
-   * Each message is automatically locked, kept alive via periodic visibility
-   * extensions during processing, and acknowledged upon successful handler completion.
-   * The handler is not called when the queue is empty — check `result.ok` instead.
-   *
-   * This is an arrow function property so it can be destructured:
-   * ```typescript
-   * const { receive } = new QueueClient({ region: process.env.QUEUE_REGION! });
-   * const result = await receive("my-topic", "my-group", handler);
-   * if (!result.ok) console.log(result.reason);
-   * ```
-   *
-   * @param topicName - Name of the topic (pattern: `[A-Za-z0-9_-]+`)
-   * @param consumerGroup - Name of the consumer group (pattern: `[A-Za-z0-9_-]+`)
-   * @param handler - Function to process each message payload and metadata.
-   *                  Not called when the queue is empty.
-   * @param options - Optional receive options (visibilityTimeoutSeconds, limit, or messageId)
-   * @returns Discriminated result: `{ ok: true }` on success, `{ ok: false, reason }` otherwise
-   */
-  receive = async (topicName, consumerGroup, handler, options) => {
-    const api = getApiClient(this);
-    const topic = new Topic(api, topicName);
-    const visibilityTimeoutSeconds = options && "visibilityTimeoutSeconds" in options ? options.visibilityTimeoutSeconds : void 0;
-    const consumer = topic.consumerGroup(
-      consumerGroup,
-      visibilityTimeoutSeconds !== void 0 ? { visibilityTimeoutSeconds } : {}
-    );
-    try {
-      let count;
-      const retry = options?.retry;
-      if (options && "messageId" in options) {
-        count = await consumer.consume(handler, {
-          messageId: options.messageId,
-          retry
-        });
-      } else {
-        const limit = options && "limit" in options ? options.limit : void 0;
-        count = await consumer.consume(handler, {
-          ...limit !== void 0 ? { limit } : {},
-          retry
-        });
-      }
-      if (count === 0) {
-        return { ok: false, reason: "empty" };
-      }
-      return { ok: true };
-    } catch (error) {
-      if (options && "messageId" in options && error instanceof MessageNotFoundError) {
-        return { ok: false, reason: "not_found", messageId: options.messageId };
-      }
-      if (options && "messageId" in options && error instanceof MessageNotAvailableError) {
-        return {
-          ok: false,
-          reason: "not_available",
-          messageId: options.messageId
-        };
-      }
-      if (options && "messageId" in options && error instanceof MessageAlreadyProcessedError) {
-        return {
-          ok: false,
-          reason: "already_processed",
-          messageId: options.messageId
-        };
-      }
-      throw error;
-    }
-  };
   /**
    * Create a Web API route handler for processing queue callback messages.
    *
@@ -1596,7 +1542,7 @@ var QueueClient = class {
    *
    * This is an arrow function property so it can be destructured:
    * ```typescript
-   * const { handleCallback } = new QueueClient({ region: process.env.QUEUE_REGION! });
+   * const { handleCallback } = new QueueClient();
    * export const POST = handleCallback(handler);
    * ```
    *
@@ -1638,7 +1584,7 @@ var QueueClient = class {
    *
    * This is an arrow function property so it can be destructured:
    * ```typescript
-   * const { handleNodeCallback } = new QueueClient({ region: process.env.QUEUE_REGION! });
+   * const { handleNodeCallback } = new QueueClient();
    * app.post("/api/queue", handleNodeCallback(handler));
    * ```
    *
@@ -1674,6 +1620,107 @@ var QueueClient = class {
     };
   };
 };
+var PollingQueueClient = class {
+  constructor(options) {
+    apiClients.set(this, new ApiClient(options));
+  }
+  /**
+   * Send a message to a topic.
+   *
+   * This is an arrow function property so it can be destructured:
+   * ```typescript
+   * const { send } = new PollingQueueClient({ region: "iad1" });
+   * await send("my-topic", payload);
+   * ```
+   *
+   * @param topicName - Name of the topic (pattern: `[A-Za-z0-9_-]+`)
+   * @param payload - The data to send (serialized via the configured transport)
+   * @param options - Optional send options (idempotencyKey, retentionSeconds, delaySeconds, headers)
+   * @returns `{ messageId }` — `messageId` is `null` when the server accepted
+   *   the message for deferred processing (no ID available yet)
+   */
+  send = async (topicName, payload, options) => {
+    const api = getApi(this);
+    const result = await api.sendMessage({
+      queueName: topicName,
+      payload,
+      idempotencyKey: options?.idempotencyKey,
+      retentionSeconds: options?.retentionSeconds,
+      delaySeconds: options?.delaySeconds,
+      headers: options?.headers
+    });
+    return { messageId: result.messageId };
+  };
+  /**
+   * Receive and process messages from a topic.
+   *
+   * Each message is automatically locked, kept alive via periodic visibility
+   * extensions during processing, and acknowledged upon successful handler completion.
+   * The handler is not called when the queue is empty — check `result.ok` instead.
+   *
+   * This is an arrow function property so it can be destructured:
+   * ```typescript
+   * const { receive } = new PollingQueueClient({ region: "iad1" });
+   * const result = await receive("my-topic", "my-group", handler);
+   * if (!result.ok) console.log(result.reason);
+   * ```
+   *
+   * @param topicName - Name of the topic (pattern: `[A-Za-z0-9_-]+`)
+   * @param consumerGroup - Name of the consumer group (pattern: `[A-Za-z0-9_-]+`)
+   * @param handler - Function to process each message payload and metadata.
+   *                  Not called when the queue is empty.
+   * @param options - Optional receive options (visibilityTimeoutSeconds, limit, or messageId)
+   * @returns Discriminated result: `{ ok: true }` on success, `{ ok: false, reason }` otherwise
+   */
+  receive = async (topicName, consumerGroup, handler, options) => {
+    const api = getApi(this);
+    const topic = new Topic(api, topicName);
+    const visibilityTimeoutSeconds = options && "visibilityTimeoutSeconds" in options ? options.visibilityTimeoutSeconds : void 0;
+    const consumer = topic.consumerGroup(
+      consumerGroup,
+      visibilityTimeoutSeconds !== void 0 ? { visibilityTimeoutSeconds } : {}
+    );
+    try {
+      let count;
+      const retry = options?.retry;
+      if (options && "messageId" in options) {
+        count = await consumer.consume(handler, {
+          messageId: options.messageId,
+          retry
+        });
+      } else {
+        const limit = options && "limit" in options ? options.limit : void 0;
+        count = await consumer.consume(handler, {
+          ...limit !== void 0 ? { limit } : {},
+          retry
+        });
+      }
+      if (count === 0) {
+        return { ok: false, reason: "empty" };
+      }
+      return { ok: true };
+    } catch (error) {
+      if (options && "messageId" in options && error instanceof MessageNotFoundError) {
+        return { ok: false, reason: "not_found", messageId: options.messageId };
+      }
+      if (options && "messageId" in options && error instanceof MessageNotAvailableError) {
+        return {
+          ok: false,
+          reason: "not_available",
+          messageId: options.messageId
+        };
+      }
+      if (options && "messageId" in options && error instanceof MessageAlreadyProcessedError) {
+        return {
+          ok: false,
+          reason: "already_processed",
+          messageId: options.messageId
+        };
+      }
+      throw error;
+    }
+  };
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BadRequestError,
@@ -1692,6 +1739,7 @@ var QueueClient = class {
   MessageLockedError,
   MessageNotAvailableError,
   MessageNotFoundError,
+  PollingQueueClient,
   QueueClient,
   QueueEmptyError,
   StreamTransport,