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('ws.js');
const ws = new ws_js( debug, URL );

// BUILT
const ws = require('ws.js').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/.