@riaskov/nevo-messaging 1.0.0

package/dist/common/base.client.d.ts

@@ -0,0 +1,12 @@
+import { MessagePayload, MicroserviceConfig, TransportClientOptions } from "./types";
+export declare abstract class BaseMessagingClient {
+    protected readonly options: TransportClientOptions;
+    protected readonly microservices: Map<string, string>;
+    protected constructor(options?: TransportClientOptions);
+    protected registerMicroservices(configs: MicroserviceConfig[]): void;
+    protected query<T = any>(serviceName: string, method: string, params: any): Promise<T>;
+    protected emit(serviceName: string, method: string, params: any): Promise<void>;
+    protected createMessagePayload(method: string, params: any): MessagePayload;
+    protected abstract _queryMicroservice<T>(clientName: string, method: string, params: any): Promise<T>;
+    protected abstract _emitToMicroservice(clientName: string, method: string, params: any): Promise<void>;
+}

package/dist/common/base.client.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseMessagingClient = void 0;
+const node_crypto_1 = require("node:crypto");
+const common_1 = require("../common");
+const errors_1 = require("./errors");
+class BaseMessagingClient {
+    constructor(options) {
+        this.microservices = new Map();
+        this.options = {
+            timeout: 20000,
+            debug: false,
+            ...options
+        };
+    }
+    registerMicroservices(configs) {
+        for (const config of configs) {
+            this.microservices.set(config.serviceName, config.clientName);
+        }
+    }
+    async query(serviceName, method, params) {
+        const clientName = this.microservices.get(serviceName);
+        if (!clientName) {
+            throw new errors_1.MessagingError(common_1.ErrorCode.UNKNOWN, {
+                message: `Microservice ${serviceName} is not registered`,
+                serviceName
+            });
+        }
+        return this._queryMicroservice(clientName, method, params);
+    }
+    async emit(serviceName, method, params) {
+        const clientName = this.microservices.get(serviceName);
+        if (!clientName) {
+            throw new errors_1.MessagingError(common_1.ErrorCode.UNKNOWN, {
+                message: `Microservice ${serviceName} is not registered`,
+                serviceName
+            });
+        }
+        return this._emitToMicroservice(clientName, method, params);
+    }
+    createMessagePayload(method, params) {
+        const uuid = (0, node_crypto_1.randomUUID)();
+        const request = { uuid, method, params };
+        return {
+            key: uuid,
+            value: JSON.stringify(request)
+        };
+    }
+}
+exports.BaseMessagingClient = BaseMessagingClient;

package/dist/common/base.controller.d.ts

@@ -0,0 +1,28 @@
+import { AfterHook, BeforeHook, ServiceMethodHandler, ServiceMethodMapping, SystemAfterHook, SystemBeforeHook, MessageResponse } from "./types";
+export declare abstract class BaseMessageController {
+    protected readonly methodRegistry: ServiceMethodMapping;
+    serviceInstances: any[];
+    protected readonly serviceName: string;
+    protected readonly beforeHook?: BeforeHook;
+    protected readonly afterHook?: AfterHook;
+    protected readonly systemBeforeHook: SystemBeforeHook;
+    protected readonly systemAfterHook: SystemAfterHook;
+    protected readonly debug: boolean;
+    protected constructor(serviceName: string, serviceInstances: any[], methodHandlers: ServiceMethodMapping, options?: {
+        onBefore?: BeforeHook;
+        onAfter?: AfterHook;
+        debug?: boolean;
+    });
+    protected registerMethodHandlers(handlers: ServiceMethodMapping): void;
+    protected findServiceInstance(methodName: string): any;
+    protected executeHandler(handler: ServiceMethodHandler, params: unknown): Promise<unknown>;
+    protected formatResult(result: unknown): Promise<unknown>;
+    protected createErrorResponse(uuid: string, method: string, error: any): MessageResponse;
+    processMessage(data: any): Promise<MessageResponse>;
+    protected abstract extractMessageData(data: any): {
+        method: string;
+        uuid: string;
+        params: any;
+    };
+    abstract handleMessage(data: any): Promise<MessageResponse>;
+}

package/dist/common/base.controller.js

@@ -0,0 +1,159 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseMessageController = void 0;
+const _1 = require("./");
+class BaseMessageController {
+    constructor(serviceName, serviceInstances, methodHandlers, options) {
+        this.methodRegistry = {};
+        this.serviceInstances = [];
+        this.serviceName = serviceName;
+        this.serviceInstances = serviceInstances || [];
+        this.beforeHook = options?.onBefore;
+        this.afterHook = options?.onAfter;
+        this.debug = options?.debug || false;
+        this.systemBeforeHook = (context) => {
+            if (this.debug) {
+                console.log(`[${this.constructor.name}] Received:`, {
+                    method: context.method,
+                    uuid: context.uuid
+                });
+            }
+        };
+        this.systemAfterHook = (context) => {
+            if (this.debug) {
+                console.log(`[${this.constructor.name}] Responding:`, {
+                    method: context.method,
+                    uuid: context.uuid,
+                    success: context.response.params.result !== "error"
+                });
+            }
+        };
+        if (methodHandlers) {
+            this.registerMethodHandlers(methodHandlers);
+        }
+    }
+    registerMethodHandlers(handlers) {
+        Object.entries(handlers).forEach(([methodName, handler]) => {
+            this.methodRegistry[methodName] = handler;
+        });
+    }
+    findServiceInstance(methodName) {
+        for (const instance of this.serviceInstances) {
+            if (typeof instance[methodName] === "function") {
+                return instance;
+            }
+        }
+        return null;
+    }
+    async executeHandler(handler, params) {
+        const { serviceMethod, paramTransformer, resultTransformer } = handler;
+        const serviceInstance = this.findServiceInstance(serviceMethod);
+        if (!serviceInstance) {
+            throw new _1.MessagingError(_1.ErrorCode.UNKNOWN, {
+                message: `No service found with method: ${serviceMethod}`
+            });
+        }
+        const methodArgs = paramTransformer ? paramTransformer(params) : [params];
+        try {
+            const result = await serviceInstance[serviceMethod](...methodArgs);
+            return resultTransformer ? resultTransformer(result) : result;
+        }
+        catch (error) {
+            if (error.message?.includes("is not a function")) {
+                throw new _1.MessagingError(_1.ErrorCode.UNKNOWN, {
+                    message: `Method '${serviceMethod}' not found in service`
+                });
+            }
+            throw error;
+        }
+    }
+    async formatResult(result) {
+        if (result instanceof Promise) {
+            result = await result;
+        }
+        return (0, _1.serializeBigInt)(result);
+    }
+    createErrorResponse(uuid, method, error) {
+        if (error instanceof _1.MessagingError) {
+            return {
+                uuid,
+                method,
+                params: {
+                    result: "error",
+                    error: error.toJSON()
+                }
+            };
+        }
+        console.error(`Unexpected error in ${method}:`, error);
+        return {
+            uuid,
+            method,
+            params: {
+                result: "error",
+                error: {
+                    code: _1.ErrorCode.UNKNOWN,
+                    message: process.env["NODE_ENV"] !== "production" ? error.message : "Internal server error",
+                    details: {},
+                    service: this.serviceName
+                }
+            }
+        };
+    }
+    async processMessage(data) {
+        const { method, uuid, params } = this.extractMessageData(data);
+        const baseContext = {
+            method,
+            serviceName: this.serviceName,
+            uuid,
+            rawData: data
+        };
+        const requestContext = {
+            ...baseContext,
+            params
+        };
+        try {
+            await this.systemBeforeHook(requestContext);
+            let processedParams = params;
+            if (this.beforeHook) {
+                const hookResult = await this.beforeHook(requestContext);
+                if (hookResult !== undefined) {
+                    processedParams = hookResult;
+                }
+            }
+            const handler = this.methodRegistry[method];
+            if (!handler) {
+                throw new _1.MessagingError(_1.ErrorCode.UNKNOWN, {
+                    message: `Method handler not found: ${method}`
+                });
+            }
+            const result = await this.executeHandler(handler, processedParams);
+            const formattedResult = await this.formatResult(result);
+            let response = {
+                uuid,
+                method,
+                params: { result: formattedResult }
+            };
+            const responseContext = {
+                ...baseContext,
+                params: processedParams,
+                result: formattedResult,
+                response
+            };
+            if (this.afterHook) {
+                const hookResponse = await this.afterHook(responseContext);
+                if (hookResponse !== undefined) {
+                    response = hookResponse;
+                }
+            }
+            await this.systemAfterHook({
+                ...responseContext,
+                response
+            });
+            return response;
+        }
+        catch (error) {
+            return this.createErrorResponse(uuid, method, error);
+        }
+    }
+}
+exports.BaseMessageController = BaseMessageController;

package/dist/common/bigint.utils.d.ts

@@ -0,0 +1,7 @@
+export interface BigIntSerializable {
+    [key: string]: any;
+}
+export declare function serializeBigInt(obj: any): any;
+export declare function deserializeBigInt(obj: any): any;
+export declare function stringifyWithBigInt(obj: any): string;
+export declare function parseWithBigInt(str: string): any;

package/dist/common/bigint.utils.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serializeBigInt = serializeBigInt;
+exports.deserializeBigInt = deserializeBigInt;
+exports.stringifyWithBigInt = stringifyWithBigInt;
+exports.parseWithBigInt = parseWithBigInt;
+function serializeBigInt(obj) {
+    if (obj === null || obj === undefined) {
+        return obj;
+    }
+    if (typeof obj === "bigint") {
+        return `${obj.toString()}n`;
+    }
+    if (Array.isArray(obj)) {
+        return obj.map(serializeBigInt);
+    }
+    if (typeof obj === "object") {
+        const serialized = {};
+        for (const [key, value] of Object.entries(obj)) {
+            serialized[key] = serializeBigInt(value);
+        }
+        return serialized;
+    }
+    return obj;
+}
+function deserializeBigInt(obj) {
+    if (obj === null || obj === undefined) {
+        return obj;
+    }
+    if (typeof obj === "string" && /^\d+n$/.test(obj)) {
+        return BigInt(obj.slice(0, -1));
+    }
+    if (Array.isArray(obj)) {
+        return obj.map(deserializeBigInt);
+    }
+    if (typeof obj === "object") {
+        const deserialized = {};
+        for (const [key, value] of Object.entries(obj)) {
+            deserialized[key] = deserializeBigInt(value);
+        }
+        return deserialized;
+    }
+    return obj;
+}
+function stringifyWithBigInt(obj) {
+    return JSON.stringify(serializeBigInt(obj));
+}
+function parseWithBigInt(str) {
+    return deserializeBigInt(JSON.parse(str));
+}

package/dist/common/error-code.d.ts

@@ -0,0 +1,3 @@
+export declare enum ErrorCode {
+    UNKNOWN = 0
+}

package/dist/common/error-code.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ErrorCode = void 0;
+var ErrorCode;
+(function (ErrorCode) {
+    ErrorCode[ErrorCode["UNKNOWN"] = 0] = "UNKNOWN";
+})(ErrorCode || (exports.ErrorCode = ErrorCode = {}));

package/dist/common/error-messages.d.ts

@@ -0,0 +1 @@
+export declare const ErrorMessages: Record<number, string>;

package/dist/common/error-messages.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ErrorMessages = void 0;
+const _1 = require("./");
+exports.ErrorMessages = {
+    [_1.ErrorCode.UNKNOWN]: "An unknown error occurred"
+};

package/dist/common/errors.d.ts

@@ -0,0 +1,9 @@
+import { ErrorCode, ErrorDetails } from "./";
+export declare class MessagingError extends Error {
+    readonly code: ErrorCode;
+    readonly details: Record<string, unknown>;
+    readonly serviceName: string;
+    constructor(code: ErrorCode, options?: Record<string, unknown>, serviceName?: string);
+    toJSON(): ErrorDetails;
+    static fromJSON(error: ErrorDetails): MessagingError;
+}

package/dist/common/errors.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MessagingError = void 0;
+const _1 = require("./");
+class MessagingError extends Error {
+    constructor(code, options, serviceName = "unknown") {
+        super(options?.["message"] || _1.ErrorMessages[code]);
+        this.name = "MessagingError";
+        this.code = code;
+        this.details = { ...(options || {}) };
+        this.serviceName = serviceName;
+        if (process.env["MODE"] === "production") {
+            this.stack = "";
+        }
+        else if (this.stack) {
+            const stack = this.stack.split("\n");
+            this.stack = stack.slice(1).join("\n");
+        }
+    }
+    toJSON() {
+        const error = {
+            code: this.code,
+            message: this.message,
+            details: this.details,
+            service: this.serviceName
+        };
+        if (process.env["MODE"] !== "production" && this.stack) {
+            error.stack = this.stack;
+        }
+        return error;
+    }
+    static fromJSON(error) {
+        const { code, message, details, service, stack } = error;
+        const messagingError = new MessagingError(code, { message, ...details }, service);
+        if (process.env["MODE"] !== "production" && stack) {
+            messagingError.stack = stack;
+        }
+        return messagingError;
+    }
+}
+exports.MessagingError = MessagingError;

package/dist/common/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./types";
+export * from "./errors";
+export * from "./base.client";
+export * from "./base.controller";
+export * from "./service-utils";
+export * from "./error-code";
+export * from "./error-messages";
+export * from "./bigint.utils";

package/dist/common/index.js

@@ -0,0 +1,24 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types"), exports);
+__exportStar(require("./errors"), exports);
+__exportStar(require("./base.client"), exports);
+__exportStar(require("./base.controller"), exports);
+__exportStar(require("./service-utils"), exports);
+__exportStar(require("./error-code"), exports);
+__exportStar(require("./error-messages"), exports);
+__exportStar(require("./bigint.utils"), exports);

package/dist/common/service-utils.d.ts

@@ -0,0 +1,21 @@
+import { ServiceMethodHandler, ServiceMethodMapping } from "./types";
+export type MethodOf<T> = {
+    [K in keyof T]: T[K] extends (...args: any[]) => any ? K : never;
+}[keyof T] & string;
+export type ServiceMethod<TParams = unknown, TResult = unknown> = {
+    params: TParams;
+    result: TResult;
+};
+export type ServiceMethodMap = Record<string, ServiceMethod>;
+export declare function mapServiceMethods<T>(service: T, customMappings?: Record<string, string | [
+    string,
+    {
+        paramTransformer?: (params: unknown) => unknown[];
+        resultTransformer?: (result: unknown) => unknown;
+    }?
+]>): Record<string, ServiceMethodHandler>;
+export declare const createServiceClient: <T extends ServiceMethodMap>(serviceName: string) => {
+    query: <M extends keyof T & string>(method: M, params: T[M]["params"]) => Promise<T[M]["result"]>;
+    emit: <M extends keyof T & string>(method: M, params: T[M]["params"]) => Promise<void>;
+};
+export declare function createMethodHandlers(mappings: Record<string, [string, ((params: unknown) => unknown[])?, ((result: unknown) => unknown)?]>): ServiceMethodMapping;

package/dist/common/service-utils.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createServiceClient = void 0;
+exports.mapServiceMethods = mapServiceMethods;
+exports.createMethodHandlers = createMethodHandlers;
+function mapServiceMethods(service, customMappings) {
+    const serviceMethods = Object.getOwnPropertyNames(Object.getPrototypeOf(service)).filter((name) => name !== "constructor" && typeof service[name] === "function");
+    const resultMappings = {};
+    if (customMappings) {
+        Object.entries(customMappings).forEach(([eventName, mapping]) => {
+            let methodPrefix;
+            let options;
+            if (typeof mapping === "string") {
+                methodPrefix = mapping;
+            }
+            else {
+                ;
+                [methodPrefix, options] = mapping;
+            }
+            const matchingMethod = serviceMethods.find((method) => method.toLowerCase().startsWith(methodPrefix.toLowerCase()));
+            if (matchingMethod) {
+                resultMappings[eventName] = {
+                    serviceMethod: matchingMethod,
+                    paramTransformer: options?.paramTransformer,
+                    resultTransformer: options?.resultTransformer
+                };
+            }
+        });
+    }
+    return resultMappings;
+}
+// @ts-ignore
+const createServiceClient = (serviceName) => ({
+    // @ts-ignore
+    query: (method, params) => {
+        throw new Error("Implementation required in subclass");
+    },
+    // @ts-ignore
+    emit: (method, params) => {
+        throw new Error("Implementation required in subclass");
+    }
+});
+exports.createServiceClient = createServiceClient;
+function createMethodHandlers(mappings) {
+    return Object.entries(mappings).reduce((handlers, [methodName, config]) => {
+        const [serviceMethod, paramTransformer, resultTransformer] = config;
+        handlers[methodName] = {
+            serviceMethod,
+            paramTransformer,
+            resultTransformer
+        };
+        return handlers;
+    }, {});
+}

package/dist/common/signal-router.decorator.d.ts

@@ -0,0 +1,9 @@
+import "reflect-metadata";
+import { Type } from "@nestjs/common";
+import { BeforeHook, AfterHook } from "./types";
+export declare function createSignalRouterDecorator<T>(controllerClass: Type<T>, serviceType: Type<any> | Type<any>[], options?: {
+    before?: BeforeHook;
+    after?: AfterHook;
+    debug?: boolean;
+    eventPattern?: string;
+}): (target: any) => any;

package/dist/common/signal-router.decorator.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSignalRouterDecorator = createSignalRouterDecorator;
+require("reflect-metadata");
+const common_1 = require("@nestjs/common");
+const signal_decorator_1 = require("../signal.decorator");
+function createSignalRouterDecorator(controllerClass, serviceType, options) {
+    return function (target) {
+        (0, common_1.Controller)()(target);
+        const originalPrototype = target.prototype;
+        Reflect.defineProperty(target, "prototype", {
+            value: {
+                ...originalPrototype,
+                onModuleInit() {
+                    if (originalPrototype.onModuleInit) {
+                        originalPrototype.onModuleInit.call(this);
+                    }
+                    const serviceInstances = Array.isArray(serviceType)
+                        ? // @ts-ignore
+                            serviceType.map((type) => this[findPropertyNameByType(this, type)]).filter(Boolean)
+                        : // @ts-ignore
+                            [this[findPropertyNameByType(this, serviceType)]].filter(Boolean);
+                    const signals = (0, signal_decorator_1.getClassSignals)(target);
+                    const serviceName = options?.eventPattern || target.name.toLowerCase().replace("controller", "");
+                    const controller = new controllerClass(serviceName, serviceInstances, createHandlersFromSignals(signals), {
+                        onBefore: options?.before,
+                        onAfter: options?.after,
+                        debug: options?.debug
+                    });
+                    Object.getOwnPropertyNames(controller).forEach((key) => {
+                        if (key !== "constructor" && key !== "serviceInstances") {
+                            this[key] = controller[key];
+                        }
+                    });
+                    const controllerProto = Object.getPrototypeOf(controller);
+                    Object.getOwnPropertyNames(controllerProto).forEach((key) => {
+                        if (key !== "constructor" && typeof controllerProto[key] === "function") {
+                            this[key] = controllerProto[key].bind(this);
+                        }
+                    });
+                }
+            },
+            writable: true,
+            configurable: true
+        });
+        return target;
+    };
+}
+function findPropertyNameByType(instance, type) {
+    for (const key of Object.keys(instance)) {
+        if (instance[key] instanceof type) {
+            return key;
+        }
+    }
+    return null;
+}
+function createHandlersFromSignals(signals) {
+    return signals.reduce((handlers, signal) => {
+        handlers[signal.signalName] = {
+            serviceMethod: signal.methodName,
+            paramTransformer: signal.paramTransformer,
+            resultTransformer: signal.resultTransformer,
+            options: signal.options
+        };
+        return handlers;
+    }, {});
+}

package/dist/common/types.d.ts

@@ -0,0 +1,72 @@
+import { ClientProxy } from "@nestjs/microservices";
+export interface MessagingClientProxy extends ClientProxy {
+    subscribeToResponseOf(pattern: string): void;
+}
+export interface MessagePayload {
+    key: string;
+    value: string;
+}
+export interface MessageRequest<T = unknown> {
+    uuid: string;
+    method: string;
+    params: T;
+}
+export interface MessageResponse<T = unknown> {
+    uuid: string;
+    method: string;
+    params: {
+        result: T | "error";
+        error?: ErrorDetails;
+    };
+}
+export interface ErrorDetails {
+    code: number;
+    message: string;
+    details?: Record<string, unknown>;
+    service?: string;
+    stack?: string;
+}
+export interface HookContext {
+    method: string;
+    serviceName: string;
+    uuid: string;
+    rawData: unknown;
+}
+export interface BeforeHookContext extends HookContext {
+    params: unknown;
+    options?: Record<string, unknown>;
+}
+export interface AfterHookContext extends HookContext {
+    params: unknown;
+    result: unknown;
+    response: MessageResponse;
+    options?: Record<string, unknown>;
+}
+export type BeforeHook = (context: BeforeHookContext) => Promise<unknown> | unknown;
+export type AfterHook = (context: AfterHookContext) => Promise<MessageResponse> | MessageResponse;
+export type SystemBeforeHook = (context: BeforeHookContext) => Promise<void> | void;
+export type SystemAfterHook = (context: AfterHookContext) => Promise<void> | void;
+export interface ServiceMethodHandler {
+    serviceMethod: string;
+    paramTransformer?: (params: unknown) => unknown[];
+    resultTransformer?: (result: unknown) => unknown;
+    options?: Record<string, unknown>;
+}
+export interface ServiceMethodMapping {
+    [methodName: string]: ServiceMethodHandler;
+}
+export interface TransportClientOptions {
+    clientId?: string;
+    timeout?: number;
+    debug?: boolean;
+    [key: string]: any;
+}
+export interface TransportServerOptions {
+    serviceName: string;
+    debug?: boolean;
+    [key: string]: any;
+}
+export interface MicroserviceConfig {
+    serviceName: string;
+    clientName: string;
+}

package/dist/common/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./signal.decorator";
+export * from "./signal-router.utils";
+export * from "./transports";
+export * from "./common";