@vercel/queue 0.1.7 → 0.2.1

package/dist/index.d.mts

@@ -755,6 +755,73 @@ declare function handleCallback<T = unknown>(handler: MessageHandler<T>, options
     retry?: RetryHandler;
 }): (requestOrEvent: CallbackRequestInput) => Promise<Response>;
 
+/**
+ * Options for {@link registerDevConsumer}.
+ */
+interface RegisterDevConsumerOptions {
+    /**
+     * Topic name to subscribe to. Supports wildcard patterns (e.g. `"user-*"`).
+     */
+    topic: string;
+    /**
+     * The QueueClient instance used for callback processing (visibility
+     * extensions, acks, etc.). Messages delivered to the handler are fetched
+     * via this client.
+     */
+    client: QueueClient;
+    /**
+     * Function invoked with each message delivered to the topic.
+     */
+    handler: MessageHandler;
+    /**
+     * Logical identifier for this consumer. Multiple consumers for the same
+     * topic must use distinct groups; re-registering with the same group
+     * replaces the previous handler (useful for HMR).
+     *
+     * @default "dev-consumer"
+     */
+    consumerGroup?: string;
+    /**
+     * Lock duration for in-flight messages. Forwarded to `coreHandleCallback`.
+     */
+    visibilityTimeoutSeconds?: number;
+    /**
+     * Called when the handler throws. Return `{ afterSeconds: N }` to schedule
+     * local re-delivery, or `{ acknowledge: true }` to drop the message.
+     */
+    retry?: RetryHandler;
+}
+/**
+ * Register a consumer for a topic without relying on `vercel.json` route
+ * discovery or stack-trace-based caller detection.
+ *
+ * Intended for framework integrations (e.g. Nitro) where queue handlers are
+ * wired through a central dispatcher rather than per-file `handleCallback()`
+ * calls. The caller supplies the topic and a handler; `send()` in dev mode
+ * will route messages through it via the same retry/re-delivery machinery
+ * used for file-discovered handlers.
+ *
+ * Call only when `isDevMode()` is true. In production this has no effect on
+ * routing — messages are delivered by the Vercel Queue Service directly.
+ *
+ * @returns An unregister function. Calling it removes the handler that this
+ *   call registered; if the entry was replaced (via re-registration with the
+ *   same `consumerGroup`), the unregister is a no-op.
+ *
+ * @example
+ * ```ts
+ * const unregister = registerDevConsumer({
+ *   topic: "orders",
+ *   client,
+ *   handler: async (message, metadata) => {
+ *     await dispatch(message, metadata);
+ *   },
+ *   consumerGroup: "nitro-vercel-queue",
+ * });
+ * ```
+ */
+declare function registerDevConsumer(options: RegisterDevConsumerOptions): () => void;
+
 /**
  * Core queue callback utilities for handling incoming webhook payloads
  * from Vercel triggers using the CloudEvent specification.
@@ -828,4 +895,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, 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, handleCallback, parseCallback, parseRawCallback, send };
+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 RegisterDevConsumerOptions, type RetryDirective, type RetryHandler, type SendOptions, type SendResult, StreamTransport, type Transport, UnauthorizedError, type VercelRegion, handleCallback, parseCallback, parseRawCallback, registerDevConsumer, send };

package/dist/index.d.ts

@@ -755,6 +755,73 @@ declare function handleCallback<T = unknown>(handler: MessageHandler<T>, options
     retry?: RetryHandler;
 }): (requestOrEvent: CallbackRequestInput) => Promise<Response>;
 
+/**
+ * Options for {@link registerDevConsumer}.
+ */
+interface RegisterDevConsumerOptions {
+    /**
+     * Topic name to subscribe to. Supports wildcard patterns (e.g. `"user-*"`).
+     */
+    topic: string;
+    /**
+     * The QueueClient instance used for callback processing (visibility
+     * extensions, acks, etc.). Messages delivered to the handler are fetched
+     * via this client.
+     */
+    client: QueueClient;
+    /**
+     * Function invoked with each message delivered to the topic.
+     */
+    handler: MessageHandler;
+    /**
+     * Logical identifier for this consumer. Multiple consumers for the same
+     * topic must use distinct groups; re-registering with the same group
+     * replaces the previous handler (useful for HMR).
+     *
+     * @default "dev-consumer"
+     */
+    consumerGroup?: string;
+    /**
+     * Lock duration for in-flight messages. Forwarded to `coreHandleCallback`.
+     */
+    visibilityTimeoutSeconds?: number;
+    /**
+     * Called when the handler throws. Return `{ afterSeconds: N }` to schedule
+     * local re-delivery, or `{ acknowledge: true }` to drop the message.
+     */
+    retry?: RetryHandler;
+}
+/**
+ * Register a consumer for a topic without relying on `vercel.json` route
+ * discovery or stack-trace-based caller detection.
+ *
+ * Intended for framework integrations (e.g. Nitro) where queue handlers are
+ * wired through a central dispatcher rather than per-file `handleCallback()`
+ * calls. The caller supplies the topic and a handler; `send()` in dev mode
+ * will route messages through it via the same retry/re-delivery machinery
+ * used for file-discovered handlers.
+ *
+ * Call only when `isDevMode()` is true. In production this has no effect on
+ * routing — messages are delivered by the Vercel Queue Service directly.
+ *
+ * @returns An unregister function. Calling it removes the handler that this
+ *   call registered; if the entry was replaced (via re-registration with the
+ *   same `consumerGroup`), the unregister is a no-op.
+ *
+ * @example
+ * ```ts
+ * const unregister = registerDevConsumer({
+ *   topic: "orders",
+ *   client,
+ *   handler: async (message, metadata) => {
+ *     await dispatch(message, metadata);
+ *   },
+ *   consumerGroup: "nitro-vercel-queue",
+ * });
+ * ```
+ */
+declare function registerDevConsumer(options: RegisterDevConsumerOptions): () => void;
+
 /**
  * Core queue callback utilities for handling incoming webhook payloads
  * from Vercel triggers using the CloudEvent specification.
@@ -828,4 +895,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, 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, handleCallback, parseCallback, parseRawCallback, send };
+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 RegisterDevConsumerOptions, type RetryDirective, type RetryHandler, type SendOptions, type SendResult, StreamTransport, type Transport, UnauthorizedError, type VercelRegion, handleCallback, parseCallback, parseRawCallback, registerDevConsumer, send };

package/dist/index.js

@@ -54,6 +54,7 @@ __export(index_exports, {
   handleCallback: () => handleCallback2,
   parseCallback: () => parseCallback,
   parseRawCallback: () => parseRawCallback,
+  registerDevConsumer: () => registerDevConsumer,
   send: () => send
 });
 module.exports = __toCommonJS(index_exports);
@@ -657,7 +658,13 @@ function parseBinaryHeaders(headers) {
       `Missing required CloudEvent headers: ${missingFields.join(", ")}`
     );
   }
-  const region = getHeader(headers, "ce-vqsregion") ?? void 0;
+  const rawRegion = getHeader(headers, "ce-vqsregion") ?? void 0;
+  if (rawRegion !== void 0 && !/^[a-z]{2,5}[0-9]{1,2}$/.test(rawRegion)) {
+    throw new Error(
+      `Invalid ce-vqsregion header: ${JSON.stringify(rawRegion)}. Region must match /^[a-z]{2,5}[0-9]{1,2}$/ (e.g. "iad1", "lhr1").`
+    );
+  }
+  const region = rawRegion;
   const base = {
     queueName,
     consumerGroup,
@@ -1002,6 +1009,44 @@ Add a trigger to vercel.json:
     );
   }
 }
+function registerDevConsumer(options) {
+  const {
+    topic,
+    client,
+    handler,
+    consumerGroup = "dev-consumer",
+    visibilityTimeoutSeconds,
+    retry
+  } = options;
+  const entry = {
+    consumerGroup,
+    handler,
+    client,
+    options: visibilityTimeoutSeconds !== void 0 || retry !== void 0 ? { visibilityTimeoutSeconds, retry } : void 0
+  };
+  const registry = getHandlerRegistry();
+  const existing = registry.get(topic) ?? [];
+  const existingIndex = existing.findIndex(
+    (e) => e.consumerGroup === consumerGroup
+  );
+  if (existingIndex >= 0) {
+    existing[existingIndex] = entry;
+  } else {
+    existing.push(entry);
+  }
+  registry.set(topic, existing);
+  return () => {
+    const current = registry.get(topic);
+    if (!current) return;
+    const filtered = current.filter((e) => e !== entry);
+    if (filtered.length === current.length) return;
+    if (filtered.length === 0) {
+      registry.delete(topic);
+    } else {
+      registry.set(topic, filtered);
+    }
+  };
+}
 function lookupHandlers(topicName) {
   const registry = getHandlerRegistry();
   const result = [];
@@ -1509,6 +1554,14 @@ function parseQueueHeaders(headers) {
     receiptHandle
   };
 }
+var REGION_PATTERN = /^[a-z]{2,5}[0-9]{1,2}$/;
+function validateRegion(region) {
+  if (!REGION_PATTERN.test(region)) {
+    throw new Error(
+      `Invalid region code: ${JSON.stringify(region)}. Region must match the pattern /^[a-z]{2,5}[0-9]{1,2}$/ (e.g. "iad1", "lhr1").`
+    );
+  }
+}
 var DEFAULT_BASE_URL_RESOLVER = (region) => new URL(`https://${region}.vercel-queue.com`);
 function resolveBaseUrl(region, resolver) {
   return (resolver ?? DEFAULT_BASE_URL_RESOLVER)(region);
@@ -1526,6 +1579,7 @@ var ApiClient = class _ApiClient {
   baseUrlResolver;
   dispatcher;
   constructor(options) {
+    validateRegion(options.region);
     this.region = options.region;
     this.baseUrlResolver = options.resolveBaseUrl;
     this.baseUrl = resolveBaseUrl(this.region, this.baseUrlResolver);
@@ -1640,7 +1694,7 @@ Cause: ${cause}`
       }
       console.debug("[VQS Debug] Request:", JSON.stringify(logData, null, 2));
     }
-    init.headers.set("User-Agent", `@vercel/queue/${"0.1.7"}`);
+    init.headers.set("User-Agent", `@vercel/queue/${"0.2.1"}`);
     init.headers.set("Vqs-Client-Ts", (/* @__PURE__ */ new Date()).toISOString());
     const fetchInit = this.dispatcher ? { ...init, dispatcher: this.dispatcher } : init;
     const response = await fetch(url, fetchInit);
@@ -2330,6 +2384,7 @@ function handleCallback2(handler, options) {
   handleCallback,
   parseCallback,
   parseRawCallback,
+  registerDevConsumer,
   send
 });
 //# sourceMappingURL=index.js.map