@randajan/bifrost

Bifrost is a versatile library for seamless data communication between backend and frontend applications via Socket.IO integration. Key features include:

• Asynchronous function handling for efficient operation.
• Automatic response processing for streamlined development.
• Automatic thread lock setting for simplified state synchronization.
• Easy management of client connection groups for WebSocket connections.

Say goodbye to cumbersome data transfer mechanisms and embrace the simplicity and efficiency of Bifrost for effortless data or state teleportation.

Install

npm install @randajan/bifrost

or

yarn add @randajan/bifrost

Client application

Client example

import socketIOClient from "socket.io-client";
import { BifrostRouter } from "@randajan/bifrost/client";

// Connect to Socket.io server
const socket = socketIOClient(`https://example.com`);

// Create router using Socket.io socket
const bifrost = new BifrostRouter(socket);

const msg = "TEST-MSG";
console.log(`Client send: ${msg}`);

// Send message to server
bifrost.tx("testChannel", { msg }).then(console.log);

// Register receiver
bifrost.rx("testChannel", (socket, { msg }) => {
    console.log(`Client received: '${msg}'`);

    // Reply to received message
    return `Client reply to: '${msg}'`;
});

Client Router API

| Function | Description | Parameters | Return Value | |-|-|-|-| | tx | Sends data on the specified channel and processes responses using the provided function. | channel - Name of the channel to send data on.transceiver - Object or Function for sending data on the channel.Note: If transceiver is a function, it accepts a async callback parameter for sending data on the channel. | Promise - Asynchronous operation that resolves with the result of the data transfer. | | rx | Registers a receiver function for handling data received on the specified channel. | channel - Name of the channel to receive data on.receiver - Function for processing received data.Note: If receiver is a function, it accepts the received data as a parameter. | Function - Function for unregistering the receiver from the specified channel. | | createBeam | Creates interface for easy data sharing | channel - Name of the used channel.options - check ription bellow | Beam - Instance of the interface. |

Server application

Server example

import { createServer as createServerHTTP } from "http";
import { Server as IO } from "socket.io";

import { ServerRouter } from "@randajan/bifrost/server";

// Create simple HTTP server
const http = createServerHTTP();
http.listen(80);

// Register Socket.IO API with CORS enabled
const io = new IO(http);

// Create router using Socket.IO API
const bifrost = new ServerRouter(io);

// Register receiver for "testChannel"
bifrost.rx("testChannel", (socket, { msg }) => {
    console.log(`Server received: '${msg}'`);

    setTimeout(async _ => {
        const msg = "TEST-BROADCAST";
        console.log(`Server send ${msg}`);

        // Send broadcast message
        bifrost.tx("testChannel", { msg }).then(console.log);
    }, 1000);

    // Reply to received message
    return `Server reply to: '${msg}'`;
});

Server Router API

| Function | Description | Parameters | Return Value | |-|-|-|-| | tx | Sends data on the specified channel to the provided sockets using the transceiver function and processes responses using the provided function. | channel - Name of the channel to send data on.sockets - Array of sockets to send data to.transceiver - Object or Function for sending data on the channel.Note: If transceiver is a function, it accepts a async callback parameter for sending data on the channel. | Promise - Asynchronous operation that resolves with the result of the data transfer. | | txBroad | Sends data on the specified channel to all known sockets using the transceiver function and processes responses using the provided function. | channel - Name of the channel to send data on.sockets - Array of sockets to send data to.transceiver - Object or Function for sending data on the channel.Note: If transceiver is a function, it accepts a async callback parameter for sending data on the channel. | Promise - Asynchronous operation that resolves with the result of the data transfer. | | rx | Registers a receiver function for handling data received on the specified channel from all connected sockets. | channel - Name of the channel to register the receiver for.receiver - Function for processing received data. | Function - Function for unregistering the receiver from the specified channel. | | on | Registers a function to execute when a new socket connects to the server. | event - 'hi' or 'bye'execute - Function to execute when a new socket connects. | Function - Function for unregistering the listener. | | createGroup | Creates a new group for managing sockets with the specified grouper function. | socketGroupProp - Function that takes a socket object as input parameter and returns an its groupId | SocketsGroup - Instance of the created group. | | createBeam | Creates interface for easy data sharing | channel - Name of the used channel.options - check description bellow | Beam - Instance of the interface. |

Server Sockets Groups API

| Function | Description | Parameters | Return Value | |-|-|-|-| | resetAll | Reassigning allt sockets to their corresponding groups based on the grouper function. | - | - | | reset | Reassigning sockets in some group to their corresponding groups based on the grouper function. | groupId | - | | resetSocket | Reassigning socket to it's corresponding groups based on the grouper function. | socket - socket that should be reseted | - | | resetSockets | Reassigning sockets to their corresponding groups based on the grouper function. | sockets - Array of sockets that should be reseted | - | | get | Retrieves an array of sockets associated with the specified group ID. | groupId - ID of the group to retrieve sockets for. | Array of sockets associated with the specified group ID. | | on | Registers a function to execute when a new socket connects to the server. | event - 'hi', 'bye' or 'reset'execute - Function to execute when a new socket connects. | Function - Function for unregistering the listener. | | tx | Sends data on the specified channel to the sockets associated with the specified group ID using the transceiver function. | channel - Name of the channel to send data on.groupId - ID of the group to send data to.transceiver - Function or code for sending data on the channel. | Promise - Asynchronous operation that resolves when all data has been sent. | | txBroad | Sends data on the specified channel to the sockets associated with the specified group ID using the transceiver function. | channel - Name of the channel to send data on.transceiver - Function or code for sending data on the channel.socket - Source socket for obtain groupId and send data to whole group. excludeSocket - Boolean that determines if the provided socket will be excluded from broadcast | Promise - Asynchronous operation that resolves when all data has been sent. | | createBeam | Creates interface for easy data sharing across sockets groups | channel - Name of the used channel.options - check description bellow | Beam - Instance of the interface. |

Beam interface API

Beam is perfect for very easy data sharing across multiple sockets. It can be used instead of REST API. Beam was renamed to Vault, improved and moved to separate library @randajan/vault-kit

This project currently uses Vault instead of Beam interface and all options are passed to Vault.

Additional arguments ...args

Argument Differences for Various Beam Implementations:

Client Implementation All additional arguments are optional.

Server Implementation First argument is an optional socket client source (Socket.IO) to exclude from notifications. Other arguments are optional.

Server Group Implementation First argument is groupId to identify a group of sockets. Second argument is an optional socket client source (Socket.IO) to exclude from notifications. Other arguments are optional.

License

MIT © randajan