chore: bump version to 1.6.1

docs: update type definitions

example/cli.js

@@ -1,48 +1,91 @@
+#!/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;
 
-if (shouldShowHelp(args)) {
+try {
-    printHelp();
+	const args = parseArgs(process.argv.slice(2));
-    process.exit(1);
+
+	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;
+			});
+		}
+	}
+
+	return args;
 }
 
-// easter egg <3
+function validateArgs(args) {
-if (args.j && args.b) {
+	if (args.j && args.b) {
-    printInterestingFacts();
+		printInterestingFacts();
-    process.exit(0);
+		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) {
-    return args.help || args.h || Object.keys(args).length === 0;
+	return args.help || args.h || Object.keys(args).length === 0;
 }
 
 function printHelp() {
-    console.log(`node cli.js [..]
+	console.log(`node cli.js [..]
     A simple to use, efficient, and full-featured Minecraft server info parser!
     
     USAGE:
@@ -51,12 +94,17 @@ 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() {
-    console.log(`Some interesting facts about MOTDs on bedrock:
+	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
     colons that warp up and down rapidly
@@ -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 });
+	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 });
+	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})
+Players: ${data.players.online}/${data.players.max}
+Name: ${data.name}
+Gamemode: ${data.gameMode}`);
 }
-
-// parsing command line arguments
-function getArgs() {
-    const args = {};
-    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

@@ -1,61 +1,85 @@
 /**
  * Implementation of the RakNet ping/pong protocol.
- * @see https://wiki.vg/Raknet_Protocol
+ * @see https://minecraft.wiki/w/Minecraft_Wiki:Projects/wiki.vg_merge/Raknet_Protocol
  */
 
-'use strict';
+"use strict";
 
-import dgram from 'node:dgram';
+import dgram from "node:dgram";
-import crypto from 'node:crypto'
+import crypto from "node:crypto";
 
 const MAGIC = "00ffff00fefefefefdfdfdfd12345678";
 const START_TIME = new Date().getTime();
+const UNCONNECTED_PONG = 0x1c;
 
 /**
  * Creates an Unconnected Ping packet.
  * @param {number} pingId
  * @returns {Buffer}
- * @see {@link https://wiki.vg/Raknet_Protocol#Unconnected_Ping}
+ * @see {@link https://minecraft.wiki/w/Minecraft_Wiki:Projects/wiki.vg_merge/Raknet_Protocol#Unconnected_Ping}
  */
 const createUnconnectedPingFrame = (timestamp) => {
-    const buffer = Buffer.alloc(33);
+	const buffer = Buffer.alloc(33);
-    buffer.writeUInt8(0x01, 0); // Packet ID
+	buffer.writeUInt8(0x01, 0); // Packet ID
-    buffer.writeBigInt64LE(BigInt(timestamp), 1); // Timestamp
+	buffer.writeBigInt64LE(BigInt(timestamp), 1); // Timestamp
-    Buffer.from(MAGIC, "hex").copy(buffer, 9); // OFFLINE_MESSAGE_DATA_ID (Magic)
+	Buffer.from(MAGIC, "hex").copy(buffer, 9); // OFFLINE_MESSAGE_DATA_ID (Magic)
-    Buffer.from(crypto.randomBytes(8)).copy(buffer, 25); // Client GUID
+	Buffer.from(crypto.randomBytes(8)).copy(buffer, 25); // Client GUID
-    return buffer;
+	return buffer;
 };
 
 /**
  * Extract Modt from Unconnected Pong Packet and convert to an object
  * @param {Buffer} unconnectedPongPacket
  * @returns {Object}
- * @see {@link https://wiki.vg/Raknet_Protocol#Unconnected_Pong}
+ * @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 (
-    const offset = 33;
+		!Buffer.isBuffer(unconnectedPongPacket) ||
-    const length = unconnectedPongPacket.readUInt16BE(offset);
+		unconnectedPongPacket.length < 35
-    let modt = unconnectedPongPacket.toString("utf-8", offset + 2, offset + 2 + length);
+	) {
+		throw new Error("Invalid pong packet");
+	}
 
-    const components = modt.split(';');
+	const offset = 33;
-    const parsedComponents = {
+	const length = unconnectedPongPacket.readUInt16BE(offset);
-        edition: components[0],
-        name: components[1],
-        version: {
-            protocolVersion: Number(components[2]),
-            minecraftVersion: components[3],
-        },
-        players: {
-            online: Number(components[4]),
-            max: Number(components[5])
-        },
-        serverId: components[6],
-        mapName: components[7],
-        gameMode: components[8]
-    };
 
-    return parsedComponents;
+	// Check for buffer bounds
+	if (offset + 2 + length > unconnectedPongPacket.length) {
+		throw new Error("Malformed pong packet");
+	}
+
+	let modt = unconnectedPongPacket.toString(
+		"utf-8",
+		offset + 2,
+		offset + 2 + length
+	);
+
+	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],
+		version: {
+			protocolVersion: Number(components[2]),
+			minecraftVersion: components[3],
+		},
+		players: {
+			online: Number(components[4]),
+			max: Number(components[5]),
+		},
+		serverId: components[6],
+		mapName: components[7],
+		gameMode: components[8],
+	};
+
+	return parsedComponents;
 };
 
 /**
@@ -66,63 +90,66 @@ const extractModt = (unconnectedPongPacket) => {
  * @param {number} [timeout=5000] - The timeout duration in milliseconds.
  */
 const ping = (host, port = 19132, cb, timeout = 5000) => {
-    const socket = dgram.createSocket('udp4');
+	const socket = dgram.createSocket("udp4");
 
-    // Set manual timeout interval.
+	// Set manual timeout interval.
-    // This ensures the connection will NEVER hang regardless of internal state
+	// This ensures the connection will NEVER hang regardless of internal state
-    const timeoutTask = setTimeout(() => {
+	const timeoutTask = setTimeout(() => {
-        socket.emit('error', new Error('Socket timeout'));
+		socket.emit("error", new Error("Socket timeout"));
-    }, timeout);
+	}, timeout);
 
-    const closeSocket = () => {
+	const closeSocket = () => {
-        socket.close();
+		socket.close();
-        clearTimeout(timeoutTask);
+		clearTimeout(timeoutTask);
-    };
+	};
 
-    // Generic error handler
+	// Generic error handler
-    // This protects multiple error callbacks given the complex socket state
+	// This protects multiple error callbacks given the complex socket state
-    // This is mostly dangerous since it can swallow errors
+	// This is mostly dangerous since it can swallow errors
-    let didFireError = false;
+	let didFireError = false;
 
-    /**
+	/**
-     * Handle any error that occurs during the ping process.
+	 * Handle any error that occurs during the ping process.
-     * @param {Error} err The error that occurred.
+	 * @param {Error} err The error that occurred.
-     */
+	 */
-    const handleError = (err) => {
+	const handleError = (err) => {
-        closeSocket();
+		closeSocket();
 
-        if (!didFireError) {
+		if (!didFireError) {
-            didFireError = true;
+			didFireError = true;
-            cb(null, err);
+			cb(null, err);
-        }
+		}
-    };
+	};
 
-    try {
+	try {
-        const ping = createUnconnectedPingFrame(new Date().getTime() - START_TIME);
+		const ping = createUnconnectedPingFrame(new Date().getTime() - START_TIME);
-        socket.send(ping, 0, ping.length, port, host);
+		socket.send(ping, 0, ping.length, port, host);
-    } catch (err) {
+	} catch (err) {
-        handleError(err);
+		handleError(err);
-    }
+	}
 
-    socket.on('message', (pongPacket) => {
+	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) {
-                const modtObject = extractModt(pongPacket);
+			handleError(new Error(`Unexpected packet ID: 0x${id.toString(16)}`));
-                closeSocket();
+			return;
-                cb(modtObject, null);
+		}
-                break;
-            }
 
-            default: {
+		try {
-                handleError(new Error('Received unexpected packet'));
+			const modtObject = extractModt(pongPacket);
-                break;
+			closeSocket();
-            }
+			cb(modtObject, null);
-        }
+		} catch (err) {
-    });
+			handleError(err);
+		}
+	});
 
-    socket.on('error', handleError);
+	socket.on("error", handleError);
 };
 
 /**
@@ -133,13 +160,18 @@ const ping = (host, port = 19132, cb, timeout = 5000) => {
  * @returns {Promise<import('../types/index.js').BedrockPingResponse>}
  */
 export const pingBedrock = (host, options = {}) => {
-    if (!host) throw new Error('Host argument is not provided');
+	if (!host) throw new Error("Host argument is not provided");
 
-    const { port = 19132, timeout = 5000 } = options;
+	const { port = 19132, timeout = 5000 } = options;
 
-    return new Promise((resolve, reject) => {
+	return new Promise((resolve, reject) => {
-        ping(host, port, (res, err) => {
+		ping(
-            err ? reject(err) : resolve(res);
+			host,
-        }, timeout);
+			port,
-    });
+			(res, err) => {
+				err ? reject(err) : resolve(res);
+			},
+			timeout
+		);
+	});
 };

lib/java.js

@@ -1,118 +1,125 @@
 /**
  * Implementation of the Java Minecraft ping protocol.
- * @see https://wiki.vg/Server_List_Ping
+ * @see https://minecraft.wiki/w/Minecraft_Wiki:Projects/wiki.vg_merge/Server_List_Ping
  */
 
-'use strict';
+"use strict";
 
-import net from 'node:net';
+import net from "node:net";
-import varint from './varint.js';
+import varint from "./varint.js";
 
 /**
  * Ping a Minecraft Java server.
  * @param {string} host The host of the Java server.
+ * @param {string} virtualHost The host sent in handshake.
  * @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.
  * @param {number} [protocolVersion=-1] The protocol version of the Java client.
  */
-function ping(host, port = 25565, cb, timeout = 5000, protocolVersion = -1) {
+function ping(host, virtualHost, port = 25565, cb, timeout = 5000, protocolVersion = -1) {
-    const socket = net.createConnection(({ host, port }));
+	const socket = net.createConnection({ host, port });
 
-    // Set manual timeout interval.
+	// Set manual timeout interval.
-    // This ensures the connection will NEVER hang regardless of internal state
+	// This ensures the connection will NEVER hang regardless of internal state
-    const timeoutTask = setTimeout(() => {
+	const timeoutTask = setTimeout(() => {
-        socket.emit('error', new Error('Socket timeout'));
+		socket.emit("error", new Error("Socket timeout"));
-    }, timeout);
+	}, timeout);
 
-    const closeSocket = () => {
+	const closeSocket = () => {
-        socket.destroy();
+		socket.destroy();
-        clearTimeout(timeoutTask);
+		clearTimeout(timeoutTask);
-    };
+	};
 
-    // Generic error handler
+	// Generic error handler
-    // This protects multiple error callbacks given the complex socket state
+	// This protects multiple error callbacks given the complex socket state
-    // This is mostly dangerous since it can swallow errors
+	// This is mostly dangerous since it can swallow errors
-    let didFireError = false;
+	let didFireError = false;
 
-    /**
+	/**
-     * Handle any error that occurs during the ping process.
+	 * Handle any error that occurs during the ping process.
-     * @param {Error} err The error that occurred.
+	 * @param {Error} err The error that occurred.
-     */
+	 */
-    const handleError = (err) => {
+	const handleError = (err) => {
-        closeSocket();
+		closeSocket();
 
-        if (!didFireError) {
+		if (!didFireError) {
-            didFireError = true;
+			didFireError = true;
-            cb(null, err);
+			cb(null, err);
-        }
+		}
-    };
+	};
 
-    // #setNoDelay instantly flushes data during read/writes
+	// #setNoDelay instantly flushes data during read/writes
-    // This prevents the runtime from delaying the write at all
+	// This prevents the runtime from delaying the write at all
-    socket.setNoDelay(true);
+	socket.setNoDelay(true);
 
-    socket.on('connect', () => {
+	socket.on("connect", () => {
-        const handshake = varint.concat([
+		const handshake = varint.concat([
-            varint.encodeInt(0),
+			varint.encodeInt(0),
-            varint.encodeInt(protocolVersion),
+			varint.encodeInt(protocolVersion),
-            varint.encodeInt(host.length),
+			varint.encodeInt(virtualHost.length),
-            varint.encodeString(host),
+			varint.encodeString(virtualHost),
-            varint.encodeUShort(port),
+			varint.encodeUShort(port),
-            varint.encodeInt(1)
+			varint.encodeInt(1),
-        ]);
+		]);
 
-        socket.write(handshake);
+		socket.write(handshake);
 
-        const request = varint.concat([
+		const request = varint.concat([varint.encodeInt(0)]);
-            varint.encodeInt(0)
-        ]);
 
-        socket.write(request);
+		socket.write(request);
-    });
+	});
 
-    let incomingBuffer = Buffer.alloc(0);
+	let incomingBuffer = Buffer.alloc(0);
 
-    socket.on('data', (data) => {
+	socket.on("data", (data) => {
-        incomingBuffer = Buffer.concat([incomingBuffer, data]);
+		incomingBuffer = Buffer.concat([incomingBuffer, data]);
 
-        // Wait until incomingBuffer is at least 5 bytes long to ensure it has captured the first VarInt value
+		// 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
+		// This value is used to determine the full read length of the response
-        // "VarInts are never longer than 5 bytes"
+		// "VarInts are never longer than 5 bytes"
-        // https://wiki.vg/Data_types#VarInt_and_VarLong
+		// https://minecraft.wiki/w/Minecraft_Wiki:Projects/wiki.vg_merge/Data_types#VarInt_and_VarLong
-        if (incomingBuffer.length < 5) {
+		if (incomingBuffer.length < 5) {
-            return;
+			return;
-        }
+		}
 
-        let offset = 0;
+		let offset = 0;
-        const packetLength = varint.decodeInt(incomingBuffer, offset);
+		const packetLength = varint.decodeInt(incomingBuffer, offset);
 
-        // Ensure incomingBuffer contains the full response
+		// Ensure incomingBuffer contains the full response
-        if (incomingBuffer.length - offset < packetLength) {
+		if (incomingBuffer.length - offset < packetLength) {
-            return;
+			return;
-        }
+		}
 
-        const packetId = varint.decodeInt(incomingBuffer, varint.decodeLength(packetLength));
+		const packetId = varint.decodeInt(
+			incomingBuffer,
+			varint.decodeLength(packetLength)
+		);
 
-        if (packetId === 0) {
+		if (packetId === 0) {
-            const data = incomingBuffer.subarray(varint.decodeLength(packetLength) + varint.decodeLength(packetId));
+			const data = incomingBuffer.subarray(
-            const responseLength = varint.decodeInt(data, 0);
+				varint.decodeLength(packetLength) + varint.decodeLength(packetId)
-            const response = data.subarray(varint.decodeLength(responseLength), varint.decodeLength(responseLength) + responseLength);
+			);
+			const responseLength = varint.decodeInt(data, 0);
+			const response = data.subarray(
+				varint.decodeLength(responseLength),
+				varint.decodeLength(responseLength) + responseLength
+			);
 
-            try {
+			try {
-                const message = JSON.parse(response);
+				const message = JSON.parse(response);
 
-                closeSocket();
+				closeSocket();
-                cb(message, null);
+				cb(message, null);
-            } catch (err) {
+			} catch (err) {
-                handleError(err);
+				handleError(err);
-            }
+			}
-        } else {
+		} else {
-            handleError(new Error('Received unexpected packet'));
+			handleError(new Error("Received unexpected packet"));
-        }
+		}
-    });
+	});
 
-    socket.on('error', handleError);
+	socket.on("error", handleError);
 }
 
 /**
@@ -123,13 +130,20 @@ function ping(host, port = 25565, cb, timeout = 5000, protocolVersion = -1) {
  * @returns {Promise<import('../types/index.js').JavaPingResponse>}
  */
 export function pingJava(host, options = {}) {
-    if (!host) throw new Error('Host argument is not provided');
+	if (!host) throw new Error("Host argument is not provided");
 
-    const { port = 25565, timeout = 5000, protocolVersion = -1 } = options;
+	const { port = 25565, timeout = 5000, protocolVersion = -1, virtualHost = null } = options;
 
-    return new Promise((resolve, reject) => {
+	return new Promise((resolve, reject) => {
-        ping(host, port, (res, err) => {
+		ping(
-            err ? reject(err) : resolve(res);
+			host,
-        }, timeout, protocolVersion);
+			virtualHost || host,
-    });
+			port,
+			(res, err) => {
+				err ? reject(err) : resolve(res);
+			},
+			timeout,
+			protocolVersion
+		);
+	});
 }

lib/varint.js

@@ -1,127 +1,123 @@
-// https://wiki.vg/Data_types
+// https://minecraft.wiki/w/Minecraft_Wiki:Projects/wiki.vg_merge/Protocol#Data_types
 
 /**
  * A utility object for encoding and decoding varints.
  */
 const varint = {
-    /**
+	/**
-     * Encodes an integer value into a varint byte buffer.
+	 * Encodes an integer value into a varint byte buffer.
-     * @param {number} val - The integer value to encode.
+	 * @param {number} val - The integer value to encode.
-     * @returns {Buffer}
+	 * @returns {Buffer}
-     */
+	 */
-    encodeInt: (val) => {
+	encodeInt: (val) => {
-        // "constInts are never longer than 5 bytes"
+		// "VarInts are never longer than 5 bytes"
-        // https://wiki.vg/Data_types#constInt_and_constLong
+		// https://minecraft.wiki/w/Minecraft_Wiki:Projects/wiki.vg_merge/Data_types#VarInt_and_VarLong
-        const buf = Buffer.alloc(5);
+		const buf = Buffer.alloc(5);
-        let written = 0;
+		let written = 0;
 
-        while (true) {
+		while (true) {
-            const byte = val & 0x7F;
+			const byte = val & 0x7f;
-            val >>>= 7;
+			val >>>= 7;
 
-            if (val === 0) {
+			if (val === 0) {
-                buf.writeUInt8(byte, written++);
+				buf.writeUInt8(byte, written++);
-                break;
+				break;
-            }
+			}
 
-            buf.writeUInt8(byte | 0x80, written++);
+			buf.writeUInt8(byte | 0x80, written++);
-        }
+		}
 
-        return buf.slice(0, written);
+		return buf.subarray(0, written);
-    },
+	},
 
-    /**
+	/**
-     * Encodes a string value into a UTF-8 byte buffer.
+	 * Encodes a string value into a UTF-8 byte buffer.
-     * @param {string} val - The string value to encode.
+	 * @param {string} val - The string value to encode.
-     * @returns {Buffer}
+	 * @returns {Buffer}
-     */
+	 */
-    encodeString: (val) => {
+	encodeString: (val) => {
-        return Buffer.from(val, 'utf-8');
+		return Buffer.from(val, "utf-8");
-    },
+	},
 
-    /**
+	/**
-     * Encodes an unsigned short value into a byte buffer.
+	 * Encodes an unsigned short value into a byte buffer.
-     * @param {number} val - The unsigned short value to encode.
+	 * @param {number} val - The unsigned short value to encode.
-     * @returns {Buffer}
+	 * @returns {Buffer}
-     */
+	 */
-    encodeUShort: (val) => {
+	encodeUShort: (val) => {
-        return Buffer.from([val >> 8, val & 0xFF]);
+		return Buffer.from([val >> 8, val & 0xff]);
-    },
+	},
 
-    /**
+	/**
-     * Concatenates multiple byte buffers into a single byte buffer.
+	 * Concatenates multiple byte buffers into a single byte buffer.
-     * @param {Buffer[]} chunks - An array of byte buffers to concatenate.
+	 * @param {Buffer[]} chunks - An array of byte buffers to concatenate.
-     * @returns {Buffer}
+	 * @returns {Buffer}
-     */
+	 */
-    concat: (chunks) => {
+	concat: (chunks) => {
-        let length = 0;
+		let length = 0;
 
-        for (const chunk of chunks) {
+		for (const chunk of chunks) {
-            length += chunk.length;
+			length += chunk.length;
-        }
+		}
 
-        const buffer = [
+		const buffer = [varint.encodeInt(length), ...chunks];
-            varint.encodeInt(length),
-            ...chunks
-        ];
 
-        return Buffer.concat(buffer);
+		return Buffer.concat(buffer);
-    },
+	},
 
-    /**
+	/**
-     * 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 {Buffer} buffer - The byte buffer to decode from.
-     * @param {number} offset - The offset in the buffer to start decoding from.
+	 * @param {number} offset - The offset in the buffer to start decoding from.
-     * @returns {number}
+	 * @returns {number}
-     */
+	 */
-    decodeInt: (buffer, offset) => {
+	decodeInt: (buffer, offset) => {
-        let val = 0;
+		// Fast path for single-byte varints
-        let count = 0;
+		const firstByte = buffer.readUInt8(offset);
+		if (firstByte < 0x80) {
+			return firstByte;
+		}
 
-        while (true) {
+		let val = firstByte & 0x7f;
-            const byte = buffer.readUInt8(offset++);
+		let position = 7;
 
-            val |= (byte & 0x7F) << count++ * 7;
+		while (position < 32) {
+			const byte = buffer.readUInt8(++offset);
+			val |= (byte & 0x7f) << position;
 
-            if ((byte & 0x80) !== 0x80) {
+			if ((byte & 0x80) === 0) {
-                break;
+				return val;
-            }
+			}
-        }
 
-        return val;
+			position += 7;
-    },
+		}
 
-    /**
+		throw new Error("VarInt is too big");
-     * 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);
-        const N4 = Math.pow(2, 28);
-        const N5 = Math.pow(2, 35);
-        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
+	/**
-        return (
+	 * Calculates how many bytes are needed to encode a number as a VarInt
-            val < N1 ? 1
+	 * VarInts use a variable number of bytes to efficiently encode integers
-                : val < N2 ? 2
+	 * Each byte uses 7 bits for the value and 1 bit to indicate if more bytes follow
-                    : val < N3 ? 3
+	 * VarInts are never longer than 5 bytes
-                        : val < N4 ? 4
+	 *
-                            : val < N5 ? 5
+	 * @param {number} val - The number to calculate the VarInt length for
-                                : val < N6 ? 6
+	 * @returns {1|2|3|4|5} The number of bytes needed to encode the value
-                                    : val < N7 ? 7
+	 */
-                                        : val < N8 ? 8
+	decodeLength: (val) => {
-                                            : val < N9 ? 9
+		// Using bit shifts to calculate power of 2 thresholds
-                                                : 10
+		// 1 << 7  = 2^7  = 128      - Numbers below this fit in 1 byte
-        );
+		// 1 << 14 = 2^14 = 16,384   - Numbers below this fit in 2 bytes
-    }
+		// 1 << 21 = 2^21 = 2,097,152 - Numbers below this fit in 3 bytes
+		// 1 << 28 = 2^28 = 268,435,456 - Numbers below this fit in 4 bytes
+		// Any larger number needs 5 bytes (maximum VarInt size)
+
+		if (val < 1 << 7) return 1;
+		if (val < 1 << 14) return 2;
+		if (val < 1 << 21) return 3;
+		if (val < 1 << 28) return 4;
+		return 5;
+	},
 };
 
 export default varint;

package.json

@@ -1,22 +1,22 @@
 {
-  "name": "@minescope/mineping",
+	"name": "@minescope/mineping",
-  "version": "1.5.0",
+	"version": "1.6.1",
-  "description": "Ping both Minecraft Bedrock and Java servers.",
+	"description": "Ping both Minecraft Bedrock and Java servers.",
-  "main": "index.js",
+	"main": "index.js",
-  "types": "types/index.d.ts",
+	"types": "types/index.d.ts",
-  "keywords": [],
+	"keywords": [],
-  "author": {
+	"author": {
-    "name": "Timofey (xzeldon)",
+		"name": "Timofey (xzeldon)",
-    "email": "contact@zeldon.ru",
+		"email": "contact@zeldon.ru",
-    "url": "https://zeldon.ru"
+		"url": "https://zeldon.ru"
-  },
+	},
-  "repository": {
+	"repository": {
-    "type": "git",
+		"type": "git",
-    "url": "git://github.com/minescope/mineping.git"
+		"url": "git://github.com/minescope/mineping.git"
-  },
+	},
-  "type": "module",
+	"type": "module",
-  "engines": {
+	"engines": {
-    "node": ">=14"
+		"node": ">=14"
-  },
+	},
-  "license": "MIT"
+	"license": "MIT"
-}
+}

types/lib/bedrock.d.ts

@@ -1,53 +1,61 @@
 /**
- * @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 = {
-    edition: string;
+	edition: string;
-    name: string;
+	name: string;
-    version: {
+	version: {
-        protocolVersion: number;
+		protocolVersion: number;
-        minecraftVersion: string;
+		minecraftVersion: string;
-    };
+	};
-    players: {
+	players: {
-        online: number;
+		online: number;
-        max: number;
+		max: number;
-    };
+	};
-    serverId: string;
+	serverId: string;
-    mapName: string;
+	mapName: string;
-    gameMode: string;
+	gameMode: string;
 };
 
 /**
  * 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.
- * 
+ *
  * ```js
  * import { pingBedrock } from '@minescope/mineping';
- * 
+ *
  * const data = await pingBedrock('mco.mineplex.com');
  * console.log(data);
  * ```
- * 
+ *
  * 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/java.d.ts

@@ -4,49 +4,50 @@
  * @param protocolVersion The protocol version.
  */
 export type JavaPingOptions = {
-    port?: number | undefined,
+	port?: number | undefined;
-    timeout?: number | undefined,
+	timeout?: number | undefined;
-    protocolVersion?: number | undefined;
+	protocolVersion?: number | undefined;
+	virtualHost?: string | undefined;
 };
 
 /**
  * JSON format chat component used for description field.
- * @see https://wiki.vg/Chat
+ * @see https://minecraft.wiki/w/Minecraft_Wiki:Projects/wiki.vg_merge/Chat
  */
 export type ChatComponent = {
-    text: string;
+	text: string;
-    bold?: boolean;
+	bold?: boolean;
-    italic?: boolean;
+	italic?: boolean;
-    underlined?: boolean;
+	underlined?: boolean;
-    strikethrough?: boolean;
+	strikethrough?: boolean;
-    obfuscated?: boolean;
+	obfuscated?: boolean;
-    color?: string;
+	color?: string;
-    extra?: ChatComponent[];
+	extra?: ChatComponent[];
 };
 
 export type SampleProp = {
-    name: string,
+	name: string;
-    id: string;
+	id: string;
 };
 
 /**
  * `JSON Response` field of Response packet.
- * @see https://wiki.vg/Server_List_Ping#Response
+ * @see https://minecraft.wiki/w/Minecraft_Wiki:Projects/wiki.vg_merge/Server_List_Ping#Status_Response
  */
 export type JavaPingResponse = {
-    version: {
+	version: {
-        name: string;
+		name: string;
-        protocol: number;
+		protocol: number;
-    };
+	};
-    players: {
+	players: {
-        max: number;
+		max: number;
-        online: number;
+		online: number;
-        sample?: SampleProp[];
+		sample?: SampleProp[];
-    };
+	};
-    description: string | ChatComponent;
+	description: string | ChatComponent;
-    favicon?: string;
+	favicon?: string;
-    enforcesSecureChat?: boolean;
+	enforcesSecureChat?: boolean;
-    previewsChat?: boolean;
+	previewsChat?: boolean;
 };
 
 /**
@@ -76,5 +77,7 @@ export type JavaPingResponse = {
  * ```
  * @see [source](https://github.com/minescope/mineping/blob/915edbec9c9ad811459458600af3531ec0836911/lib/java.js#L117)
  */
-export function pingJava(host: string, options?: JavaPingOptions): Promise<JavaPingResponse>;
+export function pingJava(
-
+	host: string,
+	options?: JavaPingOptions
+): Promise<JavaPingResponse>;

types/lib/varint.d.ts

@@ -1,10 +1,44 @@
 export default varint;
 declare namespace varint {
-    function encodeInt(val: number): Buffer;
+	/**
-    function encodeString(val: string): Buffer;
+	 * Encodes an integer value into a varint byte buffer.
-    function encodeUShort(val: number): Buffer;
+	 * @param val - The integer value to encode.
-    function concat(chunks: Buffer[]): Buffer;
+	 */
-    function decodeInt(buffer: Buffer, offset: number): number;
+	function encodeInt(val: number): Buffer;
-    function decodeString(val: Buffer, offset?: number): string;
+
-    function decodeLength(val: number): 5 | 7 | 8 | 1 | 2 | 3 | 4 | 6 | 9 | 10;
+	/**
+	 * 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;
+
+	/**
+	 * 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;
 }