From bb800d9b9c41bcf5614a4de1d1f158c532fe9efb Mon Sep 17 00:00:00 2001 From: Matt Van Horn Date: Wed, 27 May 2026 01:08:00 -0700 Subject: [PATCH] docs: warn about empty-object UwsSocketImpl.data cast at class level (#191) `UwsSocketImpl` initializes `_data = {} as TData` in its constructor. That cast is safe for object `TData` without required fields, but it silently lies for primitive `TData` or types with required properties: `socket.data` then reads as `{}` typed at `TData`, and the caller is none the wiser. The `data` getter already mentions this, but readers browsing the class for an API overview can miss the per-property note. Lift the warning to the class-level JSDoc so it shows up in IntelliSense and the rendered API docs alongside the rest of the class description. --- src/websocket/core/socket.ts | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/src/websocket/core/socket.ts b/src/websocket/core/socket.ts index 45df502..90c65dd 100644 --- a/src/websocket/core/socket.ts +++ b/src/websocket/core/socket.ts @@ -4,8 +4,15 @@ import { RoomManager } from '../rooms'; import { BroadcastOperator } from './broadcast-operator'; /** - * Socket wrapper that provides a Socket.IO-like API over native uWebSockets.js - * This class wraps the native uWS.WebSocket and adds convenient methods + * Socket wrapper that provides a Socket.IO-like API over native uWebSockets.js. + * This class wraps the native uWS.WebSocket and adds convenient methods. + * + * IMPORTANT: `data` is initialized as an empty object cast to `TData`. The cast + * is safe for object types without required fields (the common case) but is + * unsafe when `TData` is a primitive type or has required properties: reading + * `socket.data` before assigning to it will surface a partially-typed value. + * Always assign `socket.data` before reading it in those cases. + * * @template TData - Type of custom data attached to the socket * @template TEmitData - Type of data that can be emitted */