mirror of
https://github.com/minescope/mineping.git
synced 2025-07-12 12:24:36 +03:00
refactor: introduce typescript for static type checking
We use JSDoc for documentation, but these annotations were not being validated. This meant that type information could become outdated or incorrect without any warning. This commit introduces the TypeScript compiler (`tsc`) as a static analysis tool to leverage our existing JSDoc comments. To support this, JSDoc annotations across the codebase have been improved for accuracy. Additionally, the `varint` module now uses a custom `VarIntError` class for better type inference and error handling. A new `typecheck` script has been added to `package.json` to run this validation.
This commit is contained in:
@ -18,44 +18,50 @@ const UNCONNECTED_PONG = 0x1c;
|
||||
/**
|
||||
* Representation of raw, semicolon-delimited MOTD string.
|
||||
* This struct directly mirrors the fields and order from the server response.
|
||||
* @see {@link https://minecraft.wiki/w/RakNet#Unconnected_Pong}
|
||||
* See [`Unconnected Pong Documentation`](https://minecraft.wiki/w/RakNet#Unconnected_Pong) for more details.
|
||||
* @typedef {object} BedrockMotd
|
||||
* @property {string} edition - The edition of the server (MCPE or MCEE)
|
||||
* @property {string} name - The primary name of the server (first line of MOTD)
|
||||
* @property {number} protocol - The protocol version
|
||||
* @property {string} version - The game version (e.g., "1.21.2")
|
||||
* @property {number} playerCount - The current number of players online
|
||||
* @property {number} playerMax - The maximum number of players allowed
|
||||
* @property {bigint} serverGuid - The server's GUID
|
||||
* @property {string} subName - The secondary name of the server (second line of MOTD)
|
||||
* @property {string} gamemode - The default gamemode (e.g., "Survival")
|
||||
* @property {boolean | undefined} nintendoLimited - Whether the server is Nintendo limited
|
||||
* @property {string | undefined} port - The server's IPv4 port, if provided
|
||||
* @property {string | undefined} ipv6Port - The server's IPv6 port, if provided
|
||||
* @property {string | undefined} editorMode - Whether the server is in editor mode, if provided. See: https://learn.microsoft.com/en-us/minecraft/creator/documents/bedrockeditor/editoroverview?view=minecraft-bedrock-stable
|
||||
* @property {string} edition - The edition of the server (MCPE or MCEE).
|
||||
* @property {string} name - The primary name of the server (first line of MOTD).
|
||||
* @property {number} protocol - The protocol version.
|
||||
* @property {string} version - The game version (e.g., "1.21.2").
|
||||
* @property {number} playerCount - The current number of players online.
|
||||
* @property {number} playerMax - The maximum number of players allowed.
|
||||
* @property {bigint} serverGuid - The server's GUID.
|
||||
* @property {string} subName - The secondary name of the server (second line of MOTD).
|
||||
* @property {string} gamemode - The default gamemode (e.g., "Survival").
|
||||
* @property {boolean} [nintendoLimited] - Whether the server is Nintendo limited.
|
||||
* @property {number} [port] - The server's IPv4 port, if provided.
|
||||
* @property {number} [ipv6Port] - The server's IPv6 port, if provided.
|
||||
* @property {boolean} [editorMode] - Whether the server is in editor mode, if provided. See [Minecraft Editor Mode Documentation](https://learn.microsoft.com/en-us/minecraft/creator/documents/bedrockeditor/editoroverview?view=minecraft-bedrock-stable) for more details.
|
||||
*/
|
||||
|
||||
/**
|
||||
* Represents the structured and user-friendly response from a server ping.
|
||||
* This is the public-facing object that users of the library will receive.
|
||||
* @typedef {object} BedrockPingResponse
|
||||
* @property {string} edition
|
||||
* @property {string} name
|
||||
* @property {string} levelName
|
||||
* @property {string} gamemode
|
||||
* @property {{ protocol: number, minecraft: string }} version
|
||||
* @property {{ online: number, max: number }} players
|
||||
* @property {{ v4: number | undefined, v6: number | undefined }} port
|
||||
* @property {bigint} guid
|
||||
* @property {boolean | undefined} isNintendoLimited
|
||||
* @property {string | undefined} isEditorModeEnabled
|
||||
* @property {string} edition - The edition of the server (MCPE or MCEE).
|
||||
* @property {string} name - The primary name of the server (first line of MOTD).
|
||||
* @property {string} levelName - The name of the world or level being hosted.
|
||||
* @property {string} gamemode - The default gamemode of the server.
|
||||
* @property {{ protocol: number, minecraft: string }} version - Game and protocol versions.
|
||||
* @property {{ online: number, max: number }} players - Current and maximum player counts.
|
||||
* @property {{ v4?: number, v6?: number }} port - Announced IPv4 and IPv6 ports.
|
||||
* @property {bigint} guid - The server's unique 64-bit GUID.
|
||||
* @property {boolean} [isNintendoLimited] - True if the server restricts Nintendo Switch players.
|
||||
* @property {boolean} [isEditorModeEnabled] - True if the server is in editor mode. See [Minecraft Editor Mode Documentation](https://learn.microsoft.com/en-us/minecraft/creator/documents/bedrockeditor/editoroverview?view=minecraft-bedrock-stable) for more details.
|
||||
*/
|
||||
|
||||
/**
|
||||
* @typedef {object} BedrockPingOptions
|
||||
* @property {number} [port=19132] - The server port to ping.
|
||||
* @property {number} [timeout=5000] - The timeout in milliseconds for the request.
|
||||
*/
|
||||
|
||||
/**
|
||||
* Creates an Unconnected Ping packet.
|
||||
* @param {number} timestamp - The current time delta since the script started
|
||||
* See [Unconnected Ping Documentation](https://minecraft.wiki/w/RakNet#Unconnected_Ping) for more details.
|
||||
* @param {number} timestamp - The current time delta since the script started.
|
||||
* @returns {Buffer}
|
||||
* @see {@link https://minecraft.wiki/w/RakNet#Unconnected_Ping}
|
||||
*/
|
||||
const createUnconnectedPingFrame = (timestamp) => {
|
||||
const buffer = Buffer.alloc(33);
|
||||
@ -68,8 +74,9 @@ const createUnconnectedPingFrame = (timestamp) => {
|
||||
|
||||
/**
|
||||
* Parses the semicolon-delimited MOTD string into a structured object.
|
||||
* @param {string} motdString - The raw MOTD string from the server
|
||||
* @throws {Error} If the MOTD string is missing required fields
|
||||
* @param {string} motdString - The raw MOTD string from the server.
|
||||
* @returns {BedrockMotd} The parsed internal MOTD object.
|
||||
* @throws {Error} If the MOTD string is missing required fields.
|
||||
*/
|
||||
const parseMotd = (motdString) => {
|
||||
const parts = motdString.split(";");
|
||||
@ -122,8 +129,8 @@ const parseMotd = (motdString) => {
|
||||
|
||||
/**
|
||||
* Transforms the raw MOTD object into a user-friendly, nested structure.
|
||||
* @param {BedrockMotd} motd - The parsed MOTD object
|
||||
* @returns {BedrockPingResponse}
|
||||
* @param {BedrockMotd} motd - The parsed MOTD object.
|
||||
* @returns {BedrockPingResponse} The final, user-facing response object.
|
||||
*/
|
||||
const transformMotd = (motd) => {
|
||||
return {
|
||||
@ -151,9 +158,9 @@ const transformMotd = (motd) => {
|
||||
|
||||
/**
|
||||
* Extracts the MOTD string from an Unconnected Pong packet and parses it.
|
||||
* @param {Buffer} pongPacket - The raw pong packet from the server
|
||||
* @returns {BedrockPingResponse}
|
||||
* @throws {Error} If the packet is malformed
|
||||
* @param {Buffer} pongPacket - The raw pong packet from the server.
|
||||
* @returns {BedrockPingResponse} The final response object.
|
||||
* @throws {Error} If the packet is malformed.
|
||||
*/
|
||||
const parseUnconnectedPong = (pongPacket) => {
|
||||
if (!Buffer.isBuffer(pongPacket) || pongPacket.length < 35) {
|
||||
@ -189,11 +196,9 @@ const parseUnconnectedPong = (pongPacket) => {
|
||||
|
||||
/**
|
||||
* Asynchronously pings a Minecraft Bedrock server.
|
||||
* @param {string} host - The IP address or hostname of the server
|
||||
* @param {object} [options] - Optional configuration
|
||||
* @param {number} [options.port=19132] - The server port
|
||||
* @param {number} [options.timeout=5000] - The request timeout in milliseconds
|
||||
* @returns {Promise<BedrockPingResponse>} A promise that resolves with the server's parsed MOTD
|
||||
* @param {string} host - The IP address or hostname of the server.
|
||||
* @param {BedrockPingOptions} [options={}] - Optional configuration.
|
||||
* @returns {Promise<BedrockPingResponse>} A promise that resolves with the server's parsed MOTD.
|
||||
*/
|
||||
export const pingBedrock = (host, options = {}) => {
|
||||
if (!host) {
|
||||
|
||||
Reference in New Issue
Block a user