message-nexus 1.1.1 → 1.1.3

package/README.md

@@ -22,7 +22,8 @@ pnpm add message-nexus
 - **Retry Mechanism**: Automatic retry on request failure, configurable retry counts and delays
 - **Message Validation**: Runtime message format validation to prevent illegal messages
 - **Monitoring Metrics**: Built-in message statistics and performance monitoring
-- **Structured Logging**: Supports custom log handlers for easy debugging and production monitoring
+- **Structured Logging**: Supports adjustable log levels (DEBUG, INFO, WARN, ERROR) and custom log handlers or simple loggers (like `console`) for easy debugging and production monitoring.
+
 - **Resource Management**: All drivers support the `destroy()` method to properly clean up resources.
 
 ## Quick Start
@@ -156,19 +157,39 @@ receiverNexus.handle('SYNC_STATE', (params, context) => {
 #### Constructor
 
 ```typescript
-new MessageNexus<RequestPayload, ResponsePayload>(
+new MessageNexus<InvokeMap, NotificationMap>(
   driver: BaseDriver,
   options?: MessageNexusOptions
 )
 ```
 
+**Generics:**
+
+- `InvokeMap`: A record mapping method names to `{ params: any; result: any }`. Defaults to `DefaultRegistry`.
+- `NotificationMap`: A record mapping notification method names to their parameter types. Defaults to `Record<string, any>`.
+
 **Options:**
 
-| Parameter  | Type   | Default Value  | Description                           |
-| ---------- | ------ | -------------- | ------------------------------------- |
-| instanceId | string | auto-generated | Instance ID, used for message routing |
-| timeout    | number | 10000          | Request timeout (milliseconds)        |
-| logger     | Logger | new Logger()   | Logger instance                       |
+| Parameter     | Type                         | Default Value  | Description                                |
+| ------------- | ---------------------------- | -------------- | ------------------------------------------ |
+| instanceId    | string                       | auto-generated | Instance ID, used for message routing      |
+| timeout       | number                       | 10000          | Request timeout (milliseconds)             |
+| logger        | LoggerInterface \| SimpleLogger | new Logger()   | Logger instance or simple logger (e.g. `console`) |
+| loggerEnabled | boolean                      | false          | Whether to enable logging                  |
+| logLevel      | LogLevel                     | LogLevel.INFO  | Minimum log level to report                |
+
+**LogLevel:** `DEBUG`, `INFO`, `WARN`, `ERROR`
+
+**SimpleLogger Interface:**
+
+```typescript
+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
+}
+```
 
 #### Methods
 
@@ -177,15 +198,17 @@ new MessageNexus<RequestPayload, ResponsePayload>(
 Send request and wait for response.
 
 ```typescript
-nexus.invoke<T>(methodOrOptions: string | InvokeOptions): Promise<T>
+nexus.invoke<K extends keyof InvokeMap>(
+  methodOrOptions: K | InvokeOptions<K, InvokeMap[K]['params']>
+): Promise<InvokeMap[K]['result']>
 ```
 
 **Options:**
 
 | Parameter  | Type                    | Required | Description                  |
 | ---------- | ----------------------- | -------- | ---------------------------- |
-| method     | string                  | Yes      | Message method               |
-| params     | unknown                 | No       | Request data                 |
+| method     | K                       | Yes      | Message method               |
+| params     | InvokeMap[K]['params']  | No       | Request data                 |
 | to         | string                  | No       | Target instance ID           |
 | metadata   | Record<string, unknown> | No       | Metadata                     |
 | timeout    | number                  | No       | Timeout (overrides global)   |
@@ -214,15 +237,17 @@ const result = await nexus.invoke({
 Send a one-way notification (Fire-and-Forget). Does not wait for a response and does not generate an ID. Complies with JSON-RPC 2.0 Notification specification.
 
 ```typescript
-nexus.notify(methodOrOptions: string | Omit<InvokeOptions, 'timeout' | 'retryCount' | 'retryDelay'>): void
+nexus.notify<K extends keyof NotificationMap>(
+  methodOrOptions: K | NotificationOptions<K, NotificationMap[K]>
+): void
 ```
 
 **Options:**
 
 | Parameter | Type                    | Required | Description         |
 | --------- | ----------------------- | -------- | ------------------- |
-| method    | string                  | Yes      | Notification method |
-| params    | unknown                 | No       | Notification data   |
+| method    | K                       | Yes      | Notification method |
+| params    | NotificationMap[K]      | No       | Notification data   |
 | to        | string                  | No       | Target instance ID  |
 | metadata  | Record<string, unknown> | No       | Metadata            |
 
@@ -245,7 +270,10 @@ nexus.notify({
 Register a request handler for a specific method. The return value (or resolved value of a returned Promise) is automatically sent back as the response.
 
 ```typescript
-nexus.handle<Params, Result>(method: string, handler: InvokeHandler<Params, Result>): () => void
+nexus.handle<K extends keyof InvokeMap>(
+  method: K,
+  handler: InvokeHandler<InvokeMap[K]['params'], InvokeMap[K]['result']>
+): () => void
 ```
 
 **Parameters:**
@@ -279,7 +307,10 @@ unsubscribe()
 Register a handler for a specific notification method (one-way messages).
 
 ```typescript
-nexus.onNotification<Params>(method: string, handler: NotificationHandler<Params>): () => void
+nexus.onNotification<K extends keyof NotificationMap>(
+  method: K,
+  handler: NotificationHandler<NotificationMap[K]>
+): () => void
 ```
 
 **Example:**
@@ -295,22 +326,56 @@ unsubscribe()
 
 ##### onError()
 
-Register error handler.
+Register a global error handler for background errors (e.g., driver failures, invalid incoming messages). For request-specific errors, use `try/catch` with `invoke()`.
 
 ```typescript
-nexus.onError(handler: ErrorHandler): () => void
+nexus.onError(handler: (error: Error | NexusError, context?: Record<string, unknown>) => void): () => void
 ```
 
 **Example:**
 
 ```typescript
 nexus.onError((error, context) => {
-  console.error('Bridge error:', error.message, context)
+  if (error instanceof NexusError) {
+    console.error(`Bridge error [${error.code}]: ${error.message}`, error.data)
+  } else {
+    console.error('System error:', error.message)
+  }
   // Send to error tracking service
   Sentry.captureException(error, { extra: context })
 })
 ```
 
+#### Errors
+
+MessageNexus provides a structured error system based on the JSON-RPC 2.0 specification.
+
+##### NexusError
+
+A custom error class that includes a numeric code and optional data.
+
+```typescript
+class NexusError<D = any> extends Error {
+  code: number    // JSON-RPC or Nexus-specific error code
+  data?: D        // Optional additional error information
+}
+```
+
+##### NexusErrorCode
+
+Common error codes exported by the library:
+
+| Code | Name | Description |
+| --- | --- | --- |
+| -32700 | `ParseError` | Invalid JSON received by the server |
+| -32600 | `InvalidRequest` | The JSON sent is not a valid Request object |
+| -32601 | `MethodNotFound` | The method does not exist / is not registered |
+| -32602 | `InvalidParams` | Invalid method parameter(s) |
+| -32603 | `InternalError` | Internal JSON-RPC error (e.g., handler threw an exception) |
+| -32001 | `Timeout` | Request timed out |
+| -32002 | `SendFailed` | Failed to send message via driver |
+| -32003 | `InvalidResponse` | Received a response that doesn't match the request |
+
 ##### getMetrics()
 
 Get monitoring metrics.
@@ -547,28 +612,33 @@ function onUserConfirm(id: string) {
 
 ### 1. Type Safety
 
-MessageNexus uses TypeScript generics to provide full type inference:
+MessageNexus uses TypeScript generics and Schema mapping to provide full type inference across method names, parameters, and results:
 
 ```typescript
-interface UserRequest {
-  userId: number
+// 1. Define your protocol schemas
+interface MyInvokeMap {
+  'getUser': { params: { id: number }; result: { name: string; age: number } };
+  'calculate': { params: { a: number; b: number }; result: number };
 }
 
-interface UserResponse {
-  id: number
-  name: string
+interface MyNotificationMap {
+  'onLog': { message: string; level: 'info' | 'warn' | 'error' };
 }
 
-const nexus = new MessageNexus<UserRequest, UserResponse>(driver)
+// 2. Initialize with your schemas
+const nexus = new MessageNexus<MyInvokeMap, MyNotificationMap>(driver)
 
-// Full type inference
-const response = await nexus.invoke({
-  method: 'GET_USER',
-  params: { userId: 123 }, // Type: UserRequest
-})
+// 3. Enjoy full type inference and autocompletion
+const response = await nexus.invoke('getUser', { id: 123 })
+// response Type: { name: string; age: number }
 
-// response Type: UserResponse
-console.log(response.name)
+nexus.notify('onLog', { message: 'Ready', level: 'info' })
+
+// 4. Type-safe handlers
+nexus.handle('calculate', (params) => {
+  // params Type: { a: number; b: number }
+  return params.a + params.b // result Type must be number
+})
 ```
 
 ### 2. Memory Safety
@@ -581,12 +651,13 @@ console.log(response.name)
 - **Driver Lifecycle**: Each driver implements the `destroy()` method to correctly release resources
 - **Emitter Isolation**: Recommended to use `createEmitter()` to create independent instances, avoiding memory leaks caused by shared singletons
 
-### 3. Error Recovery
+### 3. Error Recovery & Handling
 
 - **Auto Reconnect**: WebSocket automatic reconnection mechanism with exponential backoff strategy
 - **Request Retry**: Automatic retry on request failure, configurable retry counts and delays
 - **Message Queue**: Offline message caching, automatically sent after connection recovery
-- **Error Callback**: Unified error handling mechanism
+- **Structured Error Handling**: Dedicated `NexusError` class and standard codes (JSON-RPC 2.0 compatible) for precise diagnostic and fault recovery
+- **Unified Error Callback**: Global `onError` listener for non-request background errors
 
 ### 4. Security Hardening
 
@@ -610,15 +681,6 @@ console.log(`Avg latency: ${metrics.averageLatency}ms`)
 console.log(`Pending: ${metrics.pendingMessages}, Queued: ${metrics.queuedMessages}`)
 ```
 
-## Testing
-
-Run unit tests:
-
-```bash
-cd packages/message-nexus
-pnpm test:run
-```
-
 ## License
 
 MIT