Skip to content

feat(defineWebSocketHandler): support callback with event #1242

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pi0 merged 4 commits into from
Dec 8, 2025
Merged

feat(defineWebSocketHandler): support callback with event #1242

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
8779d46
feat: allow event callback as parameter to defineWebSocketHandler
dardanbujupaj Nov 16, 2025
67621cf
chore: apply automated updates
autofix-ci[bot] Nov 16, 2025
1f30c74
fix: add promise return type for websocket handler hooks
dardanbujupaj Nov 16, 2025
f864742
Merge branch 'main' into feat/websocket-event-param
pi0 Dec 8, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/2.utils/9.more.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,7 +81,7 @@ You can return a new Response from the handler to replace the original response.

Define WebSocket hooks.

### `defineWebSocketHandler(hooks)`
### `defineWebSocketHandler()`

@coderabbitai coderabbitai Bot Dec 8, 2025

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Documentation signature appears incomplete.

The auto-generated signature shows defineWebSocketHandler() with no parameters, but the implementation accepts a required hooks parameter. This may be an issue with the JSDoc comment in src/utils/ws.ts not documenting the parameter, causing automd to generate an incomplete signature.

Consider adding a @param JSDoc tag to the function in src/utils/ws.ts to ensure the documentation reflects the actual API.

🤖 Prompt for AI Agents 
In docs/2.utils/9.more.md around line 84, the generated signature for
defineWebSocketHandler() is missing its required parameter because the
implementation in src/utils/ws.ts does not document the parameter; update
src/utils/ws.ts by adding a JSDoc @param tag for the required hooks argument
(describe its expected type/shape and whether properties are optional), include
a short description and an example if helpful, and ensure the function JSDoc
block is directly above the function so the docs generator picks it up.


Define WebSocket event handler.

Expand Down
15 changes: 11 additions & 4 deletions src/utils/ws.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,13 @@
import { defineHandler } from "../handler.ts";

import type { Hooks as WebSocketHooks } from "crossws";
import type { H3Event } from "../event.ts";
import type { EventHandler } from "../types/handler.ts";

export type {
Hooks as WebSocketHooks,
Peer as WebSocketPeer,
Message as WebSocketMessage,
Peer as WebSocketPeer,
} from "crossws";

/**
Expand All @@ -26,15 +27,21 @@ export function defineWebSocket(
* @see https://h3.dev/guide/websocket
*/
export function defineWebSocketHandler(
hooks: Partial<WebSocketHooks>,
hooks:
| Partial<WebSocketHooks>
| ((
event: H3Event,
) => Partial<WebSocketHooks> | Promise<Partial<WebSocketHooks>>),
): EventHandler {
return defineHandler(function _webSocketHandler() {
return defineHandler(function _webSocketHandler(event) {
const crossws = typeof hooks === "function" ? hooks(event) : hooks;

return Object.assign(
new Response("WebSocket upgrade is required.", {
status: 426,
}),
{
crossws: hooks,
crossws,
},
);
});
Expand Down
9 changes: 9 additions & 0 deletions test/ws.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,4 +19,13 @@ describe("defineWebSocketHandler", () => {
// expect((res as Response).statusText).toBe("Upgrade Required");
expect((res as any).crossws).toEqual(hooks);
});

it("should attach the provided hooks with function argument", () => {
const wsHandler = defineWebSocketHandler(() => hooks);
const res = wsHandler({} as any);
expect(res).toBeInstanceOf(Response);
expect((res as Response).status).toBe(426);
// expect((res as Response).statusText).toBe("Upgrade Required");
expect((res as any).crossws).toEqual(hooks);
});
});