topsyde-utils 1.0.205 → 1.0.206

package/dist/server/bun/websocket/websocket.types.js.map

@@ -1 +1 @@
-{"version":3,"file":"websocket.types.js","sourceRoot":"","sources":["../../../../src/server/bun/websocket/websocket.types.ts"],"names":[],"mappings":"","sourcesContent":["import { ServerWebSocket, WebSocketHandler } from \"bun\";\nimport Channel from \"./Channel\";\nimport Websocket from \"./Websocket\";\n\nexport type BunWebsocketMessage = string | Buffer<ArrayBufferLike>;\n\nexport type WebsocketChannel<T extends I_WebsocketChannel = Channel> = Map<string, T>;\nexport type WebsocketClients = Map<string, I_WebsocketClient>;\nexport type WebsocketMessageOptions = {\n\t/**\n\t * Additional data to include in the message content\n\t * If an object is provided, it will be merged with the content\n\t * If a primitive value is provided, it will be added as content.data\n\t */\n\tdata?: any;\n\n\t/**\n\t * Client information to include in the message\n\t * Will be added as content.client\n\t */\n\tclient?: Partial<WebsocketEntityData> & {\n\t\t[key: string]: any;\n\t};\n\n\t/**\n\t * Channel metadata to include in the message\n\t * If true, all metadata will be included\n\t * If an array of strings, only the specified keys will be included\n\t */\n\tincludeMetadata?: boolean | string[];\n\n\t/**\n\t * Client IDs to exclude from receiving the broadcast\n\t * Useful for sending messages to all clients except the sender\n\t */\n\texcludeClients?: string[];\n\n\t/**\n\t * Channel to include in the message\n\t * Defaults to the channel of the message\n\t */\n\tchannel?: string;\n\n\t/**\n\t * Whether to include timestamp in the message\n\t * Defaults to true\n\t */\n\tincludeTimestamp?: boolean;\n\n\t/**\n\t * Custom fields to add to the root of the message\n\t * These will be merged with the message object\n\t */\n\tcustomFields?: Record<string, any>;\n\n\t/**\n\t * Transform function to modify the final message before sending\n\t * This is applied after all other processing\n\t */\n\ttransform?: (message: any) => any;\n\n\t/**\n\t * Priority of the message (higher numbers = higher priority)\n\t * Can be used by clients to determine processing order\n\t */\n\tpriority?: number;\n\n\t/**\n\t * Message expiration time in milliseconds since epoch\n\t * Can be used by clients to ignore outdated messages\n\t */\n\texpiresAt?: number;\n\n\t/**\n\t * Metadata to include in the message\n\t * If an array of strings, only the specified keys will be included\n\t */\n\tmetadata?: boolean | string[] | Record<string, string>;\n};\n\nexport type WebsocketMessage<T extends Record<string, any> = Record<string, any>> = {\n\t/**\n\t * Message type identifier used for client-side routing\n\t */\n\ttype: string;\n\t/**\n\t * Message content - can be any data structure\n\t * If a string is provided, it will be wrapped in {message: string}\n\t */\n\tcontent: T;\n\t/**\n\t * Channel ID\n\t */\n\tchannel?: string;\n\t/**\n\t * Timestamp of the message\n\t */\n\ttimestamp?: string;\n\t/**\n\t * Any additional custom fields\n\t */\n\t[key: string]: any;\n};\n\nexport type WebsocketStructuredMessage<T extends Record<string, any> = Record<string, any>> = WebsocketMessage<T> & WebsocketMessageOptions;\n\nexport type WebsocketEntityId = string;\nexport type WebsocketEntityName = string;\nexport type WebsocketEntityData = { id: WebsocketEntityId; name: WebsocketEntityName };\n\nexport interface I_WebsocketEntity extends WebsocketEntityData {\n\tws: ServerWebSocket<WebsocketEntityData>;\n}\n\nexport interface I_WebsocketClient extends I_WebsocketEntity {\n\tchannels: WebsocketChannel<I_WebsocketChannel>;\n\tsend(message: string, options?: WebsocketMessageOptions): void;\n\tsend(message: WebsocketStructuredMessage): void;\n\tsubscribe(channel: string): any;\n\tjoinChannel(channel: I_WebsocketChannel, send?: boolean): void;\n\tleaveChannel(channel: I_WebsocketChannel, send?: boolean): void;\n\tjoinChannels(channels: I_WebsocketChannel[], send?: boolean): void;\n\tleaveChannels(channels?: I_WebsocketChannel[], send?: boolean): void;\n\tunsubscribe(channel: string): any;\n\twhoami(): WebsocketEntityData;\n}\n\nexport interface I_WebsocketChannelEntity<T extends Websocket = Websocket> extends WebsocketEntityData {\n\tws: T;\n}\n\n// New types for the broadcast method\nexport type BroadcastOptions = WebsocketMessageOptions & {\n\tdebug?: boolean;\n};\nexport interface I_WebsocketChannel<T extends Websocket = Websocket> extends I_WebsocketChannelEntity<T> {\n\tlimit: number;\n\tmembers: Map<string, I_WebsocketClient>;\n\tmetadata: Record<string, string>;\n\tcreatedAt: Date;\n\tbroadcast(message: WebsocketStructuredMessage | string, options?: BroadcastOptions): void;\n\thasMember(client: I_WebsocketEntity | string): boolean;\n\taddMember(entity: I_WebsocketClient): I_WebsocketClient | false;\n\tremoveMember(entity: I_WebsocketEntity): I_WebsocketClient | false;\n\tgetMember(client: I_WebsocketEntity | string): I_WebsocketClient | undefined;\n\tgetMembers(clients?: string[] | I_WebsocketEntity[]): I_WebsocketClient[];\n\tgetMetadata(): Record<string, string>;\n\tgetCreatedAt(): Date;\n\tgetId(): string;\n\tgetSize(): number;\n\tgetLimit(): number;\n\tgetName(): string;\n\tcanAddMember(): boolean;\n}\n\n/**\n * Interface for implementing custom WebSocket behavior.\n *\n * @interface I_WebsocketInterface\n *\n * @property {Function} setup - Initializes the WebSocket handler with channels and clients\n *\n * The interface supports three optional handler methods:\n *\n * - `message`: Custom message handler that replaces the default handler\n * - `open`: Connection handler that runs after the default open handler\n * - `close`: Disconnection handler that runs before the default close handler\n */\nexport type WebsocketInterfaceHandlers = Partial<WebSocketHandler<WebsocketEntityData>>;\n\n/**\n * Interface for implementing custom WebSocket behavior.\n *\n * @interface I_WebsocketInterface\n *\n * @property {Function} setup - Initializes the WebSocket handler with channels and clients\n *\n * The interface supports three optional handler methods:\n *\n * - `message`: Custom message handler that replaces the default handler\n * - `open`: Connection handler that runs after the default open handler\n * - `close`: Disconnection handler that runs before the default close handler\n */\nexport interface I_WebsocketInterface {\n\thandlers: (channels: WebsocketChannel, clients: WebsocketClients) => WebsocketInterfaceHandlers;\n}\n"]}
+{"version":3,"file":"websocket.types.js","sourceRoot":"","sources":["../../../../src/server/bun/websocket/websocket.types.ts"],"names":[],"mappings":"","sourcesContent":["import { ServerWebSocket, WebSocketHandler } from \"bun\";\nimport Channel from \"./Channel\";\nimport Websocket from \"./Websocket\";\nimport { E_ClientState } from \"./websocket.enums\";\n\nexport type BunWebsocketMessage = string | Buffer<ArrayBufferLike>;\n\nexport type WebsocketChannel<T extends I_WebsocketChannel = Channel> = Map<string, T>;\nexport type WebsocketClients = Map<string, I_WebsocketClient>;\nexport type WebsocketMessageOptions = {\n\t/**\n\t * Additional data to include in the message content\n\t * If an object is provided, it will be merged with the content\n\t * If a primitive value is provided, it will be added as content.data\n\t */\n\tdata?: any;\n\n\t/**\n\t * Client information to include in the message\n\t * Will be added as content.client\n\t */\n\tclient?: Partial<WebsocketEntityData> & {\n\t\t[key: string]: any;\n\t};\n\n\t/**\n\t * Channel metadata to include in the message\n\t * If true, all metadata will be included\n\t * If an array of strings, only the specified keys will be included\n\t */\n\tincludeMetadata?: boolean | string[];\n\n\t/**\n\t * Client IDs to exclude from receiving the broadcast\n\t * Useful for sending messages to all clients except the sender\n\t */\n\texcludeClients?: string[];\n\n\t/**\n\t * Channel to include in the message\n\t * Defaults to the channel of the message\n\t */\n\tchannel?: string;\n\n\t/**\n\t * Whether to include timestamp in the message\n\t * Defaults to true\n\t */\n\tincludeTimestamp?: boolean;\n\n\t/**\n\t * Custom fields to add to the root of the message\n\t * These will be merged with the message object\n\t */\n\tcustomFields?: Record<string, any>;\n\n\t/**\n\t * Transform function to modify the final message before sending\n\t * This is applied after all other processing\n\t */\n\ttransform?: (message: any) => any;\n\n\t/**\n\t * Priority of the message (higher numbers = higher priority)\n\t * Can be used by clients to determine processing order\n\t */\n\tpriority?: number;\n\n\t/**\n\t * Message expiration time in milliseconds since epoch\n\t * Can be used by clients to ignore outdated messages\n\t */\n\texpiresAt?: number;\n\n\t/**\n\t * Metadata to include in the message\n\t * If an array of strings, only the specified keys will be included\n\t */\n\tmetadata?: boolean | string[] | Record<string, string>;\n};\n\nexport type WebsocketMessage<T extends Record<string, any> = Record<string, any>> = {\n\t/**\n\t * Message type identifier used for client-side routing\n\t */\n\ttype: string;\n\t/**\n\t * Message content - can be any data structure\n\t * If a string is provided, it will be wrapped in {message: string}\n\t */\n\tcontent: T;\n\t/**\n\t * Channel ID\n\t */\n\tchannel?: string;\n\t/**\n\t * Timestamp of the message\n\t */\n\ttimestamp?: string;\n\t/**\n\t * Any additional custom fields\n\t */\n\t[key: string]: any;\n};\n\n/**\n * Message structure sent over the wire to clients.\n * This is the actual WebSocket payload format - transport options are NOT included.\n */\nexport type WebsocketStructuredMessage<T extends Record<string, any> = Record<string, any>> = {\n\t/** Message type identifier for client-side routing */\n\ttype: string;\n\n\t/** Message payload */\n\tcontent: T;\n\n\t/** Channel ID where message originated */\n\tchannel?: string;\n\n\t/** ISO timestamp when message was created */\n\ttimestamp?: string;\n\n\t/** Client information (who sent this) */\n\tclient?: WebsocketEntityData;\n\n\t/** Channel metadata (if included) */\n\tmetadata?: Record<string, string>;\n\n\t/** Message priority for client-side processing */\n\tpriority?: number;\n\n\t/** Expiration timestamp (milliseconds since epoch) */\n\texpiresAt?: number;\n\n\t/** Any additional custom fields */\n\t[key: string]: any;\n};\n\n/**\n * @deprecated This type incorrectly mixed transport options with wire format.\n * Use WebsocketStructuredMessage for wire format and WebsocketMessageOptions for options.\n * This will be removed in a future version.\n */\nexport type deprecated_WebsocketStructuredMessage<T extends Record<string, any> = Record<string, any>> = WebsocketMessage<T> & WebsocketMessageOptions;\n\nexport type WebsocketEntityId = string;\nexport type WebsocketEntityName = string;\nexport type WebsocketEntityData = { id: WebsocketEntityId; name: WebsocketEntityName };\n\nexport interface I_WebsocketEntity extends WebsocketEntityData {\n\tws: ServerWebSocket<WebsocketEntityData>;\n}\n\nexport interface I_WebsocketClient extends I_WebsocketEntity {\n\tchannels: WebsocketChannel<I_WebsocketChannel>;\n\tstate: E_ClientState;\n\tsend(message: string, options?: WebsocketMessageOptions): void;\n\tsend(message: WebsocketStructuredMessage): void;\n\tsubscribe(channel: string): any;\n\tjoinChannel(channel: I_WebsocketChannel, send?: boolean): boolean;\n\tleaveChannel(channel: I_WebsocketChannel, send?: boolean): void;\n\tjoinChannels(channels: I_WebsocketChannel[], send?: boolean): void;\n\tleaveChannels(channels?: I_WebsocketChannel[], send?: boolean): void;\n\tunsubscribe(channel: string): any;\n\twhoami(): WebsocketEntityData;\n\tcanReceiveMessages(): boolean;\n\tmarkConnected(): void;\n\tmarkDisconnecting(): void;\n\tmarkDisconnected(): void;\n\tgetConnectionInfo(): { id: string; name: string; state: E_ClientState; connectedAt?: Date; disconnectedAt?: Date; uptime: number; channelCount: number };\n}\n\nexport interface I_WebsocketChannelEntity<T extends Websocket = Websocket> extends WebsocketEntityData {\n\tws: T;\n}\n\n// New types for the broadcast method\nexport type BroadcastOptions = WebsocketMessageOptions & {\n\tdebug?: boolean;\n};\n\n// Result type for addMember operations\nexport type AddMemberResult = { success: true; client: I_WebsocketClient } | { success: false; reason: \"full\" | \"already_member\" | \"error\"; error?: Error };\n\n// Options for addMember operations\nexport type AddMemberOptions = {\n\t/** Whether to notify client when channel is full (default: false) */\n\tnotify_when_full?: boolean;\n};\nexport interface I_WebsocketChannel<T extends Websocket = Websocket> extends I_WebsocketChannelEntity<T> {\n\tlimit: number;\n\tmembers: Map<string, I_WebsocketClient>;\n\tmetadata: Record<string, string>;\n\tcreatedAt: Date;\n\tbroadcast(message: WebsocketStructuredMessage | string, options?: BroadcastOptions): void;\n\thasMember(client: I_WebsocketEntity | string): boolean;\n\taddMember(entity: I_WebsocketClient, options?: AddMemberOptions): AddMemberResult;\n\tremoveMemberInternal(entity: I_WebsocketClient): void;\n\tremoveMember(entity: I_WebsocketEntity): I_WebsocketClient | false;\n\tgetMember(client: I_WebsocketEntity | string): I_WebsocketClient | undefined;\n\tgetMembers(clients?: string[] | I_WebsocketEntity[]): I_WebsocketClient[];\n\tgetMetadata(): Record<string, string>;\n\tgetCreatedAt(): Date;\n\tgetId(): string;\n\tgetSize(): number;\n\tgetLimit(): number;\n\tgetName(): string;\n\tcanAddMember(): boolean;\n}\n\n/**\n * Interface for implementing custom WebSocket behavior.\n *\n * @interface I_WebsocketInterface\n *\n * @property {Function} setup - Initializes the WebSocket handler with channels and clients\n *\n * The interface supports three optional handler methods:\n *\n * - `message`: Custom message handler that replaces the default handler\n * - `open`: Connection handler that runs after the default open handler\n * - `close`: Disconnection handler that runs before the default close handler\n */\nexport type WebsocketInterfaceHandlers = Partial<WebSocketHandler<WebsocketEntityData>>;\n\n/**\n * Interface for implementing custom WebSocket behavior.\n *\n * @interface I_WebsocketInterface\n *\n * @property {Function} setup - Initializes the WebSocket handler with channels and clients\n *\n * The interface supports three optional handler methods:\n *\n * - `message`: Custom message handler that replaces the default handler\n * - `open`: Connection handler that runs after the default open handler\n * - `close`: Disconnection handler that runs before the default close handler\n */\nexport interface I_WebsocketInterface {\n\thandlers: (channels: WebsocketChannel, clients: WebsocketClients) => WebsocketInterfaceHandlers;\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "topsyde-utils",
-  "version": "1.0.205",
+  "version": "1.0.206",
   "description": "A bundle of TypeScript utility classes and functions",
   "type": "module",
   "main": "dist/index.js",

package/src/__tests__/app.test.ts

@@ -83,7 +83,7 @@ describe("Websocket Tests", () => {
 			content: { text: "Broadcast to all channels" },
 		};
 
-		_Websocket.BraodcastAll(message);
+		_Websocket.BroadCastAll(message);
 		// No assertion needed, just checking it doesn't throw
 	});
 

package/src/__tests__/singleton.test.ts

@@ -292,8 +292,10 @@ describe("Singleton", () => {
 	});
 	it("should allow custom client implementation", () => {
 		class CustomClient extends Client {
-			public send(message: WebsocketStructuredMessage) {
-				console.log("CONSOLE LOG");
+			public send(message: string, options?: app.WebsocketMessageOptions): void;
+			public send(message: WebsocketStructuredMessage): void;
+			public send(message: WebsocketStructuredMessage | string, options?: app.WebsocketMessageOptions): void {
+				console.log("CUSTOM SEND");
 			}
 		}
 		const ws = app.Websocket.GetInstance<app.Websocket>({ clientClass: CustomClient });
@@ -382,7 +384,7 @@ describe("Singleton", () => {
 		// Update expectations to match actual structure - we don't care about exact format
 		// as long as it contains the message
 		expect(parsedJson).toHaveProperty("type", message.type);
-		expect(parsedJson).toHaveProperty("channel", channel.name);
+		expect(parsedJson).toHaveProperty("channel", channel.id);
 
 		spy.mockRestore();
 	});
@@ -395,7 +397,7 @@ describe("Singleton", () => {
 		ws.set(server);
 
 		const channel = ws.createChannel("test", "Test Channel");
-		const message = { type: "test", content: { message: "test message" },  };
+		const message = { type: "test", content: { message: "test message" } };
 		channel.broadcast(message, { debug: true, client: { id: "test", name: "Test Client" } });
 		expect(mockPublish).toHaveBeenCalledWith(channel.id, expect.any(String));
 	});

package/src/index.ts

@@ -45,7 +45,7 @@ export { default as Service } from "./server/service";
 export { default as Database } from "./server/base/base.database";
 export { default as Router } from "./server/bun/router/router";
 export { default as Router_Internal } from "./server/bun/router/router.internal";
-export { default as Websocket } from "./server/bun/websocket/Websocket";
+export { default as GameWebsocket } from "./server/bun/websocket/Websocket";
 export { default as Message } from "./server/bun/websocket/Message";
 export { default as Channel } from "./server/bun/websocket/Channel";
 export { default as Client } from "./server/bun/websocket/Client";
@@ -65,7 +65,7 @@ export { RxjsDataType, NamespaceActions, MultiNamespaceActions } from "./client/
 export { ControllerResponse, ControllerAction, ControllerMap, ControllerOptions } from "./server/controller";
 export { Routes } from "./server/bun/router/routes";
 export { WebsocketConstructorOptions, I_WebsocketConstructor } from "./server/bun/websocket/Websocket";
-export { E_WebsocketMessageType, E_WebsocketMessagePriority } from "./server/bun/websocket/websocket.enums";
+export { E_WebsocketMessageType, E_WebsocketMessagePriority, E_ClientState } from "./server/bun/websocket/websocket.enums";
 export {
 	BunWebsocketMessage,
 	WebsocketChannel,
@@ -80,6 +80,8 @@ export {
 	I_WebsocketClient,
 	I_WebsocketChannelEntity,
 	BroadcastOptions,
+	AddMemberResult,
+	AddMemberOptions,
 	I_WebsocketChannel,
 	WebsocketInterfaceHandlers,
 	I_WebsocketInterface,

package/src/server/bun/websocket/Channel.ts

@@ -1,15 +1,25 @@
 import { Guards, Lib } from "../../../utils";
 import Message from "./Message";
 import Websocket from "./Websocket";
-import type {
-	BroadcastOptions,
-	I_WebsocketChannel,
-	I_WebsocketClient,
-	I_WebsocketEntity,
-	WebsocketChannel,
-	WebsocketMessage
-} from "./websocket.types";
-
+import type { BroadcastOptions, I_WebsocketChannel, I_WebsocketClient, I_WebsocketEntity, WebsocketChannel, WebsocketMessage, AddMemberResult, AddMemberOptions } from "./websocket.types";
+import { E_WebsocketMessageType } from "./websocket.enums";
+
+/**
+ * Channel - Pub/sub topic for WebSocket clients
+ *
+ * ## Membership Contract
+ * - `addMember()` validates capacity and adds to `members` map
+ * - Client drives join via `joinChannel()` which subscribes and handles rollback
+ * - If subscription fails, membership is automatically rolled back
+ * - Member count never exceeds `limit`
+ *
+ * @example
+ * const channel = new Channel("game-1", "Game Room", ws, 10);
+ * const result = channel.addMember(client);
+ * if (result.success) {
+ *   channel.broadcast({ type: "player.joined", content: { player: client.whoami() } });
+ * }
+ */
 export default class Channel<T extends Websocket = Websocket> implements I_WebsocketChannel<T> {
 	public createdAt: Date = new Date();
 	public id: string;
@@ -18,7 +28,6 @@ export default class Channel<T extends Websocket = Websocket> implements I_Webso
 	public members: Map<string, I_WebsocketClient>;
 	public metadata: Record<string, string>;
 	public ws: T;
-	private message: Message;
 
 	constructor(id: string, name: string, ws: T, limit?: number, members?: Map<string, I_WebsocketClient>, metadata?: Record<string, string>) {
 		this.id = id;
@@ -27,8 +36,6 @@ export default class Channel<T extends Websocket = Websocket> implements I_Webso
 		this.members = members ?? new Map();
 		this.metadata = metadata ?? {};
 		this.ws = ws;
-		this.message = new Message();
-		
 	}
 
 	public broadcast(message: WebsocketMessage | string, options?: BroadcastOptions) {
@@ -39,30 +46,34 @@ export default class Channel<T extends Websocket = Websocket> implements I_Webso
 			};
 			message = msg;
 		}
-		const output = this.message.create(message, { ...options, channel: this.name });
-		if (options) {
-			// Include channel metadata if requested
-			if (options.includeMetadata) {
-				output.metadata = options.includeMetadata === true ? this.getMetadata() : this.getFilteredMetadata(options.includeMetadata);
-			}
 
-			// Handle excluded clients if needed
-			if (options.excludeClients && options.excludeClients.length > 0) {
-				// For large channels with many excluded clients, it might be more efficient
-				// to send directly to each client instead of using channel publish
-				if (this.members.size > 10 && options.excludeClients.length > this.members.size / 3) {
-					const serializedMessage = this.message.serialize(output);
-					for (const [clientId, client] of this.members) {
-						if (!options.excludeClients.includes(clientId)) {
-							client.ws.send(serializedMessage);
-						}
+		const output = Message.Create(message, { ...options, channel: this.id });
+
+		// Include channel metadata if requested
+		if (options?.includeMetadata) {
+			output.metadata = options.includeMetadata === true ? this.getMetadata() : this.getFilteredMetadata(options.includeMetadata);
+		}
+
+		const serializedMessage = Message.Serialize(output);
+
+		// If we need to exclude clients, send individually to prevent excluded clients from receiving
+		if (options?.excludeClients && options.excludeClients.length > 0) {
+			const excludeSet = new Set(options.excludeClients); // O(1) lookup
+
+			for (const [clientId, client] of this.members) {
+				if (!excludeSet.has(clientId)) {
+					try {
+						client.ws.send(serializedMessage);
+					} catch (error) {
+						Lib.Warn(`Failed to send to client ${clientId}:`, error);
 					}
-					return;
 				}
 			}
+			return;
 		}
-		// Publish to the channel
-		this.ws.server.publish(this.id, this.message.serialize(output));
+
+		// Otherwise use pub/sub for everyone
+		this.ws.server.publish(this.id, serializedMessage);
 	}
 
 	// Helper method for filtered metadata
@@ -84,11 +95,53 @@ export default class Channel<T extends Websocket = Websocket> implements I_Webso
 		return this.members.has(client.id);
 	}
 
-	public addMember(client: I_WebsocketClient) {
-		if (!this.canAddMember()) return false;
-		this.members.set(client.id, client);
-		client.joinChannel(this);
-		return client;
+	public addMember(client: I_WebsocketClient, options?: AddMemberOptions): AddMemberResult {
+		// Check if already a member
+		if (this.members.has(client.id)) {
+			return { success: false, reason: 'already_member' };
+		}
+
+		// Check capacity (atomic check)
+		if (this.members.size >= this.limit) {
+			// Optionally notify client why they can't join
+			if (options?.notify_when_full) {
+				this.notifyChannelFull(client);
+			}
+			return { success: false, reason: 'full' };
+		}
+
+		try {
+			this.members.set(client.id, client);
+			return { success: true, client };
+		} catch (error) {
+			// Rollback
+			this.members.delete(client.id);
+			return {
+				success: false,
+				reason: 'error',
+				error: error instanceof Error ? error : new Error(String(error))
+			};
+		}
+	}
+
+	private notifyChannelFull(client: I_WebsocketClient): void {
+		client.send({
+			type: E_WebsocketMessageType.ERROR,
+			content: {
+				message: `Channel "${this.name}" is full (${this.limit} members)`,
+				code: 'CHANNEL_FULL',
+				channel: this.id
+			}
+		});
+	}
+
+	/**
+	 * Internal method to remove a member without triggering client-side cleanup.
+	 * Used for rollback operations when joinChannel fails.
+	 * @internal
+	 */
+	public removeMemberInternal(client: I_WebsocketClient): void {
+		this.members.delete(client.id);
 	}
 
 	public removeMember(entity: I_WebsocketEntity) {

package/src/server/bun/websocket/Client.ts

@@ -9,15 +9,33 @@ import type {
 	WebsocketMessageOptions,
 	WebsocketMessage,
 } from "./websocket.types";
-import { E_WebsocketMessageType } from "./websocket.enums";
+import { E_WebsocketMessageType, E_ClientState } from "./websocket.enums";
 import { Guards, Lib } from "../../../utils";
 import Message from "./Message";
 
+/**
+ * Client - Connected WebSocket client with channel membership
+ *
+ * ## Channel Membership
+ * - Maintains own channel list and handles Bun pub/sub subscriptions
+ * - `joinChannel()` adds to channel, subscribes, and handles rollback on failure
+ * - Always use `channel.addMember(client)` in application code, not `client.joinChannel()` directly
+ *
+ * @example
+ * // ✅ Correct
+ * channel.addMember(client);
+ *
+ * // ❌ Incorrect - internal use only
+ * client.joinChannel(channel);
+ */
 export default class Client implements I_WebsocketClient {
 	private _id: string;
 	private _name: string;
 	private _ws: ServerWebSocket<WebsocketEntityData>;
 	private _channels: WebsocketChannel<I_WebsocketChannel>;
+	private _state: E_ClientState;
+	private _connectedAt?: Date;
+	private _disconnectedAt?: Date;
 
 	private set ws(value: ServerWebSocket<WebsocketEntityData>) {
 		this._ws = value;
@@ -51,25 +69,84 @@ export default class Client implements I_WebsocketClient {
 		return this._channels;
 	}
 
+	public get state(): E_ClientState {
+		return this._state;
+	}
+
 	constructor(entity: I_WebsocketEntity) {
 		this._id = entity.id;
 		this._name = entity.name;
 		this._ws = entity.ws;
-		this.ws = entity.ws;
 		this._channels = new Map();
+		this._state = E_ClientState.CONNECTING;
+	}
+
+	public canReceiveMessages(): boolean {
+		return this._state === E_ClientState.CONNECTED;
+	}
+
+	public markConnected(): void {
+		this._state = E_ClientState.CONNECTED;
+		this._connectedAt = new Date();
+	}
+
+	public markDisconnecting(): void {
+		this._state = E_ClientState.DISCONNECTING;
 	}
 
-	public joinChannel(channel: I_WebsocketChannel, send: boolean = true) {
+	public markDisconnected(): void {
+		this._state = E_ClientState.DISCONNECTED;
+		this._disconnectedAt = new Date();
+	}
+
+	public getConnectionInfo() {
+		return {
+			id: this.id,
+			name: this.name,
+			state: this._state,
+			connectedAt: this._connectedAt,
+			disconnectedAt: this._disconnectedAt,
+			uptime: this._connectedAt ? Date.now() - this._connectedAt.getTime() : 0,
+			channelCount: this._channels.size,
+		};
+	}
+
+	public joinChannel(channel: I_WebsocketChannel, send: boolean = true): boolean {
 		const channel_id = channel.getId();
-		this.subscribe(channel_id);
-		this.channels.set(channel_id, channel);
-		if (send)
-			this.send({
-				type: E_WebsocketMessageType.CLIENT_JOIN_CHANNEL,
-				content: { message: "Welcome to the channel" },
-				channel: channel_id,
-				client: this.whoami(),
-			});
+
+		// Check if already joined
+		if (this.channels.has(channel_id)) {
+			return false;
+		}
+
+		// Try to add to channel first
+		const result = channel.addMember(this);
+		if (!result.success) {
+			return false; // Channel full, already member, or other issue
+		}
+
+		try {
+			// Subscribe to channel's pub/sub topic
+			this.subscribe(channel_id);
+			this.channels.set(channel_id, channel);
+
+			// Send join notification
+			if (send) {
+				this.send({
+					type: E_WebsocketMessageType.CLIENT_JOIN_CHANNEL,
+					content: { message: "Welcome to the channel" },
+					channel: channel_id,
+					client: this.whoami(),
+				});
+			}
+
+			return true;
+		} catch (error) {
+			// Rollback channel membership on failure
+			channel.removeMemberInternal(this);
+			this.channels.delete(channel_id);
+			throw error;
+		}
 	}
 
 	public leaveChannel(channel: I_WebsocketChannel, send: boolean = true) {
@@ -107,14 +184,27 @@ export default class Client implements I_WebsocketClient {
 	public send(message: string, options?: WebsocketMessageOptions): void;
 	public send(message: WebsocketStructuredMessage): void;
 	public send(message: WebsocketStructuredMessage | string, options?: WebsocketMessageOptions): void {
-		if (Guards.IsString(message)) {
-			const msg: WebsocketMessage = {
-				type: "message",
-				content: { message },
-			};
-			message = Message.Create(msg, options);
+		// Check state before sending
+		if (!this.canReceiveMessages()) {
+			Lib.Warn(`Cannot send to client ${this.id} in state ${this._state}`);
+			return;
+		}
+
+		try {
+			if (Guards.IsString(message)) {
+				const msg: WebsocketMessage = {
+					type: "message",
+					content: { message },
+				};
+				message = Message.Create(msg, options);
+			}
+			this.ws.send(JSON.stringify({ client: this.whoami(), ...message }));
+		} catch (error) {
+			Lib.Warn(`Failed to send message to client ${this.id}:`, error);
+			if (error instanceof Error && error.message.includes("closed")) {
+				this.markDisconnected();
+			}
 		}
-		this.ws.send(JSON.stringify({ client: this.whoami(), ...message }));
 	}
 
 	public subscribe(channel: string): void {