topsyde-utils 1.3.2 → 2.0.1

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;
-		}
-	}
-}

package/src/utils/BaseDto.ts

@@ -1,77 +0,0 @@
-import type { ClassConstructor, ClassTransformOptions } from "class-transformer";
-import { instanceToPlain, plainToInstance } from "class-transformer";
-import Guards from "./Guards";
-import { ValidationError, validateSync } from "class-validator";
-
-/**
- * Base typesafe class for Data Transfer Objects (DTOs)
- */
-export abstract class Dto {
-	/**
-	 * Default options for class transformation
-	 */
-	protected static readonly defaultTransformOptions: ClassTransformOptions = {
-		excludeExtraneousValues: true,
-		enableCircularCheck: true,
-		exposeDefaultValues: true,
-		enableImplicitConversion: false, // Safer default, especially when using class-validator
-	};
-
-	/**
-	 * Validates the DTO instance
-	 * @throws ValidationError[] if validation fails
-	 */
-	public validate(): ValidationError[] {
-		const errors = validateSync(this, {
-			validationError: { target: false },
-			forbidUnknownValues: true,
-		});
-		if (errors.length > 0) {
-			throw errors;
-		}
-		return errors;
-	}
-
-	/**
-	 * Converts the DTO to a plain object
-	 * @param options - Class transformer options for controlling exposure and transformation
-	 * @returns Plain object representation of the DTO
-	 */
-	public toJSON<T = Record<string, unknown>>(include_undefined: boolean = true, options?: ClassTransformOptions): T {
-		const value = instanceToPlain(this, {
-			...Dto.defaultTransformOptions,
-			...options,
-		}) as T;
-
-		if (!include_undefined) {
-			return Object.fromEntries(Object.entries(value as Record<string, unknown>).filter(([_, v]) => !Guards.IsNil(v))) as T;
-		}
-
-		return value;
-	}
-
-	/**
-	 * Creates a new instance of the DTO with validation (infers class from `this`)
-	 * @param data - Data to create the DTO from
-	 * @param options - Class transformer options
-	 * @returns New instance of the DTO
-	 */
-	public static Create<T extends Dto>(this: ClassConstructor<T>, data: Record<string, unknown>, options: ClassTransformOptions = {}): T {
-		const instance = plainToInstance(this, data, {
-			...Dto.defaultTransformOptions,
-			...options,
-		});
-
-		return instance;
-	}
-
-	/**
-	 * Creates an array of DTOs from an array of plain objects
-	 */
-	public static CreateMany<T extends Dto>(this: ClassConstructor<T>, dataArray: Record<string, unknown>[], options: ClassTransformOptions = {}): T[] {
-		return plainToInstance(this, dataArray, {
-			...Dto.defaultTransformOptions,
-			...options,
-		}) as T[];
-	}
-}

package/src/utils/BaseEntity.ts

@@ -1,49 +0,0 @@
-import { ClassConstructor, instanceToPlain, plainToInstance } from "class-transformer";
-import { Dto } from "./BaseDto";
-
-export default abstract class BaseEntity {
-	/**
-	 * Converts entity to plain object
-	 */
-	public toJSON<T = Record<string, unknown>>(): T {
-		return instanceToPlain(this) as T;
-	}
-
-	/**
-	 * Abstract method - entities must define how to convert to DTO
-	 */
-	public abstract toDto(): Dto;
-
-	/**
-	 * Updates entity with partial data (immutable - returns new instance)
-	 * @param data - Partial data to update
-	 * @param validate - Whether to validate after update (default: true)
-	 */
-	public update<T extends BaseEntity>(this: T, data: Partial<T>): T {
-		const updated = Object.assign(Object.create(Object.getPrototypeOf(this)), this, data);
-		return updated;
-	}
-
-	/**
-	 * Creates a new entity instance from DTO (infers class from `this`)
-	 *
-	 * NOTE: This is a BASE implementation that uses plainToInstance.
-	 * Derived classes should override if they need custom construction logic.
-	 *
-	 * @param dto - DTO to create entity from
-	 */
-	public static FromDto<T extends BaseEntity>(this: ClassConstructor<T>, dto: Dto): T {
-		const instance = plainToInstance(this, dto.toJSON());
-		return instance;
-	}
-
-	/**
-	 * Creates multiple entities from DTOs
-	 */
-	public static FromDtos<T extends BaseEntity>(this: ClassConstructor<T>, dtos: Dto[]): T[] {
-		return plainToInstance(
-			this,
-			dtos.map((dto) => dto.toJSON()),
-		);
-	}
-}

package/src/utils/dto_validators/IsNumberOrRangeConstraint.ts

@@ -1,32 +0,0 @@
-import { ValidatorConstraint, ValidatorConstraintInterface, ValidationArguments } from "class-validator";
-
-/**
- * Custom validator for number | number[] type
- * Validates that value is either a single number or a 2-element number array [min, max]
- */
-
-@ValidatorConstraint({ name: "isNumberOrRange", async: false })
-export class IsNumberOrRangeConstraint implements ValidatorConstraintInterface {
-	validate(value: any, args: ValidationArguments) {
-		// Allow single number
-		if (typeof value === "number" && !isNaN(value)) {
-			return true;
-		}
-
-		// Allow array of exactly 2 numbers (range)
-		if (Array.isArray(value)) {
-			if (value.length !== 2) return false;
-			if (typeof value[0] !== "number" || isNaN(value[0])) return false;
-			if (typeof value[1] !== "number" || isNaN(value[1])) return false;
-			// Optional: Validate min <= max
-			if (value[0] > value[1]) return false;
-			return true;
-		}
-
-		return false;
-	}
-
-	defaultMessage(args: ValidationArguments) {
-		return "Value must be a number or a 2-element number array [min, max]";
-	}
-}

package/src/utils/dto_validators/index.ts

@@ -1,4 +0,0 @@
-// This file is auto-generated by scripts/generate-indexes.ts
-// Do not edit this file directly
-
-export * from './IsNumberOrRangeConstraint';