@randajan/bifrost

@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 state sharing	channel - Name of the used channel. opt - check Beam.opt description 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.
welcome	Registers a function to execute when a new socket connects to the server.	execute - Function to execute when a new socket connects. Note: The result of execute function can be cleanUp function. That will be called after client disconnects from the server.	Function - Function for unregistering the listener.
farewell	Registers a function to execute when a socket disconnects from the server.	execute - Function to execute when a socket disconnects.	Function - Function for unregistering the listener.
createGroup	Creates a new group for managing sockets with the specified name and grouper function.	name - Name of the group to create. socketGroupProp - Function that takes a socket object as input parameter and returns an its groupId OR it could be also string that represent the property name of the socket that represent the groupId. In this case if the socket property changes it's value the group will be auto-reseted	SocketsGroup - Instance of the created group.
getGroup	Retrieves the group with the specified name.	name - Name of the group to retrieve.	SocketsGroup - Instance of the requested group.
createBeam	Creates interface for easy state sharing	channel - Name of the used channel. opt - check Beam.opt description bellow	Beam - Instance of the interface.

Server Sockets Groups API

Function	Description	Parameters	Return Value
reset	Resets the socket group by reassigning sockets to their corresponding groups based on the grouper function.	-	-
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.
watch	Provide watcher for any group changes. For every change and every socket will be called the watcher separately with arguments watcher(socket, event, toGroupId, fromGroupId). There is threee possible events: welcome, farewell and reset.	-	-
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 state sharing across sockets groups	channel - Name of the used channel. opt - check Beam.opt description bellow	Beam - Instance of the interface.

Beam interface API

Beam is perfect for very easy state sharing across multiple sockets. It can be used instead of REST API.

Function	Description	Parameters	Return Value
refresh	Updates the state from the server. If a synchronization is in progress, waits for it to complete.	...args - additional arguments	Promise<boolean> - Returns true if the state is ready
get	Retrieves the current state. If the state is uninitialized or a synchronization is in progress, waits for it to complete.	...args - additional arguments	Promise<any> - Returns the current state
set	Sets a new state and synchronizes it.	newState - new state ...args - additional arguments	Promise<any> - Returns the current state after setting
watch	Adds a function to watch for state changes. The function will be called whenever the state changes.	watcher - function to be called on state change	Promise<Function> - Returns a function to cancel the watcher

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.

All additional arguments will be passed 1:1 to functions get and set provided by Beam.opt.

Beam.opt

opt should be an object that contains the following properties:

Name	Type	Required / Optional	Description
get	Function	Required	Function that returns the current state. Can be async.
set	Function	Required	Function that sets the provided state and returns the current state. Can be async.
trait	Function	Optional	Function that processes newState, allowing for state modification or validation. The returned value is passed to set.
allowChanges	String	Optional	Enum that can be "local", "remote", or "none". Controls the direction of state change propagation.
queue	Object	Optional	Object representing settings for delayed processing when using the set method. Described in the @randajan/queue package.

License

MIT © randajan