topsyde-utils 1.0.150 → 1.0.152

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

@@ -0,0 +1,186 @@
+import { ServerWebSocket, WebSocketHandler } from "bun";
+import Channel from "./Channel";
+import Websocket from "./Websocket";
+
+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;
+};
+
+export type 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>;
+	send(message: WebsocketStructuredMessage): any;
+	subscribe(channel: string): any;
+	joinChannel(channel: I_WebsocketChannel, send?: boolean): void;
+	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;
+}
+
+export interface I_WebsocketChannelEntity<T extends Websocket = Websocket> extends WebsocketEntityData {
+	ws: T;
+}
+
+// New types for the broadcast method
+export type BroadcastOptions = WebsocketMessageOptions & {
+	debug?: 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, options?: BroadcastOptions): void;
+	hasMember(client: I_WebsocketEntity | string): boolean;
+	addMember(entity: I_WebsocketClient): I_WebsocketClient | false;
+	removeMember(entity: I_WebsocketEntity): 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

@@ -0,0 +1,121 @@
+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): I_ApplicationResponse<T> {
+		return { status: true, data };
+	}
+
+	public failure<T>(data: T): I_ApplicationResponse<T> {
+		return { status: false, data };
+	}
+
+	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

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

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

package/src/singleton.ts

@@ -0,0 +1,28 @@
+export default abstract class Singleton {
+	private static readonly _instances = new Map<string, Singleton>();
+
+	protected timestamp: Date;
+
+	protected constructor() {
+		this.timestamp = new Date();
+	}
+
+	public static GetInstance<T extends Singleton>(...args: any[]): T {
+		const className = this.name;
+
+		if (!Singleton._instances.has(className)) {
+			const instance = Reflect.construct(this, args) as T;
+			Singleton._instances.set(className, instance);
+		}
+
+		return Singleton._instances.get(className) as T;
+	}
+
+	public static ResetInstances(): void {
+		Singleton._instances.clear();
+	}
+
+	public static ResetInstance(className: string): void {
+		Singleton._instances.delete(className);
+	}
+}

package/src/throwable.ts

@@ -0,0 +1,87 @@
+import { Guards, Lib } from "./utils";
+
+
+/**
+ * @description Custom error class for errors that are expected to be thrown
+ * and should not trigger retry mechanisms or be reported to error monitoring services.
+ *
+ * Use this class when you want to throw an error that:
+ * 1. Is an expected part of the application flow
+ * 2. Should not be retried by retry handlers
+ * 3. Should not be reported to error monitoring services like Sentry
+ */
+class Throwable extends Error {
+	/** Flag indicating this is a deliberate error that shouldn't be retried */
+	public readonly isDeliberate: boolean = true;
+
+	/** Original error if this Throwable wraps another error */
+	public readonly originalError?: Error;
+
+	/** Additional context that might be helpful for debugging */
+	public readonly context?: Record<string, unknown>;
+
+	/**
+	 * Create a new Throwable error
+	 * @param message Error message or existing Error object to wrap
+	 * @param options Configuration options
+	 */
+	constructor(
+		message: unknown,
+		options: {
+			/** Whether to log this error to console (default: true) */
+			logError?: boolean;
+			/** Additional context data to attach to the error */
+			context?: Record<string, unknown>;
+		} = {},
+	) {
+		const { logError = true, context } = options;
+
+		// Format the message appropriately based on type
+		const _message = Guards.IsString(message) ? message : message instanceof Error ? message.message : JSON.stringify(message);
+
+		super(_message);
+		this.name = "Throwable";
+		this.context = context;
+
+		// Log the error if requested
+		if (logError) {
+			if (context) {
+				Lib.$Log("Throwable: ", _message, "Context:", context);
+			} else {
+				Lib.$Log("Throwable: ", message);
+			}
+		}
+
+		// Capture stack trace and cause if wrapping an existing error
+		if (message instanceof Error) {
+			this.stack = message.stack;
+			this.cause = message.cause;
+			this.originalError = message;
+		}
+	}
+
+	/**
+	 * Check if an error is a Throwable
+	 * @param e Any error to check
+	 * @returns True if the error is a Throwable
+	 */
+	static IsThrowable(e: any): e is Throwable {
+		return e instanceof Throwable;
+	}
+
+	/**
+	 * Create a Throwable from any error or message
+	 * @param error Error or message to convert
+	 * @param context Additional context to attach
+	 * @returns A new Throwable instance
+	 */
+	static from(error: unknown, context?: Record<string, unknown>): Throwable {
+		if (error instanceof Throwable) {
+			return error;
+		}
+
+		return new Throwable(error, { context });
+	}
+}
+
+export default Throwable;

package/src/types.ts

@@ -0,0 +1,10 @@
+export type ClassConstructor<T> = new (...args: any[]) => T;
+export type NonNullableType<T> = Exclude<T, null | undefined>;
+type ObjectKeysValues = string | number | string[] | number[] | null;
+export type ObjectKeys<T, U = ObjectKeysValues> = Partial<Record<keyof T, U>>;
+export type KVObj<T> = { key: string; value: T };
+export interface I_ApplicationResponse<T = unknown> {
+	status: boolean | number;
+	data: T;
+	error?: T;
+}

package/src/utils/Console.ts

@@ -0,0 +1,85 @@
+import { LOG_COLORS, LOG_ICONS } from "../consts";
+
+export class Console {
+	/**
+	 * Print a blank line
+	 */
+	static blank(): void {
+		console.log("");
+	}
+
+	/**
+	 * Print a success message
+	 */
+	static success(message: string): void {
+		console.log(`  ${LOG_COLORS.text.green}${LOG_ICONS.success}${LOG_COLORS.reset}  ${message}`);
+	}
+
+	/**
+	 * Print an info message
+	 */
+	static info(message: string): void {
+		console.log(`  ${LOG_COLORS.text.blue}${LOG_ICONS.info}${LOG_COLORS.reset}  ${message}`);
+	}
+
+	/**
+	 * Print a warning message
+	 */
+	static warning(message: string): void {
+		console.log(`  ${LOG_COLORS.text.yellow}${LOG_ICONS.warning}${LOG_COLORS.reset}  ${message}`);
+	}
+
+	/**
+	 * Print an error message
+	 */
+	static error(message: string): void {
+		console.log(`  ${LOG_COLORS.text.red}${LOG_ICONS.error}${LOG_COLORS.reset}  ${message}`);
+	}
+
+	/**
+	 * Print a debug message
+	 */
+	static debug(message: string): void {
+		console.log(`  ${LOG_COLORS.text.magenta}${LOG_ICONS.debug}${LOG_COLORS.reset}  ${message}`);
+	}
+
+	/**
+	 * Print a list item with an arrow
+	 */
+	static item(label: string, value: string): void {
+		console.log(`  ${LOG_COLORS.text.cyan}${LOG_ICONS.arrow}${LOG_COLORS.reset}  ${LOG_COLORS.bright}${label}:${LOG_COLORS.reset} ${value}`);
+	}
+
+	/**
+	 * Print a header with optional emoji
+	 */
+	static header(text: string, emoji?: string): void {
+		const icon = emoji ? `${emoji} ` : "";
+		console.log(`  ${icon}${LOG_COLORS.bright}${text}${LOG_COLORS.reset}`);
+	}
+
+	/**
+	 * Print a subheader with dimmed text
+	 */
+	static subheader(text: string): void {
+		console.log(`  ${LOG_COLORS.dim}${text}${LOG_COLORS.reset}`);
+	}
+
+	/**
+	 * Print a ready message with timing
+	 */
+	static ready(timeMs: number): void {
+		console.log(
+			`  ${LOG_COLORS.text.green}✓${LOG_COLORS.reset}  ${LOG_COLORS.dim}Ready in${LOG_COLORS.reset} ${LOG_COLORS.text.cyan}${timeMs}ms${LOG_COLORS.reset}`,
+		);
+	}
+
+	/**
+	 * Get a colored string
+	 */
+	static colorize(text: string, color: keyof typeof LOG_COLORS.text): string {
+		return `${LOG_COLORS.text[color]}${text}${LOG_COLORS.reset}`;
+	}
+}
+
+export default Console;

package/src/utils/Guards.ts

@@ -0,0 +1,61 @@
+import type { NonNullableType } from "../types";
+import Lib from "./Lib";
+
+class Guards {
+	public static IsString(value: any): value is string;
+	public static IsString(value: any, as_typeof: boolean): value is NonNullableType<string>;
+	public static IsString(value: any, as_typeof: boolean, excludeNull: true): value is NonNullableType<string>;
+	public static IsString(value: any, as_typeof: boolean = false, excludeNull = false): value is string | NonNullableType<string> {
+		const output = Lib.IsString(value, as_typeof);
+		return excludeNull ? !Guards.IsNil(value) && output : output;
+	}
+
+	public static IsNumber(value: any): value is number;
+	public static IsNumber(value: any, as_typeof: boolean): value is NonNullableType<number>;
+	public static IsNumber(value: any, as_typeof: boolean, excludeNull: true): value is NonNullableType<number>;
+	public static IsNumber(value: any, as_typeof: boolean = false, excludeNull = false): value is number | NonNullableType<number> {
+		const output = Lib.IsNumber(value, as_typeof);
+		return excludeNull ? !Guards.IsNil(value) && output : output;
+	}
+
+	public static IsBoolean(value: any): value is boolean;
+	public static IsBoolean(value: any, excludeNull: true): value is NonNullableType<boolean>;
+	public static IsBoolean(value: any, excludeNull = false): value is boolean | NonNullableType<boolean> {
+		const output = Lib.GetType(value, true) === "boolean";
+		return excludeNull ? !Guards.IsNil(value) && output : output;
+	}
+
+	public static IsArray<T>(value: any): value is T[];
+	public static IsArray<T>(value: any, excludeNull: true): value is NonNullableType<T[]>;
+	public static IsArray<T>(value: any, excludeNull = false): value is T[] | NonNullableType<T[]> {
+		const output = Lib.IsArray(value);
+		return excludeNull ? !Guards.IsNil(value) && output : output;
+	}
+
+	public static IsObject(value: any): value is object;
+	public static IsObject(value: any, excludeNull: true): value is NonNullableType<object>;
+	public static IsObject(value: any, excludeNull = false): value is object | NonNullableType<object> {
+		const output = Lib.IsObject(value);
+		return excludeNull ? !Guards.IsNil(value) && output : output;
+	}
+
+	public static IsFunction(value: any): value is Function;
+	public static IsFunction(value: any, excludeNull: true): value is NonNullableType<Function>;
+	public static IsFunction(value: any, excludeNull = false): value is Function | NonNullableType<Function> {
+		const output = Lib.IsFunction(value);
+		return excludeNull ? !Guards.IsNil(value) && output : output;
+	}
+
+	public static IsNil(value: any): value is null | undefined {
+		return Lib.IsNil(value);
+	}
+
+	public static IsType<T>(obj: any): obj is T;
+	public static IsType<T>(obj: any, keys: (keyof T)[]): obj is T;
+	public static IsType<T>(obj: any, keys?: (keyof T)[]): obj is T {
+		if (!keys) return !this.IsNil(obj);
+		return keys.every((key) => key in obj);
+	}
+}
+
+export default Guards;