@vercel/queue 0.0.0-alpha.3 → 0.0.0-alpha.31

package/dist/types-JvOenjfT.d.ts

@@ -0,0 +1,256 @@
+/**
+ * Serializer/Deserializer interface for message payloads
+ */
+interface Transport<T = unknown> {
+    /**
+     * Serialize a value to a buffer or stream for transmission
+     */
+    serialize(value: T): Buffer | ReadableStream<Uint8Array>;
+    /**
+     * Deserialize a readable stream back to the original value
+     */
+    deserialize(stream: ReadableStream<Uint8Array>): Promise<T>;
+    /**
+     * Optional cleanup method for deserialized payloads that may contain resources
+     * Should be called when the payload is no longer needed, especially in error cases
+     * @param payload The deserialized payload to clean up
+     */
+    finalize?(payload: T): Promise<void>;
+    /**
+     * MIME type for this serialization format
+     */
+    contentType: string;
+}
+/**
+ * Built-in JSON serializer/deserializer
+ * This implementation reads the entire stream into memory for JSON parsing
+ */
+declare class JsonTransport<T = unknown> implements Transport<T> {
+    readonly contentType = "application/json";
+    readonly replacer?: Parameters<typeof JSON.parse>[1];
+    readonly reviver?: Parameters<typeof JSON.parse>[1];
+    constructor(options?: {
+        replacer?: Parameters<typeof JSON.parse>[1];
+        reviver?: Parameters<typeof JSON.parse>[1];
+    });
+    serialize(value: T): Buffer;
+    deserialize(stream: ReadableStream<Uint8Array>): Promise<T>;
+}
+/**
+ * Built-in Buffer serializer/deserializer (reads entire stream into a Buffer)
+ */
+declare class BufferTransport implements Transport<Buffer> {
+    readonly contentType = "application/octet-stream";
+    serialize(value: Buffer): Buffer;
+    deserialize(stream: ReadableStream<Uint8Array>): Promise<Buffer>;
+}
+/**
+ * Stream serializer/deserializer (pass-through for streaming binary data)
+ * This is ideal for large payloads that don't need to be buffered in memory
+ *
+ * IMPORTANT: When using StreamTransport, you must call finalize(payload) when done
+ * processing the message to prevent resource leaks, especially in error cases.
+ * ConsumerGroup handles this automatically, but direct QueueClient usage requires manual cleanup.
+ *
+ * Example usage:
+ * ```typescript
+ * const transport = new StreamTransport();
+ * try {
+ *   for await (const message of client.receiveMessages(options, transport)) {
+ *     // Process the stream...
+ *     const reader = message.payload.getReader();
+ *     // ... handle stream data
+ *   }
+ * } catch (error) {
+ *   // Cleanup is handled automatically by ConsumerGroup
+ *   // or manually: await transport.finalize(message.payload);
+ * }
+ */
+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>>;
+    finalize(payload: ReadableStream<Uint8Array>): Promise<void>;
+}
+
+/**
+ * Vercel Queue Service client types
+ */
+
+/**
+ * Shared options for publishing messages
+ */
+interface PublishOptions {
+    /**
+     * Unique key to prevent duplicate message submissions
+     * @default random UUID
+     */
+    idempotencyKey?: string;
+    /**
+     * Message retention time in seconds
+     * @default 86400 (24 hours)
+     * @min 60
+     * @max 86400
+     */
+    retentionSeconds?: number;
+    /**
+     * Explicit deployment identifier to include in the `Vqs-Deployment-Id` header
+     * If provided, this takes precedence over any value from the environment
+     */
+    deploymentId?: string;
+}
+interface SendMessageOptions<T = unknown> extends PublishOptions {
+    /**
+     * The queue name to send the message to
+     */
+    queueName: string;
+    /**
+     * The message payload
+     */
+    payload: T;
+}
+interface SendMessageResponse {
+    /**
+     * The generated message ID
+     */
+    messageId: string;
+}
+interface Message<T = unknown> {
+    /**
+     * The message ID
+     */
+    messageId: string;
+    /**
+     * The deserialized message payload
+     * Note: If using streaming transports, 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
+     */
+    deliveryCount: number;
+    /**
+     * When the message was created
+     */
+    createdAt: Date;
+    /**
+     * MIME type of the message content
+     */
+    contentType: string;
+    /**
+     * Unique ticket for this message delivery (required for delete/patch operations)
+     */
+    ticket: string;
+}
+/**
+ * Result indicating the message should be timed out for retry later
+ */
+interface MessageTimeoutResult {
+    /**
+     * Time in seconds before the message becomes visible again
+     */
+    timeoutSeconds: number;
+}
+/**
+ * Result returned by message handlers
+ */
+type MessageHandlerResult = void | MessageTimeoutResult;
+/**
+ * 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<MessageHandlerResult> | MessageHandlerResult;
+/**
+ * Options for creating a ConsumerGroup instance
+ */
+interface ConsumerGroupOptions<T = unknown> {
+    /**
+     * Serializer/deserializer for the payload
+     * @default JsonTransport instance
+     */
+    transport?: Transport<T>;
+    /**
+     * Time in seconds that messages will be invisible to other consumers
+     * @default 30
+     */
+    visibilityTimeoutSeconds?: number;
+    /**
+     * How often to refresh the visibility timeout during processing (in seconds)
+     * @default 10
+     */
+    refreshInterval?: number;
+}
+/**
+ * Error thrown when a message is not found (404)
+ */
+declare class MessageNotFoundError extends Error {
+    constructor(messageId: string);
+}
+/**
+ * Error thrown when a message is not available for processing (409)
+ * This can happen when the message is in the wrong state, already claimed, etc.
+ */
+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 (204)
+ */
+declare class QueueEmptyError extends Error {
+    constructor(queueName: string, consumerGroup: string);
+}
+/**
+ * Error thrown when a message is temporarily locked (423)
+ */
+declare class MessageLockedError extends Error {
+    readonly retryAfter?: number;
+    constructor(messageId: string, retryAfter?: number);
+}
+/**
+ * Error thrown when authentication fails (401)
+ */
+declare class UnauthorizedError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Error thrown when access is forbidden (403)
+ */
+declare class ForbiddenError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Error thrown for bad requests (400)
+ */
+declare class BadRequestError extends Error {
+    constructor(message: string);
+}
+/**
+ * Error thrown for internal server errors (500)
+ */
+declare class InternalServerError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Error thrown when batch limit parameter is invalid
+ */
+declare class InvalidLimitError extends Error {
+    constructor(limit: number, min?: number, max?: number);
+}
+
+export { BufferTransport as B, type ConsumerGroupOptions as C, ForbiddenError as F, InternalServerError as I, JsonTransport as J, type MessageHandler as M, type PublishOptions as P, QueueEmptyError as Q, StreamTransport as S, type Transport as T, UnauthorizedError as U, BadRequestError as a, InvalidLimitError as b, MessageCorruptedError as c, MessageLockedError as d, MessageNotAvailableError as e, MessageNotFoundError as f, type Message as g, type MessageHandlerResult as h, type MessageMetadata as i, type MessageTimeoutResult as j, type SendMessageOptions as k, type SendMessageResponse as l };

package/package.json

@@ -1,28 +1,44 @@
 {
   "name": "@vercel/queue",
-  "version": "0.0.0-alpha.3",
-  "access": "restricted",
+  "version": "0.0.0-alpha.31",
+  "publishConfig": {
+    "access": "public"
+  },
   "description": "A Node.js library for interacting with the Vercel Queue Service API",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
+  "bin": {
+    "vercel-queue-local-init": "./bin/local-discover.js"
+  },
   "exports": {
     ".": {
       "import": {
-        "types": "./dist/index.d.ts",
+        "types": "./dist/index.d.mts",
         "default": "./dist/index.mjs"
       },
       "require": {
         "types": "./dist/index.d.ts",
         "default": "./dist/index.js"
       }
+    },
+    "./nextjs/pages": {
+      "import": {
+        "types": "./dist/nextjs-pages.d.mts",
+        "default": "./dist/nextjs-pages.mjs"
+      },
+      "require": {
+        "types": "./dist/nextjs-pages.d.ts",
+        "default": "./dist/nextjs-pages.js"
+      }
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "bin"
   ],
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=20.0.0"
   },
   "keywords": [
     "vercel",
@@ -34,7 +50,8 @@
   "author": "Timer <timer@vercel.com>",
   "license": "MIT",
   "dependencies": {
-    "mixpart": "0.0.4"
+    "@vercel/oidc": "^3.0.5",
+    "mixpart": "0.0.5-alpha.1"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.52.8",