From 7248a0096c35f3b2db1917d2bdb9a4185df9ca66 Mon Sep 17 00:00:00 2001 From: Timofey Gelazoniya Date: Sun, 22 Jun 2025 01:48:06 +0300 Subject: [PATCH] feat: add typescript declaration files Types are automatically generated from the existsing JSDoc comments in the js source code. Use `types:build` script from `package.json` to produce d.ts files. --- lib/bedrock.js | 4 +- package.json | 3 +- tsconfig.json | 18 +++--- types/index.d.ts | 2 + types/lib/bedrock.d.ts | 131 +++++++++++++++++++++++++++++++++++++++++ types/lib/java.d.ts | 63 ++++++++++++++++++++ types/lib/varint.d.ts | 49 +++++++++++++++ 7 files changed, 256 insertions(+), 14 deletions(-) create mode 100644 types/index.d.ts create mode 100644 types/lib/bedrock.d.ts create mode 100644 types/lib/java.d.ts create mode 100644 types/lib/varint.d.ts diff --git a/lib/bedrock.js b/lib/bedrock.js index 3ba0bf0..e748207 100644 --- a/lib/bedrock.js +++ b/lib/bedrock.js @@ -200,7 +200,7 @@ const parseUnconnectedPong = (pongPacket) => { * @param {BedrockPingOptions} [options={}] - Optional configuration. * @returns {Promise} A promise that resolves with the server's parsed MOTD. */ -export const pingBedrock = (host, options = {}) => { +export async function pingBedrock(host, options = {}) { if (!host) { throw new Error("Host argument is required."); } @@ -258,4 +258,4 @@ export const pingBedrock = (host, options = {}) => { socket.emit("error", err); } }); -}; +} diff --git a/package.json b/package.json index 8e70489..4caf366 100644 --- a/package.json +++ b/package.json @@ -8,7 +8,8 @@ "scripts": { "test": "vitest run", "test:watch": "vitest", - "typecheck": "tsc --noEmit" + "types:check": "tsc --noEmit", + "types:build": "tsc" }, "repository": { "type": "git", diff --git a/tsconfig.json b/tsconfig.json index 79a5509..043595e 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -1,14 +1,10 @@ { + "include": ["lib/**/*.js", "index.js"], "compilerOptions": { "allowJs": true, - "checkJs": true, - "noEmit": true, - "strict": true, - "moduleResolution": "node", - "target": "ES2022", - "lib": ["ES2022"], - "esModuleInterop": true - }, - "include": ["lib", "index.js"], - "exclude": ["node_modules"] -} + "declaration": true, + "emitDeclarationOnly": true, + "outDir": "types", + "removeComments": false + } +} \ No newline at end of file diff --git a/types/index.d.ts b/types/index.d.ts new file mode 100644 index 0000000..399ec54 --- /dev/null +++ b/types/index.d.ts @@ -0,0 +1,2 @@ +export { pingJava } from "./lib/java.js"; +export { pingBedrock } from "./lib/bedrock.js"; diff --git a/types/lib/bedrock.d.ts b/types/lib/bedrock.d.ts new file mode 100644 index 0000000..5e53688 --- /dev/null +++ b/types/lib/bedrock.d.ts @@ -0,0 +1,131 @@ +/** + * Asynchronously pings a Minecraft Bedrock server. + * @param {string} host - The IP address or hostname of the server. + * @param {BedrockPingOptions} [options={}] - Optional configuration. + * @returns {Promise} A promise that resolves with the server's parsed MOTD. + */ +export function pingBedrock(host: string, options?: BedrockPingOptions): Promise; +/** + * Representation of raw, semicolon-delimited MOTD string. + * This struct directly mirrors the fields and order from the server response. + * See [`Unconnected Pong Documentation`](https://minecraft.wiki/w/RakNet#Unconnected_Pong) for more details. + */ +export type BedrockMotd = { + /** + * - The edition of the server (MCPE or MCEE). + */ + edition: string; + /** + * - The primary name of the server (first line of MOTD). + */ + name: string; + /** + * - The protocol version. + */ + protocol: number; + /** + * - The game version (e.g., "1.21.2"). + */ + version: string; + /** + * - The current number of players online. + */ + playerCount: number; + /** + * - The maximum number of players allowed. + */ + playerMax: number; + /** + * - The server's GUID. + */ + serverGuid: bigint; + /** + * - The secondary name of the server (second line of MOTD). + */ + subName: string; + /** + * - The default gamemode (e.g., "Survival"). + */ + gamemode: string; + /** + * - Whether the server is Nintendo limited. + */ + nintendoLimited?: boolean; + /** + * - The server's IPv4 port, if provided. + */ + port?: number; + /** + * - The server's IPv6 port, if provided. + */ + ipv6Port?: number; + /** + * - 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. + */ + editorMode?: boolean; +}; +/** + * Represents the structured and user-friendly response from a server ping. + * This is the public-facing object that users of the library will receive. + */ +export type BedrockPingResponse = { + /** + * - The edition of the server (MCPE or MCEE). + */ + edition: string; + /** + * - The primary name of the server (first line of MOTD). + */ + name: string; + /** + * - The name of the world or level being hosted. + */ + levelName: string; + /** + * - The default gamemode of the server. + */ + gamemode: string; + /** + * - Game and protocol versions. + */ + version: { + protocol: number; + minecraft: string; + }; + /** + * - Current and maximum player counts. + */ + players: { + online: number; + max: number; + }; + /** + * - Announced IPv4 and IPv6 ports. + */ + port: { + v4?: number; + v6?: number; + }; + /** + * - The server's unique 64-bit GUID. + */ + guid: bigint; + /** + * - True if the server restricts Nintendo Switch players. + */ + isNintendoLimited?: boolean; + /** + * - 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. + */ + isEditorModeEnabled?: boolean; +}; +export type BedrockPingOptions = { + /** + * - The server port to ping. + */ + port?: number; + /** + * - The timeout in milliseconds for the request. + */ + timeout?: number; +}; diff --git a/types/lib/java.d.ts b/types/lib/java.d.ts new file mode 100644 index 0000000..76dd39b --- /dev/null +++ b/types/lib/java.d.ts @@ -0,0 +1,63 @@ +/** + * Asynchronously Pings a Minecraft Java Edition server. + * This function performs an SRV lookup and then attempts to connect and retrieve the server status. + * @param {string} host - The server address to ping. + * @param {JavaPingOptions} [options={}] - Optional configuration. + * @returns {Promise} A promise that resolves with the server's status. + */ +export function pingJava(host: string, options?: JavaPingOptions): Promise; +/** + * Represents the structured and user-friendly response from a server ping. + * The fields and their optionality are based on the protocol documentation. + * See [Status Response Documentation](https://minecraft.wiki/w/Java_Edition_protocol/Server_List_Ping#Status_Response) for more details. + */ +export type JavaPingResponse = { + /** + * - Contains the server's version name and protocol number. + */ + version: { + name: string; + protocol: number; + }; + /** + * - Player count and a sample of online players. + */ + players?: { + max: number; + online: number; + sample?: Array<{ + name: string; + id: string; + }>; + }; + /** + * - The server's Message of the Day (MOTD). + */ + description?: object | string; + /** + * - A Base64-encoded 64x64 PNG image data URI. + */ + favicon?: string; + /** + * - True if the server requires clients to have a Mojang-signed public key. + */ + enforcesSecureChat?: boolean; + /** + * - True if a mod is installed to disable chat reporting. + */ + preventsChatReports?: boolean; +}; +export type JavaPingOptions = { + /** + * - The fallback port if an SRV record is not found. + */ + port?: number; + /** + * - The connection timeout in milliseconds. + */ + timeout?: number; + /** + * - The protocol version to use in the handshake. `-1` is for auto-detection. + */ + protocolVersion?: number; +}; diff --git a/types/lib/varint.d.ts b/types/lib/varint.d.ts new file mode 100644 index 0000000..7b5bcd1 --- /dev/null +++ b/types/lib/varint.d.ts @@ -0,0 +1,49 @@ +/** + * Encodes an integer into a VarInt buffer. + * VarInts are never longer than 5 bytes for the Minecraft protocol. + * @param {number} value The integer to encode + * @returns {Buffer} The encoded VarInt as a buffer + * @throws {VarIntError} if the value is too large to be encoded + */ +export function encodeVarInt(value: number): Buffer; +/** + * Encodes a string into a UTF-8 buffer. + * @param {string} value The string to encode + * @returns {Buffer} + */ +export function encodeString(value: string): Buffer; +/** + * Encodes an unsigned short (16-bit big-endian) into a 2-byte buffer. + * @param {number} value The number to encode + * @returns {Buffer} + */ +export function encodeUShort(value: number): Buffer; +/** + * Creates a Minecraft-style packet by concatenating chunks and prefixing the total length as a VarInt. + * @param {Buffer[]} chunks An array of buffers to include in the packet payload + * @returns {Buffer} The complete packet with its length prefix + */ +export function concatPackets(chunks: Buffer[]): Buffer; +/** + * Decodes a VarInt from a buffer. + * Returns the decoded value and the number of bytes it consumed. + * @param {Buffer} buffer The buffer to read from + * @param {number} [offset=0] The starting offset in the buffer + * @returns {{ value: number, bytesRead: number }} + * @throws {VarIntError} if the buffer is too short or the VarInt is malformed + */ +export function decodeVarInt(buffer: Buffer, offset?: number): { + value: number; + bytesRead: number; +}; +export const ERR_VARINT_BUFFER_UNDERFLOW: "VARINT_BUFFER_UNDERFLOW"; +export const ERR_VARINT_MALFORMED: "VARINT_MALFORMED"; +export const ERR_VARINT_ENCODE_TOO_LARGE: "VARINT_ENCODE_TOO_LARGE"; +export class VarIntError extends Error { + /** + * @param {string} message The error message. + * @param {string} code The error code. + */ + constructor(message: string, code: string); + code: string; +}