@vercel/queue 0.0.0-alpha.15 → 0.0.0-alpha.17

package/README.md

@@ -18,6 +18,11 @@ A TypeScript client library for interacting with the Vercel Queue Service API, d
 npm install @vercel/queue
 ```
 
+The package includes:
+
+- **Main Library**: Queue client and utilities for production and development
+- **CLI Tool**: `npx @vercel/queue/local-discover` for local development handler discovery
+
 ## Quick Start
 
 For local development, you'll need to pull your Vercel environment variables:
@@ -30,15 +35,53 @@ npm i -g vercel
 vc env pull
 ```
 
+## Local Development
+
+**Queues just work locally.** When you `send()` messages in development mode, they automatically trigger your handlers locally - no external queue infrastructure needed.
+
+### Next.js Lazy Loading
+
+For Next.js API routes (or others that are lazy-loaded), run this simple command to ensure handlers are discovered:
+
+```bash
+npx @vercel/queue/local-discover
+```
+
+That's it! The script reads your `vercel.json`, finds your queue handlers, and triggers Next.js to load them.
+
+### Example Workflow
+
+```bash
+# Start your dev server
+npm run dev
+
+# Discover handlers (only needed for Next.js lazy loading)
+npx @vercel/queue/local-discover
+
+# Send messages - they process locally automatically!
+```
+
+### CLI Options
+
+```bash
+# Custom port
+npx @vercel/queue/local-discover --port 3001
+
+# Different config file
+npx @vercel/queue/local-discover --config ./my-vercel.json
+
+# Skip vercel.json, use defaults
+npx @vercel/queue/local-discover --no-vercel-config
+```
+
 ### TypeScript Configuration
 
 Update your `tsconfig.json` to use `"bundler"` module resolution for proper package export resolution:
 
-```json5
+```json
 {
   "compilerOptions": {
     "moduleResolution": "bundler"
-    // ... other options
   }
 }
 ```
@@ -140,7 +183,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:
 
-```json5
+```json
 {
   "functions": {
     "app/api/queue/route.ts": {
@@ -149,9 +192,9 @@ Configure which topics and consumers your API route handles:
           "type": "queue/v1beta",
           "topic": "my-topic",
           "consumer": "my-consumer",
-          "maxAttempts": 3, // Optional: Maximum number of delivery attempts (default: 3)
-          "retryAfterSeconds": 60, // Optional: Delay between retries (default: 60)
-          "initialDelaySeconds": 0 // Optional: Initial delay before first delivery (default: 0)
+          "maxAttempts": 3,
+          "retryAfterSeconds": 60,
+          "initialDelaySeconds": 0
         },
         {
           "type": "queue/v1beta",
@@ -162,8 +205,8 @@ Configure which topics and consumers your API route handles:
           "type": "queue/v1beta",
           "topic": "order-events",
           "consumer": "analytics",
-          "maxAttempts": 5, // Retry up to 5 times
-          "retryAfterSeconds": 300 // Wait 5 minutes between retries
+          "maxAttempts": 5,
+          "retryAfterSeconds": 300
         }
       ]
     }
@@ -305,7 +348,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`:
 
-```json5
+```json
 {
   "functions": {
     "app/api/queue/route.ts": {

package/bin/local-discover.js

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+
+/**
+ * Standalone CLI script to discover queue handlers in development mode
+ * This script is self-contained and doesn't import from the main package
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+function showHelp() {
+  console.log(`
+@vercel/queue local-discover - Discover queue handlers in development mode
+
+USAGE:
+  npx @vercel/queue/local-discover [options]
+
+OPTIONS:
+  --port <number>        Port number for Next.js dev server (default: 3000)
+  --config <path>        Path to vercel.json file (default: ./vercel.json)
+  --no-vercel-config     Skip reading vercel.json, use default routes
+  --help, -h             Show this help message
+
+EXAMPLES:
+  npx @vercel/queue/local-discover
+  npx @vercel/queue/local-discover --port 3001
+  npx @vercel/queue/local-discover --config ./my-vercel.json
+  npx @vercel/queue/local-discover --no-vercel-config
+`);
+}
+
+/**
+ * Read vercel.json and extract function endpoints with queue triggers
+ */
+function readVercelConfig(configPath = "./vercel.json") {
+  try {
+    const fullPath = path.resolve(configPath);
+    const configContent = fs.readFileSync(fullPath, "utf-8");
+    const config = JSON.parse(configContent);
+
+    const routes = [];
+
+    // Extract routes from functions with queue triggers
+    if (config.functions) {
+      for (const [functionPath, functionConfig] of Object.entries(
+        config.functions,
+      )) {
+        if (
+          functionConfig &&
+          typeof functionConfig === "object" &&
+          "experimentalTriggers" in functionConfig
+        ) {
+          const triggers = functionConfig.experimentalTriggers;
+          if (Array.isArray(triggers)) {
+            // Check if any trigger is a queue trigger
+            const hasQueueTrigger = triggers.some(
+              (trigger) =>
+                trigger &&
+                typeof trigger === "object" &&
+                trigger.type === "queue/v1beta",
+            );
+
+            if (hasQueueTrigger) {
+              // Convert file path to API route
+              // app/api/vm/queue/route.ts -> /api/vm/queue
+              // pages/api/queue.ts -> /api/queue
+              let apiPath = functionPath;
+
+              if (apiPath.startsWith("app/api/")) {
+                apiPath = apiPath.replace("app/api/", "/api/");
+              } else if (apiPath.startsWith("pages/api/")) {
+                apiPath = apiPath.replace("pages/api/", "/api/");
+              }
+
+              // Remove file extensions and /route suffix
+              apiPath = apiPath.replace(
+                /\/(route|index)\.(ts|js|tsx|jsx)$/,
+                "",
+              );
+              apiPath = apiPath.replace(/\.(ts|js|tsx|jsx)$/, "");
+
+              routes.push(apiPath);
+            }
+          }
+        }
+      }
+    }
+
+    return routes;
+  } catch (error) {
+    // vercel.json might not exist or be malformed
+    return [];
+  }
+}
+
+/**
+ * Make OPTIONS requests to trigger Next.js lazy loading
+ */
+async function discoverQueueHandlers(options = {}) {
+  if (process.env.NODE_ENV !== "development") {
+    console.log("[Dev Mode] Not in development mode, skipping discovery");
+    return;
+  }
+
+  const baseUrl = options.baseUrl || "http://localhost:3000";
+  const fromVercelConfig = options.fromVercelConfig ?? true;
+  const configPath = options.configPath || "./vercel.json";
+
+  let routes = options.routes || [];
+
+  // Auto-discover from vercel.json if enabled
+  if (fromVercelConfig && routes.length === 0) {
+    const configRoutes = readVercelConfig(configPath);
+    if (configRoutes.length > 0) {
+      routes = configRoutes;
+      console.log(
+        `[Dev Mode] Found ${configRoutes.length} queue endpoints in vercel.json`,
+      );
+    } else {
+      // Fallback to common routes
+      routes = ["/api/queue/callback", "/api/queue", "/api/queues/callback"];
+      console.log("[Dev Mode] No vercel.json found, using default routes");
+    }
+  }
+
+  console.log(
+    "[Dev Mode] Making OPTIONS requests to trigger module loading...",
+  );
+
+  for (const route of routes) {
+    try {
+      // Make an OPTIONS request to trigger module loading without processing
+      const response = await fetch(`${baseUrl}${route}`, {
+        method: "OPTIONS",
+        // Add a header to identify this as a discovery request
+        headers: { "x-queue-discovery": "true" },
+      });
+
+      // Any response means the route exists and module was loaded
+      console.log(`[Dev Mode] ✓ ${route} (${response.status})`);
+    } catch (error) {
+      // Ignore errors - route might not exist or server not running
+      console.log(`[Dev Mode] ✗ ${route} (server may not be running)`);
+    }
+  }
+
+  console.log("[Dev Mode] Module loading complete.");
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const options = {};
+
+  // Parse simple command line arguments
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--help" || arg === "-h") {
+      showHelp();
+      return;
+    } else if (arg === "--port" && args[i + 1]) {
+      options.baseUrl = `http://localhost:${args[i + 1]}`;
+      i++;
+    } else if (arg === "--config" && args[i + 1]) {
+      options.configPath = args[i + 1];
+      i++;
+    } else if (arg === "--no-vercel-config") {
+      options.fromVercelConfig = false;
+    }
+  }
+
+  try {
+    await discoverQueueHandlers(options);
+  } catch (error) {
+    console.error("Failed to discover queue handlers:", error.message);
+    process.exit(1);
+  }
+}
+
+main();