@vercel/queue 0.0.0-alpha.12 → 0.0.0-alpha.14

package/README.md

@@ -34,7 +34,7 @@ vc env pull
 
 Update your `tsconfig.json` to use `"bundler"` module resolution for proper package export resolution:
 
-```json
+```json5
 {
   "compilerOptions": {
     "moduleResolution": "bundler"
@@ -140,7 +140,7 @@ While you can split handlers into separate routes if needed (e.g., for code orga
 
 Configure which topics and consumers your API route handles:
 
-```json
+```json5
 {
   "functions": {
     "app/api/queue/route.ts": {
@@ -305,7 +305,7 @@ interface MessageTimeoutResult {
 
 If you need more than 1,000 messages per second, you can create multiple topics (e.g., user-specific or shard-based topics) and handle them with a single consumer using wildcards in your `vercel.json`:
 
-```json
+```json5
 {
   "functions": {
     "app/api/queue/route.ts": {

package/dist/index.d.mts

@@ -27,6 +27,12 @@ interface Transport<T = unknown> {
  */
 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>;
 }

package/dist/index.d.ts

@@ -27,6 +27,12 @@ interface Transport<T = unknown> {
  */
 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>;
 }

package/dist/index.js

@@ -41,27 +41,36 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/transports.ts
+async function streamToBuffer(stream) {
+  let totalLength = 0;
+  const reader = stream.getReader();
+  const chunks = [];
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      chunks.push(value);
+      totalLength += value.length;
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  return Buffer.concat(chunks, totalLength);
+}
 var JsonTransport = class {
   contentType = "application/json";
+  replacer;
+  reviver;
+  constructor(options = {}) {
+    this.replacer = options.replacer;
+    this.reviver = options.reviver;
+  }
   serialize(value) {
-    return Buffer.from(JSON.stringify(value), "utf8");
+    return Buffer.from(JSON.stringify(value, this.replacer), "utf8");
   }
   async deserialize(stream) {
-    const reader = stream.getReader();
-    let totalLength = 0;
-    const chunks = [];
-    try {
-      while (true) {
-        const { done, value } = await reader.read();
-        if (done) break;
-        chunks.push(value);
-        totalLength += value.length;
-      }
-    } finally {
-      reader.releaseLock();
-    }
-    const buffer = Buffer.concat(chunks, totalLength);
-    return JSON.parse(buffer.toString("utf8"));
+    const buffer = await streamToBuffer(stream);
+    return JSON.parse(buffer.toString("utf8"), this.reviver);
   }
 };
 var BufferTransport = class {
@@ -70,25 +79,7 @@ var BufferTransport = class {
     return value;
   }
   async deserialize(stream) {
-    const reader = stream.getReader();
-    const chunks = [];
-    try {
-      while (true) {
-        const { done, value } = await reader.read();
-        if (done) break;
-        chunks.push(value);
-      }
-    } finally {
-      reader.releaseLock();
-    }
-    const totalLength = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
-    const buffer = new Uint8Array(totalLength);
-    let offset = 0;
-    for (const chunk of chunks) {
-      buffer.set(chunk, offset);
-      offset += chunk.length;
-    }
-    return Buffer.from(buffer);
+    return await streamToBuffer(stream);
   }
 };
 var StreamTransport = class {
@@ -842,111 +833,6 @@ var ConsumerGroup = class {
   }
 };
 
-// src/topic.ts
-var Topic = class {
-  client;
-  topicName;
-  transport;
-  /**
-   * Create a new Topic instance
-   * @param client QueueClient instance to use for API calls
-   * @param topicName Name of the topic to work with
-   * @param transport Optional serializer/deserializer for the payload (defaults to JSON)
-   */
-  constructor(client, topicName, transport) {
-    this.client = client;
-    this.topicName = topicName;
-    this.transport = transport || new JsonTransport();
-  }
-  /**
-   * Publish a message to the topic
-   * @param payload The data to publish
-   * @param options Optional publish options
-   * @returns An object containing the message ID
-   * @throws {BadRequestError} When request parameters are invalid
-   * @throws {UnauthorizedError} When authentication fails
-   * @throws {ForbiddenError} When access is denied (environment mismatch)
-   * @throws {InternalServerError} When server encounters an error
-   */
-  async publish(payload, options) {
-    const result = await this.client.sendMessage(
-      {
-        queueName: this.topicName,
-        payload,
-        idempotencyKey: options?.idempotencyKey,
-        retentionSeconds: options?.retentionSeconds
-      },
-      this.transport
-    );
-    return { messageId: result.messageId };
-  }
-  /**
-   * Create a consumer group for this topic
-   * @param consumerGroupName Name of the consumer group
-   * @param options Optional configuration for the consumer group
-   * @returns A ConsumerGroup instance
-   */
-  consumerGroup(consumerGroupName, options) {
-    const consumerOptions = {
-      ...options,
-      transport: options?.transport || this.transport
-    };
-    return new ConsumerGroup(
-      this.client,
-      this.topicName,
-      consumerGroupName,
-      consumerOptions
-    );
-  }
-  /**
-   * Get the topic name
-   */
-  get name() {
-    return this.topicName;
-  }
-  /**
-   * Get the transport used by this topic
-   */
-  get serializer() {
-    return this.transport;
-  }
-};
-
-// src/factory.ts
-async function send(topicName, payload, options) {
-  const transport = options?.transport || new JsonTransport();
-  const client = new QueueClient();
-  const result = await client.sendMessage(
-    {
-      queueName: topicName,
-      payload,
-      idempotencyKey: options?.idempotencyKey,
-      retentionSeconds: options?.retentionSeconds
-    },
-    transport
-  );
-  return { messageId: result.messageId };
-}
-async function receive(topicName, consumerGroup, handler, options) {
-  const transport = options?.transport || new JsonTransport();
-  const client = new QueueClient();
-  const topic = new Topic(client, topicName, transport);
-  const { messageId, skipPayload, ...consumerGroupOptions } = options || {};
-  const consumer = topic.consumerGroup(consumerGroup, consumerGroupOptions);
-  if (messageId) {
-    if (skipPayload) {
-      return consumer.consume(handler, {
-        messageId,
-        skipPayload: true
-      });
-    } else {
-      return consumer.consume(handler, { messageId });
-    }
-  } else {
-    return consumer.consume(handler);
-  }
-}
-
 // src/callback.ts
 function validateWildcardPattern(pattern) {
   const firstIndex = pattern.indexOf("*");
@@ -1026,7 +912,7 @@ function handleCallback(handlers) {
       }
     }
   }
-  return async (request) => {
+  const routeHandler = async (request) => {
     try {
       const { queueName, consumerGroup, messageId } = await parseCallback(request);
       const topicHandler = findTopicHandler(queueName, handlers);
@@ -1067,6 +953,309 @@ function handleCallback(handlers) {
       );
     }
   };
+  if (isDevMode()) {
+    registerDevRouteHandler(routeHandler, handlers);
+  }
+  return routeHandler;
+}
+
+// src/dev.ts
+var devRouteHandlers = /* @__PURE__ */ new Map();
+var wildcardRouteHandlers = /* @__PURE__ */ new Map();
+var routeHandlerKeys = /* @__PURE__ */ new WeakMap();
+function cleanupDeadRefs(key, refs) {
+  const aliveRefs = refs.filter((ref) => ref.deref() !== void 0);
+  if (aliveRefs.length === 0) {
+    wildcardRouteHandlers.delete(key);
+  } else if (aliveRefs.length < refs.length) {
+    wildcardRouteHandlers.set(key, aliveRefs);
+  }
+}
+function isDevMode() {
+  return process.env.NODE_ENV === "development";
+}
+function registerDevRouteHandler(routeHandler, handlers) {
+  const existingKeys = routeHandlerKeys.get(routeHandler);
+  if (existingKeys) {
+    const newKeys = /* @__PURE__ */ new Set();
+    for (const topicName in handlers) {
+      for (const consumerGroup in handlers[topicName]) {
+        newKeys.add(`${topicName}:${consumerGroup}`);
+      }
+    }
+    for (const key of existingKeys) {
+      if (!newKeys.has(key)) {
+        const [topicPattern] = key.split(":");
+        if (topicPattern.includes("*")) {
+          const refs = wildcardRouteHandlers.get(key);
+          if (refs) {
+            const filteredRefs = refs.filter(
+              (ref) => ref.deref() !== routeHandler
+            );
+            if (filteredRefs.length === 0) {
+              wildcardRouteHandlers.delete(key);
+            } else {
+              wildcardRouteHandlers.set(key, filteredRefs);
+            }
+          }
+        } else {
+          devRouteHandlers.delete(key);
+        }
+      }
+    }
+  }
+  const keys = /* @__PURE__ */ new Set();
+  for (const topicName in handlers) {
+    for (const consumerGroup in handlers[topicName]) {
+      const key = `${topicName}:${consumerGroup}`;
+      keys.add(key);
+      if (topicName.includes("*")) {
+        const weakRef = new WeakRef(routeHandler);
+        const existing = wildcardRouteHandlers.get(key) || [];
+        cleanupDeadRefs(key, existing);
+        const cleanedRefs = wildcardRouteHandlers.get(key) || [];
+        cleanedRefs.push(weakRef);
+        wildcardRouteHandlers.set(key, cleanedRefs);
+      } else {
+        devRouteHandlers.set(key, {
+          routeHandler,
+          topicPattern: topicName
+        });
+      }
+    }
+  }
+  routeHandlerKeys.set(routeHandler, keys);
+}
+function findRouteHandlersForTopic(topicName) {
+  const handlersMap = /* @__PURE__ */ new Map();
+  for (const [
+    key,
+    { routeHandler, topicPattern }
+  ] of devRouteHandlers.entries()) {
+    const [_, consumerGroup] = key.split(":");
+    if (topicPattern === topicName) {
+      if (!handlersMap.has(routeHandler)) {
+        handlersMap.set(routeHandler, /* @__PURE__ */ new Set());
+      }
+      handlersMap.get(routeHandler).add(consumerGroup);
+    }
+  }
+  for (const [key, refs] of wildcardRouteHandlers.entries()) {
+    const [pattern, consumerGroup] = key.split(":");
+    if (matchesWildcardPattern(topicName, pattern)) {
+      cleanupDeadRefs(key, refs);
+      const cleanedRefs = wildcardRouteHandlers.get(key) || [];
+      for (const ref of cleanedRefs) {
+        const routeHandler = ref.deref();
+        if (routeHandler) {
+          if (!handlersMap.has(routeHandler)) {
+            handlersMap.set(routeHandler, /* @__PURE__ */ new Set());
+          }
+          handlersMap.get(routeHandler).add(consumerGroup);
+        }
+      }
+    }
+  }
+  return handlersMap;
+}
+function createMockCloudEventRequest(topicName, consumerGroup, messageId) {
+  const cloudEvent = {
+    type: "com.vercel.queue.v1beta",
+    source: `/topic/${topicName}/consumer/${consumerGroup}`,
+    id: messageId,
+    datacontenttype: "application/json",
+    data: {
+      messageId,
+      queueName: topicName,
+      consumerGroup
+    },
+    time: (/* @__PURE__ */ new Date()).toISOString(),
+    specversion: "1.0"
+  };
+  return new Request("https://localhost/api/queue/callback", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/cloudevents+json"
+    },
+    body: JSON.stringify(cloudEvent)
+  });
+}
+var DEV_CALLBACK_DELAY = 1e3;
+function triggerDevCallbacks(topicName, messageId) {
+  const handlersMap = findRouteHandlersForTopic(topicName);
+  if (handlersMap.size === 0) {
+    return;
+  }
+  const consumerGroups = Array.from(
+    new Set(
+      Array.from(handlersMap.values()).flatMap((groups) => Array.from(groups))
+    )
+  );
+  console.log(
+    `[Dev Mode] Triggering local callbacks for topic "${topicName}" \u2192 consumers: ${consumerGroups.join(", ")}`
+  );
+  setTimeout(async () => {
+    for (const [routeHandler, consumerGroups2] of handlersMap.entries()) {
+      for (const consumerGroup of consumerGroups2) {
+        try {
+          const request = createMockCloudEventRequest(
+            topicName,
+            consumerGroup,
+            messageId
+          );
+          const response = await routeHandler(request);
+          if (response.ok) {
+            try {
+              const responseData = await response.json();
+              if (responseData.status === "success") {
+                console.log(
+                  `[Dev Mode] Message processed for ${topicName}/${consumerGroup}`
+                );
+              }
+            } catch (jsonError) {
+              console.error(
+                `[Dev Mode] Failed to parse success response for ${topicName}/${consumerGroup}:`,
+                jsonError
+              );
+            }
+          } else {
+            try {
+              const errorData = await response.json();
+              console.error(
+                `[Dev Mode] Failed to process message for ${topicName}/${consumerGroup}:`,
+                errorData.error || response.statusText
+              );
+            } catch (jsonError) {
+              console.error(
+                `[Dev Mode] Failed to process message for ${topicName}/${consumerGroup}:`,
+                response.statusText
+              );
+            }
+          }
+        } catch (error) {
+          console.error(
+            `[Dev Mode] Error triggering callback for ${topicName}/${consumerGroup}:`,
+            error
+          );
+        }
+      }
+    }
+  }, DEV_CALLBACK_DELAY);
+}
+function clearDevHandlers() {
+  devRouteHandlers.clear();
+  wildcardRouteHandlers.clear();
+}
+if (process.env.NODE_ENV === "test" || process.env.VITEST) {
+  globalThis.__clearDevHandlers = clearDevHandlers;
+}
+
+// src/topic.ts
+var Topic = class {
+  client;
+  topicName;
+  transport;
+  /**
+   * Create a new Topic instance
+   * @param client QueueClient instance to use for API calls
+   * @param topicName Name of the topic to work with
+   * @param transport Optional serializer/deserializer for the payload (defaults to JSON)
+   */
+  constructor(client, topicName, transport) {
+    this.client = client;
+    this.topicName = topicName;
+    this.transport = transport || new JsonTransport();
+  }
+  /**
+   * Publish a message to the topic
+   * @param payload The data to publish
+   * @param options Optional publish options
+   * @returns An object containing the message ID
+   * @throws {BadRequestError} When request parameters are invalid
+   * @throws {UnauthorizedError} When authentication fails
+   * @throws {ForbiddenError} When access is denied (environment mismatch)
+   * @throws {InternalServerError} When server encounters an error
+   */
+  async publish(payload, options) {
+    const result = await this.client.sendMessage(
+      {
+        queueName: this.topicName,
+        payload,
+        idempotencyKey: options?.idempotencyKey,
+        retentionSeconds: options?.retentionSeconds
+      },
+      this.transport
+    );
+    if (isDevMode()) {
+      triggerDevCallbacks(this.topicName, result.messageId);
+    }
+    return { messageId: result.messageId };
+  }
+  /**
+   * Create a consumer group for this topic
+   * @param consumerGroupName Name of the consumer group
+   * @param options Optional configuration for the consumer group
+   * @returns A ConsumerGroup instance
+   */
+  consumerGroup(consumerGroupName, options) {
+    const consumerOptions = {
+      ...options,
+      transport: options?.transport || this.transport
+    };
+    return new ConsumerGroup(
+      this.client,
+      this.topicName,
+      consumerGroupName,
+      consumerOptions
+    );
+  }
+  /**
+   * Get the topic name
+   */
+  get name() {
+    return this.topicName;
+  }
+  /**
+   * Get the transport used by this topic
+   */
+  get serializer() {
+    return this.transport;
+  }
+};
+
+// src/factory.ts
+async function send(topicName, payload, options) {
+  const transport = options?.transport || new JsonTransport();
+  const client = new QueueClient();
+  const result = await client.sendMessage(
+    {
+      queueName: topicName,
+      payload,
+      idempotencyKey: options?.idempotencyKey,
+      retentionSeconds: options?.retentionSeconds
+    },
+    transport
+  );
+  return { messageId: result.messageId };
+}
+async function receive(topicName, consumerGroup, handler, options) {
+  const transport = options?.transport || new JsonTransport();
+  const client = new QueueClient();
+  const topic = new Topic(client, topicName, transport);
+  const { messageId, skipPayload, ...consumerGroupOptions } = options || {};
+  const consumer = topic.consumerGroup(consumerGroup, consumerGroupOptions);
+  if (messageId) {
+    if (skipPayload) {
+      return consumer.consume(handler, {
+        messageId,
+        skipPayload: true
+      });
+    } else {
+      return consumer.consume(handler, { messageId });
+    }
+  } else {
+    return consumer.consume(handler);
+  }
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {