topsyde-utils 1.0.204 → 1.0.206

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

@@ -1,24 +1,23 @@
 import Guards from "../../../utils/Guards";
-import {
-	WebsocketStructuredMessage,
-	WebsocketMessage,
-	WebsocketMessageOptions,
-	I_WebsocketChannel,
-	I_WebsocketClient,
-	WebsocketEntityData,
-} from "./websocket.types";
+import { WebsocketStructuredMessage, WebsocketMessage, WebsocketMessageOptions, I_WebsocketClient, WebsocketEntityData } from "./websocket.types";
 
 export default class Message {
-	private messageTemplate: WebsocketStructuredMessage<any>;
-
-	constructor() {
-		this.messageTemplate = { type: "", content: {}, channel: "", timestamp: "" };
-	}
-
-	public create(message: WebsocketMessage, options?: WebsocketMessageOptions): WebsocketStructuredMessage {
-		// Clone the template (faster than creating new objects)
-		const output = Object.assign({}, this.messageTemplate);
-		// Set the dynamic properties in a single pass
+	// Shared template for all messages
+	private static readonly MESSAGE_TEMPLATE: WebsocketStructuredMessage<any> = {
+		type: "",
+		content: {},
+		channel: "",
+		timestamp: "",
+	};
+
+	// Private constructor to prevent instantiation
+	private constructor() {}
+
+	public static Create(message: WebsocketMessage, options?: WebsocketMessageOptions): WebsocketStructuredMessage {
+		// Clone the template
+		const output = Object.assign({}, Message.MESSAGE_TEMPLATE);
+
+		// Set the dynamic properties
 		output.type = message.type;
 		output.channel = message.channel || options?.channel || "N/A";
 
@@ -31,7 +30,7 @@ export default class Message {
 			output.content = {};
 		}
 
-		// Process options in a single pass if provided
+		// Process options if provided
 		if (options) {
 			// Add data if provided
 			if (options.data !== undefined) {
@@ -43,18 +42,20 @@ export default class Message {
 					output.content.data = options.data;
 				}
 			}
+
 			// Add client information if provided
 			if (options.client && Guards.IsObject(options.client) && Guards.IsString(options.client.id, true)) {
 				output.client = {
 					id: options.client.id,
-					name: options.client.name,
+					name: options.client.name || "Unknown",
 				};
-			} /* else {
-				delete output.client;
-			} */
+			}
 
 			// Include channel metadata if requested
-			if (options.includeMetadata !== false) output.metadata = options.metadata;
+			// Include channel metadata if provided as an object
+			if (options.metadata && Guards.IsObject(options.metadata) && !Guards.IsArray(options.metadata)) {
+				output.metadata = options.metadata;
+			}
 
 			// Add timestamp if requested (default: true)
 			if (options.includeTimestamp !== false) {
@@ -81,8 +82,7 @@ export default class Message {
 
 			// Apply custom transformation if provided
 			if (options.transform) {
-				const transformed = options.transform(output);
-				return transformed;
+				return options.transform(output);
 			}
 		} else {
 			output.timestamp = new Date().toISOString();
@@ -91,19 +91,21 @@ export default class Message {
 		return output;
 	}
 
-	public createWhisper(message: Omit<WebsocketMessage, "type">, options?: WebsocketMessageOptions) {
-		return this.create({ ...message, content: message.content, channel: message.channel, type: "whisper" }, options);
+	public static CreateWhisper(message: Omit<WebsocketMessage, "type">, options?: WebsocketMessageOptions): WebsocketStructuredMessage {
+		return Message.Create({ ...message, content: message.content, channel: message.channel, type: "whisper" }, options);
+	}
+
+	public static Serialize<T = string>(message: WebsocketStructuredMessage, transform?: (message: WebsocketStructuredMessage) => T): string | T {
+		return transform ? transform(message) : JSON.stringify(message);
 	}
 
-	public send(target: I_WebsocketClient, message: WebsocketStructuredMessage): void;
-	public send(target: I_WebsocketClient, message: WebsocketMessage, options?: WebsocketMessageOptions): void;
-	public send(target: I_WebsocketClient, message: WebsocketStructuredMessage | WebsocketMessage, options?: WebsocketMessageOptions): void {
-		target.send(this.create(message, options));
+	public static Send(target: I_WebsocketClient, message: WebsocketMessage, options?: WebsocketMessageOptions): void {
+		target.send(Message.Create(message, options));
 	}
 
-	public alert(target: I_WebsocketClient, reason: string, client?: WebsocketEntityData) {
+	public static Alert(target: I_WebsocketClient, reason: string, client?: WebsocketEntityData): void {
 		target.send(
-			this.create(
+			Message.Create(
 				{
 					content: {
 						message: reason,
@@ -115,19 +117,4 @@ export default class Message {
 			),
 		);
 	}
-
-	public serialize<T = string>(message: WebsocketStructuredMessage, transform?: (message: WebsocketStructuredMessage) => T) {
-		return transform ? transform(message) : JSON.stringify(message);
-	}
-
-	public static Serialize<T = string>(message: WebsocketStructuredMessage, transform: (message: WebsocketStructuredMessage) => T): T;
-	public static Serialize<T = string>(message: WebsocketStructuredMessage, transform?: (message: WebsocketStructuredMessage) => T): string | T;
-	public static Serialize<T = string>(message: WebsocketStructuredMessage, transform?: (message: WebsocketStructuredMessage) => T): string | T {
-		return transform ? transform(message) : JSON.stringify(message);
-	}
-
-	public static Create(message: WebsocketMessage, options?: WebsocketMessageOptions): WebsocketStructuredMessage{
-		const msg = new Message();
-		return msg.create(message, options);
-	}
 }

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

@@ -28,6 +28,26 @@ export interface I_WebsocketConstructor {
 	options?: WebsocketConstructorOptions;
 }
 
+/**
+ * Websocket - Singleton managing clients, channels, and message routing
+ *
+ * ## API Design: Static vs Instance
+ * - **Static methods**: Use in application code (e.g., `Websocket.Broadcast()`, `Websocket.GetClient()`)
+ * - **Instance methods**: Use when extending the class (e.g., `protected createClient()`)
+ *
+ * Static methods are facades that call the singleton instance internally.
+ *
+ * @example
+ * // Application code - use static methods
+ * Websocket.Broadcast("lobby", { type: "chat", content: { message: "Hi!" } });
+ *
+ * // Extension - override instance methods
+ * class GameWebsocket extends Websocket {
+ *   protected createClient(entity: I_WebsocketEntity) {
+ *     return new GameClient(entity);
+ *   }
+ * }
+ */
 export default class Websocket extends Singleton {
 	protected _channels: WebsocketChannel;
 	protected _clients: Map<string, I_WebsocketClient> = new Map();
@@ -111,7 +131,7 @@ export default class Websocket extends Singleton {
 		if (this._ws_interface_handlers.message) return this._ws_interface_handlers.message(ws, message);
 
 		ws.send("This is the message from the server: " + message);
-		Websocket.BraodcastAll({ type: "client.message.received", content: { message } });
+		Websocket.BroadCastAll({ type: "client.message.received", content: { message } });
 	};
 
 	private clientConnected = (ws: ServerWebSocket<WebsocketEntityData>) => {
@@ -124,7 +144,14 @@ export default class Websocket extends Singleton {
 		this._clients.set(client.id, client);
 
 		client.send({ type: E_WebsocketMessageType.CLIENT_CONNECTED, content: { message: "Welcome to the server", client: client.whoami() } });
-		global.addMember(client);
+
+		// Client handles its own joining logic with rollback support
+		if (!client.joinChannel(global)) {
+			Lib.Warn(`Failed to add client ${client.id} to global channel`);
+		}
+
+		// Mark as fully connected
+		client.markConnected();
 
 		if (this._ws_interface_handlers.open) this._ws_interface_handlers.open(ws);
 	};
@@ -132,15 +159,23 @@ export default class Websocket extends Singleton {
 	private clientDisconnected = (ws: ServerWebSocket<WebsocketEntityData>, code: number, reason: string) => {
 		if (this._options.debug) Lib.Log("Client disconnected", ws.data);
 
-		if (this._ws_interface_handlers.close) this._ws_interface_handlers.close(ws, code, reason);
-
 		const client = this._clients.get(ws.data.id);
 		if (!client) return;
 
+		// Mark as disconnecting
+		client.markDisconnecting();
+
+		if (this._ws_interface_handlers.close) this._ws_interface_handlers.close(ws, code, reason);
+
+		// Remove from all channels
 		this._channels.forEach((channel) => {
 			channel.removeMember(client);
 		});
 
+		// Mark as disconnected
+		client.markDisconnected();
+
+		// Remove from registry
 		this._clients.delete(ws.data.id);
 	};
 
@@ -196,7 +231,7 @@ export default class Websocket extends Singleton {
 	 * @param message - The message
 	 * @param args - The arguments
 	 */
-	public static BraodcastAll(message: WebsocketStructuredMessage, ...args: any[]) {
+	public static BroadCastAll(message: WebsocketStructuredMessage, ...args: any[]) {
 		const ws = this.GetInstance<Websocket>();
 		ws._channels.forEach((channel) => channel.broadcast(message, ...args));
 	}
@@ -297,14 +332,39 @@ export default class Websocket extends Singleton {
 	}
 
 	/**
-	 * Generate a message
-	 * @returns The generated message
+	 * Get all connected clients (excluding connecting/disconnecting)
+	 * @returns Array of connected clients
 	 */
-	public static GenerateMessage(): WebsocketStructuredMessage {
-		const msg: WebsocketStructuredMessage = {
-			type: "",
-			content: {},
+	public static GetConnectedClients(): I_WebsocketClient[] {
+		const ws = this.GetInstance<Websocket>();
+		return Array.from(ws._clients.values()).filter(
+			client => client.state === "connected"
+		);
+	}
+
+	/**
+	 * Get client statistics by state
+	 * @returns Object with counts by state
+	 */
+	public static GetClientStats() {
+		const ws = this.GetInstance<Websocket>();
+		const stats = {
+			total: ws._clients.size,
+			connecting: 0,
+			connected: 0,
+			disconnecting: 0,
+			disconnected: 0,
 		};
-		return msg;
+
+		for (const client of ws._clients.values()) {
+			switch (client.state) {
+				case "connecting": stats.connecting++; break;
+				case "connected": stats.connected++; break;
+				case "disconnecting": stats.disconnecting++; break;
+				case "disconnected": stats.disconnected++; break;
+			}
+		}
+
+		return stats;
 	}
 }

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

@@ -8,7 +8,7 @@ export * from './Channel';
 export * from './Client';
 export * from './websocket.enums';
 export * from './websocket.types';
-export { default as Websocket } from './Websocket';
+export { default as GameWebsocket } from './Websocket';
 export { default as Message } from './Message';
 export { default as Channel } from './Channel';
 export { default as Client } from './Client';

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

@@ -20,3 +20,10 @@ export enum E_WebsocketMessagePriority {
 	MEDIUM = 1,
 	HIGH = 2,
 }
+
+export enum E_ClientState {
+	CONNECTING = "connecting",
+	CONNECTED = "connected",
+	DISCONNECTING = "disconnecting",
+	DISCONNECTED = "disconnected",
+}

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

@@ -1,6 +1,7 @@
 import { ServerWebSocket, WebSocketHandler } from "bun";
 import Channel from "./Channel";
 import Websocket from "./Websocket";
+import { E_ClientState } from "./websocket.enums";
 
 export type BunWebsocketMessage = string | Buffer<ArrayBufferLike>;
 
@@ -102,7 +103,45 @@ export type WebsocketMessage<T extends Record<string, any> = Record<string, any>
 	[key: string]: any;
 };
 
-export type WebsocketStructuredMessage<T extends Record<string, any> = Record<string, any>> = WebsocketMessage<T> & WebsocketMessageOptions;
+/**
+ * Message structure sent over the wire to clients.
+ * This is the actual WebSocket payload format - transport options are NOT included.
+ */
+export type WebsocketStructuredMessage<T extends Record<string, any> = Record<string, any>> = {
+	/** Message type identifier for client-side routing */
+	type: string;
+
+	/** Message payload */
+	content: T;
+
+	/** Channel ID where message originated */
+	channel?: string;
+
+	/** ISO timestamp when message was created */
+	timestamp?: string;
+
+	/** Client information (who sent this) */
+	client?: WebsocketEntityData;
+
+	/** Channel metadata (if included) */
+	metadata?: Record<string, string>;
+
+	/** Message priority for client-side processing */
+	priority?: number;
+
+	/** Expiration timestamp (milliseconds since epoch) */
+	expiresAt?: number;
+
+	/** Any additional custom fields */
+	[key: string]: any;
+};
+
+/**
+ * @deprecated This type incorrectly mixed transport options with wire format.
+ * Use WebsocketStructuredMessage for wire format and WebsocketMessageOptions for options.
+ * This will be removed in a future version.
+ */
+export type deprecated_WebsocketStructuredMessage<T extends Record<string, any> = Record<string, any>> = WebsocketMessage<T> & WebsocketMessageOptions;
 
 export type WebsocketEntityId = string;
 export type WebsocketEntityName = string;
@@ -114,15 +153,21 @@ export interface I_WebsocketEntity extends WebsocketEntityData {
 
 export interface I_WebsocketClient extends I_WebsocketEntity {
 	channels: WebsocketChannel<I_WebsocketChannel>;
+	state: E_ClientState;
 	send(message: string, options?: WebsocketMessageOptions): void;
 	send(message: WebsocketStructuredMessage): void;
 	subscribe(channel: string): any;
-	joinChannel(channel: I_WebsocketChannel, send?: boolean): void;
+	joinChannel(channel: I_WebsocketChannel, send?: boolean): boolean;
 	leaveChannel(channel: I_WebsocketChannel, send?: boolean): void;
 	joinChannels(channels: I_WebsocketChannel[], send?: boolean): void;
 	leaveChannels(channels?: I_WebsocketChannel[], send?: boolean): void;
 	unsubscribe(channel: string): any;
 	whoami(): WebsocketEntityData;
+	canReceiveMessages(): boolean;
+	markConnected(): void;
+	markDisconnecting(): void;
+	markDisconnected(): void;
+	getConnectionInfo(): { id: string; name: string; state: E_ClientState; connectedAt?: Date; disconnectedAt?: Date; uptime: number; channelCount: number };
 }
 
 export interface I_WebsocketChannelEntity<T extends Websocket = Websocket> extends WebsocketEntityData {
@@ -133,6 +178,15 @@ export interface I_WebsocketChannelEntity<T extends Websocket = Websocket> exten
 export type BroadcastOptions = WebsocketMessageOptions & {
 	debug?: boolean;
 };
+
+// Result type for addMember operations
+export type AddMemberResult = { success: true; client: I_WebsocketClient } | { success: false; reason: "full" | "already_member" | "error"; error?: Error };
+
+// Options for addMember operations
+export type AddMemberOptions = {
+	/** Whether to notify client when channel is full (default: false) */
+	notify_when_full?: boolean;
+};
 export interface I_WebsocketChannel<T extends Websocket = Websocket> extends I_WebsocketChannelEntity<T> {
 	limit: number;
 	members: Map<string, I_WebsocketClient>;
@@ -140,7 +194,8 @@ export interface I_WebsocketChannel<T extends Websocket = Websocket> extends I_W
 	createdAt: Date;
 	broadcast(message: WebsocketStructuredMessage | string, options?: BroadcastOptions): void;
 	hasMember(client: I_WebsocketEntity | string): boolean;
-	addMember(entity: I_WebsocketClient): I_WebsocketClient | false;
+	addMember(entity: I_WebsocketClient, options?: AddMemberOptions): AddMemberResult;
+	removeMemberInternal(entity: I_WebsocketClient): void;
 	removeMember(entity: I_WebsocketEntity): I_WebsocketClient | false;
 	getMember(client: I_WebsocketEntity | string): I_WebsocketClient | undefined;
 	getMembers(clients?: string[] | I_WebsocketEntity[]): I_WebsocketClient[];

package/src/utils/BaseEntity.ts

@@ -26,6 +26,10 @@ export default abstract class BaseEntity {
 
 	/**
 	 * Creates a new entity instance from DTO (infers class from `this`)
+	 *
+	 * NOTE: This is a BASE implementation that uses plainToInstance.
+	 * Derived classes should override if they need custom construction logic.
+	 *
 	 * @param dto - DTO to create entity from
 	 */
 	public static FromDto<T extends BaseEntity>(this: ClassConstructor<T>, dto: Dto): T {
@@ -37,6 +41,9 @@ export default abstract class BaseEntity {
 	 * Creates multiple entities from DTOs
 	 */
 	public static FromDtos<T extends BaseEntity>(this: ClassConstructor<T>, dtos: Dto[]): T[] {
-		return plainToInstance(this, dtos.map((dto) => dto.toJSON()));
+		return plainToInstance(
+			this,
+			dtos.map((dto) => dto.toJSON()),
+		);
 	}
 }