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

@@ -200,7 +200,7 @@ const parseUnconnectedPong = (pongPacket) => {
  * @param {BedrockPingOptions} [options={}] - Optional configuration.
  * @returns {Promise<BedrockPingResponse>} 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);
 		}
 	});
-};
+}

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",

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
+	}
+}

types/index.d.ts

@@ -0,0 +1,2 @@
+export { pingJava } from "./lib/java.js";
+export { pingBedrock } from "./lib/bedrock.js";

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<BedrockPingResponse>} A promise that resolves with the server's parsed MOTD.
+ */
+export function pingBedrock(host: string, options?: BedrockPingOptions): Promise<BedrockPingResponse>;
+/**
+ * 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;
+};

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<JavaPingResponse>} A promise that resolves with the server's status.
+ */
+export function pingJava(host: string, options?: JavaPingOptions): Promise<JavaPingResponse>;
+/**
+ * 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;
+};

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;
+}