ws.js

by NeutronX-dev

Table of Contents

• Node.js Client
• • Get Started
• • Implementation
• • Methods
• • Examples
• Node.js Server
• • Get Started
• • Implementation
• • Methods
• • Examples
• Other Exports
• • Fetch Close Code

Node.js Client

Get Started (node client)

To install ws.js you need to input the following in your console:

npm i nex.ws

Implementation (node client)

To start using ws.js (client) you need to write the following code:

// CLASS
const ws_js = require('nex.ws');
const ws = new ws_js( debug, URL );

// BUILT
const ws = require('nex.ws').build.client( debug, URL );

Methods (node client)

Class	Method	Parameters	Promise	Return
ws.js.client	constructor	boolean debug, string URL (all opt.)	NO	void
ws.js.client	.setURL	string URL	NO	void
ws.js.client	.setHeaders	object headers (JSON)	NO	void
ws.js.client	.setAgent	string proxy, string type	NO	void
ws.js.client	.isOpen	NONE	NO	true or false
ws.js.client	.isClosed	NONE	NO	true or false
ws.js.client	.isConnecting	NONE	NO	true or false
ws.js.client	.on	string event, function callback, boolean bind (opt.)	NO	void
ws.js.client	.connect	string proxy, string type	YES	JSON {success, time, message, external}
ws.js.client	.send	ANY message	YES	true or false
ws.js.client	.close	int code, string data	NO	true or false

constructor (node client)

• Parameters
• • boolean debug (optional)
• • string URL (optional)
• Description: Make the Class.
• Return: void

.setURL (node client)

• Parameters
• • string URL (required)
• Description: Set an URL to connect (if not set in the constructor)
• Return: void

.setHeaders (node client)

• Parameters
• • object headers (JSON) (required)
• Description: Sets the connection Headers.
• Return: void

.setAgent (node client)

• Parameters
• • string proxy (required)
• • string type ("http", "https", or "socks") (required)
• Description: Makes an type agent from proxy to connect with.
• Return: void

.isOpen (node client)

• Parameters
• • NONE
• Return: true or false

.isClosed (node client)

• Parameters
• • NONE
• Return: true or false

.isConnecting (node client)

• Parameters
• • NONE
• Return: true or false

.on (node client)

• Parameters
• • string event (required) ("open", "close", "message", or "error")
• • function callback (required)
• • boolean bind (optional)
• Description: Set a callback for an event.
• Return: void

.connect (node client)

• Parameters
• • NONE
• Return: void

.send (node client)

• Parameters
• • ANY message (required)
• Return: true or false

.close (node client)

• Parameters
• • int message (optional)
• • string data (optional)
• Return: true or false

on Information (node client)

Event	Parameters	Values
open	NONE	N/A
close	NONE	N/A
message	JSON or String res	string message, bool parsed
error	String err	N/A

Examples (node client)

Example #1:

Connection to wss://echo.websocket.org (debug mode)

const ws_js = require('ws.js');

const client = new ws_js(true);                                // Make class on debug mode.
client.setURL("wss://echo.websocket.org");                     // Sets URL to connect to.
client.on("open", () => {                                      // Set a callback that:
    console.log("[Custom Callback] Opened");                   //   logs "Opened" when connection opens
});
client.on("message", (message, parsed) => {
    if(parsed){                                                // If the text was parsed (String -> JSON)
        console.log(JSON.stringify(message, true, '   '));     // Format and print the JSON.
    } else {                                                   // else (if unable to parse)
        console.log(message);                                  // Print the unparsed string
    }
});

client.connect().then((res) => {
    console.log(`[Custom Callback] connected within ${res.time} ms.`);
    client.send({                                              // Send a JSON with
        type: 'ws.js'                                          // property "type", value "l"
    });
});
client.close(0);                                               // Closes the connection.

Console:

> [ws.js] URL set. (URL: wss://echo.websocket.org)
> [ws.js] Headers set. (Headers: {})
> [ws.js] Set callback for event "open".
> [ws.js] Set callback for event "message".
> [ws.js] Starting to Connect...
> [ws.js] Binded Callbacks.
> [Custom Callback] Opened
> [ws.js] Made a connection to wss://echo.websocket.org successfuly.
> [Custom Callback] connected within 196 ms.
> [ws.js] Sent a message. (JSON) (16 bytes)
> [ws.js] [+] Message (16 bytes)
> {
>    "type": "ws.js"
> }

How does it work?

I made a ws.js object on debug mode (shows when setters are triggered, when a connection is made, messages sent/recieved, etc...) set the URL to wss://echo.websocket.org which is basically a WebSocket server that sends back any messages it recieves. I made a callback that whenever a message is recieved checks if it was parsed, if it was then format and print the recieved message, if it is not parsed or was unable to parse print the text message alone. Then I triggered the .connect method, waited for the WebSocket to make the connection, and send a message (JSON: {type: "ws.js"}). It was sent, the echo server sent it back, triggering the message event which prints the message.

Other

In order for ws.js to work you need to set a URL, either as the second parameter of the constructor, or using the .setURL method.

The debug mode logs pretty much everything, When setters are trigerred, connection started, ended, recieved/sent messages, etc...

Node.js Server

Get Started (node server)

To install ws.js you need to input the following in your console:

npm i nex.ws

Implementation (node server)

To start using ws.js (server) you need to write the following code:

// CLASS
const ws_js = require('ws.js');
const ws = new ws_js.server( debug );

// BUILT
const ws = require('ws.js').build.server( debug );

Methods (node client)

Class	Method	Parameters	Promise	Return
ws.js.server	constructor	boolean debug	NO	void
ws.js.server	.addServer	server instance (e.x.: express().listen())	NO	void
ws.js.server	.addPort	int port	NO	void
ws.js.server	.on	string event, function callback, boolean bind (opt.)	NO	void
ws.js.server	.listen	N/A	NO	void
ws.js.server	.broadcast	ANY message	YES	int sent (successful sent messages)
ws.js.server	.getActiveSockets	int socketID	NO	[Socket, Socket, ...] or Socket
ws.js.server	.getInactiveSockets	int socketID	NO	[JSON, JSON, ...] or JSON
ws.js.server	.destroy	N/A	NO	N/A

.constructor (node server)

• Parameters
• • boolean debug (optional)
• Description: Make the Class.
• Return: void

.addServer (node server)

• Parameters
• • server instance (required)
• Description: Bind the WebSocket Server to another Server.
• Return: void

.addPort (node server)

• Parameters
• • int port (required)
• Description: Sets a port to listen to.
• Return: void

.on (node server)

• Parameters
• • string event (required)
• • function ballback (required)
• • bool bind (optional)
• Description: Set a callback for an Event.
• Return: void

.listen (node server)

• Parameters
• • string event (required)
• • function ballback (required)
• • bool bind (optional)
• Description: Set a callback for an Event.
• Return: void

.broadcast (node server)

• Parameters
• • ANY message (required)
• Description: Sends a message to all active Sockets
• Return: void

.getActiveSockets (node server)

• Parameters
• • int socketID (optional)
• Description: Gets an active Socket from an ID, or all if not specified.
• Return: [Socket, Socket, ...] or Socket.

.getInactiveSockets (node server)

• Parameters
• • int socketID (optional)
• Description: Gets an inactive Socket from an ID, or all if not specified.
• Return: [JSON, JSON, ...] or JSON. ({id: int, connected: int, elapsed: int})

Other Exports

Here are other extra functions included in the module.

Fetch Close Code

• CALL: <ws_js>.FetchCloseCode(code);
• RETURN: { name: "", description: "" }
• DESCRIPTION: Returns a name and description of the close code (code).

LICENSE

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.