data-channel-router

A modern library designed for robust communication in scenarios where multiple data channels are available (e.g., different service endpoints, fallback paths, etc.). It automatically manages failover, monitors health, enables customizable concurrency, and offers event-based hooks to keep your application responsive and resilient.

Live demo

Feature	Description
Automatic Failover	Switches between multiple defined channels upon failure
Ping Mechanism	Uses ping functions for health checking and determines signal quality using a configurable delay map
Concurrency Controls	Configure how many ping or route requests run in parallel (maxThreads, maxPingThreads)
Event-Driven	Emits events for stats updates, failures, recoveries, buffering, and channel changes
Stat Tracking & Availability Check	Exposes properties like .stats, .isAvailable, and a .router object to dispatch route calls
No Dependencies	Lightweight setup, completely self-contained

Pros & Potential Use Cases

Advantages:

Reliability: Built-in failover and health checks mitigate channel disruptions. Efficiency: Concurrency settings help you fine-tune resource usage and latency. Event Rich: Easy to integrate observability and reactive patterns. Lightweight & Dependency-Free: Eliminates risk of dependency bloat or conflicts.

Ideal Scenarios:

Multi-endpoint APIs (e.g., primary + fallback service endpoints). Real-time systems where channel latency and reliability matter. Distributed networks or microservice architectures where fallback resilience is critical.

Installation

Run

npm i data-channel-router

Pretty straightforward — no dependencies

Basic Usage Example

// Channel route description interface
interface IRoutes {
    getUser: (userId: string) => Promise<any>;
}

const routes = (channelService: string): IRoutes => ({
    getUser: async (userId: string) => {
        const route = `${channelService}/user/${userId}`;
        try {
            await fetch(`${channelService}/user/${userId}`);
        } catch (err) {
            // Do something
        }
    },
    // etc
});

const channel1: IDataChannelOptions<IRoutes> = {
    id: 1,
    ping: () => {
        return fetch('channel1/ping');
    },
    routes: routes('service1.my-web-application.com'),
};
const channel2: IDataChannelOptions<IRoutes> = {
    id: 2,
    ping: () => {
        return fetch('channel2/ping');
    },
    routes: routes('service2.my-web-application.com'),
};

// Channel list
const channels: Array<IDataChannelOptions> = [
    channel1, channel2,
];

const dc = new DataChannelRouter<IRoutes>({
    channels,
    // Set up ping delay matching to determine connection quality
    delayMap: {
        [DataChannelSignalQuality.VERY_HIGH]: 50,
        [DataChannelSignalQuality.HIGH]: 100,
        [DataChannelSignalQuality.MIDDLE]: 500,
        [DataChannelSignalQuality.LOW]: 1000,
        [DataChannelSignalQuality.VERY_LOW]: 2000,
    },
    // Sets the number of parallel route requests
    maxThreads: 6,
    // Sets the number of parallel ping requests
    maxPingThreads: 4,
    // Sets the timeout between pings
    pingTimeout: 2000,
});

// Listening to changes in statistics
dc.addEventListener(DataChannelRouterEvents.STATS, (stats: IDataChannelsStats) => {
    let statStr = '';
    for (const idStr in stats) {
        const id = Number(idStr), stat = stats[id];
        statStr += `channel${id}: status: ${stat.status}; signal: ${stat.signal} <br/>`;
    }
    console.info(statStr);
});
// Listen for buffering changes
dc.addEventListener(DataChannelRouterEvents.BUFFERING, (bufferSize: number) => {
    console.info(`Buffering: ${bufferSize}`);
});
// Listening for ping failure event
dc.addEventListener(DataChannelRouterEvents.PING_FAILURE, (channelId: Id) => {
    console.info(`Ping failure on channel${channelId}`);
});
// Listen for route failure event
dc.addEventListener(DataChannelRouterEvents.ROUTE_ERROR, (routeName: string, channelId: Id) => {
    log(`Route error ${routeName} on channel${channelId}`);
});
// Listen for channel failure recovery event
dc.addEventListener(DataChannelRouterEvents.CHANNEL_RECOVERY, (channel: IDataChannelInfo) => {
    log(`The channel${channel.id} has been recovered`);
});
// Start the channel change listener
dc.addEventListener(DataChannelRouterEvents.CHANNEL_CHANGE, (channel: IDataChannelInfo | null) => {
    if (channel) {
        // Do something
        // It is possible to implement a subscription to listen to sockets on a given channel and close sockets of an inactive channel.
        // See the example of implementation at https://github.com/DjonnyX/data-channel-router/blob/main/src/index.ts
    } else {
        throw Error('No data channels available.');
    }
});

// Next, each time we call a route, we first check the availability of the router.
if (!dc.isAvailable) {
    throw Error('No data channels available.');
} else {
    dc.router.getUser('666');
}

API

DataChannelRouter

Methods

Method	Arguments	Description
constructor	options: IDataChannelRouterOptions	Class constructor.
add	channel: IDataChannelOptions	Adds a new data channel.
dispose		Clears all data. Called before deletion.

Properties

Property	Type	Description
buffering	number	Readonly. Returns the buffering value
isAvailable	boolean	Readonly. Returns true if there are data channels available.
router	R	Generic type. Router.
stats	IDataChannelsStats	Readonly. Returns statistics for data channels.

Events

Name	Type	Description
DataChannelRouterEvents.CHANNEL_CHANGE	(channel: IDataChannelInfo) => void	Emitted when the data transmission channel changes.
DataChannelRouterEvents.CHANNEL_UNAVAILABLE	(channel: IDataChannelInfo) => void => void	Emitted when the data channel becomes unavailable.
DataChannelRouterEvents.CHANNEL_RECOVERY	(channel: IDataChannelInfo) => void => void	Emitted when a previously faulty channel becomes operational again.
DataChannelRouterEvents.CHANGE	(channel: IDataChannelInfo | null) => void => void	Emit when changing the statuses of the channels.
DataChannelRouterEvents.PING_FAILURE	(channelId: Id) => void => void	Emitted during ping failure.
DataChannelRouterEvents.ROUTE_ERROR	(routeName: string, channelId: Id) => void	Emitted when a route call fails.
DataChannelRouterEvents.STATS	(stats: IDataChannelsStats) => void	Emitted when the signal and status in data channels changes.
DataChannelRouterEvents.BUFFERING	(bufferSize: number) => void	Emitted when the buffer size changes.

License

MIT License

Copyright (c) 2025 djonnyx (Evgenii Grebennikov)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.