topsyde-utils 1.3.2 → 2.0.0

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

@@ -1,252 +0,0 @@
-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>;
-
-export type WebsocketChannel<T extends I_WebsocketChannel = Channel> = Map<string, T>;
-export type WebsocketClients = Map<string, I_WebsocketClient>;
-export type WebsocketMessageOptions = {
-	/**
-	 * Additional data to include in the message content
-	 * If an object is provided, it will be merged with the content
-	 * If a primitive value is provided, it will be added as content.data
-	 */
-	data?: any;
-
-	/**
-	 * Client information to include in the message
-	 * Will be added as content.client
-	 */
-	client?: Partial<WebsocketEntityData> & {
-		[key: string]: any;
-	};
-
-	/**
-	 * Channel metadata to include in the message
-	 * If true, all metadata will be included
-	 * If an array of strings, only the specified keys will be included
-	 */
-	includeMetadata?: boolean | string[];
-
-	/**
-	 * Client IDs to exclude from receiving the broadcast
-	 * Useful for sending messages to all clients except the sender
-	 */
-	excludeClients?: string[];
-
-	/**
-	 * Channel to include in the message
-	 * Defaults to the channel of the message
-	 */
-	channel?: string;
-
-	/**
-	 * Whether to include timestamp in the message
-	 * Defaults to true
-	 */
-	includeTimestamp?: boolean;
-
-	/**
-	 * Custom fields to add to the root of the message
-	 * These will be merged with the message object
-	 */
-	customFields?: Record<string, any>;
-
-	/**
-	 * Transform function to modify the final message before sending
-	 * This is applied after all other processing
-	 */
-	transform?: (message: any) => any;
-
-	/**
-	 * Priority of the message (higher numbers = higher priority)
-	 * Can be used by clients to determine processing order
-	 */
-	priority?: number;
-
-	/**
-	 * Message expiration time in milliseconds since epoch
-	 * Can be used by clients to ignore outdated messages
-	 */
-	expiresAt?: number;
-
-	/**
-	 * Metadata to include in the message
-	 * If an array of strings, only the specified keys will be included
-	 */
-	metadata?: boolean | string[] | Record<string, string>;
-};
-
-export type WebsocketMessage<T extends Record<string, any> = Record<string, any>> = {
-	/**
-	 * Message type identifier used for client-side routing
-	 */
-	type: string;
-	/**
-	 * Message content - can be any data structure
-	 * If a string is provided, it will be wrapped in {message: string}
-	 */
-	content: T;
-	/**
-	 * Channel ID
-	 */
-	channel?: string;
-	/**
-	 * Timestamp of the message
-	 */
-	timestamp?: string;
-	/**
-	 * Any additional custom fields
-	 */
-	[key: string]: any;
-};
-
-/**
- * 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;
-export type WebsocketEntityData = { id: WebsocketEntityId; name: WebsocketEntityName };
-
-export interface I_WebsocketEntity extends WebsocketEntityData {
-	ws: ServerWebSocket<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;
-	trackChannel(channel: I_WebsocketChannel): void;
-	untrackChannel(channel: I_WebsocketChannel): void;
-	joinChannel(channel: I_WebsocketChannel, send?: boolean): { success: boolean; reason: string };
-	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 {
-	ws: T;
-}
-
-// New types for the broadcast method
-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;
-	/** Whether to send welcome notification to client on successful join (default: false) */
-	notify?: boolean;
-};
-
-// Options for removeMember operations
-export type RemoveMemberOptions = {
-	/** Whether to send goodbye notification to client on successful leave (default: false) */
-	notify?: boolean;
-};
-
-export interface I_WebsocketChannel<T extends Websocket = Websocket> extends I_WebsocketChannelEntity<T> {
-	limit: number;
-	members: Map<string, I_WebsocketClient>;
-	metadata: Record<string, string>;
-	createdAt: Date;
-	broadcast(message: WebsocketStructuredMessage | string, options?: BroadcastOptions): void;
-	hasMember(client: I_WebsocketEntity | string): boolean;
-	addMember(entity: I_WebsocketClient, options?: AddMemberOptions): AddMemberResult;
-	removeFromMembersMap(entity: I_WebsocketClient): void;
-	removeMember(entity: I_WebsocketEntity, options?: RemoveMemberOptions): I_WebsocketClient | false;
-	getMember(client: I_WebsocketEntity | string): I_WebsocketClient | undefined;
-	getMembers(clients?: string[] | I_WebsocketEntity[]): I_WebsocketClient[];
-	getMetadata(): Record<string, string>;
-	getCreatedAt(): Date;
-	getId(): string;
-	getSize(): number;
-	getLimit(): number;
-	getName(): string;
-	canAddMember(): boolean;
-}
-
-/**
- * Interface for implementing custom WebSocket behavior.
- *
- * @interface I_WebsocketInterface
- *
- * @property {Function} setup - Initializes the WebSocket handler with channels and clients
- *
- * The interface supports three optional handler methods:
- *
- * - `message`: Custom message handler that replaces the default handler
- * - `open`: Connection handler that runs after the default open handler
- * - `close`: Disconnection handler that runs before the default close handler
- */
-export type WebsocketInterfaceHandlers = Partial<WebSocketHandler<WebsocketEntityData>>;
-
-/**
- * Interface for implementing custom WebSocket behavior.
- *
- * @interface I_WebsocketInterface
- *
- * @property {Function} setup - Initializes the WebSocket handler with channels and clients
- *
- * The interface supports three optional handler methods:
- *
- * - `message`: Custom message handler that replaces the default handler
- * - `open`: Connection handler that runs after the default open handler
- * - `close`: Disconnection handler that runs before the default close handler
- */
-export interface I_WebsocketInterface {
-	handlers: (channels: WebsocketChannel, clients: WebsocketClients) => WebsocketInterfaceHandlers;
-}

package/src/server/controller.ts

@@ -1,121 +0,0 @@
-import { ERROR_CODE } from "../errors";
-import Initializable, { InitializableOptions } from "../initializable";
-import { I_ApplicationResponse } from "../types";
-import { Guards } from "../utils";
-
-export type ControllerResponse<T = unknown> = Promise<I_ApplicationResponse<T> | PromiseLike<I_ApplicationResponse<T>>>;
-export type ControllerAction<T> = (req: Request) => ControllerResponse<T>;
-
-export type ControllerMap<T = unknown> = Map<string, ControllerAction<T>>;
-
-export type ControllerOptions<T = unknown> = InitializableOptions & {
-	path: string | undefined;
-	post: Map<string, ControllerAction<T>>;
-	get: ControllerMap<T>;
-	controllerMap: Map<string, ControllerMap<T>>;
-};
-
-export default abstract class Controller extends Initializable {
-	path: string | undefined;
-	post: Map<string, ControllerAction<any>> = new Map();
-	get: ControllerMap = new Map();
-	controllerMap: Map<string, ControllerMap> = new Map();
-
-	constructor() {
-		super();
-		this.POST();
-		this.GET();
-		this.setControllerMap();
-	}
-
-	public static Create<T>(this: new () => T): T {
-		return new this();
-	}
-
-	public static async AsyncCreate<T>(this: new () => T): Promise<T> {
-		return new this();
-	}
-
-	public async call<T>(request: Request): Promise<T> {
-		await this.isInitialized();
-		const action = this.resolve(request);
-		return await action(request);
-	}
-
-	public success<T>(data: T, after_action?: () => void | Promise<void>): I_ApplicationResponse<T> {
-		return { status: true, data, after_action };
-	}
-
-	public failure<T>(data: T, after_action?: () => void | Promise<void>): I_ApplicationResponse<T> {
-		return { status: false, data, after_action };
-	}
-
-	private setControllerMap() {
-		this.controllerMap.set("GET", this.get);
-		this.controllerMap.set("POST", this.post);
-	}
-
-	private resolve(req: Request): Function {
-		const url = new URL(req.url);
-		const endpointArray = url.pathname.split("/");
-		const actionName = endpointArray.slice(2).join("/");
-
-		if (!Guards.IsString(actionName, true)) throw ERROR_CODE.INVALID_ACTION;
-
-		const methodMap = this.controllerMap.get(req.method);
-
-		if (Guards.IsNil(methodMap)) {
-			throw ERROR_CODE.INVALID_METHOD;
-		}
-
-		return this.resolveAction(methodMap, actionName);
-	}
-
-	private resolveAction(methodMap: ControllerMap, actionName: string) {
-		const action = methodMap.get(actionName) as Function;
-
-		if (!Guards.IsFunction(action, true)) {
-			throw ERROR_CODE.NO_ACTION_IN_MAP;
-		}
-
-		return action;
-	}
-
-	/**
-	 * Abstract method that needs to be implemented in derived classes.
-	 * This method is used to map post actions to their corresponding handler methods.
-	 *
-	 * Each action is a string that represents a specific operation, and the handler is a function that performs this operation.
-	 * The handler is bound to the current context (`this`) to ensure it has access to the class's properties and methods.
-	 *
-	 * Example implementation:
-	 *
-	 * ```typescript
-	 * setActionsMap() {
-	 *     this.post.set("action", this.controllerMethod.bind(this));
-	 * }
-	 * ```
-	 *
-	 * In this example, when "https://webserver_url:port/controller/action" is called by the router, the `controllerMethod` method will be called.
-	 */
-	abstract POST(): void;
-
-	/**
-	 * Abstract method that needs to be implemented in derived classes.
-	 * This method is used to map actions to their corresponding handler methods.
-	 *
-	 * Each action is a string that represents a specific operation, and the handler is a function that performs this operation.
-	 * The handler is bound to the current context (`this`) to ensure it has access to the class's properties and methods.
-	 *
-	 * Example implementation:
-	 *
-	 * ```typescript
-	 * setActionsMap() {
-	 *     this.get.set("action", this.controllerMethod.bind(this));
-	 * }
-	 * ```
-	 *
-	 * In this example, when "https://webserver_url:port/controller/action" is called by the router, the `controllerMethod` method will be called.
-	 */
-	abstract GET(): void;
-}

package/src/server/index.ts

@@ -1,7 +0,0 @@
-// This file is auto-generated by scripts/generate-indexes.ts
-// Do not edit this file directly
-
-export * from './controller';
-export * from './service';
-export { default as Controller } from './controller';
-export { default as Service } from './service';

package/src/server/service.ts

@@ -1,36 +0,0 @@
-import { ERROR_CODE } from "../errors";
-import Initializable from "../initializable";
-import { Guards } from "../utils";
-
-export default abstract class Service extends Initializable {
-	async validateRequestBody<T>(request: Request, keys: (keyof T)[]): Promise<T> {
-		return await Service.validateRequestBody(request, keys);
-	}
-
-	static async validateRequestBody<T>(request: Request, keys: (keyof T)[]): Promise<T> {
-		try {
-			let body;
-			try {
-				body = await request.json();
-			} catch (e) {
-				body = await request.text();
-				const cleanedBody = body
-					.replace(/\/\/.*$/gm, "") // Remove comments
-					.replace(/\n/g, "") // Remove newlines
-					.replace(/\s+/g, " ") // Replace multiple spaces with single space
-					.trim(); // Remove leading/trailing whitespace
-
-				body = JSON.parse(cleanedBody);
-			}
-			if (Guards.IsNil(body)) throw ERROR_CODE.REQ_BODY_EMPTY;
-			if (!Guards.IsType<T>(body, keys)) {
-				console.error(`Expected keys: ${keys.join(", ")}`);
-				throw ERROR_CODE.INVALID_METHOD_INPUT;
-			}
-			return body;
-		} catch (e) {
-			if (e instanceof Error || e instanceof SyntaxError) throw "Could not parse request body: " + e;
-			throw e;
-		}
-	}
-}