next-ws 0.0.0-beta-20250822123253 → 0.0.0-beta-20250823112013

package/README.md

@@ -50,14 +50,14 @@ To set up a WebSocket server with `next-ws`, you need to patch your local Next.j
 
 ## 🚀 Usage
 
-Using WebSocket connections in your Next.js app directory is simple with `next-ws`. You can handle WebSocket connections directly in your API routes via exported `SOCKET` functions. Here's an example of a simple WebSocket echo server:
+Using WebSocket connections in your Next.js app directory is simple with `next-ws`. You can handle WebSocket connections directly in your API routes via exported `UPGRADE` functions.
 
 ```js
-export function SOCKET(
+export function UPGRADE(
   client: import('ws').WebSocket,
-  request: import('http').IncomingMessage,
   server: import('ws').WebSocketServer,
-  context: { params: Record<string, string | string[]> },
+  request: import('next/server').NextRequest,
+  context: import('next-ws/server').RouteContext<'/api/ws'>,
 ) {
   // ...
 }
@@ -70,25 +70,24 @@ export function SOCKET(
 
 ### Echo Server
 
-This example demonstrates a simple WebSocket echo server that sends back any message it receives. Create a new API route file anywhere in your app directory and export a `SOCKET` function to handle WebSocket connections:
+This example demonstrates a simple WebSocket echo server that sends back any message it receives. Create a new API route file anywhere in your app directory and export a `UPGRADE` function to handle WebSocket connections:
 
 ```ts
 // app/api/ws/route.ts (can be any route file in the app directory)
 
-export function SOCKET(
-  client: import("ws").WebSocket,
-  request: import("http").IncomingMessage,
-  server: import("ws").WebSocketServer
+export function UPGRADE(
+  client: import('ws').WebSocket,
+  server: import('ws').WebSocketServer
 ) {
-  console.log("A client connected");
+  console.log('A client connected');
 
-  client.on("message", (message) => {
-    console.log("Received message:", message);
+  client.on('message', (message) => {
+    console.log('Received message:', message);
     client.send(message);
   });
 
-  client.on("close", () => {
-    console.log("A client disconnected");
+  client.once('close', () => {
+    console.log('A client disconnected');
   });
 }
 ```

package/dist/cli.cjs

@@ -27,7 +27,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 var import_minimist = __toESM(require("minimist"));
 
 // package.json
-var version = "0.0.0-beta-20250822123253";
+var version = "0.0.0-beta-20250823112013";
 
 // src/commands/helpers/define.ts
 function defineCommandGroup(definition) {

package/dist/server/index.cjs

@@ -52,13 +52,13 @@ function mainProcessOnly(callerName) {
   if (!meta.isCustomServer && !meta.isMainProcess) {
     throw new Error(
       `[next-ws] Attempt to call '${callerName}' outside the main process.
-You may be attempting to interact with the WebSocket server outside of a SOCKET handler. This will fail in production, as Next.js employs a worker process for routing, which do not have access to the WebSocket server on the main process.
+You may be attempting to interact with the WebSocket server outside of an UPGRADE handler. This will fail in production, as Next.js employs a worker process for routing, which do not have access to the WebSocket server on the main process.
 You can resolve this by using a custom server.`
     );
   } else if (!meta.isCustomServer) {
     logger.warnOnce(
       `[next-ws] The function '${callerName}' was called without a custom server.
-This could lead to unintended behaviour, especially if you're attempting to interact with the WebSocket server outside of a SOCKET handler.
+This could lead to unintended behaviour, especially if you're attempting to interact with the WebSocket server outside of an UPGRADE handler.
 Please note, while such configurations might function during development, they will fail in production. This is because Next.js employs a worker process for routing in production, which do not have access to the WebSocket server on the main process.
 You can resolve this by using a custom server.`
     );
@@ -168,6 +168,23 @@ async function importRouteModule(nextServer, filePath) {
   }
 }
 
+// src/server/helpers/request.ts
+var import_server = require("next/server");
+function toNextRequest(message) {
+  const controller = new AbortController();
+  const headers = new Headers(message.headers);
+  const protocol = "encrypted" in message.socket ? "https" : "http";
+  const url = `${protocol}://${headers.get("host")}${message.url}`;
+  message.once("aborted", () => controller.abort());
+  return new import_server.NextRequest(url, {
+    method: message.method,
+    headers,
+    body: message.method === "GET" || message.method === "HEAD" ? void 0 : message,
+    signal: controller.signal,
+    referrer: headers.get("referer") || void 0
+  });
+}
+
 // src/server/setup.ts
 function setupWebSocketServer(nextServer) {
   process.env.NEXT_WS_MAIN_PROCESS = String(1);
@@ -191,8 +208,8 @@ function setupWebSocketServer(nextServer) {
   if (Reflect.has(httpServer, kInstalled)) return;
   Reflect.set(httpServer, kInstalled, true);
   httpServer.on("upgrade", async (message, socket, head) => {
-    const url = new URL(message.url ?? "", "ws://next");
-    const pathname = url.pathname;
+    const request = toNextRequest(message);
+    const pathname = request.nextUrl.pathname;
     if (pathname.includes("/_next")) return;
     const route = findMatchingRoute(nextServer, pathname);
     if (!route) {
@@ -204,23 +221,30 @@ function setupWebSocketServer(nextServer) {
       logger3.error(`[next-ws] could not import module for page ${pathname}`);
       return socket.end();
     }
+    const handleUpgrade = module2.userland.UPGRADE;
     const handleSocket = module2.userland.SOCKET;
-    if (!handleSocket || typeof handleSocket !== "function") {
-      logger3.error(
-        `[next-ws] route '${pathname}' does not export a valid 'SOCKET' handler`
-      );
+    if ((!handleUpgrade || typeof handleUpgrade !== "function") && (!handleSocket || typeof handleSocket !== "function")) {
+      logger3.error(`[next-ws] route '${pathname}' does not export a handler`);
       return socket.end();
     }
+    if (handleSocket)
+      logger3.warnOnce(
+        "DeprecationWarning: [next-ws] SOCKET is deprecated, use UPGRADE instead, see https://github.com/apteryxxyz/next-ws#-usage"
+      );
     wsServer.handleUpgrade(message, socket, head, async (client) => {
       wsServer.emit("connection", client, message);
       try {
         const context = { params: route.params };
-        const handleClose = (
-          //
-          await handleSocket(client, message, wsServer, context)
-        );
-        if (typeof handleClose === "function")
-          client.once("close", () => handleClose());
+        if (handleUpgrade) {
+          await handleUpgrade(client, wsServer, request, context);
+        } else if (handleSocket) {
+          const handleClose = (
+            //
+            await handleSocket(client, message, wsServer, context)
+          );
+          if (typeof handleClose === "function")
+            client.once("close", () => handleClose());
+        }
       } catch (cause) {
         logger3.error(
           `[next-ws] error in socket handler for '${pathname}'`,

package/dist/server/index.d.ts

@@ -1,7 +1,27 @@
-import { Server } from 'node:http';
+import * as next_server from 'next/server';
+import * as http from 'http';
+import * as ws from 'ws';
 import { WebSocketServer } from 'ws';
+import { Server } from 'node:http';
 import NextNodeServer from 'next/dist/server/next-server.js';
 
+/** @deprecated Prefer UPGRADE and {@link UpgradeHandler} */
+type SocketHandler = (client: ws.WebSocket, request: http.IncomingMessage, server: ws.WebSocketServer, context: {
+    params: Record<string, string | string[]>;
+}) => unknown;
+type UpgradeHandler = (client: ws.WebSocket, server: ws.WebSocketServer, request: next_server.NextRequest, context: RouteContext<string>) => unknown;
+
+type RouteParams<Path extends string> = Path extends `${infer Before}[[...${infer Param}]]${infer After}` ? RouteParams<Before> & {
+    [K in Param]?: string[];
+} & RouteParams<After> : Path extends `${infer Before}[...${infer Param}]${infer After}` ? RouteParams<Before> & {
+    [K in Param]: string[];
+} & RouteParams<After> : Path extends `${infer Before}[${infer Param}]${infer After}` ? RouteParams<Before> & {
+    [K in Param]: string;
+} & RouteParams<After> : {};
+type RouteContext<Path extends string> = {
+    params: Record<string, string | string[] | undefined> & RouteParams<Path> & RouteParams<Path>;
+};
+
 declare function getHttpServer(): Server | undefined;
 declare function setHttpServer<T extends Server | undefined>(server: T): T;
 declare function getWebSocketServer(): WebSocketServer | undefined;
@@ -9,4 +29,4 @@ declare function setWebSocketServer<T extends WebSocketServer | undefined>(serve
 
 declare function setupWebSocketServer(nextServer: NextNodeServer): void;
 
-export { getHttpServer, getWebSocketServer, setHttpServer, setWebSocketServer, setupWebSocketServer };
+export { type RouteContext, type SocketHandler, type UpgradeHandler, getHttpServer, getWebSocketServer, setHttpServer, setWebSocketServer, setupWebSocketServer };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "next-ws",
-  "version": "0.0.0-beta-20250822123253",
+  "version": "0.0.0-beta-20250823112013",
   "description": "Add support for WebSockets in the Next.js app directory",
   "license": "MIT",
   "keywords": [