topsyde-utils 1.3.1 → 2.0.0

package/src/server/bun/router/controller-discovery.ts

@@ -1,94 +0,0 @@
-import { join } from 'path';
-import { readdirSync, statSync } from 'fs';
-import { Lib } from '../../../utils';
-import { Routes } from './routes';
-
-const fallbackRoutes: Routes = {};
-
-/**
- * Dynamically discovers and loads controllers from the components directory
- */
-export class ControllerDiscovery {
-	public static async DiscoverRoutes(componentPaths: string[]) {
-		try {
-			const allDiscoveredRoutes: Routes = {};
-
-			// Discover controllers in all specified component paths
-			for (const path of componentPaths) {
-				const discoveredRoutes = await ControllerDiscovery.Find(path);
-
-				// Merge discovered routes
-				Object.assign(allDiscoveredRoutes, discoveredRoutes);
-			}
-
-			// Use discovered routes if any were found, otherwise use fallback
-			if (Object.keys(allDiscoveredRoutes).length > 0) {
-				Lib.Log(`Using auto-discovered routes from paths: ${componentPaths.join(', ')}`);
-				return allDiscoveredRoutes;
-			} else {
-				Lib.Log('No routes discovered, using fallback routes');
-				return fallbackRoutes;
-			}
-		} catch (error) {
-			// If auto-discovery fails, use fallback routes
-			Lib.Warn('Controller auto-discovery failed, using fallback routes:', error);
-			return fallbackRoutes;
-		}
-	}
-
-	/**
-	 * Discovers controllers in the specified directory
-	 * @param componentsPath Optional custom path to components directory (relative to project root)
-	 * @returns Routes object with discovered controllers
-	 */
-	public static async Find(componentsPath?: string): Promise<Routes> {
-		const routes: Routes = {};
-		
-		// Get project root - use process.cwd() to get the root of the project using this library
-		const projectRoot = process.cwd();
-		
-		// Use provided path or default to components directory
-		const componentsDir = componentsPath
-			? join(projectRoot, componentsPath) // From project root
-			: join(projectRoot, 'src', 'components'); // Default location
-		
-		Lib.Log(`Looking for controllers in: ${componentsDir}`);
-
-		try {
-			// Get all component directories
-			const componentFolders = readdirSync(componentsDir).filter(folder =>
-				statSync(join(componentsDir, folder)).isDirectory()
-			);
-
-			// Process each component folder
-			for (const componentName of componentFolders) {
-				const controllerPath = join(componentsDir, componentName, `${componentName}.controller.ts`);
-
-				try {
-					// Check if controller file exists
-					const controllerFile = Bun.file(controllerPath);
-					if (await controllerFile.exists()) {
-						// Import the controller
-						try {
-							const module = await import(controllerPath);
-							const Controller = module.default;
-
-							if (Controller && typeof Controller === 'function') {
-								routes[componentName] = Controller;
-								Lib.Log(`Registered controller: ${componentName}`);
-							}
-						} catch (err) {
-							Lib.Warn(`Failed to import controller for ${componentName}:`, err);
-						}
-					}
-				} catch (err) {
-					Lib.Warn(`Error processing component ${componentName}:`, err);
-				}
-			}
-		} catch (err) {
-			Lib.Warn(`Error discovering controllers in ${componentsDir}:`, err);
-		}
-
-		return routes;
-	}
-}

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

@@ -1,9 +0,0 @@
-// This file is auto-generated by scripts/generate-indexes.ts
-// Do not edit this file directly
-
-export * from './controller-discovery';
-export * from './routes';
-export * from './router';
-export * from './router.internal';
-export { default as Router } from './router';
-export { default as Router_Internal } from './router.internal';

package/src/server/bun/router/router.internal.ts

@@ -1,64 +0,0 @@
-import { Throwable } from "../../..";
-import { ERROR_CODE } from "../../../errors";
-import Controller from "../../controller";
-import { Debug } from "../../../utils/Lib";
-import { Routes } from "./routes";
-
-class Router_Internal {
-	private registry = new Map<string, Controller>();
-	private routes: Routes;
-
-	constructor(routes?: Routes) {
-		this.routes = routes ?? {};
-	}
-
-	async post<T>(req: Request): Promise<T> {
-		return await this.handleRequest(req);
-	}
-
-	async get<T>(req: Request): Promise<T> {
-		return await this.handleRequest(req);
-	}
-
-	private async handleRequest<T>(request: Request): Promise<T> {
-		const path = this.getPath(request);
-		const output = await this.resolve(path).call<T>(request);
-		return output;
-	}
-
-	private getPath(request: Request): string {
-		return new URL(request.url).pathname;
-	}
-
-	private resolve(path: string): Controller {
-		const controllerKey = path.split("/")[1];
-		return this.register(controllerKey, () => this.controllerFactory(controllerKey));
-	}
-
-	private register(controllerKey: string, factory: () => Controller): Controller {
-		if (!this.registry.has(controllerKey)) {
-			this.registry.set(controllerKey, factory());
-			Debug.Log(`Caching controller: /${controllerKey}`);
-		}
-		return this.registry.get(controllerKey) as Controller;
-	}
-
-	public setRoutes(routes: Routes): void {
-		this.routes = routes;
-	}
-
-	private controllerFactory(controllerKey: string): Controller {
-		try {
-			if (!(controllerKey in this.routes)) throw new Throwable(`${ERROR_CODE.INVALID_CONTROLLER}: ${controllerKey}`, { logError: false });
-
-			const ControllerClass = this.routes[controllerKey as keyof typeof this.routes];
-
-			return new ControllerClass();
-		} catch (err) {
-			console.error("controllerFactory", err);
-			throw err;
-		}
-	}
-}
-
-export default Router_Internal;

package/src/server/bun/router/router.ts

@@ -1,51 +0,0 @@
-import { ERROR_CODE } from "../../../errors";
-import Singleton from "../../../singleton";
-import Guards from "../../../utils/Guards";
-import Router_Internal from "./router.internal";
-import { Routes } from "./routes";
-
-type MethodMap<T> = {
-	[method: string]: (req: Request) => Promise<T>;
-};
-
-class Router extends Singleton {
-	private internal: Router_Internal;
-
-	public constructor(routes?: Routes) {
-		super();
-		this.internal = new Router_Internal(routes);
-	}
-
-	private setRoutes(routes: Routes): void {
-		this.internal.setRoutes(routes);
-	}
-
-	public static async Call<T>(request: Request): Promise<T> {
-		if (Guards.IsNil(request)) throw ERROR_CODE.NO_REQUEST;
-		const methods: MethodMap<T> = this.getMethodMap();
-		const method = methods[request.method];
-
-		if (Guards.IsNil(method)) throw ERROR_CODE.INVALID_METHOD;
-
-		return await method(request);
-	}
-
-	public static SetRoutes(routes: Routes) {
-		this.GetInstance<Router>().setRoutes(routes);
-	}
-
-	private static getMethodMap<T>(): MethodMap<T> {
-		const router = this.GetInstance<Router>();
-		return {
-			GET: async (req) => await router.internal.get(req),
-			POST: async (req) => await router.internal.post(req),
-		};
-	}
-
-	public static GetQueryParams(request: Request): URLSearchParams {
-		const url = new URL(request.url);
-		return url.searchParams;
-	}
-}
-
-export default Router;

package/src/server/bun/router/routes.ts

@@ -1,7 +0,0 @@
-import Controller from "../../controller";
-
-export type Routes = {
-	[key: string]: new () => Controller;
-};
-
-export const routes: Routes = {};

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

@@ -1,310 +0,0 @@
-import { Guards, Lib } from "../../../utils";
-import Message from "./Message";
-import Websocket from "./Websocket";
-import type {
-	BroadcastOptions,
-	I_WebsocketChannel,
-	I_WebsocketClient,
-	I_WebsocketEntity,
-	WebsocketChannel,
-	WebsocketMessage,
-	AddMemberResult,
-	AddMemberOptions,
-	RemoveMemberOptions,
-} 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;
-	public name: string;
-	public limit: number;
-	public members: Map<string, I_WebsocketClient>;
-	public metadata: Record<string, string>;
-	public ws: T;
-
-	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;
-	}
-
-	public broadcast(message: WebsocketMessage | string, options?: BroadcastOptions) {
-		if (Guards.IsString(message)) {
-			const msg: WebsocketMessage = {
-				type: "message",
-				content: { message },
-			};
-			message = msg;
-		}
-
-		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;
-		}
-
-		// Otherwise use pub/sub for everyone
-		this.ws.server.publish(this.id, serializedMessage);
-	}
-
-	// 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);
-	}
-
-	/**
-	 * ATOMIC: Add member to channel (membership only, no side effects)
-	 * Internal method used for rollback-safe operations
-	 * @internal
-	 */
-	private addToMembersMap(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
-		if (!this.canAddMember()) {
-			// 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)),
-			};
-		}
-	}
-
-	/**
-	 * Add a client to this channel with full coordination
-	 * Handles: membership + WebSocket subscription + client-side tracking + optional notification
-	 * This ensures two-way coordination between channel and client
-	 */
-	public addMember(client: I_WebsocketClient, options?: AddMemberOptions): AddMemberResult {
-		// 1. Atomic membership add
-		const result = this.addToMembersMap(client, options);
-		if (!result.success) {
-			return result;
-		}
-
-		try {
-			// 2. Subscribe client's WebSocket to channel pub/sub topic
-			// CRITICAL: Without this, client won't receive channel.broadcast() messages
-			client.subscribe(this.id);
-
-			// 3. Track channel on client side (client's channels map)
-			client.trackChannel(this);
-
-			// 4. Optional welcome notification
-			if (options?.notify) {
-				client.send({
-					type: E_WebsocketMessageType.CLIENT_JOIN_CHANNEL,
-					content: { message: "Welcome to the channel" },
-					channel: this.id,
-					client: client.whoami(),
-				});
-			}
-
-			return result;
-		} catch (error) {
-			// Rollback on failure: remove membership + unsubscribe + untrack
-			this.removeFromMembersMap(client);
-			client.unsubscribe(this.id);
-			client.untrackChannel(this);
-			throw error;
-		}
-	}
-
-	public addMembers(clients: I_WebsocketClient[], options?: AddMemberOptions): AddMemberResult[] {
-		const results: AddMemberResult[] = [];
-		for (const client of clients) {
-			const result = this.addMember(client, options);
-			results.push(result);
-			if (!result.success) {
-				// Stop adding further members on failure
-				break;
-			}
-		}
-		return results;
-	}
-
-	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 removeFromMembersMap(client: I_WebsocketClient): void {
-		this.members.delete(client.id);
-	}
-
-	/**
-	 * Remove a client from this channel with full coordination
-	 * Handles: membership removal + WebSocket unsubscription + client-side tracking removal + optional notification
-	 * This ensures two-way coordination between channel and client
-	 */
-	public removeMember(entity: I_WebsocketEntity, options?: RemoveMemberOptions) {
-		// 1. Check if member exists
-		if (!this.members.has(entity.id)) return false;
-		const client = this.members.get(entity.id);
-		if (!client) return false;
-
-		// 2. Remove from channel members (atomic operation)
-		this.removeFromMembersMap(client);
-
-		// 3. Unsubscribe client's WebSocket from channel pub/sub topic
-		client.unsubscribe(this.id);
-
-		// 4. Untrack channel on client side (remove from client's channels map)
-		client.untrackChannel(this);
-
-		// 5. Optional goodbye notification
-		if (options?.notify) {
-			client.send({
-				type: E_WebsocketMessageType.CLIENT_LEAVE_CHANNEL,
-				content: { message: "You left the channel" },
-				channel: this.id,
-				client: client.whoami(),
-			});
-		}
-
-		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 delete() {
-		//first remove all members
-		this.members.forEach((member) => {
-			this.removeMember(member);
-		});
-		//then clear members map
-		this.members.clear();
-	}
-
-	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;
-		}
-	}
-}