Class NodeChannel

Example

Basic server usage:

import { NodeChannel, defineMessage, z } from '@xtr-dev/zodiac';

const channel = new NodeChannel();
await channel.connect('ws://management-server:8080');

Example

Microservice communication:

const channel = new NodeChannel();
channel.setReconnectOptions(50, 1000); // Very resilient
await channel.connect('ws://user-service:3001/events');

Hierarchy

BaseChannel
- NodeChannel

Index

Constructors

constructor

Methods

sendMessage on off isOpen connect disconnect send setReconnectOptions

Constructors

constructor

new NodeChannel(): NodeChannel
Returns NodeChannel
Inherited from BaseChannel.constructor

Methods

sendMessage

sendMessage<T extends MessageDefinition<any>>(
definition: T,
data: InferMessageData<T>,
): Promise<void>
Sends a type-safe, validated message using a message definition.

This is the preferred way to send messages as it provides:
- Compile-time type checking
- Runtime validation with Zod
- Automatic message ID handling
Type Parameters
- T extends MessageDefinition<any>
  The message definition type
Parameters
- definition: T
  Message definition created with defineMessage()
- data: InferMessageData<T>
  Message data that matches the definition's schema
Returns Promise<void>
Throws
When data doesn't match the schema
Example
```
const userMsg = defineMessage('user', z.object({
  name: z.string(),
  age: z.number().min(0)
}));

// Type-safe and validated
await channel.sendMessage(userMsg, {
  name: 'Alice',
  age: 25
});

// TypeScript error: missing required field
await channel.sendMessage(userMsg, { name: 'Bob' }); // Error!

// Runtime error: validation fails
await channel.sendMessage(userMsg, { name: 'Charlie', age: -1 }); // Throws!
```
Inherited from BaseChannel.sendMessage
- Defined in src/base-channel.ts:143

on

on<T>(id: string, handler: MessageHandler<T>): void
Registers a message handler for a specific message type (by string ID).
Type Parameters
- T
Parameters
- id: string
  String identifier for the message type
- handler: MessageHandler<T>
  Function to handle incoming messages
Returns void
Inherited from BaseChannel.on
- Defined in src/base-channel.ts:157
on<T extends MessageDefinition<any>>(
definition: T,
handler: MessageHandler<InferMessageData<T>>,
): void
Registers a type-safe message handler using a message definition. This is the preferred method as it provides full type safety.
Type Parameters
- T extends MessageDefinition<any>
Parameters
- definition: T
  Message definition created with defineMessage()
- handler: MessageHandler<InferMessageData<T>>
  Type-safe handler function
Returns void
Example
```
const chatMsg = defineMessage('chat', z.object({
  user: z.string(),
  text: z.string()
}));

// Fully typed handler - data.user and data.text are known
channel.on(chatMsg, (data, message) => {
  console.log(`${data.user}: ${data.text}`);
  console.log(`Sent at: ${message.timestamp}`);
});
```
Inherited from BaseChannel.on
- Defined in src/base-channel.ts:180

off

off<T>(id: string, handler: MessageHandler<T>): void
Removes a message handler for a specific message type (by string ID).
Type Parameters
- T
Parameters
- id: string
  String identifier for the message type
- handler: MessageHandler<T>
  The exact handler function to remove
Returns void
Inherited from BaseChannel.off
- Defined in src/base-channel.ts:195
off<T extends MessageDefinition<any>>(
definition: T,
handler: MessageHandler<InferMessageData<T>>,
): void
Removes a type-safe message handler using a message definition.
Type Parameters
- T extends MessageDefinition<any>
Parameters
- definition: T
  Message definition created with defineMessage()
- handler: MessageHandler<InferMessageData<T>>
  The exact handler function to remove
Returns void
Example
```
const handler = (data) => console.log(data.text);

// Register handler
channel.on(chatMsg, handler);

// Remove the same handler instance
channel.off(chatMsg, handler);
```
Inherited from BaseChannel.off
- Defined in src/base-channel.ts:214

isOpen

isOpen(): boolean
Checks if the channel is currently connected and ready for communication.

Returns boolean
true if connected, false otherwise
Example
```
if (channel.isOpen()) {
  await channel.sendMessage(someMessage, data);
} else {
  console.log('Channel is not connected');
}
```
Inherited from BaseChannel.isOpen
- Defined in src/base-channel.ts:271

connect

connect(url: string): Promise<void>
Establishes a WebSocket connection using the Node.js 'ws' library.

Optimized for server environments with enhanced error reporting and automatic reconnection handling.
Parameters
- url: string
  WebSocket server URL (ws:// or wss://)
Returns Promise<void>
Throws
If already connected or connection is in progress

Throws
If WebSocket creation fails
Example
```
// Connect to local development server
await channel.connect('ws://localhost:8080');

// Connect to internal microservice
await channel.connect('ws://user-service:3001/websocket');

// Connect with authentication in URL
await channel.connect('wss://api.example.com/ws?token=abc123');
```
Overrides BaseChannel.connect
- Defined in src/node-channel.ts:80

disconnect

disconnect(): Promise<void>
Closes the connection and cleans up resources.

Returns Promise<void>
Overrides BaseChannel.disconnect
- Defined in src/node-channel.ts:123

send

send<T>(id: string, data: T): Promise<void>
Sends raw data over the channel. Use sendMessage() for type-safe validated sending instead.
Type Parameters
- T
Parameters
- id: string
  Message type identifier
- data: T
  Raw message data
Returns Promise<void>
Overrides BaseChannel.send
- Defined in src/node-channel.ts:144

setReconnectOptions

setReconnectOptions(maxAttempts: number, baseDelay: number): void
Configures automatic reconnection behavior for Node.js environments.

Particularly useful for microservices and server applications that need high reliability and resilience to network issues.
Parameters
- maxAttempts: number
  Maximum number of reconnection attempts (default: 5)
- baseDelay: number
  Initial delay in milliseconds (default: 1000)
Returns void
Example
```
// High-reliability microservice configuration
channel.setReconnectOptions(100, 500);

// Development environment (quick failure)
channel.setReconnectOptions(3, 1000);

// Critical service (very persistent)
channel.setReconnectOptions(1000, 2000);
```
- Defined in src/node-channel.ts:183

Class NodeChannel

Example

Example

Hierarchy

Index

Constructors

Methods

Constructors

constructor

Returns NodeChannel

Methods

sendMessage

Type Parameters

Parameters

Returns Promise<void>

Throws

Example

on

Type Parameters

Parameters

Returns void

Type Parameters

Parameters

Returns void

Example

off

Type Parameters

Parameters

Returns void

Type Parameters

Parameters

Returns void

Example

isOpen

Returns boolean

Example

connect

Parameters

Returns Promise<void>

Throws

Throws

Example

disconnect

Returns Promise<void>

send

Type Parameters

Parameters

Returns Promise<void>

setReconnectOptions

Parameters

Returns void

Example

Settings

On This Page