refactor!: decouple Raknet MOTD parsing and response shaping

The previous implementation of the RakNet ping was monolithic, mixing
socket management, raw packet validation, and data transformation into
a single, complex flow.

This refactor introduces a clear, multi-stage
processing pipeline that separates these concerns. The logic is now
broken down into multi-stage pipeline: extracting the MOTD string
from the raw pong packet -> parsing that string into a raw
object -> transforming the raw data into a
user-friendly response object.

Additionally, the socket handling logic is improved
with idempotent cleanup function to prevent resource
leaks or race conditions.

As part of this overhaul, external TypeScript definition (`.d.ts`)
files have been removed in favor of rich JSDoc annotations.

BREAKING CHANGE: The structure of the resolved `BedrockPingResponse`
object has been significantly changed to improve clarity and
consistency.
This commit is contained in:
2025-06-16 01:09:41 +03:00
parent cbaa1a3e3e
commit 3c2c049c19
7 changed files with 258 additions and 321 deletions

View File

@ -1,61 +0,0 @@
/**
* @param port The server port (1-65535).
* @param timeout The read/write socket timeout in milliseconds.
*/
export type BedrockPingOptions = {
port?: number & { _brand: "Port" }; // 1-65535
timeout?: number & { _brand: "Timeout" }; // > 0
};
export type BedrockPingResponse = {
edition: string;
name: string;
version: {
protocolVersion: number;
minecraftVersion: string;
};
players: {
online: number;
max: number;
};
serverId: string;
mapName: string;
gameMode: string;
};
/**
* Asynchronously ping Minecraft Bedrock server.
*
* @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
* {
* edition: "MCPE",
* name: "Mineplex",
* version: {
* protocolVersion: 475,
* minecraftVersion: "1.18.0"
* },
* players: {
* online: 5206,
* max: 5207
* },
* serverId: "12345678",
* mapName: "Lobby",
* gameMode: "Survival"
* }
* ```
*/
export function pingBedrock(
host: string,
options?: BedrockPingOptions
): Promise<BedrockPingResponse>;