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

package/dist/types-BLG4ASI_.d.ts

@@ -0,0 +1,504 @@
+/**
+ * Serializer/Deserializer interface for message payloads.
+ *
+ * Built-in implementations:
+ * - `JsonTransport` - JSON serialization (default, buffers entire payload)
+ * - `BufferTransport` - Binary data (buffers entire payload)
+ * - `StreamTransport` - Pass-through streaming (no buffering, ideal for large payloads)
+ */
+interface Transport<T = unknown> {
+    /**
+     * Serialize a value to a buffer or stream for transmission.
+     * The result is sent as the request body with the `contentType` header.
+     */
+    serialize(value: T): Buffer | ReadableStream<Uint8Array>;
+    /**
+     * Deserialize a readable stream back to the original value.
+     * Called when receiving messages from the queue.
+     */
+    deserialize(stream: ReadableStream<Uint8Array>): Promise<T>;
+    /**
+     * Optional cleanup method for deserialized payloads that may contain resources.
+     * Called automatically by ConsumerGroup on error; manual cleanup required for direct client usage.
+     * @param payload The deserialized payload to clean up
+     */
+    finalize?(payload: T): Promise<void>;
+    /**
+     * MIME type for this serialization format.
+     * Sent as the Content-Type header when publishing messages.
+     */
+    contentType: string;
+}
+/**
+ * JSON serializer/deserializer (default transport).
+ *
+ * Ideal for structured data. Buffers the entire payload in memory for parsing.
+ *
+ * @example
+ * ```typescript
+ * // Default usage
+ * await send("topic", { data: "example" });
+ *
+ * // With custom serialization
+ * const transport = new JsonTransport({
+ *   replacer: (key, value) => key === "password" ? undefined : value,
+ *   reviver: (key, value) => key === "date" ? new Date(value) : value,
+ * });
+ * await send("topic", { data: "example" }, { transport });
+ * ```
+ */
+declare class JsonTransport<T = unknown> implements Transport<T> {
+    readonly contentType = "application/json";
+    readonly replacer?: Parameters<typeof JSON.stringify>[1];
+    readonly reviver?: Parameters<typeof JSON.parse>[1];
+    /**
+     * 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?: {
+        replacer?: Parameters<typeof JSON.stringify>[1];
+        reviver?: Parameters<typeof JSON.parse>[1];
+    });
+    serialize(value: T): Buffer;
+    deserialize(stream: ReadableStream<Uint8Array>): Promise<T>;
+}
+/**
+ * Binary data serializer/deserializer.
+ *
+ * Ideal for binary data that fits in memory. Buffers the entire payload.
+ *
+ * @example
+ * ```typescript
+ * const transport = new BufferTransport();
+ * await send("binary-topic", myBuffer, { transport });
+ * ```
+ */
+declare class BufferTransport implements Transport<Buffer> {
+    readonly contentType = "application/octet-stream";
+    serialize(value: Buffer): Buffer;
+    deserialize(stream: ReadableStream<Uint8Array>): Promise<Buffer>;
+}
+/**
+ * Pass-through stream serializer/deserializer.
+ *
+ * Ideal for large files and real-time streams. Does not buffer data in memory.
+ *
+ * **Important:** When using StreamTransport, you must call `finalize(payload)` when done
+ * processing to prevent resource leaks. ConsumerGroup handles this automatically;
+ * direct client usage requires manual cleanup.
+ *
+ * @example
+ * ```typescript
+ * const transport = new StreamTransport();
+ *
+ * // Sending a stream
+ * await send("large-file", myReadableStream, { transport });
+ *
+ * // Receiving - cleanup handled by ConsumerGroup
+ * await receive("large-file", "processor", async (stream, meta) => {
+ *   const reader = stream.getReader();
+ *   // Process chunks...
+ * }, { transport });
+ *
+ * // Direct client usage - manual cleanup required
+ * try {
+ *   for await (const msg of client.receiveMessages(options, transport)) {
+ *     // Process stream...
+ *   }
+ * } catch (error) {
+ *   await transport.finalize(msg.payload); // Manual cleanup
+ * }
+ * ```
+ */
+declare class StreamTransport implements Transport<ReadableStream<Uint8Array>> {
+    readonly contentType = "application/octet-stream";
+    serialize(value: ReadableStream<Uint8Array>): ReadableStream<Uint8Array>;
+    deserialize(stream: ReadableStream<Uint8Array>): Promise<ReadableStream<Uint8Array>>;
+    /**
+     * Consume any remaining stream data to prevent resource leaks.
+     * Called automatically by ConsumerGroup; manual call required for direct client usage.
+     */
+    finalize(payload: ReadableStream<Uint8Array>): Promise<void>;
+}
+
+/**
+ * Vercel Queue Service client types
+ */
+
+interface QueueClientOptions {
+    /**
+     * Base URL for the Vercel Queue Service API.
+     * Can also be set via VERCEL_QUEUE_BASE_URL environment variable.
+     * @default "https://vercel-queue.com"
+     */
+    baseUrl?: string;
+    /**
+     * Base path for API endpoints.
+     * Can also be set via VERCEL_QUEUE_BASE_PATH environment variable.
+     * @default "/api/v3/topic"
+     */
+    basePath?: string;
+    /**
+     * Authentication token for the Vercel Queue Service API.
+     * If not provided, the client will attempt to get a token via OIDC
+     * when running in a Vercel Function environment.
+     */
+    token?: string;
+    /**
+     * Custom headers to include in all requests.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Deployment ID to include in requests.
+     * Used for message routing and lease validation.
+     * @default process.env.VERCEL_DEPLOYMENT_ID if pinToDeployment is true
+     */
+    deploymentId?: string;
+    /**
+     * Whether to pin messages to the current deployment when publishing.
+     * When true, sends VERCEL_DEPLOYMENT_ID from environment, ensuring
+     * messages are routed to consumers on the same deployment.
+     *
+     * - Only affects send/publish operations
+     * - Consume operations always send deployment ID in production
+     * - Ignored in development mode (deployment ID is never sent locally)
+     * @default true
+     */
+    pinToDeployment?: boolean;
+}
+/**
+ * Options for publishing messages to a topic.
+ */
+interface PublishOptions {
+    /**
+     * Unique key to prevent duplicate message submissions.
+     * Deduplication window: `min(message retention, 24 hours)`.
+     */
+    idempotencyKey?: string;
+    /**
+     * Message retention time in seconds. After this period, the message expires.
+     * @default 86400 (24 hours)
+     * @minimum 60 (1 minute)
+     * @maximum 86400 (24 hours)
+     */
+    retentionSeconds?: number;
+    /**
+     * Delay delivery of the message by this many seconds.
+     * The message will not be visible to consumers until the delay has passed.
+     * @default 0
+     * @minimum 0
+     * @maximum Value of retentionSeconds (delay cannot exceed retention)
+     */
+    delaySeconds?: number;
+}
+interface SendMessageOptions<T = unknown> extends PublishOptions {
+    /**
+     * The topic/queue name to send the message to.
+     * Must match pattern: `[A-Za-z0-9_-]+`
+     */
+    queueName: string;
+    /**
+     * The message payload. Will be serialized using the provided transport.
+     */
+    payload: T;
+}
+interface SendMessageResponse {
+    /**
+     * The generated message ID
+     */
+    messageId: string;
+}
+interface Message<T = unknown> {
+    /**
+     * Unique message identifier. Used for receive-by-ID operations.
+     */
+    messageId: string;
+    /**
+     * The deserialized message payload.
+     * Note: If using StreamTransport, ensure proper cleanup by calling
+     * `transport.finalize(payload)` when done processing, especially in error cases.
+     */
+    payload: T;
+    /**
+     * Number of times this message has been delivered.
+     * Starts at 1 for the first delivery, increments on each retry.
+     */
+    deliveryCount: number;
+    /**
+     * Timestamp when the message was created/published.
+     */
+    createdAt: Date;
+    /**
+     * MIME type of the message content.
+     * Set by the transport's `contentType` property during publish.
+     */
+    contentType: string;
+    /**
+     * Receipt handle (lease token) for this message delivery.
+     * Required for delete and visibility extension operations.
+     * Valid only until the visibility timeout expires.
+     */
+    receiptHandle: string;
+}
+interface ReceiveMessagesOptions<T = unknown> {
+    /**
+     * The topic/queue name to receive messages from.
+     * Must match pattern: `[A-Za-z0-9_-]+`
+     */
+    queueName: string;
+    /**
+     * Consumer group name. Each consumer group maintains independent message state.
+     * Must match pattern: `[A-Za-z0-9_-]+`
+     */
+    consumerGroup: string;
+    /**
+     * Time in seconds that messages will be invisible to other consumers after receipt.
+     * Set to 0 for immediate re-visibility (useful for peeking).
+     * @default 30
+     * @minimum 0
+     * @maximum 3600 (1 hour)
+     */
+    visibilityTimeoutSeconds?: number;
+    /**
+     * Maximum number of messages to retrieve in a single request.
+     * @default 1
+     * @minimum 1
+     * @maximum 10
+     */
+    limit?: number;
+    /**
+     * Maximum concurrent in-flight messages for this consumer group.
+     * When limit is reached, receive requests throw ConcurrencyLimitError.
+     * @default unlimited
+     * @minimum 1
+     */
+    maxConcurrency?: number;
+}
+interface DeleteMessageOptions {
+    /**
+     * The topic/queue name the message belongs to.
+     */
+    queueName: string;
+    /**
+     * Consumer group name.
+     */
+    consumerGroup: string;
+    /**
+     * Receipt handle received when the message was consumed.
+     */
+    receiptHandle: string;
+}
+interface DeleteMessageResponse {
+    /**
+     * Whether the message was successfully deleted
+     */
+    deleted: boolean;
+}
+interface ChangeVisibilityOptions {
+    /**
+     * The topic/queue name the message belongs to.
+     */
+    queueName: string;
+    /**
+     * Consumer group name.
+     */
+    consumerGroup: string;
+    /**
+     * Receipt handle received when the message was consumed.
+     */
+    receiptHandle: string;
+    /**
+     * New visibility timeout in seconds.
+     * Cannot extend beyond the message's original expiration time.
+     * @minimum 0
+     * @maximum 3600 (1 hour)
+     */
+    visibilityTimeoutSeconds: number;
+}
+interface ChangeVisibilityResponse {
+    /**
+     * Whether the visibility was successfully updated
+     */
+    success: boolean;
+}
+/**
+ * Message metadata provided to handlers
+ */
+interface MessageMetadata {
+    messageId: string;
+    deliveryCount: number;
+    createdAt: Date;
+    topicName: string;
+    consumerGroup: string;
+}
+/**
+ * Message handler function type
+ */
+type MessageHandler<T = unknown> = (message: T, metadata: MessageMetadata) => Promise<void> | void;
+/**
+ * Options for creating a ConsumerGroup instance.
+ */
+interface ConsumerGroupOptions<T = unknown> {
+    /**
+     * Serializer/deserializer for the payload.
+     * Built-in options: JsonTransport, BufferTransport, StreamTransport.
+     * @default JsonTransport
+     */
+    transport?: Transport<T>;
+    /**
+     * Time in seconds that messages will be invisible to other consumers after receipt.
+     * The ConsumerGroup will automatically extend this timeout during processing.
+     * @default 30
+     * @minimum 0
+     * @maximum 3600 (1 hour)
+     */
+    visibilityTimeoutSeconds?: number;
+    /**
+     * How often (in seconds) to refresh the visibility timeout during message processing.
+     * Should be less than visibilityTimeoutSeconds to prevent message redelivery.
+     * @default Math.floor(visibilityTimeoutSeconds / 3)
+     */
+    visibilityRefreshInterval?: number;
+}
+interface ReceiveMessageByIdOptions<T = unknown> {
+    /**
+     * The topic/queue name to receive the message from.
+     * Must match pattern: `[A-Za-z0-9_-]+`
+     */
+    queueName: string;
+    /**
+     * Consumer group name.
+     * Must match pattern: `[A-Za-z0-9_-]+`
+     */
+    consumerGroup: string;
+    /**
+     * The specific message ID to retrieve.
+     */
+    messageId: string;
+    /**
+     * Time in seconds that the message will be invisible to other consumers after receipt.
+     * @default 30
+     * @minimum 0
+     * @maximum 3600 (1 hour)
+     */
+    visibilityTimeoutSeconds?: number;
+    /**
+     * Maximum concurrent in-flight messages for this consumer group.
+     * @default unlimited
+     * @minimum 1
+     */
+    maxConcurrency?: number;
+}
+interface ReceiveMessageByIdResponse<T = unknown> {
+    message: Message<T>;
+}
+/**
+ * Error thrown when a message does not exist or has expired.
+ */
+declare class MessageNotFoundError extends Error {
+    constructor(messageId: string);
+}
+/**
+ * Error thrown when a message exists but cannot be processed.
+ * This can happen when the message is in the wrong state or already claimed by another consumer.
+ */
+declare class MessageNotAvailableError extends Error {
+    constructor(messageId: string, reason?: string);
+}
+/**
+ * Error thrown when message data is corrupted or can't be parsed
+ */
+declare class MessageCorruptedError extends Error {
+    constructor(messageId: string, reason: string);
+}
+/**
+ * Error thrown when there are no messages available in the queue.
+ */
+declare class QueueEmptyError extends Error {
+    constructor(queueName: string, consumerGroup: string);
+}
+/**
+ * Error thrown when a message is temporarily locked by another consumer.
+ * The message is currently being processed and cannot be claimed.
+ */
+declare class MessageLockedError extends Error {
+    /** Suggested retry delay in seconds, if provided by the server. */
+    readonly retryAfter?: number;
+    constructor(messageId: string, retryAfter?: number);
+}
+/**
+ * Error thrown when authentication fails.
+ * This typically means the token is missing, invalid, or expired.
+ */
+declare class UnauthorizedError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Error thrown when access is forbidden.
+ * This typically means the queue belongs to a different environment or project.
+ */
+declare class ForbiddenError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Error thrown when request parameters are invalid.
+ */
+declare class BadRequestError extends Error {
+    constructor(message: string);
+}
+/**
+ * Error thrown when the server encounters an unexpected error.
+ */
+declare class InternalServerError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Error thrown when the batch limit parameter is outside the valid range.
+ * The limit must be between 1 and 10 (inclusive).
+ */
+declare class InvalidLimitError extends Error {
+    constructor(limit: number, min?: number, max?: number);
+}
+/**
+ * Error thrown when attempting to process a message that has already been successfully processed.
+ */
+declare class MessageAlreadyProcessedError extends Error {
+    constructor(messageId: string);
+}
+/**
+ * Error thrown when the concurrency limit is exceeded.
+ * This occurs when maxConcurrency is set and too many messages are already in-flight.
+ */
+declare class ConcurrencyLimitError extends Error {
+    /** Current number of in-flight messages for this consumer group. */
+    readonly currentInflight?: number;
+    /** Maximum allowed concurrent messages (as configured). */
+    readonly maxConcurrency?: number;
+    constructor(message?: string, currentInflight?: number, maxConcurrency?: number);
+}
+/**
+ * Error thrown when a duplicate idempotency key is detected.
+ * The message was already sent within the deduplication window.
+ */
+declare class DuplicateMessageError extends Error {
+    readonly idempotencyKey?: string;
+    constructor(message: string, idempotencyKey?: string);
+}
+/**
+ * Error thrown when consumer discovery fails.
+ * This typically means the deployment could not be reached or is not configured correctly.
+ */
+declare class ConsumerDiscoveryError extends Error {
+    readonly deploymentId?: string;
+    constructor(message: string, deploymentId?: string);
+}
+/**
+ * Error thrown when the consumer registry is not configured for the project.
+ */
+declare class ConsumerRegistryNotConfiguredError extends Error {
+    constructor(message?: string);
+}
+
+export { BufferTransport as B, type ChangeVisibilityOptions as C, type DeleteMessageOptions as D, ForbiddenError as F, InternalServerError as I, JsonTransport as J, type Message as M, type PublishOptions as P, type QueueClientOptions as Q, type ReceiveMessagesOptions as R, type SendMessageOptions as S, type Transport as T, UnauthorizedError as U, type SendMessageResponse as a, type ReceiveMessageByIdOptions as b, type ReceiveMessageByIdResponse as c, type DeleteMessageResponse as d, type ChangeVisibilityResponse as e, type MessageHandler as f, type ConsumerGroupOptions as g, StreamTransport as h, BadRequestError as i, ConcurrencyLimitError as j, ConsumerDiscoveryError as k, ConsumerRegistryNotConfiguredError as l, DuplicateMessageError as m, InvalidLimitError as n, MessageAlreadyProcessedError as o, MessageCorruptedError as p, MessageLockedError as q, MessageNotAvailableError as r, MessageNotFoundError as s, QueueEmptyError as t, type MessageMetadata as u };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vercel/queue",
-  "version": "0.0.0-alpha.34",
+  "version": "0.0.0-alpha.35",
   "publishConfig": {
     "access": "public"
   },