topsyde-utils 1.3.2 → 2.0.1

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

@@ -1,120 +0,0 @@
-import Guards from "../../../utils/Guards";
-import { WebsocketStructuredMessage, WebsocketMessage, WebsocketMessageOptions, I_WebsocketClient, WebsocketEntityData } from "./websocket.types";
-
-export default class Message {
-	// 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";
-
-		// Process message content based on type
-		if (typeof message.content === "string") {
-			output.content = { message: message.content };
-		} else if (typeof message.content === "object" && message.content !== null) {
-			output.content = { ...message.content };
-		} else {
-			output.content = {};
-		}
-
-		// Process options if provided
-		if (options) {
-			// Add data if provided
-			if (options.data !== undefined) {
-				if (typeof options.data === "object" && options.data !== null && !Array.isArray(options.data)) {
-					// Merge object data with content
-					Object.assign(output.content, options.data);
-				} else {
-					// Set as data property for other types
-					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 || "Unknown",
-				};
-			}
-
-			// Include channel metadata if requested
-			// 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) {
-				output.timestamp = new Date().toISOString();
-			} else {
-				// Remove timestamp if explicitly disabled
-				delete output.timestamp;
-			}
-
-			// Add priority if specified
-			if (options.priority !== undefined) {
-				output.priority = options.priority;
-			}
-
-			// Add expiration if specified
-			if (options.expiresAt !== undefined) {
-				output.expiresAt = options.expiresAt;
-			}
-
-			// Add any custom fields to the root of the message
-			if (options.customFields) {
-				Object.assign(output, options.customFields);
-			}
-
-			// Apply custom transformation if provided
-			if (options.transform) {
-				return options.transform(output);
-			}
-		} else {
-			output.timestamp = new Date().toISOString();
-		}
-
-		return output;
-	}
-
-	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 static Send(target: I_WebsocketClient, message: WebsocketMessage, options?: WebsocketMessageOptions): void {
-		target.send(Message.Create(message, options));
-	}
-
-	public static Alert(target: I_WebsocketClient, reason: string, client?: WebsocketEntityData): void {
-		target.send(
-			Message.Create(
-				{
-					content: {
-						message: reason,
-					},
-					channel: "alert",
-					type: "message",
-				},
-				{ client },
-			),
-		);
-	}
-}

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

@@ -1,402 +0,0 @@
-import { Server, ServerWebSocket, WebSocketHandler } from "bun";
-import Singleton from "../../../singleton";
-import { Lib } from "../../../utils";
-import { Console } from "../../../utils/Console";
-import Channel from "./Channel";
-import Client from "./Client";
-import type {
-	I_WebsocketChannel,
-	I_WebsocketClient,
-	I_WebsocketEntity,
-	I_WebsocketInterface,
-	WebsocketChannel,
-	WebsocketEntityData,
-	BunWebsocketMessage,
-	WebsocketStructuredMessage,
-} from "./websocket.types";
-import { E_WebsocketMessageType } from "./websocket.enums";
-
-export type WebsocketConstructorOptions = {
-	debug?: boolean;
-	global_channel_limit?: number;
-};
-
-export interface I_WebsocketConstructor {
-	ws_interface?: I_WebsocketInterface;
-	channels?: WebsocketChannel;
-	clientClass?: typeof Client;
-	channelClass?: typeof Channel;
-	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
- * MyWebsocket extends Websocket:
- *   protected createClient(entity) {
- *     return new MyCustomClient(entity);
- *   }
- */
-export default class Websocket extends Singleton {
-	protected _channels: WebsocketChannel;
-	protected _clients: Map<string, I_WebsocketClient> = new Map();
-	protected _server!: Server;
-	protected _channelClass: typeof Channel;
-	protected _clientClass: typeof Client;
-	protected _ws_interface?: I_WebsocketInterface;
-	protected _options: WebsocketConstructorOptions;
-	protected _ws_interface_handlers: Partial<WebSocketHandler<WebsocketEntityData>>;
-	protected _lastId = 1;
-
-	protected constructor(options?: I_WebsocketConstructor) {
-		super();
-		this._ws_interface = options?.ws_interface;
-		this._channels = options?.channels ?? new Map<string, Channel>();
-		this._clientClass = options?.clientClass ?? Client;
-		this._channelClass = options?.channelClass ?? Channel.GetChannelType(options?.channels);
-		this._options = options?.options ?? { debug: false };
-		this.createChannel("global", "Global", this._options.global_channel_limit ?? 1000);
-		this._ws_interface_handlers = this._ws_interface?.handlers(this._channels, this._clients) ?? {};
-	}
-
-	protected set server(value: Server) {
-		this._server = value;
-	}
-
-	public get server(): Server {
-		return this._server;
-	}
-
-	public set(server: Server) {
-		this.server = server;
-		Console.blank();
-		Console.success("Websocket server set");
-	}
-
-	/**
-	 * Create a new channel
-	 * @param id - The id of the channel
-	 * @param name - The name of the channel
-	 * @param limit - The limit of the channel
-	 * @returns The created channel
-	 */
-	public createChannel(id: string, name: string, limit?: number): Channel {
-		if (this._channels.has(id)) return this._channels.get(id) as Channel;
-		const channel = new this._channelClass(id, name, this, limit);
-		this._channels.set(id, channel);
-		return channel;
-	}
-
-	/**
-	 * Remove a channel
-	 * @param id - The id of the channel
-	 */
-	public removeChannel(id: string) {
-		const channel = this._channels.get(id);
-		if (!channel) return;
-		channel.delete();
-		this._channels.delete(id);
-	}
-
-	/**
-	 * Create a new channel
-	 * @param id - The id of the channel
-	 * @param name - The name of the channel
-	 * @param limit - The limit of the channel
-	 * @returns The created channel
-	 */
-	public static CreateChannel(id: string, name: string, limit?: number) {
-		const ws = this.GetInstance<Websocket>();
-		return ws.createChannel(id, name, limit);
-	}
-
-	public handlers(): WebSocketHandler<WebsocketEntityData> {
-		return {
-			open: this.clientConnected,
-			message: this.clientMessageReceived,
-			close: this.clientDisconnected,
-		};
-	}
-
-	private clientMessageReceived = (ws: ServerWebSocket<WebsocketEntityData>, message: BunWebsocketMessage) => {
-		try {
-			if (Websocket.Heartbeat(ws, message)) return;
-
-			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.BroadCastAll({ type: "client.message.received", content: { message } });
-		} catch (error) {
-			console.error(error instanceof Error ? error.message : error);
-			ws.close(1011, "Internal server error during message handling: " + (error instanceof Error ? error.message : error));
-		}
-	};
-
-	private clientConnected = (ws: ServerWebSocket<WebsocketEntityData>) => {
-		try {
-			if (this._options.debug) Lib.Log("[debug] Client connected", ws.data);
-
-			const global = this._channels.get("global");
-			if (!global) throw new Error("Global channel not found");
-
-			const client = Websocket.CreateClient({ id: ws.data.id, ws: ws, name: ws.data.name });
-			this._clients.set(client.id, client);
-			this._lastId++;
-			if ((Number(client.id) || 0) >= this._lastId) this._lastId = Number(client.id) + 1;
-
-			// Mark as fully connected
-			client.markConnected();
-
-			client.send({ type: E_WebsocketMessageType.CLIENT_CONNECTED, content: { message: "Welcome to the server", client: client.whoami() } });
-
-			// Client handles its own joining logic with rollback support
-			const joinResult = client.joinChannel(global);
-			if (!joinResult.success) {
-				throw new Error("Failed to join global channel: " + joinResult.reason);
-			}
-
-			if (this._ws_interface_handlers.open) this._ws_interface_handlers.open(ws);
-		} catch (error) {
-			console.error(error instanceof Error ? error.message : error);
-			ws.close(1011, "Internal server error during connection setup: " + (error instanceof Error ? error.message : error));
-		}
-	};
-
-	private clientDisconnected = (ws: ServerWebSocket<WebsocketEntityData>, code: number, reason: string) => {
-		try {
-			if (this._options.debug) Lib.Log("Client disconnected", ws.data);
-
-			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);
-			});
-
-			// Remove from registry
-			this._clients.delete(ws.data.id);
-			// Mark as disconnected
-			client.markDisconnected();
-		} catch (error) {
-			console.error(error instanceof Error ? error.message : error);
-			ws.close(1011, "Internal server error during disconnection: " + (error instanceof Error ? error.message : error));
-		}
-	};
-
-	private handleHeartbeat = (ws: ServerWebSocket<WebsocketEntityData>, message: BunWebsocketMessage) => {
-		if (message === "ping") {
-			const pong: WebsocketStructuredMessage = { type: "pong", content: { message: "pong" } };
-			ws.send(JSON.stringify(pong));
-			return true;
-		}
-		return false;
-	};
-
-	protected createClient(entity: I_WebsocketEntity): I_WebsocketClient {
-		return new this._clientClass(entity);
-	}
-
-	/**
-	 * Handle the heartbeat
-	 * @param ws - The websocket
-	 * @param message - The message
-	 * @returns True if the heartbeat was handled, false otherwise
-	 */
-	public static Heartbeat(ws: ServerWebSocket<WebsocketEntityData>, message: BunWebsocketMessage) {
-		const self = this.GetInstance<Websocket>();
-		return self.handleHeartbeat(ws, message);
-	}
-
-	/**
-	 * Get the server
-	 * @returns The server
-	 */
-	public static Server() {
-		return this.GetInstance<Websocket>().server;
-	}
-
-	/**
-	 * Broadcast a message to a channel
-	 * @param channel - The channel
-	 * @param message - The message
-	 * @param args - The arguments
-	 */
-	public static Broadcast(channel: string, message: WebsocketStructuredMessage, ...args: any[]) {
-		// Get the server from the singleton instance
-		const ws = this.GetInstance<Websocket>();
-		if (!ws.server) {
-			throw new Error("Websocket server not set");
-		}
-		ws.server.publish(channel, JSON.stringify({ message, args }));
-	}
-
-	/**
-	 * Broadcast a message to all channels
-	 * @param message - The message
-	 * @param args - The arguments
-	 */
-	public static BroadCastAll(message: WebsocketStructuredMessage, ...args: any[]) {
-		const ws = this.GetInstance<Websocket>();
-		ws._channels.forEach((channel) => channel.broadcast(message, ...args));
-	}
-
-	/**
-	 * Join a channel
-	 * @param channel - The channel
-	 * @param entity - The entity
-	 */
-	public static Join(channel: string, entity: I_WebsocketEntity) {
-		const ws = this.GetInstance<Websocket>();
-		const client = ws._clients.get(entity.id);
-		if (!client) return;
-		ws._channels.get(channel)?.addMember(client);
-	}
-
-	/**
-	 * Leave a channel
-	 * @param channel - The channel
-	 * @param entity - The entity
-	 */
-	public static Leave(channel: string, entity: I_WebsocketEntity) {
-		const ws = this.GetInstance<Websocket>();
-		const client = ws._clients.get(entity.id);
-		if (!client) return;
-		ws._channels.get(channel)?.removeMember(client);
-	}
-
-	/**
-	 * Get a client
-	 * @param id - The id of the client
-	 * @param throw_if_nil - Whether to throw an error if the client is not found
-	 * @returns The client
-	 */
-	public static GetClient(id: string, throw_if_nil?: true): I_WebsocketClient;
-	public static GetClient(id: string, throw_if_nil?: false): I_WebsocketClient | undefined;
-	public static GetClient(id: string, throw_if_nil: boolean = true): I_WebsocketClient | undefined {
-		const ws = this.GetInstance<Websocket>();
-		const client = ws._clients.get(id);
-		if (!client && throw_if_nil) throw new Error(`Client with id ${id} not found`);
-		return client;
-	}
-
-	/**
-	 * Get a channel
-	 * @param id - The id of the channel
-	 * @returns The channel
-	 */
-	public static GetChannel(id: string) {
-		const ws = this.GetInstance<Websocket>();
-		return ws._channels.get(id);
-	}
-
-	/**
-	 * Get all channels
-	 * @returns The channels
-	 */
-	public static GetChannels() {
-		const ws = this.GetInstance<Websocket>();
-		return Array.from(ws._channels.values());
-	}
-
-	/**
-	 * Get all clients
-	 * @returns The clients
-	 */
-	public static GetClients() {
-		const ws = this.GetInstance<Websocket>();
-		return Array.from(ws._clients.values());
-	}
-
-	public static GetLastId() {
-		const ws = this.GetInstance<Websocket>();
-		return ws._lastId;
-	}
-
-	/**
-	 * Get the number of clients
-	 * @returns The number of clients
-	 */
-	public static GetClientCount() {
-		const ws = this.GetInstance<Websocket>();
-		return ws._clients.size;
-	}
-
-	/**
-	 * Get the number of channels
-	 * @returns The number of channels
-	 */
-	public static GetChannelCount() {
-		const ws = this.GetInstance<Websocket>();
-		return ws._channels.size;
-	}
-
-	/**
-	 * Create a client
-	 * @param entity - The entity
-	 * @returns The created client
-	 */
-	public static CreateClient(entity: I_WebsocketEntity): I_WebsocketClient {
-		const ws = this.GetInstance<Websocket>();
-		return ws.createClient(entity);
-	}
-
-	/**
-	 * Get all connected clients (excluding connecting/disconnecting)
-	 * @returns Array of connected clients
-	 */
-	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,
-		};
-
-		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

@@ -1,14 +0,0 @@
-// This file is auto-generated by scripts/generate-indexes.ts
-// Do not edit this file directly
-
-export * from './Websocket';
-export * from './websocket.guards';
-export * from './Message';
-export * from './Channel';
-export * from './Client';
-export * from './websocket.enums';
-export * from './websocket.types';
-export { default as Websocket } 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

@@ -1,29 +0,0 @@
-export enum E_WebsocketMessageType {
-	CLIENT_CONNECTED = "client.connected",
-	CLIENT_DISCONNECTED = "client.disconnected",
-	CLIENT_JOIN_CHANNEL = "client.join.channel",
-	CLIENT_LEAVE_CHANNEL = "client.leave.channel",
-	CLIENT_JOIN_CHANNELS = "client.join.channels",
-	CLIENT_LEAVE_CHANNELS = "client.leave.channels",
-	PING = "ping",
-	PONG = "pong",
-	MESSAGE = "message",
-	WHISPER = "whisper",
-	BROADCAST = "broadcast",
-	PROMPT = "prompt",
-	ERROR = "error",
-	SYSTEM = "system",
-}
-
-export enum E_WebsocketMessagePriority {
-	LOW = 0,
-	MEDIUM = 1,
-	HIGH = 2,
-}
-
-export enum E_ClientState {
-	CONNECTING = "connecting",
-	CONNECTED = "connected",
-	DISCONNECTING = "disconnecting",
-	DISCONNECTED = "disconnected",
-}

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

@@ -1,22 +0,0 @@
-import { I_WebsocketClient, I_WebsocketEntity, WebsocketStructuredMessage } from "./websocket.types";
-import { type ServerWebSocket } from "bun";
-
-export function IsWebsocketStructuredMessage(message: any): message is WebsocketStructuredMessage {
-	return typeof message === "object" && message !== null && "type" in message && "content" in message;
-}
-
-export function IsWebsocketEntity(entity: any): entity is I_WebsocketEntity {
-	return (
-		typeof entity === "object" &&
-		entity !== null &&
-		"id" in entity &&
-		"name" in entity &&
-		"ws" in entity &&
-		typeof entity.ws === "object" &&
-		entity.ws !== null &&
-		"send" in entity.ws &&
-		typeof entity.ws.send === "function" &&
-		"close" in entity.ws &&
-		typeof entity.ws.close === "function"
-	);
-}