chore: bump version to 1.6.1

docs: update type definitions

example/cli.js

@@ -1,40 +1,83 @@
+#!/usr/bin/env node
+
 /**
  * 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';
+import { pingBedrock, pingJava } from "../index.js";
 
-const args = getArgs();
+const DEFAULT_TIMEOUT = 5000;
+const JAVA_DEFAULT_PORT = 25565;
+const BEDROCK_DEFAULT_PORT = 19132;
+
+try {
+	const args = parseArgs(process.argv.slice(2));
 
 	if (shouldShowHelp(args)) {
 		printHelp();
+		process.exit(0);
+	}
+
+	validateArgs(args);
+
+	const port = Number(args.port) || getDefaultPort(args);
+	const timeout = Number(args.timeout) || DEFAULT_TIMEOUT;
+
+	if (args.j) {
+		await pingJavaServer(args.host, port, timeout);
+	} else if (args.b) {
+		await pingBedrockServer(args.host, port, timeout);
+	}
+} catch (err) {
+	console.error(`ERROR: ${err.message}`);
 	process.exit(1);
 }
 
-if (!args.host) {
+function parseArgs(rawArgs) {
-    console.error('ERROR: The host argument not found! Use -h or --help.');
+	const args = {};
-    process.exit(1);
+
+	for (let i = 0; i < rawArgs.length; i++) {
+		const arg = rawArgs[i];
+
+		if (arg.startsWith("--")) {
+			// Handle --key=value and --key value formats
+			const [key, value] = arg.slice(2).split("=");
+			args[key] = value ?? rawArgs[++i] ?? true;
+		} else if (arg.startsWith("-")) {
+			// Handle short flags (-j, -b, -h)
+			const flags = arg.slice(1).split("");
+			flags.forEach((flag) => {
+				args[flag] = true;
+			});
+		}
 	}
 
-// easter egg <3
+	return args;
+}
+
+function validateArgs(args) {
 	if (args.j && args.b) {
 		printInterestingFacts();
 		process.exit(0);
 	}
 
-const port = args.port || getDefaultPort(args);
+	if (!args.host) {
-const timeout = args.timeout || 500;
+		throw new Error("The host argument not found! Use -h or --help.");
+	}
 
-if (args.j) {
+	if (!args.j && !args.b) {
-    await pingJavaServer(args.host, port, timeout)
+		throw new Error("Must specify either -j or -b flag. Use -h or --help.");
-        .catch(err => console.error(`ERROR: ${err.message}`));
+	}
-} else if (args.b) {
+
-    await pingBedrockServer(args.host, port, timeout)
+	if (args.port && (isNaN(args.port) || args.port < 1 || args.port > 65535)) {
-        .catch(err => console.error(`ERROR: ${err.message}`));
+		throw new Error("Port must be a number between 1 and 65535");
-} else {
+	}
-    console.error('ERROR: Unsupported flag passed. Use -h or --help.');
+
+	if (args.timeout && (isNaN(args.timeout) || args.timeout < 0)) {
+		throw new Error("Timeout must be a positive number");
+	}
 }
 
 function shouldShowHelp(args) {
@@ -51,8 +94,13 @@ function printHelp() {
     OPTIONS:
         -j  Use for Minecraft Java Edition
         -b  Use for Minecraft Bedrock Edition
+        -h, --help  Show this help message
         
-        P.S. Don't use them at the same time!`);
+        --host     The server address (required)
+        --port     The server port (default: ${JAVA_DEFAULT_PORT} for Java, ${BEDROCK_DEFAULT_PORT} for Bedrock)
+        --timeout  The socket timeout in milliseconds (default: ${DEFAULT_TIMEOUT})
+        
+        P.S. Don't use -j and -b at the same time!`);
 }
 
 function printInterestingFacts() {
@@ -66,37 +114,27 @@ function printInterestingFacts() {
 }
 
 function getDefaultPort(args) {
-    return args.j ? 25565 : 19132;
+	return args.j ? JAVA_DEFAULT_PORT : BEDROCK_DEFAULT_PORT;
 }
 
 async function pingJavaServer(host, port, timeout) {
 	const data = await pingJava(host, { port, timeout });
-    console.log(`host: ${host}\nprotocol: ${data.version?.protocol}\nonline: ${data.players?.online}`);
+	console.log(`Host: ${host}
+Version: ${data.version?.name} (protocol: ${data.version?.protocol})
+Players: ${data.players?.online}/${data.players?.max}
+Description: ${
+		typeof data.description === "string"
+			? data.description
+			: data.description?.text
+	}`);
 }
 
 async function pingBedrockServer(host, port, timeout) {
 	const data = await pingBedrock(host, { port, timeout });
-    console.log(`host: ${host}\nprotocol: ${data.version.protocol}\nonline: ${data.players.online}`);
+	console.log(`Host: ${host}
-}
+Edition: ${data.edition}
-
+Version: ${data.version.minecraftVersion} (protocol: ${data.version.protocolVersion})
-// parsing command line arguments
+Players: ${data.players.online}/${data.players.max}
-function getArgs() {
+Name: ${data.name}
-    const args = {};
+Gamemode: ${data.gameMode}`);
-    process.argv.slice(2).forEach(arg => {
-        // long arg
-        if (arg.slice(0, 2) === '--') {
-            const longArg = arg.split('=');
-            const longArgFlag = longArg[0].slice(2, longArg[0].length);
-            const longArgValue = longArg.length > 1 ? longArg[1] : true;
-            args[longArgFlag] = longArgValue;
-            // flags
-        } else if (arg[0] === '-') {
-            const flags = arg.slice(1, arg.length).split('');
-            flags.forEach(flag => {
-                args[flag] = true;
-            });
-        }
-    });
-
-    return args;
 }

lib/bedrock.js

@@ -10,6 +10,7 @@ import crypto from "node:crypto";
 
 const MAGIC = "00ffff00fefefefefdfdfdfd12345678";
 const START_TIME = new Date().getTime();
+const UNCONNECTED_PONG = 0x1c;
 
 /**
  * Creates an Unconnected Ping packet.
@@ -30,12 +31,25 @@ const createUnconnectedPingFrame = (timestamp) => {
  * Extract Modt from Unconnected Pong Packet and convert to an object
  * @param {Buffer} unconnectedPongPacket
  * @returns {Object}
+ * @throws {Error} If packet is malformed or invalid
  * @see {@link https://minecraft.wiki/w/Minecraft_Wiki:Projects/wiki.vg_merge/Raknet_Protocol#Unconnected_Pong}
  */
 const extractModt = (unconnectedPongPacket) => {
-	// Skip everything to Modt
+	if (
+		!Buffer.isBuffer(unconnectedPongPacket) ||
+		unconnectedPongPacket.length < 35
+	) {
+		throw new Error("Invalid pong packet");
+	}
+
 	const offset = 33;
 	const length = unconnectedPongPacket.readUInt16BE(offset);
+
+	// Check for buffer bounds
+	if (offset + 2 + length > unconnectedPongPacket.length) {
+		throw new Error("Malformed pong packet");
+	}
+
 	let modt = unconnectedPongPacket.toString(
 		"utf-8",
 		offset + 2,
@@ -43,6 +57,12 @@ const extractModt = (unconnectedPongPacket) => {
 	);
 
 	const components = modt.split(";");
+
+	// Validate required components
+	if (components.length < 9) {
+		throw new Error("Invalid MODT format");
+	}
+
 	const parsedComponents = {
 		edition: components[0],
 		name: components[1],
@@ -109,20 +129,23 @@ const ping = (host, port = 19132, cb, timeout = 5000) => {
 	}
 
 	socket.on("message", (pongPacket) => {
-		const id = pongPacket[0];
+		if (!Buffer.isBuffer(pongPacket) || pongPacket.length === 0) {
+			handleError(new Error("Invalid packet received"));
+			return;
+		}
 
-		switch (id) {
+		const id = pongPacket[0];
-			case 0x1c: {
+		if (id !== UNCONNECTED_PONG) {
+			handleError(new Error(`Unexpected packet ID: 0x${id.toString(16)}`));
+			return;
+		}
+
+		try {
 			const modtObject = extractModt(pongPacket);
 			closeSocket();
 			cb(modtObject, null);
-				break;
+		} catch (err) {
-			}
+			handleError(err);
-
-			default: {
-				handleError(new Error("Received unexpected packet"));
-				break;
-			}
 		}
 	});
 

lib/varint.js

@@ -27,7 +27,7 @@ const varint = {
 			buf.writeUInt8(byte | 0x80, written++);
 		}
 
-		return buf.slice(0, written);
+		return buf.subarray(0, written);
 	},
 
 	/**
@@ -66,65 +66,57 @@ const varint = {
 	},
 
 	/**
-	 * Decodes a varint integer value from a byte buffer.
+	 * Decodes a varint integer value from a 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;
+		// Fast path for single-byte varints
-		let count = 0;
+		const firstByte = buffer.readUInt8(offset);
-
+		if (firstByte < 0x80) {
-		while (true) {
+			return firstByte;
-			const byte = buffer.readUInt8(offset++);
-
-			val |= (byte & 0x7f) << (count++ * 7);
-
-			if ((byte & 0x80) !== 0x80) {
-				break;
-			}
 		}
 
+		let val = firstByte & 0x7f;
+		let position = 7;
+
+		while (position < 32) {
+			const byte = buffer.readUInt8(++offset);
+			val |= (byte & 0x7f) << position;
+
+			if ((byte & 0x80) === 0) {
 				return val;
+			}
+
+			position += 7;
+		}
+
+		throw new Error("VarInt is too big");
 	},
 
 	/**
-	 * Calculates the number of bytes required to decode a varint integer value.
+	 * Calculates how many bytes are needed to encode a number as a VarInt
-	 * @param {number} val - The varint integer value.
+	 * VarInts use a variable number of bytes to efficiently encode integers
-	 * @returns {5 | 7 | 8 | 1 | 2 | 3 | 4 | 6 | 9 | 10}
+	 * Each byte uses 7 bits for the value and 1 bit to indicate if more bytes follow
+	 * VarInts are never longer than 5 bytes
+	 *
+	 * @param {number} val - The number to calculate the VarInt length for
+	 * @returns {1|2|3|4|5} The number of bytes needed to encode the value
 	 */
 	decodeLength: (val) => {
-		// Constants representing the powers of 2 used for comparison
+		// Using bit shifts to calculate power of 2 thresholds
-		const N1 = Math.pow(2, 7);
+		// 1 << 7  = 2^7  = 128      - Numbers below this fit in 1 byte
-		const N2 = Math.pow(2, 14);
+		// 1 << 14 = 2^14 = 16,384   - Numbers below this fit in 2 bytes
-		const N3 = Math.pow(2, 21);
+		// 1 << 21 = 2^21 = 2,097,152 - Numbers below this fit in 3 bytes
-		const N4 = Math.pow(2, 28);
+		// 1 << 28 = 2^28 = 268,435,456 - Numbers below this fit in 4 bytes
-		const N5 = Math.pow(2, 35);
+		// Any larger number needs 5 bytes (maximum VarInt size)
-		const N6 = Math.pow(2, 42);
-		const N7 = Math.pow(2, 49);
-		const N8 = Math.pow(2, 56);
-		const N9 = Math.pow(2, 63);
 
-		// Return the number of bytes required based on the value
+		if (val < 1 << 7) return 1;
-		return val < N1
+		if (val < 1 << 14) return 2;
-			? 1
+		if (val < 1 << 21) return 3;
-			: val < N2
+		if (val < 1 << 28) return 4;
-			? 2
+		return 5;
-			: val < N3
-			? 3
-			: val < N4
-			? 4
-			: val < N5
-			? 5
-			: val < N6
-			? 6
-			: val < N7
-			? 7
-			: val < N8
-			? 8
-			: val < N9
-			? 9
-			: 10;
 	},
 };
 

package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@minescope/mineping",
-  "version": "1.6.0",
+	"version": "1.6.1",
 	"description": "Ping both Minecraft Bedrock and Java servers.",
 	"main": "index.js",
 	"types": "types/index.d.ts",

types/lib/bedrock.d.ts

@@ -1,10 +1,10 @@
 /**
- * @param port The server port.
+ * @param port The server port (1-65535).
- * @param timeout The read/write socket timeout.
+ * @param timeout The read/write socket timeout in milliseconds.
  */
 export type BedrockPingOptions = {
-    port?: number;
+	port?: number & { _brand: "Port" }; // 1-65535
-    timeout?: number;
+	timeout?: number & { _brand: "Timeout" }; // > 0
 };
 
 export type BedrockPingResponse = {
@@ -26,8 +26,6 @@ export type BedrockPingResponse = {
 /**
  * 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 host The Bedrock server address.
  * @param options The configuration for pinging Minecraft Bedrock server.
  *
@@ -41,13 +39,23 @@ export type BedrockPingResponse = {
  * The resulting output will resemble:
  * ```console
  * {
- *   version: { name: 'Mineplex', protocol: '475' },
+ *   edition: "MCPE",
- *   players: { max: '5207', online: '5206' },
+ *   name: "Mineplex",
- *   description: ' New Costumes',
+ *   version: {
- *   gamemode: 'Survival'
+ *     protocolVersion: 475,
+ *     minecraftVersion: "1.18.0"
+ *   },
+ *   players: {
+ *     online: 5206,
+ *     max: 5207
+ *   },
+ *   serverId: "12345678",
+ *   mapName: "Lobby",
+ *   gameMode: "Survival"
  * }
  * ```
- * @see [source](https://github.com/minescope/mineping/blob/915edbec9c9ad811459458600af3531ec0836911/lib/bedrock.js#L204)
  */
-export function pingBedrock(host: string, options?: BedrockPingOptions): Promise<BedrockPingResponse>;
+export function pingBedrock(
-
+	host: string,
+	options?: BedrockPingOptions
+): Promise<BedrockPingResponse>;

types/lib/varint.d.ts

@@ -1,10 +1,44 @@
 export default varint;
 declare namespace varint {
+	/**
+	 * Encodes an integer value into a varint byte buffer.
+	 * @param val - The integer value to encode.
+	 */
 	function encodeInt(val: number): Buffer;
+
+	/**
+	 * Encodes a string value into a UTF-8 byte buffer.
+	 * @param val - The string value to encode.
+	 */
 	function encodeString(val: string): Buffer;
+
+	/**
+	 * Encodes an unsigned short value into a byte buffer.
+	 * @param val - The unsigned short value to encode.
+	 */
 	function encodeUShort(val: number): Buffer;
+
+	/**
+	 * Concatenates multiple byte buffers into a single byte buffer.
+	 * @param chunks - An array of byte buffers to concatenate.
+	 */
 	function concat(chunks: Buffer[]): Buffer;
+
+	/**
+	 * Decodes a varint integer value from a buffer.
+	 * @param buffer - The byte buffer to decode from.
+	 * @param offset - The offset in the buffer to start decoding from.
+	 */
 	function decodeInt(buffer: Buffer, offset: number): number;
-    function decodeString(val: Buffer, offset?: number): string;
+
-    function decodeLength(val: number): 5 | 7 | 8 | 1 | 2 | 3 | 4 | 6 | 9 | 10;
+	/**
+	 * Calculates how many bytes are needed to encode a number as a VarInt.
+	 * VarInts use a variable number of bytes to efficiently encode integers.
+	 * Each byte uses 7 bits for the value and 1 bit to indicate if more bytes follow.
+	 * VarInts are never longer than 5 bytes.
+	 *
+	 * @param val - The number to calculate the VarInt length for.
+	 * @returns The number of bytes needed to encode the value (1-5).
+	 */
+	function decodeLength(val: number): 1 | 2 | 3 | 4 | 5;
 }