@vercel/queue 0.0.0-alpha.34 → 0.0.0-alpha.36

package/dist/index.mjs

@@ -19,6 +19,12 @@ var JsonTransport = class {
   contentType = "application/json";
   replacer;
   reviver;
+  /**
+   * Create a new JsonTransport.
+   * @param options - Optional JSON serialization options
+   * @param options.replacer - Custom replacer for JSON.stringify
+   * @param options.reviver - Custom reviver for JSON.parse
+   */
   constructor(options = {}) {
     this.replacer = options.replacer;
     this.reviver = options.reviver;
@@ -48,6 +54,10 @@ var StreamTransport = class {
   async deserialize(stream) {
     return stream;
   }
+  /**
+   * Consume any remaining stream data to prevent resource leaks.
+   * Called automatically by ConsumerGroup; manual call required for direct client usage.
+   */
   async finalize(payload) {
     const reader = payload.getReader();
     try {
@@ -98,6 +108,7 @@ var QueueEmptyError = class extends Error {
   }
 };
 var MessageLockedError = class extends Error {
+  /** Suggested retry delay in seconds, if provided by the server. */
   retryAfter;
   constructor(messageId, retryAfter) {
     const retryMessage = retryAfter ? ` Retry after ${retryAfter} seconds.` : " Try again later.";
@@ -143,7 +154,9 @@ var MessageAlreadyProcessedError = class extends Error {
   }
 };
 var ConcurrencyLimitError = class extends Error {
+  /** Current number of in-flight messages for this consumer group. */
   currentInflight;
+  /** Maximum allowed concurrent messages (as configured). */
   maxConcurrency;
   constructor(message = "Concurrency limit exceeded", currentInflight, maxConcurrency) {
     super(message);
@@ -530,19 +543,55 @@ var QueueClient = class {
     }
     return response;
   }
+  /**
+   * Send a message to a topic.
+   *
+   * @param options - Message options including queue name, payload, and optional settings
+   * @param options.queueName - Topic name (pattern: `[A-Za-z0-9_-]+`)
+   * @param options.payload - Message payload
+   * @param options.idempotencyKey - Optional deduplication key (dedup window: min(retention, 24h))
+   * @param options.retentionSeconds - Message TTL (default: 86400, min: 60, max: 86400)
+   * @param options.delaySeconds - Delivery delay (default: 0, max: retentionSeconds)
+   * @param transport - Serializer for the payload
+   * @returns Promise with the generated messageId
+   * @throws {DuplicateMessageError} When idempotency key was already used
+   * @throws {ConsumerDiscoveryError} When consumer discovery fails
+   * @throws {ConsumerRegistryNotConfiguredError} When registry not configured
+   * @throws {BadRequestError} When parameters are invalid
+   * @throws {UnauthorizedError} When authentication fails
+   * @throws {ForbiddenError} When access is denied
+   * @throws {InternalServerError} When server encounters an error
+   */
   async sendMessage(options, transport) {
     const {
       queueName,
       payload,
       idempotencyKey,
       retentionSeconds,
-      delaySeconds
+      delaySeconds,
+      headers: optionHeaders
     } = options;
-    const headers = new Headers({
-      Authorization: `Bearer ${await this.getToken()}`,
-      "Content-Type": transport.contentType,
-      ...this.customHeaders
-    });
+    const headers = new Headers();
+    if (this.customHeaders) {
+      for (const [name, value] of Object.entries(this.customHeaders)) {
+        headers.append(name, value);
+      }
+    }
+    if (optionHeaders) {
+      const protectedHeaderNames = /* @__PURE__ */ new Set(["authorization", "content-type"]);
+      const isProtectedHeader = (name) => {
+        const lower = name.toLowerCase();
+        if (protectedHeaderNames.has(lower)) return true;
+        return lower.startsWith("vqs-");
+      };
+      for (const [name, value] of Object.entries(optionHeaders)) {
+        if (!isProtectedHeader(name) && value !== void 0) {
+          headers.append(name, value);
+        }
+      }
+    }
+    headers.set("Authorization", `Bearer ${await this.getToken()}`);
+    headers.set("Content-Type", transport.contentType);
     const deploymentId = this.getSendDeploymentId();
     if (deploymentId) {
       headers.set("Vqs-Deployment-Id", deploymentId);
@@ -592,6 +641,25 @@ var QueueClient = class {
     const responseData = await response.json();
     return responseData;
   }
+  /**
+   * Receive messages from a topic as an async generator.
+   *
+   * @param options - Receive options
+   * @param options.queueName - Topic name (pattern: `[A-Za-z0-9_-]+`)
+   * @param options.consumerGroup - Consumer group name (pattern: `[A-Za-z0-9_-]+`)
+   * @param options.visibilityTimeoutSeconds - Lock duration (default: 30, min: 0, max: 3600)
+   * @param options.limit - Max messages to retrieve (default: 1, min: 1, max: 10)
+   * @param options.maxConcurrency - Max in-flight messages (default: unlimited, min: 1)
+   * @param transport - Deserializer for message payloads
+   * @yields Message objects with payload, messageId, receiptHandle, etc.
+   * @throws {QueueEmptyError} When no messages available
+   * @throws {InvalidLimitError} When limit is outside 1-10 range
+   * @throws {ConcurrencyLimitError} When maxConcurrency exceeded
+   * @throws {BadRequestError} When parameters are invalid
+   * @throws {UnauthorizedError} When authentication fails
+   * @throws {ForbiddenError} When access is denied
+   * @throws {InternalServerError} When server encounters an error
+   */
   async *receiveMessages(options, transport) {
     const {
       queueName,
@@ -677,6 +745,26 @@ var QueueClient = class {
       }
     }
   }
+  /**
+   * Receive a specific message by its ID.
+   *
+   * @param options - Receive options
+   * @param options.queueName - Topic name (pattern: `[A-Za-z0-9_-]+`)
+   * @param options.consumerGroup - Consumer group name (pattern: `[A-Za-z0-9_-]+`)
+   * @param options.messageId - Message ID to retrieve
+   * @param options.visibilityTimeoutSeconds - Lock duration (default: 30, min: 0, max: 3600)
+   * @param options.maxConcurrency - Max in-flight messages (default: unlimited, min: 1)
+   * @param transport - Deserializer for the message payload
+   * @returns Promise with the message
+   * @throws {MessageNotFoundError} When message doesn't exist
+   * @throws {MessageNotAvailableError} When message is in wrong state or was a duplicate
+   * @throws {MessageAlreadyProcessedError} When message was already processed
+   * @throws {ConcurrencyLimitError} When maxConcurrency exceeded
+   * @throws {BadRequestError} When parameters are invalid
+   * @throws {UnauthorizedError} When authentication fails
+   * @throws {ForbiddenError} When access is denied
+   * @throws {InternalServerError} When server encounters an error
+   */
   async receiveMessageById(options, transport) {
     const {
       queueName,
@@ -771,6 +859,21 @@ var QueueClient = class {
     }
     throw new MessageNotFoundError(messageId);
   }
+  /**
+   * Delete (acknowledge) a message after successful processing.
+   *
+   * @param options - Delete options
+   * @param options.queueName - Topic name
+   * @param options.consumerGroup - Consumer group name
+   * @param options.receiptHandle - Receipt handle from the received message (must use same deployment ID as receive)
+   * @returns Promise indicating deletion success
+   * @throws {MessageNotFoundError} When receipt handle not found
+   * @throws {MessageNotAvailableError} When receipt handle invalid or message already processed
+   * @throws {BadRequestError} When parameters are invalid
+   * @throws {UnauthorizedError} When authentication fails
+   * @throws {ForbiddenError} When access is denied
+   * @throws {InternalServerError} When server encounters an error
+   */
   async deleteMessage(options) {
     const { queueName, consumerGroup, receiptHandle } = options;
     const headers = new Headers({
@@ -815,6 +918,23 @@ var QueueClient = class {
     }
     return { deleted: true };
   }
+  /**
+   * Extend or change the visibility timeout of a message.
+   * Used to prevent message redelivery while still processing.
+   *
+   * @param options - Visibility options
+   * @param options.queueName - Topic name
+   * @param options.consumerGroup - Consumer group name
+   * @param options.receiptHandle - Receipt handle from the received message (must use same deployment ID as receive)
+   * @param options.visibilityTimeoutSeconds - New timeout (min: 0, max: 3600, cannot exceed message expiration)
+   * @returns Promise indicating success
+   * @throws {MessageNotFoundError} When receipt handle not found
+   * @throws {MessageNotAvailableError} When receipt handle invalid or message already processed
+   * @throws {BadRequestError} When parameters are invalid
+   * @throws {UnauthorizedError} When authentication fails
+   * @throws {ForbiddenError} When access is denied
+   * @throws {InternalServerError} When server encounters an error
+   */
   async changeVisibility(options) {
     const {
       queueName,
@@ -937,36 +1057,26 @@ var ConsumerGroup = class {
   refreshInterval;
   transport;
   /**
-   * Create a new ConsumerGroup instance
-   * @param client QueueClient instance to use for API calls
-   * @param topicName Name of the topic to consume from
-   * @param consumerGroupName Name of the consumer group
-   * @param options Optional configuration
+   * Create a new ConsumerGroup instance.
+   *
+   * @param client - QueueClient instance to use for API calls
+   * @param topicName - Name of the topic to consume from (pattern: `[A-Za-z0-9_-]+`)
+   * @param consumerGroupName - Name of the consumer group (pattern: `[A-Za-z0-9_-]+`)
+   * @param options - Optional configuration
+   * @param options.transport - Payload serializer (default: JsonTransport)
+   * @param options.visibilityTimeoutSeconds - Message lock duration (default: 30, max: 3600)
+   * @param options.visibilityRefreshInterval - Lock refresh interval in seconds (default: visibilityTimeout / 3)
    */
   constructor(client, topicName, consumerGroupName, options = {}) {
     this.client = client;
     this.topicName = topicName;
     this.consumerGroupName = consumerGroupName;
-    this.visibilityTimeout = options.visibilityTimeoutSeconds || 30;
-    this.refreshInterval = options.refreshInterval || 10;
+    this.visibilityTimeout = options.visibilityTimeoutSeconds ?? 30;
+    this.refreshInterval = options.visibilityRefreshInterval ?? Math.floor(this.visibilityTimeout / 3);
     this.transport = options.transport || new JsonTransport();
   }
   /**
    * Starts a background loop that periodically extends the visibility timeout for a message.
-   * This prevents the message from becoming visible to other consumers while it's being processed.
-   *
-   * The extension loop runs every `refreshInterval` seconds and updates the message's
-   * visibility timeout to `visibilityTimeout` seconds from the current time.
-   *
-   * @param receiptHandle - The receipt handle that proves ownership of the message
-   * @returns A function that when called will stop the extension loop
-   *
-   * @remarks
-   * - The first extension attempt occurs after `refreshInterval` seconds, not immediately
-   * - If an extension fails, the loop terminates with an error logged to console
-   * - The returned stop function is idempotent - calling it multiple times is safe
-   * - By default, the stop function returns immediately without waiting for in-flight
-   * - Pass `true` to the stop function to wait for any in-flight extension to complete
    */
   startVisibilityExtension(receiptHandle) {
     let isRunning = true;
@@ -1128,7 +1238,8 @@ var Topic = class {
         payload,
         idempotencyKey: options?.idempotencyKey,
         retentionSeconds: options?.retentionSeconds,
-        delaySeconds: options?.delaySeconds
+        delaySeconds: options?.delaySeconds,
+        headers: options?.headers
       },
       this.transport
     );
@@ -1238,7 +1349,7 @@ async function parseCallback(request) {
     messageId
   };
 }
-function createCallbackHandler(handlers, client) {
+function createCallbackHandler(handlers, client, visibilityTimeoutSeconds) {
   for (const topicPattern in handlers) {
     if (topicPattern.includes("*")) {
       if (!validateWildcardPattern(topicPattern)) {
@@ -1274,7 +1385,10 @@ function createCallbackHandler(handlers, client) {
         );
       }
       const topic = new Topic(client, queueName);
-      const cg = topic.consumerGroup(consumerGroup);
+      const cg = topic.consumerGroup(
+        consumerGroup,
+        visibilityTimeoutSeconds !== void 0 ? { visibilityTimeoutSeconds } : void 0
+      );
       await cg.consume(consumerGroupHandler, { messageId });
       return Response.json({ status: "success" });
     } catch (error) {
@@ -1290,8 +1404,12 @@ function createCallbackHandler(handlers, client) {
   };
   return routeHandler;
 }
-function handleCallback(handlers, client) {
-  return createCallbackHandler(handlers, client || new QueueClient());
+function handleCallback(handlers, options) {
+  return createCallbackHandler(
+    handlers,
+    options?.client || new QueueClient(),
+    options?.visibilityTimeoutSeconds
+  );
 }
 
 // src/factory.ts
@@ -1304,7 +1422,8 @@ async function send(topicName, payload, options) {
       payload,
       idempotencyKey: options?.idempotencyKey,
       retentionSeconds: options?.retentionSeconds,
-      delaySeconds: options?.delaySeconds
+      delaySeconds: options?.delaySeconds,
+      headers: options?.headers
     },
     transport
   );
@@ -1354,23 +1473,39 @@ var Client = class {
     });
   }
   /**
-   * Create a callback handler for processing queue messages
-   * Returns a Next.js route handler function that routes messages to appropriate handlers
-   * @param handlers Object with topic-specific handlers organized by consumer groups
+   * Create a callback handler for processing queue messages.
+   * Returns a Next.js route handler function that routes messages to appropriate handlers.
+   *
+   * @param handlers - Object with topic-specific handlers organized by consumer groups
+   * @param options - Optional configuration
+   * @param options.visibilityTimeoutSeconds - Message lock duration (default: 30, max: 3600)
    * @returns A Next.js route handler function
    *
    * @example
    * ```typescript
+   * // Basic usage
    * export const POST = client.handleCallback({
    *   "user-events": {
    *     "welcome": (user, metadata) => console.log("Welcoming user", user),
    *     "analytics": (user, metadata) => console.log("Tracking user", user),
    *   },
    * });
+   *
+   * // With custom visibility timeout
+   * export const POST = client.handleCallback({
+   *   "video-processing": {
+   *     "transcode": async (video) => await transcodeVideo(video),
+   *   },
+   * }, {
+   *   visibilityTimeoutSeconds: 300,  // 5 minutes for long operations
+   * });
    * ```
    */
-  handleCallback(handlers) {
-    return handleCallback(handlers, this.client);
+  handleCallback(handlers, options) {
+    return handleCallback(handlers, {
+      ...options,
+      client: this.client
+    });
   }
 };
 export {