topsyde-utils 1.0.149 → 1.0.151

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

@@ -0,0 +1,157 @@
+import { Guards, Lib } from "../../../utils";
+import Message from "./Message";
+import Websocket from "./Websocket";
+import type {
+	BroadcastOptions,
+	I_WebsocketChannel,
+	I_WebsocketClient,
+	I_WebsocketEntity,
+	WebsocketChannel,
+	WebsocketMessage,
+	WebsocketStructuredMessage,
+} from "./websocket.types";
+
+export default class Channel<T extends Websocket = Websocket> implements I_WebsocketChannel<T> {
+	public createdAt: Date = new Date();
+	public id: string;
+	public name: string;
+	public limit: number;
+	public members: Map<string, I_WebsocketClient>;
+	public metadata: Record<string, string>;
+	public ws: T;
+	// Message template for reuse
+	private messageTemplate: WebsocketStructuredMessage<any>;
+	private message: Message;
+
+	constructor(id: string, name: string, ws: T, limit?: number, members?: Map<string, I_WebsocketClient>, metadata?: Record<string, string>) {
+		this.id = id;
+		this.name = name;
+		this.limit = limit ?? 5;
+		this.members = members ?? new Map();
+		this.metadata = metadata ?? {};
+		this.ws = ws;
+		this.message = new Message();
+		this.messageTemplate = {
+			type: "",
+			content: {},
+			channel: this.id,
+			timestamp: "",
+		};
+	}
+
+	public broadcast(message: WebsocketMessage, options?: BroadcastOptions) {
+		const output = this.message.create(message, { ...options, channel: this.id });
+		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);
+						}
+					}
+					return;
+				}
+			}
+		}
+		// Publish to the channel
+		this.ws.server.publish(this.id, this.message.serialize(output));
+	}
+
+	// Helper method for filtered metadata
+	private getFilteredMetadata(keys: string[]) {
+		const metadata = this.getMetadata();
+		const filtered: Record<string, string> = {};
+
+		for (const key of keys) {
+			if (metadata[key] !== undefined) {
+				filtered[key] = metadata[key];
+			}
+		}
+
+		return filtered;
+	}
+
+	public hasMember(client: I_WebsocketEntity | string) {
+		if (typeof client === "string") return this.members.has(client);
+		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 removeMember(entity: I_WebsocketEntity) {
+		if (!this.members.has(entity.id)) return false;
+		const client = this.members.get(entity.id);
+		if (!client) return false;
+		client.leaveChannel(this);
+		this.members.delete(entity.id);
+		return client;
+	}
+
+	public getMember(client: I_WebsocketEntity | string) {
+		if (typeof client === "string") return this.members.get(client);
+		return this.members.get(client.id);
+	}
+
+	public getMembers(clients?: string[] | I_WebsocketEntity[]): I_WebsocketClient[] {
+		if (!clients) return Array.from(this.members.values());
+		return clients.map((client) => this.getMember(client)).filter((client) => client !== undefined) as I_WebsocketClient[];
+	}
+
+	public getMetadata() {
+		return this.metadata;
+	}
+
+	public getCreatedAt() {
+		return this.createdAt;
+	}
+
+	public getId() {
+		return this.id;
+	}
+
+	public getName() {
+		return this.name;
+	}
+
+	public getLimit() {
+		return this.limit;
+	}
+
+	public getSize() {
+		return this.members.size;
+	}
+
+	public canAddMember() {
+		const size = this.getSize();
+		return size < this.limit;
+	}
+
+	public static GetChannelType(channels: WebsocketChannel<I_WebsocketChannel> | undefined) {
+		if (!channels) return Channel;
+		if (channels.size > 0) {
+			const firstChannel = channels.values().next().value;
+			if (firstChannel) {
+				return firstChannel.constructor as typeof Channel;
+			} else {
+				return Channel;
+			}
+		} else {
+			Lib.Warn("Channels are empty, using default channel class");
+			return Channel;
+		}
+	}
+}

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

@@ -0,0 +1,129 @@
+import { ServerWebSocket } from "bun";
+import type {
+	I_WebsocketClient,
+	WebsocketEntityData,
+	WebsocketChannel,
+	WebsocketStructuredMessage,
+	I_WebsocketEntity,
+	I_WebsocketChannel,
+} from "./websocket.types";
+import { E_WebsocketMessageType } from "./websocket.enums";
+import { Lib } from "../../../utils";
+
+export default class Client implements I_WebsocketClient {
+	private _id: string;
+	private _name: string;
+	private _ws: ServerWebSocket<WebsocketEntityData>;
+	private _channels: WebsocketChannel<I_WebsocketChannel>;
+
+	private set ws(value: ServerWebSocket<WebsocketEntityData>) {
+		this._ws = value;
+	}
+
+	public get ws(): ServerWebSocket<WebsocketEntityData> {
+		return this._ws;
+	}
+
+	private set id(value: string) {
+		this._id = value;
+	}
+
+	public get id(): string {
+		return this._id;
+	}
+
+	public get name(): string {
+		return this._name;
+	}
+
+	private set name(value: string) {
+		this._name = value;
+	}
+
+	private set channels(value: WebsocketChannel<I_WebsocketChannel>) {
+		this._channels = value;
+	}
+
+	public get channels(): WebsocketChannel<I_WebsocketChannel> {
+		return this._channels;
+	}
+
+	constructor(entity: I_WebsocketEntity) {
+		this._id = entity.id;
+		this._name = entity.name;
+		this._ws = entity.ws;
+		this.ws = entity.ws;
+		this._channels = new Map();
+	}
+
+	public joinChannel(channel: I_WebsocketChannel, send: boolean = true) {
+		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(),
+			});
+	}
+
+	public leaveChannel(channel: I_WebsocketChannel, send: boolean = true) {
+		const channel_id = channel.getId();
+		this.channels.delete(channel_id);
+		this.unsubscribe(channel_id);
+		if (send)
+			this.send({
+				type: E_WebsocketMessageType.CLIENT_LEAVE_CHANNEL,
+				content: { message: "Left the channel" },
+				channel: channel_id,
+				client: this.whoami(),
+			});
+	}
+
+	public joinChannels(channels: I_WebsocketChannel[], send: boolean = true) {
+		channels.forEach((channel) => {
+			this.joinChannel(channel, false);
+		});
+		if (send) this.send({ type: E_WebsocketMessageType.CLIENT_JOIN_CHANNELS, content: { channels }, client: this.whoami() });
+	}
+
+	public leaveChannels(channels?: I_WebsocketChannel[], send: boolean = true) {
+		if (!channels) channels = Array.from(this.channels.values());
+		channels.forEach((channel) => {
+			this.leaveChannel(channel, false);
+		});
+		if (send) this.send({ type: E_WebsocketMessageType.CLIENT_LEAVE_CHANNELS, content: { channels }, client: this.whoami() });
+	}
+
+	public whoami(): { id: string; name: string } {
+		return { id: this.id, name: this.name };
+	}
+
+	public send(message: WebsocketStructuredMessage) {
+		this.ws.send(JSON.stringify({ client: this.whoami(), ...message }));
+	}
+
+	public subscribe(channel: string): void {
+		this.ws.subscribe(channel);
+	}
+
+	public unsubscribe(channel: string): void {
+		this.ws.unsubscribe(channel);
+	}
+
+	public static GetClientType(clients: Map<string, I_WebsocketClient> | undefined): typeof Client {
+		if (!clients) return Client;
+		if (clients.size > 0) {
+			const firstClient = clients.values().next().value;
+			if (firstClient) {
+				return firstClient.constructor as typeof Client;
+			}
+		}
+
+		// Fallback to default Client class
+		Lib.Warn("Clients map is empty, using default client class");
+		return Client;
+	}
+}

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

@@ -0,0 +1,106 @@
+import Guards from "../../../utils/Guards";
+import { WebsocketStructuredMessage, WebsocketMessage, WebsocketMessageOptions, I_WebsocketChannel, I_WebsocketClient } from "./websocket.types";
+
+export default class Message {
+	private messageTemplate: WebsocketStructuredMessage<any>;
+
+	constructor() {
+		this.messageTemplate = { type: "", content: {}, channel: "", timestamp: "", client: undefined };
+	}
+
+	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
+		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 in a single pass 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,
+				};
+			} else {
+				delete output.client;
+			}
+
+			// Include channel metadata if requested
+			if (options.includeMetadata !== false) 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) {
+				const transformed = options.transform(output);
+				return transformed;
+			}
+		} else {
+			output.timestamp = new Date().toISOString();
+		}
+
+		return output;
+	}
+
+	public createWhisper(message: Omit<WebsocketMessage, "type">, options?: WebsocketMessageOptions) {
+		return this.create({ ...message, content: message.content, channel: message.channel, type: "whisper" }, options);
+	}
+
+	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 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);
+	}
+}

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

@@ -0,0 +1,221 @@
+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;
+};
+
+export interface I_WebsocketConstructor {
+	ws_interface?: I_WebsocketInterface;
+	channels?: WebsocketChannel;
+	clientClass?: typeof Client;
+	channelClass?: typeof Channel;
+	options?: WebsocketConstructorOptions;
+}
+
+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 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", 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.success("Websocket server set");
+	}
+
+	public createChannel(id: string, name: string, limit?: number): I_WebsocketChannel {
+		if (this._channels.has(id)) return this._channels.get(id) as I_WebsocketChannel;
+		const channel = new this._channelClass(id, name, this, limit);
+		this._channels.set(id, channel);
+		return channel;
+	}
+
+	public removeChannel(id: string) {
+		this._channels.delete(id);
+	}
+
+	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) => {
+		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.BraodcastAll({ type: "client.message.received", content: { message } });
+	};
+
+	private clientConnected = (ws: ServerWebSocket<WebsocketEntityData>) => {
+		if (this._options.debug) Lib.Log("Client connected", ws.data);
+		
+		if (this._ws_interface_handlers.open) this._ws_interface_handlers.open(ws);
+		
+		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);
+		
+		client.send({ type: E_WebsocketMessageType.CLIENT_CONNECTED, content: { message: "Welcome to the server", client: client.whoami() } });
+		global.addMember(client);
+		
+		if (this._ws_interface_handlers.open) this._ws_interface_handlers.open(ws);
+	};
+
+	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;
+		
+		this._channels.forEach((channel) => {
+			channel.removeMember(client);
+		});
+
+		this._clients.delete(ws.data.id);
+	};
+
+	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);
+	}
+
+	public static Heartbeat(ws: ServerWebSocket<WebsocketEntityData>, message: BunWebsocketMessage) {
+		const self = this.GetInstance<Websocket>();
+		return self.handleHeartbeat(ws, message);
+	}
+
+	public static Server() {
+		return this.GetInstance<Websocket>().server;
+	}
+
+	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 }));
+	}
+
+	public static BraodcastAll(message: WebsocketStructuredMessage, ...args: any[]) {
+		const ws = this.GetInstance<Websocket>();
+		ws._channels.forEach((channel) => channel.broadcast(message, ...args));
+	}
+
+	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);
+	}
+
+	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);
+	}
+
+	public static GetClient(id: string) {
+		const ws = this.GetInstance<Websocket>();
+		return ws._clients.get(id);
+	}
+
+	public static GetChannel(id: string) {
+		const ws = this.GetInstance<Websocket>();
+		return ws._channels.get(id);
+	}
+
+	public static GetChannels() {
+		const ws = this.GetInstance<Websocket>();
+		return Array.from(ws._channels.values());
+	}
+
+	public static GetClients() {
+		const ws = this.GetInstance<Websocket>();
+		return Array.from(ws._clients.values());
+	}
+
+	public static GetClientCount() {
+		const ws = this.GetInstance<Websocket>();
+		return ws._clients.size;
+	}
+
+	public static GetChannelCount() {
+		const ws = this.GetInstance<Websocket>();
+		return ws._channels.size;
+	}
+
+	public static CreateClient(entity: I_WebsocketEntity): I_WebsocketClient {
+		const ws = this.GetInstance<Websocket>();
+		return ws.createClient(entity);
+	}
+
+	public static GenerateMessage(): WebsocketStructuredMessage {
+		const msg: WebsocketStructuredMessage = {
+			type: "",
+			content: {},
+		};
+		return msg;
+	}
+}

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

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

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

@@ -0,0 +1,22 @@
+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,
+}

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

@@ -0,0 +1,6 @@
+import { WebsocketStructuredMessage } from "./websocket.types";
+
+export function IsWebsocketStructuredMessage(message: any): message is WebsocketStructuredMessage {
+	return typeof message === "object" && message !== null && "type" in message && "content" in message;
+}
+