chore(package.json): update version from 1.1.0 to 1.1.1

fix(cli.js): refactor help and error handling logic for better readability and maintainability
feat(cli.js): add support for custom port and timeout options
fix(parallel.js): update list of hosts to ping
fix(bedrock.js): add comments and improve error handling in ping function
fix(java.js): add comments and improve error handling in ping function
fix(varint.js): add comments to functions and improve readability
fix(index.d.ts): export all functions from java.js and bedrock.js
fix(lib/bedrock.d.ts): update source link
fix(lib/java.d.ts): update source link

example/cli.js

@@ -1,19 +1,15 @@
+/**
+ * Usage examples:
+ * - Java (with custom timeout): node cli.js -j --host="mc.hypixel.net" --timeout 1000
+ * - Bedrock: node cli.js -b --host="play.timecrack.net"
+ */
+
 import { pingBedrock, pingJava } from '../index.js';
 
 const args = getArgs();
 
-if (args.help || args.h || Object.keys(args).length === 0) {
+if (shouldShowHelp(args)) {
-    console.log(`node cli.js [..]
+    printHelp();
-    A simple to use, efficient, and full-featured Minecraft server info parser!
-    
-    USAGE:
-        node cli.js [OPTIONS] --host <HOST> --port <PORT> --timeout <TIMEOUT>
-        
-    OPTIONS:
-        -j  Use for Minecraft Java Edition
-        -b Use for Minecraft Bedrock Edition
-        P.S. Don't use them at the same time!`);
-
     process.exit(1);
 }
 
@@ -24,6 +20,42 @@ if (!args.host) {
 
 // easter egg <3
 if (args.j && args.b) {
+    printInterestingFacts();
+    process.exit(0);
+}
+
+const port = args.port || getDefaultPort(args);
+const timeout = args.timeout || 500;
+
+if (args.j) {
+    await pingJavaServer(args.host, port, timeout)
+        .catch(err => console.error(`ERROR: ${err.message}`));
+} else if (args.b) {
+    await pingBedrockServer(args.host, port, timeout)
+        .catch(err => console.error(`ERROR: ${err.message}`));
+} else {
+    console.error('ERROR: Unsupported flag passed. Use -h or --help.');
+}
+
+function shouldShowHelp(args) {
+    return args.help || args.h || Object.keys(args).length === 0;
+}
+
+function printHelp() {
+    console.log(`node cli.js [..]
+    A simple to use, efficient, and full-featured Minecraft server info parser!
+    
+    USAGE:
+        node cli.js [OPTIONS] --host <HOST> --port <PORT> --timeout <TIMEOUT>
+        
+    OPTIONS:
+        -j  Use for Minecraft Java Edition
+        -b  Use for Minecraft Bedrock Edition
+        
+        P.S. Don't use them at the same time!`);
+}
+
+function printInterestingFacts() {
     console.log(`Some interesting facts about MOTDs on bedrock:
     - so far they seem to exclusively use legacy color codes
     - the random style has a special impl for periods, they turn into animated
@@ -31,25 +63,20 @@ if (args.j && args.b) {
     - motd_2 is ignored? client displays "motd_1 - v{version}", where the
     appended version text is considered part of motd_1 for color code processing
     - motd_2 seems to mainly be used to return the server software in use (e.g. PocketMine-MP)`);
-    process.exit(0);
 }
 
-if (args.j) {
+function getDefaultPort(args) {
-    const data = await pingJava(args.host, {
+    return args.j ? 25565 : 19132;
-        port: args.port || 25565,
+}
-        timeout: args.timeout || 500
-    });
 
-    console.log(`host: ${args.host}\nprotocol: ${data.version.protocol}\nonline: ${data.players.online}`);
+async function pingJavaServer(host, port, timeout) {
-} else if (args.b) {
+    const data = await pingJava(host, { port, timeout });
-    const data = await pingBedrock(args.host, {
+    console.log(`host: ${host}\nprotocol: ${data.version?.protocol}\nonline: ${data.players?.online}`);
-        port: args.port || 19132,
+}
-        timeout: args.timeout || 500
-    });
 
-    console.log(`host: ${args.host}\nprotocol: ${data.version.protocol}\nonline: ${data.players.online}`);
+async function pingBedrockServer(host, port, timeout) {
-} else {
+    const data = await pingBedrock(host, { port, timeout });
-    console.error('ERROR: Unsupported flag passed. Use -h or --help.');
+    console.log(`host: ${host}\nprotocol: ${data.version.protocol}\nonline: ${data.players.online}`);
 }
 
 // parsing command line arguments

example/parallel.js

@@ -0,0 +1,19 @@
+import { pingBedrock } from '../index.js';
+
+const hosts = [
+    'play.timecrack.net',
+    'geo.hivebedrock.network',
+    'oasys-pe.com',
+    'play.galaxite.net',
+];
+
+const pingPromises = hosts.map(host => pingBedrock(host));
+const results = await Promise.allSettled(pingPromises);
+
+for (let result of results) {
+    if (result.status === 'rejected') {
+        console.error(result.reason);
+    }
+
+    console.log(result.value);
+}

lib/bedrock.js

@@ -9,71 +9,126 @@
 'use strict';
 
 import dgram from 'dgram';
-import ByteBuffer from 'bytebuffer';
 
 const START_TIME = new Date().getTime();
 
 /**
- * Decode Unconnected Ping
+ * Creates a buffer with the specified length.
- * @param {number} pingId
+ * @param {number} length - The length of the buffer.
- * @returns {import('bytebuffer')}
+ * @returns {Buffer} - The created buffer.
- * @see https://wiki.vg/Raknet_Protocol#Unconnected_Ping
  */
-const UNCONNECTED_PING = (pingId) => {
+const createBuffer = (length) => {
-    // 0x01
+    const buffer = Buffer.alloc(length);
-    const bb = new ByteBuffer();
+    buffer[0] = 0x01;
-    bb.buffer[0] = 0x01;
+    return buffer;
-    bb.offset = 1;
-    return bb.writeLong(pingId).append('00ffff00fefefefefdfdfdfd12345678', 'hex').writeLong(0).flip().compact();
 };
 
 /**
- * Decode Unconnected Pong
+ * Writes a BigInt value to the buffer at the specified offset using big-endian byte order.
- * @param {import('bytebuffer')} buffer
+ * @param {Buffer} buffer - The buffer to write to.
- * @see https://wiki.vg/Raknet_Protocol#Unconnected_Pong
+ * @param {number} value - The BigInt value to write.
+ * @param {number} offset - The offset in the buffer to write the value.
+ */
+const writeBigInt64BE = (buffer, value, offset) => {
+    buffer.writeBigInt64BE(BigInt(value), offset);
+};
+
+/**
+ * Copies the specified hex value to the buffer at the specified offset.
+ * @param {Buffer} buffer - The buffer to copy to.
+ * @param {string} hex - The hex value to copy.
+ * @param {number} offset - The offset in the buffer to copy the value.
+ */
+const copyHexToBuffer = (buffer, hex, offset) => {
+    Buffer.from(hex, 'hex').copy(buffer, offset);
+};
+
+/**
+ * Reads a BigInt value from the buffer at the specified offset using big-endian byte order.
+ * @param {Buffer} buffer - The buffer to read from.
+ * @param {number} offset - The offset in the buffer to read the value.
+ * @returns {BigInt} - The read BigInt value.
+ */
+const readBigInt64BE = (buffer, offset) => {
+    return buffer.readBigInt64BE(offset);
+};
+
+/**
+ * Reads a string from the buffer at the specified offset.
+ * @param {Buffer} buffer - The buffer to read from.
+ * @param {number} offset - The offset in the buffer to read the string.
+ * @returns {string} - The read string.
+ */
+const readStringFromBuffer = (buffer, offset) => {
+    const length = buffer.readUInt16BE(offset);
+    return buffer.toString('utf8', offset + 2, offset + 2 + length);
+};
+
+/**
+ * Parses the advertise string into an object with properties.
+ * @param {string} advertiseStr - The advertise string to parse.
+ * @returns {Object} - The parsed object with properties.
+ */
+const parseAdvertiseString = (advertiseStr) => {
+    const parts = advertiseStr.split(';');
+    return {
+        gameId: parts[0],
+        description: parts[1],
+        protocolVersion: parts[2],
+        gameVersion: parts[3],
+        currentPlayers: parts[4],
+        maxPlayers: parts[5],
+        name: parts[7],
+        mode: parts[8]
+    };
+};
+
+/**
+ * Creates an Unconnected Ping buffer.
+ * @param {number} pingId - The ping ID.
+ * @returns {Buffer} - The Unconnected Ping buffer.
+ * @see {@link https://wiki.vg/Raknet_Protocol#Unconnected_Ping}
+ */
+const UNCONNECTED_PING = (pingId) => {
+    const buffer = createBuffer(35);
+    writeBigInt64BE(buffer, pingId, 1);
+    copyHexToBuffer(buffer, '00ffff00fefefefefdfdfdfd12345678', 9);
+    writeBigInt64BE(buffer, 0, 25);
+    return buffer;
+};
+
+/**
+ * Decodes an Unconnected Pong buffer and returns the parsed data.
+ * @param {Buffer} buffer - The Unconnected Pong buffer.
+ * @returns {Object} - The parsed Unconnected Pong data.
+ * @see {@link https://wiki.vg/Raknet_Protocol#Unconnected_Pong}
  */
 const UNCONNECTED_PONG = (buffer) => {
-    // 0x1c
+    const pingId = readBigInt64BE(buffer, 1);
-    buffer.offset = 1;
+    const serverId = readBigInt64BE(buffer, 9);
-    const pingId = buffer.readLong();
+    let offset = 25;
-    const serverId = buffer.readLong();
-    const offset = buffer.offset += 16;
-    const nameLength = buffer.readShort();
     let advertiseStr;
 
     try {
-        advertiseStr = buffer.readUTF8String(nameLength);
+        advertiseStr = readStringFromBuffer(buffer, offset);
     } catch (err) {
-        advertiseStr = buffer.readUTF8String(parseInt(err.message.substr(err.message.indexOf(',') + 2, 3)));
+        const length = parseInt(err.message.substr(err.message.indexOf(',') + 2, 3));
+        advertiseStr = buffer.toString('utf8', offset, offset + length);
     }
 
-    advertiseStr = advertiseStr.split(/;/g);
+    const parsedAdvertiseStr = parseAdvertiseString(advertiseStr);
-    const gameId = advertiseStr[0];
-    const description = advertiseStr[1];
-    const protocolVersion = advertiseStr[2];
-    const gameVersion = advertiseStr[3];
-    const currentPlayers = advertiseStr[4];
-    const maxPlayers = advertiseStr[5];
-    const name = advertiseStr[7];
-    const mode = advertiseStr[8];
 
-    return {
+    return { pingId, advertiseStr, serverId, offset, ...parsedAdvertiseStr };
-        pingId,
-        advertiseStr,
-        serverId,
-        offset,
-        gameId,
-        description,
-        protocolVersion,
-        gameVersion,
-        currentPlayers,
-        maxPlayers,
-        name,
-        mode
-    };
 };
 
-function ping(host, port = 19132, cb, timeout = 5000) {
+/**
+ * Sends a ping request to the specified host and port.
+ * @param {string} host - The IP address or hostname of the server.
+ * @param {number} [port=19132] - The port number.
+ * @param {function} cb - The callback function to handle the response.
+ * @param {number} [timeout=5000] - The timeout duration in milliseconds.
+ */
+const ping = (host, port = 19132, cb, timeout = 5000) => {
     const socket = dgram.createSocket('udp4');
 
     // Set manual timeout interval.
@@ -92,6 +147,10 @@ function ping(host, port = 19132, cb, timeout = 5000) {
     // This is mostly dangerous since it can swallow errors
     let didFireError = false;
 
+    /**
+     * Handle any error that occurs during the ping process.
+     * @param {Error} err The error that occurred.
+     */
     const handleError = (err) => {
         closeSocket();
 
@@ -103,19 +162,17 @@ function ping(host, port = 19132, cb, timeout = 5000) {
 
     try {
         const ping = UNCONNECTED_PING(new Date().getTime() - START_TIME);
-        socket.send(ping.buffer, 0, ping.buffer.length, port, host);
+        socket.send(ping, 0, ping.length, port, host);
     } catch (err) {
         handleError(err);
     }
 
     socket.on('message', (msg) => {
-        const buffer = new ByteBuffer().append(msg, 'hex').flip();
+        const id = msg[0];
-        const id = buffer.buffer[0];
 
         switch (id) {
-            // https://wiki.vg/Raknet_Protocol#Unconnected_Ping
             case 0x1c: {
-                const pong = UNCONNECTED_PONG(buffer);
+                const pong = UNCONNECTED_PONG(msg);
                 const clientData = {
                     version: {
                         name: pong.name,
@@ -129,8 +186,6 @@ function ping(host, port = 19132, cb, timeout = 5000) {
                     gamemode: pong.mode
                 };
 
-                // Close the socket and clear the timeout task
-                // This is a general cleanup for success conditions
                 closeSocket();
                 cb(clientData, null);
                 break;
@@ -143,19 +198,17 @@ function ping(host, port = 19132, cb, timeout = 5000) {
         }
     });
 
-    socket.on('error', (err) => handleError(err));
+    socket.on('error', handleError);
-}
+};
 
 /**
  * Asynchronously ping Minecraft Bedrock server.
- * 
  * The optional `options` argument can be an object with a `ping` (default is `19132`) or/and `timeout` (default is `5000`) property.
- * 
  * @param {string} host The Bedrock server address.
  * @param {import('../types/index.js').PingOptions} options The configuration for pinging Minecraft Bedrock server.
- * @returns {Promise<import('../types/lib/bedrock.js').BedrockPingResponse>}
+ * @returns {Promise<import('../types/index.js').BedrockPingResponse>}
  */
-export function pingBedrock(host, options = {}) {
+export const pingBedrock = (host, options = {}) => {
     if (!host) throw new Error('Host argument is not provided');
 
     const { port = 19132, timeout = 5000 } = options;
@@ -165,4 +218,4 @@ export function pingBedrock(host, options = {}) {
             err ? reject(err) : resolve(res);
         }, timeout);
     });
-}
+};

lib/java.js

@@ -10,6 +10,13 @@ import varint from './varint.js';
 
 const PROTOCOL_VERSION = 0;
 
+/**
+ * Ping a Minecraft Java server.
+ * @param {string} host The host of the Java server.
+ * @param {number} [port=25565] The port of the Java server.
+ * @param {function} cb The callback function to handle the ping response.
+ * @param {number} [timeout=5000] The timeout duration in milliseconds.
+ */
 function ping(host, port = 25565, cb, timeout = 5000) {
     const socket = net.createConnection(({ host, port }));
 
@@ -29,6 +36,10 @@ function ping(host, port = 25565, cb, timeout = 5000) {
     // This is mostly dangerous since it can swallow errors
     let didFireError = false;
 
+    /**
+     * Handle any error that occurs during the ping process.
+     * @param {Error} err The error that occurred.
+     */
     const handleError = (err) => {
         closeSocket();
 
@@ -65,6 +76,7 @@ function ping(host, port = 25565, cb, timeout = 5000) {
 
     socket.on('data', (data) => {
         incomingBuffer = Buffer.concat([incomingBuffer, data]);
+
         // Wait until incomingBuffer is at least 5 bytes long to ensure it has captured the first VarInt value
         // This value is used to determine the full read length of the response
         // "VarInts are never longer than 5 bytes"
@@ -84,16 +96,15 @@ function ping(host, port = 25565, cb, timeout = 5000) {
         const packetId = varint.decodeInt(incomingBuffer, varint.decodeLength(packetLength));
 
         if (packetId === 0) {
-            const data = incomingBuffer.slice(varint.decodeLength(packetLength) + varint.decodeLength(packetId));
+            const data = incomingBuffer.subarray(varint.decodeLength(packetLength) + varint.decodeLength(packetId));
             const responseLength = varint.decodeInt(data, 0);
-            const response = data.slice(varint.decodeLength(responseLength), varint.decodeLength(responseLength) + responseLength);
+            const response = data.subarray(varint.decodeLength(responseLength), varint.decodeLength(responseLength) + responseLength);
 
             try {
                 const message = JSON.parse(response);
-                cb(null, message);
 
-                // Close the socket and clear the timeout task
                 closeSocket();
+                cb(message, null);
             } catch (err) {
                 handleError(err);
             }
@@ -107,12 +118,10 @@ function ping(host, port = 25565, cb, timeout = 5000) {
 
 /**
  * Asynchronously ping Minecraft Java server.
- * 
  * The optional `options` argument can be an object with a `ping` (default is `25565`) or/and `timeout` (default is `5000`) property.
- * 
  * @param {string} host The Java server address.
  * @param {import('../types/index.js').PingOptions} options The configuration for pinging Minecraft Java server.
- * @returns {Promise<import('../types/lib/java.js').JavaPingResponse>}
+ * @returns {Promise<import('../types/index.js').JavaPingResponse>}
  */
 export function pingJava(host, options = {}) {
     if (!host) throw new Error('Host argument is not provided');
@@ -120,7 +129,7 @@ export function pingJava(host, options = {}) {
     const { port = 25565, timeout = 5000 } = options;
 
     return new Promise((resolve, reject) => {
-        ping(host, port, (err, res) => {
+        ping(host, port, (res, err) => {
             err ? reject(err) : resolve(res);
         }, timeout);
     });

lib/varint.js

@@ -1,6 +1,14 @@
 // https://wiki.vg/Data_types
 
+/**
+ * A utility object for encoding and decoding varints.
+ */
 const varint = {
+    /**
+     * Encodes an integer value into a varint byte buffer.
+     * @param {number} val - The integer value to encode.
+     * @returns {Buffer}
+     */
     encodeInt: (val) => {
         // "constInts are never longer than 5 bytes"
         // https://wiki.vg/Data_types#constInt_and_constLong
@@ -8,26 +16,43 @@ const varint = {
         let written = 0;
 
         while (true) {
-            if ((val & 0xFFFFFF80) === 0) {
+            const byte = val & 0x7F;
-                buf.writeUInt8(val, written++);
-                break;
-            } else {
-                buf.writeUInt8(val & 0x7F | 0x80, written++);
             val >>>= 7;
+
+            if (val === 0) {
+                buf.writeUInt8(byte, written++);
+                break;
             }
+
+            buf.writeUInt8(byte | 0x80, written++);
         }
 
         return buf.slice(0, written);
     },
 
+    /**
+     * Encodes a string value into a UTF-8 byte buffer.
+     * @param {string} val - The string value to encode.
+     * @returns {Buffer}
+     */
     encodeString: (val) => {
         return Buffer.from(val, 'utf-8');
     },
 
+    /**
+     * Encodes an unsigned short value into a byte buffer.
+     * @param {number} val - The unsigned short value to encode.
+     * @returns {Buffer}
+     */
     encodeUShort: (val) => {
         return Buffer.from([val >> 8, val & 0xFF]);
     },
 
+    /**
+     * Concatenates multiple byte buffers into a single byte buffer.
+     * @param {Buffer[]} chunks - An array of byte buffers to concatenate.
+     * @returns {Buffer}
+     */
     concat: (chunks) => {
         let length = 0;
 
@@ -43,16 +68,22 @@ const varint = {
         return Buffer.concat(buffer);
     },
 
+    /**
+     * Decodes a varint integer value from a byte buffer.
+     * @param {Buffer} buffer - The byte buffer to decode from.
+     * @param {number} offset - The offset in the buffer to start decoding from.
+     * @returns {number}
+     */
     decodeInt: (buffer, offset) => {
         let val = 0;
         let count = 0;
 
         while (true) {
-            const b = buffer.readUInt8(offset++);
+            const byte = buffer.readUInt8(offset++);
 
-            val |= (b & 0x7F) << count++ * 7;
+            val |= (byte & 0x7F) << count++ * 7;
 
-            if ((b & 0x80) != 128) {
+            if ((byte & 0x80) !== 0x80) {
                 break;
             }
         }
@@ -60,8 +91,13 @@ const varint = {
         return val;
     },
 
-    // The number of bytes that the last .decodeInt() call had to use to decode.
+    /**
+     * Calculates the number of bytes required to decode a varint integer value.
+     * @param {number} val - The varint integer value.
+     * @returns {5 | 7 | 8 | 1 | 2 | 3 | 4 | 6 | 9 | 10}
+     */
     decodeLength: (val) => {
+        // Constants representing the powers of 2 used for comparison
         const N1 = Math.pow(2, 7);
         const N2 = Math.pow(2, 14);
         const N3 = Math.pow(2, 21);
@@ -72,6 +108,7 @@ const varint = {
         const N8 = Math.pow(2, 56);
         const N9 = Math.pow(2, 63);
 
+        // Return the number of bytes required based on the value
         return (
             val < N1 ? 1
                 : val < N2 ? 2

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minescope/mineping",
-  "version": "1.0.4",
+  "version": "1.1.1",
   "description": "Ping both Minecraft Bedrock and Java servers.",
   "main": "index.js",
   "types": "types/index.d.ts",
@@ -18,8 +18,5 @@
   "engines": {
     "node": ">=14"
   },
-  "license": "MIT",
+  "license": "MIT"
-  "dependencies": {
-    "bytebuffer": "^5.0.1"
-  }
 }

types/index.d.ts

@@ -1,2 +1,2 @@
-export { pingJava } from "./lib/java.js";
+export * from "./lib/java.js";
-export { pingBedrock } from "./lib/bedrock.js";
+export * from "./lib/bedrock.js";

types/lib/bedrock.d.ts

@@ -43,7 +43,7 @@ export type BedrockPingResponse = {
  *   gamemode: 'Survival'
  * }
  * ```
- * @see [source](https://github.com/minescope/mineping/blob/24a48802300f988d3ae520edbeb4f3e12820dcc9/lib/java.js#L117)
+ * @see [source](https://github.com/minescope/mineping/blob/915edbec9c9ad811459458600af3531ec0836911/lib/bedrock.js#L204)
  */
 export function pingBedrock(host: string, options?: PingOptions): Promise<BedrockPingResponse>;
 

types/lib/java.d.ts

@@ -1,5 +1,20 @@
 import { PingOptions } from "./bedrock";
 
+/**
+ * JSON format chat component used for description field.
+ * @see https://wiki.vg/Chat
+ */
+export type ChatComponent = {
+    text: string;
+    bold?: boolean;
+    italic?: boolean;
+    underlined?: boolean;
+    strikethrough?: boolean;
+    obfuscated?: boolean;
+    color?: string;
+    extra?: ChatComponent[];
+};
+
 export type SampleProp = {
     name: string,
     id: string;
@@ -17,10 +32,12 @@ export type JavaPingResponse = {
     players: {
         max: number;
         online: number;
-        sample: SampleProp[];
+        sample?: SampleProp[];
     };
-    description: string;
+    description: string | ChatComponent;
-    favicon: string;
+    favicon?: string;
+    enforcesSecureChat?: boolean;
+    previewsChat?: boolean;
 };
 
 /**
@@ -48,7 +65,7 @@ export type JavaPingResponse = {
  * favicon: 'data:image/png;base64,iVBORw0KGg...
  }
  * ```
- * @see [source](https://github.com/minescope/mineping/blob/8c84925ef7f5c420a7ef52740cba027491e82934/lib/bedrock.js#L158)
+ * @see [source](https://github.com/minescope/mineping/blob/915edbec9c9ad811459458600af3531ec0836911/lib/java.js#L117)
  */
 export function pingJava(host: string, options?: PingOptions): Promise<JavaPingResponse>;
 

yarn.lock

@@ -1,15 +0,0 @@
-# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
-# yarn lockfile v1
-
-
-bytebuffer@^5.0.1:
-  version "5.0.1"
-  resolved "https://registry.yarnpkg.com/bytebuffer/-/bytebuffer-5.0.1.tgz#582eea4b1a873b6d020a48d58df85f0bba6cfddd"
-  integrity sha1-WC7qSxqHO20CCkjVjfhfC7ps/d0=
-  dependencies:
-    long "~3"
-
-long@~3:
-  version "3.2.0"
-  resolved "https://registry.yarnpkg.com/long/-/long-3.2.0.tgz#d821b7138ca1cb581c172990ef14db200b5c474b"
-  integrity sha1-2CG3E4yhy1gcFymQ7xTbIAtcR0s=