message-nexus 1.1.1 → 1.1.3

package/dist/index.d.cts

@@ -78,16 +78,18 @@ interface LogEntry {
     context?: string;
 }
 type LogHandler = (entry: LogEntry) => void;
-interface LoggerInterface {
+interface SimpleLogger {
+    debug(message: string, metadata?: Record<string, unknown>): void;
+    info(message: string, metadata?: Record<string, unknown>): void;
+    warn(message: string, metadata?: Record<string, unknown>): void;
+    error(message: string, metadata?: Record<string, unknown>): void;
+}
+interface LoggerInterface extends SimpleLogger {
     addHandler(handler: LogHandler): void;
     setMinLevel(level: LogLevel): void;
     enable(): void;
     disable(): void;
     isEnabled(): boolean;
-    debug(message: string, metadata?: Record<string, unknown>): void;
-    info(message: string, metadata?: Record<string, unknown>): void;
-    warn(message: string, metadata?: Record<string, unknown>): void;
-    error(message: string, metadata?: Record<string, unknown>): void;
 }
 declare class Logger implements LoggerInterface {
     private handlers;
@@ -143,21 +145,51 @@ declare function createEmitter(): Emitter<Record<EventType, Message>>;
 interface MessageNexusOptions {
     instanceId?: string;
     timeout?: number;
-    logger?: LoggerInterface;
+    logger?: LoggerInterface | SimpleLogger;
     loggerEnabled?: boolean;
+    logLevel?: LogLevel;
 }
-interface InvokeOptions {
-    method: string;
-    params?: unknown;
+/**
+ * Interface representing a method schema with parameters and results.
+ */
+interface MethodSchema {
+    params?: any;
+    result?: any;
+}
+/**
+ * Default registry for method schemas.
+ */
+type DefaultRegistry = Record<string, MethodSchema>;
+/**
+ * Helper to extract params from a schema or return any if not present.
+ */
+type GetParams<T> = T extends {
+    params: infer P;
+} ? P : any;
+/**
+ * Helper to extract result from a schema or return any if not present.
+ */
+type GetResult<T> = T extends {
+    result: infer R;
+} ? R : any;
+/**
+ * Options for invoking a method.
+ */
+interface InvokeOptions<K extends string = string, P = any> {
+    method: K;
+    params?: P;
     to?: string;
     metadata?: Record<string, unknown>;
     timeout?: number;
     retryCount?: number;
     retryDelay?: number;
 }
-interface NotificationOptions {
-    method: string;
-    params?: unknown;
+/**
+ * Options for sending a notification.
+ */
+interface NotificationOptions<K extends string = string, P = any> {
+    method: K;
+    params?: P;
     to?: string;
     metadata?: Record<string, unknown>;
 }
@@ -167,9 +199,36 @@ interface InvokeContext {
     to?: string;
     metadata?: Record<string, unknown>;
 }
-type InvokeHandler<Params = any, Result = any> = (params: Params, context: InvokeContext) => Result | Promise<Result>;
-type NotificationHandler<Params = any> = (params: Params, context: InvokeContext) => void;
-type ErrorHandler = (error: Error, context?: Record<string, unknown>) => void;
+/**
+ * Handler for an invoked method.
+ */
+type InvokeHandler<P = any, R = any> = (params: P, context: InvokeContext) => R | Promise<R>;
+/**
+ * Handler for a notification.
+ */
+type NotificationHandler<P = any> = (params: P, context: InvokeContext) => void;
+/**
+ * Standard JSON-RPC 2.0 and Nexus-specific error codes.
+ */
+declare enum NexusErrorCode {
+    ParseError = -32700,
+    InvalidRequest = -32600,
+    MethodNotFound = -32601,
+    InvalidParams = -32602,
+    InternalError = -32603,
+    Timeout = -32001,
+    SendFailed = -32002,
+    InvalidResponse = -32003
+}
+/**
+ * Custom error class for MessageNexus.
+ */
+declare class NexusError<D = any> extends Error {
+    readonly code: number;
+    readonly data?: D;
+    constructor(message: string, code?: number, data?: D);
+}
+type ErrorHandler = (error: Error | NexusError, context?: Record<string, unknown>) => void;
 interface Metrics {
     messagesSent: number;
     messagesReceived: number;
@@ -180,7 +239,7 @@ interface Metrics {
     averageLatency: number;
 }
 type MetricsCallback = (metrics: Metrics) => void;
-declare class MessageNexus<GlobalRequestPayload = unknown, GlobalResponsePayload = unknown> {
+declare class MessageNexus<InvokeMap extends object = DefaultRegistry, NotificationMap extends object = Record<string, any>> {
     driver: BaseDriver;
     pendingTasks: Map<string, {
         resolve: (value: any) => void;
@@ -201,23 +260,23 @@ declare class MessageNexus<GlobalRequestPayload = unknown, GlobalResponsePayload
     private metrics;
     private metricsCallbacks;
     constructor(driver: BaseDriver, options?: MessageNexusOptions);
-    invoke<T = GlobalResponsePayload>(methodOrOptions: string | InvokeOptions): Promise<T>;
+    invoke<K extends keyof InvokeMap>(methodOrOptions: K | InvokeOptions<K & string, GetParams<InvokeMap[K]>>): Promise<GetResult<InvokeMap[K]>>;
     private _sendMessage;
     onError(handler: ErrorHandler): () => void;
     flushQueue(): void;
-    notify(methodOrOptions: string | NotificationOptions): void;
+    notify<K extends keyof NotificationMap>(methodOrOptions: K | NotificationOptions<K & string, NotificationMap[K]>): void;
     private _validateMessage;
     _handleIncoming(data: unknown): Promise<void>;
     getMetrics(): Metrics;
     onMetrics(callback: MetricsCallback): () => boolean;
     private _notifyMetrics;
-    handle<Params = any, Result = any>(method: string, handler: InvokeHandler<Params, Result>): () => boolean;
-    removeHandler(method: string): void;
-    onNotification<Params = any>(method: string, handler: NotificationHandler<Params>): () => void;
-    offNotification(method: string, handler: NotificationHandler<any>): void;
+    handle<K extends keyof InvokeMap>(method: K, handler: InvokeHandler<GetParams<InvokeMap[K]>, GetResult<InvokeMap[K]>>): () => boolean;
+    removeHandler(method: keyof InvokeMap): void;
+    onNotification<K extends keyof NotificationMap>(method: K, handler: NotificationHandler<NotificationMap[K]>): () => void;
+    offNotification<K extends keyof NotificationMap>(method: K, handler: NotificationHandler<NotificationMap[K]>): void;
     private _reply;
     private _replyError;
     destroy(): void;
 }
 
-export { BaseDriver, BroadcastDriver, type ErrorHandler, type InvokeContext, type InvokeHandler, type InvokeOptions, type LoggerInterface, type Message, type MessageNexusOptions, type Metrics, type MetricsCallback, MittDriver, type NotificationHandler, type NotificationOptions, PostMessageDriver, WebSocketDriver, createEmitter, MessageNexus as default };
+export { BaseDriver, BroadcastDriver, type DefaultRegistry, type ErrorHandler, type InvokeContext, type InvokeHandler, type InvokeOptions, LogLevel, type LoggerInterface, type Message, type MessageNexusOptions, type MethodSchema, type Metrics, type MetricsCallback, MittDriver, NexusError, NexusErrorCode, type NotificationHandler, type NotificationOptions, PostMessageDriver, type SimpleLogger, WebSocketDriver, createEmitter, MessageNexus as default };

package/dist/index.d.ts

@@ -78,16 +78,18 @@ interface LogEntry {
     context?: string;
 }
 type LogHandler = (entry: LogEntry) => void;
-interface LoggerInterface {
+interface SimpleLogger {
+    debug(message: string, metadata?: Record<string, unknown>): void;
+    info(message: string, metadata?: Record<string, unknown>): void;
+    warn(message: string, metadata?: Record<string, unknown>): void;
+    error(message: string, metadata?: Record<string, unknown>): void;
+}
+interface LoggerInterface extends SimpleLogger {
     addHandler(handler: LogHandler): void;
     setMinLevel(level: LogLevel): void;
     enable(): void;
     disable(): void;
     isEnabled(): boolean;
-    debug(message: string, metadata?: Record<string, unknown>): void;
-    info(message: string, metadata?: Record<string, unknown>): void;
-    warn(message: string, metadata?: Record<string, unknown>): void;
-    error(message: string, metadata?: Record<string, unknown>): void;
 }
 declare class Logger implements LoggerInterface {
     private handlers;
@@ -143,21 +145,51 @@ declare function createEmitter(): Emitter<Record<EventType, Message>>;
 interface MessageNexusOptions {
     instanceId?: string;
     timeout?: number;
-    logger?: LoggerInterface;
+    logger?: LoggerInterface | SimpleLogger;
     loggerEnabled?: boolean;
+    logLevel?: LogLevel;
 }
-interface InvokeOptions {
-    method: string;
-    params?: unknown;
+/**
+ * Interface representing a method schema with parameters and results.
+ */
+interface MethodSchema {
+    params?: any;
+    result?: any;
+}
+/**
+ * Default registry for method schemas.
+ */
+type DefaultRegistry = Record<string, MethodSchema>;
+/**
+ * Helper to extract params from a schema or return any if not present.
+ */
+type GetParams<T> = T extends {
+    params: infer P;
+} ? P : any;
+/**
+ * Helper to extract result from a schema or return any if not present.
+ */
+type GetResult<T> = T extends {
+    result: infer R;
+} ? R : any;
+/**
+ * Options for invoking a method.
+ */
+interface InvokeOptions<K extends string = string, P = any> {
+    method: K;
+    params?: P;
     to?: string;
     metadata?: Record<string, unknown>;
     timeout?: number;
     retryCount?: number;
     retryDelay?: number;
 }
-interface NotificationOptions {
-    method: string;
-    params?: unknown;
+/**
+ * Options for sending a notification.
+ */
+interface NotificationOptions<K extends string = string, P = any> {
+    method: K;
+    params?: P;
     to?: string;
     metadata?: Record<string, unknown>;
 }
@@ -167,9 +199,36 @@ interface InvokeContext {
     to?: string;
     metadata?: Record<string, unknown>;
 }
-type InvokeHandler<Params = any, Result = any> = (params: Params, context: InvokeContext) => Result | Promise<Result>;
-type NotificationHandler<Params = any> = (params: Params, context: InvokeContext) => void;
-type ErrorHandler = (error: Error, context?: Record<string, unknown>) => void;
+/**
+ * Handler for an invoked method.
+ */
+type InvokeHandler<P = any, R = any> = (params: P, context: InvokeContext) => R | Promise<R>;
+/**
+ * Handler for a notification.
+ */
+type NotificationHandler<P = any> = (params: P, context: InvokeContext) => void;
+/**
+ * Standard JSON-RPC 2.0 and Nexus-specific error codes.
+ */
+declare enum NexusErrorCode {
+    ParseError = -32700,
+    InvalidRequest = -32600,
+    MethodNotFound = -32601,
+    InvalidParams = -32602,
+    InternalError = -32603,
+    Timeout = -32001,
+    SendFailed = -32002,
+    InvalidResponse = -32003
+}
+/**
+ * Custom error class for MessageNexus.
+ */
+declare class NexusError<D = any> extends Error {
+    readonly code: number;
+    readonly data?: D;
+    constructor(message: string, code?: number, data?: D);
+}
+type ErrorHandler = (error: Error | NexusError, context?: Record<string, unknown>) => void;
 interface Metrics {
     messagesSent: number;
     messagesReceived: number;
@@ -180,7 +239,7 @@ interface Metrics {
     averageLatency: number;
 }
 type MetricsCallback = (metrics: Metrics) => void;
-declare class MessageNexus<GlobalRequestPayload = unknown, GlobalResponsePayload = unknown> {
+declare class MessageNexus<InvokeMap extends object = DefaultRegistry, NotificationMap extends object = Record<string, any>> {
     driver: BaseDriver;
     pendingTasks: Map<string, {
         resolve: (value: any) => void;
@@ -201,23 +260,23 @@ declare class MessageNexus<GlobalRequestPayload = unknown, GlobalResponsePayload
     private metrics;
     private metricsCallbacks;
     constructor(driver: BaseDriver, options?: MessageNexusOptions);
-    invoke<T = GlobalResponsePayload>(methodOrOptions: string | InvokeOptions): Promise<T>;
+    invoke<K extends keyof InvokeMap>(methodOrOptions: K | InvokeOptions<K & string, GetParams<InvokeMap[K]>>): Promise<GetResult<InvokeMap[K]>>;
     private _sendMessage;
     onError(handler: ErrorHandler): () => void;
     flushQueue(): void;
-    notify(methodOrOptions: string | NotificationOptions): void;
+    notify<K extends keyof NotificationMap>(methodOrOptions: K | NotificationOptions<K & string, NotificationMap[K]>): void;
     private _validateMessage;
     _handleIncoming(data: unknown): Promise<void>;
     getMetrics(): Metrics;
     onMetrics(callback: MetricsCallback): () => boolean;
     private _notifyMetrics;
-    handle<Params = any, Result = any>(method: string, handler: InvokeHandler<Params, Result>): () => boolean;
-    removeHandler(method: string): void;
-    onNotification<Params = any>(method: string, handler: NotificationHandler<Params>): () => void;
-    offNotification(method: string, handler: NotificationHandler<any>): void;
+    handle<K extends keyof InvokeMap>(method: K, handler: InvokeHandler<GetParams<InvokeMap[K]>, GetResult<InvokeMap[K]>>): () => boolean;
+    removeHandler(method: keyof InvokeMap): void;
+    onNotification<K extends keyof NotificationMap>(method: K, handler: NotificationHandler<NotificationMap[K]>): () => void;
+    offNotification<K extends keyof NotificationMap>(method: K, handler: NotificationHandler<NotificationMap[K]>): void;
     private _reply;
     private _replyError;
     destroy(): void;
 }
 
-export { BaseDriver, BroadcastDriver, type ErrorHandler, type InvokeContext, type InvokeHandler, type InvokeOptions, type LoggerInterface, type Message, type MessageNexusOptions, type Metrics, type MetricsCallback, MittDriver, type NotificationHandler, type NotificationOptions, PostMessageDriver, WebSocketDriver, createEmitter, MessageNexus as default };
+export { BaseDriver, BroadcastDriver, type DefaultRegistry, type ErrorHandler, type InvokeContext, type InvokeHandler, type InvokeOptions, LogLevel, type LoggerInterface, type Message, type MessageNexusOptions, type MethodSchema, type Metrics, type MetricsCallback, MittDriver, NexusError, NexusErrorCode, type NotificationHandler, type NotificationOptions, PostMessageDriver, type SimpleLogger, WebSocketDriver, createEmitter, MessageNexus as default };