@deitylamb/mcping 1.1.0

package/.prettierrc

@@ -0,0 +1,7 @@
+{
+  "semi": true,
+  "singleQuote": false,
+  "trailingComma": "all",
+  "tabWidth": 2,
+  "printWidth": 80
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HarmoniaMC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,111 @@
+# @deitylamb/mcping
+
+Robust, and well-typed Minecraft server ping library for Node.js. Supports both **Java Edition** (1.7.x - 1.21+) and **Bedrock Edition**.
+
+## CLI Usage
+
+You can use the CLI to ping any server directly from your terminal:
+
+```bash
+# Using npx
+npx @deitylamb/mcping mc.hypixel.net
+
+# Options
+npx @deitylamb/mcping mc.hypixel.net --timeout 1000
+npx @deitylamb/mcping play.cubecraft.net --type bedrock
+
+# Or install globally
+npm install -g @deitylamb/mcping
+mcping mc.hypixel.net
+```
+
+## Features
+
+- **Unified API**: One simple function `ping(target, options)` for all protocols.
+- **Auto-Detect**: Automatically detects if a server is Java or Bedrock.
+- **High Performance Caching**: Built-in support for multiple caching strategies.
+- **Modern & Typed**: Written in TypeScript with full ESM and CJS support.
+- **SRV Support**: Native DNS SRV record resolution (`_minecraft._tcp` and `_minecraft._udp`).
+- **Real IP Resolution**: Always resolves and returns the final physical IP address.
+- **Rich Responses**: Includes normalized MOTD (handling JSON and colors), player counts, versions, and latency.
+- **Legacy & Modded**: Verified compatibility with 1.7.10+, Forge, and modded network proxies.
+
+## Installation
+
+```bash
+npm install @deitylamb/mcping
+```
+
+## Usage
+
+### Simple Ping (Auto-detect)
+
+```typescript
+import { ping } from "@deitylamb/mcping";
+
+const res = await ping("mc.hypixel.net");
+console.log(`${res.players.online}/${res.players.max} players online.`);
+console.log(`Resolved IP: ${res.target.ip}:${res.target.port}`);
+```
+
+### Caching Strategies
+
+The library supports two main caching strategies to optimize performance and reduce network overhead:
+
+1.  **`lazy` (Cache-Aside)**: Checks for a fresh cached result before making a network request.
+2.  **`swr` (Stale-While-Revalidate)**: Returns cached data immediately (even if stale) while refreshing the cache in the background.
+
+```typescript
+const res = await ping("mc.hypixel.net", {
+  cache: {
+    ttl: 30000, // 30 seconds
+    strategy: "swr", // 'lazy' | 'swr'
+  },
+});
+
+console.log(res.cached ? "(From Cache)" : "(Live)");
+```
+
+### Specific Protocol
+
+```typescript
+const res = await ping("geo.hivebedrock.network", { type: "bedrock" });
+```
+
+### Options
+
+```typescript
+const res = await ping("example.com", {
+  timeout: 3000, // default: 5000ms
+  type: "java", // 'java' | 'bedrock' | null (auto-detect)
+});
+```
+
+## Response Schema
+
+```typescript
+{
+  type: "java" | "bedrock";
+  version: {
+    name: string;
+    protocol: number;
+  };
+  players: {
+    online: number;
+    max: number;
+  };
+  motd: string;        // Cleaned string with formatting preserved as § codes
+  latency: number;     // Round-trip time in ms (Java only, 0 for Bedrock)
+  target: {
+    host: string;      // Resolved hostname (e.g. from SRV)
+    port: number;      // Final port
+    ip: string;        // Physical IP address
+  };
+  raw: any;            // The original raw response from the server
+  cached?: boolean;    // True if the response was served from cache
+}
+```
+
+## License
+
+MIT © HarmoniaMC

package/dist/cli.cjs

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+const require_src = require("./src-Baubd7mm.cjs");
+//#region src/ansi.ts
+const mcColorMap = {
+	"0": "\x1B[30m",
+	"1": "\x1B[34m",
+	"2": "\x1B[32m",
+	"3": "\x1B[36m",
+	"4": "\x1B[31m",
+	"5": "\x1B[35m",
+	"6": "\x1B[33m",
+	"7": "\x1B[37m",
+	"8": "\x1B[90m",
+	"9": "\x1B[94m",
+	a: "\x1B[92m",
+	b: "\x1B[96m",
+	c: "\x1B[91m",
+	d: "\x1B[95m",
+	e: "\x1B[93m",
+	f: "\x1B[97m",
+	l: "\x1B[1m",
+	m: "\x1B[9m",
+	n: "\x1B[4m",
+	o: "\x1B[3m",
+	r: "\x1B[0m"
+};
+/**
+* Converts Minecraft color codes (§) to ANSI terminal colors.
+*/
+function mcToAnsi(text) {
+	const reset = "\x1B[0m";
+	let result = "";
+	const parts = text.split("§");
+	result += parts[0];
+	for (let i = 1; i < parts.length; i++) {
+		const part = parts[i];
+		if (part.length === 0) continue;
+		const ansi = mcColorMap[part[0].toLowerCase()];
+		if (ansi) result += ansi + part.substring(1);
+		else result += "§" + part;
+	}
+	return result + reset;
+}
+//#endregion
+//#region src/cli.ts
+const colors = {
+	reset: "\x1B[0m",
+	bright: "\x1B[1m",
+	cyan: "\x1B[36m",
+	green: "\x1B[32m",
+	yellow: "\x1B[33m",
+	magenta: "\x1B[35m",
+	white: "\x1B[37m",
+	gray: "\x1B[90m"
+};
+/**
+* Poor man's argument parser
+*/
+function parseArgs(args) {
+	const result = {};
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i];
+		if (arg === "--type" || arg === "-t") {
+			const val = args[++i]?.toLowerCase();
+			if (val === "java" || val === "bedrock") result.type = val;
+		} else if (arg === "--timeout") {
+			const val = parseInt(args[++i]);
+			if (!isNaN(val)) result.timeout = val;
+		} else if (!result.target && !arg.startsWith("-")) result.target = arg;
+	}
+	return result;
+}
+async function main() {
+	const parsed = parseArgs(process.argv.slice(2));
+	if (!parsed.target) {
+		console.log(`\n${colors.bright}Usage:${colors.reset} mcping <host[:port]> [options]`);
+		console.log(`\n${colors.bright}Options:${colors.reset}`);
+		console.log(`  --type, -t <java|bedrock>  Force protocol type`);
+		console.log(`  --timeout <ms>             Connection timeout (default: 5000)`);
+		console.log(`\n${colors.bright}Examples:${colors.reset}`);
+		console.log(`  mcping mc.hypixel.net`);
+		console.log(`  mcping geo.hivebedrock.network --type bedrock`);
+		console.log(`  mcping play.example.com --timeout 2000\n`);
+		process.exit(1);
+	}
+	try {
+		const res = await require_src.ping(parsed.target, {
+			type: parsed.type,
+			timeout: parsed.timeout
+		});
+		const resolvedStr = `${res.target.ip}:${res.target.port}`;
+		const targetDisplay = parsed.target === resolvedStr ? parsed.target : `${parsed.target} ${colors.gray}→${colors.reset} ${resolvedStr}`;
+		console.log(`\n ${colors.bright}${targetDisplay}${colors.reset}`);
+		const editionStr = `${colors.bright}${res.type.toUpperCase()}${colors.reset}`;
+		const versionStr = `${colors.gray}${res.version.name}${colors.reset}`;
+		const latencyStr = res.type === "java" ? ` ${colors.magenta}${res.latency}ms${colors.reset}` : "";
+		console.log(` ${editionStr} ${colors.gray}•${colors.reset} ${versionStr}${latencyStr}`);
+		console.log(` ${colors.bright}${res.players.online}${colors.reset} ${colors.gray}/ ${res.players.max} players${colors.reset}`);
+		const cleanMotd = mcToAnsi(res.motd).trim().split("\n").map((line) => line.trim()).filter((line) => line.length > 0).join(`\n `);
+		console.log(`\n ${cleanMotd}${colors.reset}\n`);
+	} catch (err) {
+		console.error(`\n ${colors.yellow}Error:${colors.reset} ${err.message}\n`);
+		process.exit(1);
+	}
+}
+main();
+//#endregion

package/dist/cli.mjs

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+import { t as ping } from "./src-HHWxQmnZ.mjs";
+//#region src/ansi.ts
+const mcColorMap = {
+	"0": "\x1B[30m",
+	"1": "\x1B[34m",
+	"2": "\x1B[32m",
+	"3": "\x1B[36m",
+	"4": "\x1B[31m",
+	"5": "\x1B[35m",
+	"6": "\x1B[33m",
+	"7": "\x1B[37m",
+	"8": "\x1B[90m",
+	"9": "\x1B[94m",
+	a: "\x1B[92m",
+	b: "\x1B[96m",
+	c: "\x1B[91m",
+	d: "\x1B[95m",
+	e: "\x1B[93m",
+	f: "\x1B[97m",
+	l: "\x1B[1m",
+	m: "\x1B[9m",
+	n: "\x1B[4m",
+	o: "\x1B[3m",
+	r: "\x1B[0m"
+};
+/**
+* Converts Minecraft color codes (§) to ANSI terminal colors.
+*/
+function mcToAnsi(text) {
+	const reset = "\x1B[0m";
+	let result = "";
+	const parts = text.split("§");
+	result += parts[0];
+	for (let i = 1; i < parts.length; i++) {
+		const part = parts[i];
+		if (part.length === 0) continue;
+		const ansi = mcColorMap[part[0].toLowerCase()];
+		if (ansi) result += ansi + part.substring(1);
+		else result += "§" + part;
+	}
+	return result + reset;
+}
+//#endregion
+//#region src/cli.ts
+const colors = {
+	reset: "\x1B[0m",
+	bright: "\x1B[1m",
+	cyan: "\x1B[36m",
+	green: "\x1B[32m",
+	yellow: "\x1B[33m",
+	magenta: "\x1B[35m",
+	white: "\x1B[37m",
+	gray: "\x1B[90m"
+};
+/**
+* Poor man's argument parser
+*/
+function parseArgs(args) {
+	const result = {};
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i];
+		if (arg === "--type" || arg === "-t") {
+			const val = args[++i]?.toLowerCase();
+			if (val === "java" || val === "bedrock") result.type = val;
+		} else if (arg === "--timeout") {
+			const val = parseInt(args[++i]);
+			if (!isNaN(val)) result.timeout = val;
+		} else if (!result.target && !arg.startsWith("-")) result.target = arg;
+	}
+	return result;
+}
+async function main() {
+	const parsed = parseArgs(process.argv.slice(2));
+	if (!parsed.target) {
+		console.log(`\n${colors.bright}Usage:${colors.reset} mcping <host[:port]> [options]`);
+		console.log(`\n${colors.bright}Options:${colors.reset}`);
+		console.log(`  --type, -t <java|bedrock>  Force protocol type`);
+		console.log(`  --timeout <ms>             Connection timeout (default: 5000)`);
+		console.log(`\n${colors.bright}Examples:${colors.reset}`);
+		console.log(`  mcping mc.hypixel.net`);
+		console.log(`  mcping geo.hivebedrock.network --type bedrock`);
+		console.log(`  mcping play.example.com --timeout 2000\n`);
+		process.exit(1);
+	}
+	try {
+		const res = await ping(parsed.target, {
+			type: parsed.type,
+			timeout: parsed.timeout
+		});
+		const resolvedStr = `${res.target.ip}:${res.target.port}`;
+		const targetDisplay = parsed.target === resolvedStr ? parsed.target : `${parsed.target} ${colors.gray}→${colors.reset} ${resolvedStr}`;
+		console.log(`\n ${colors.bright}${targetDisplay}${colors.reset}`);
+		const editionStr = `${colors.bright}${res.type.toUpperCase()}${colors.reset}`;
+		const versionStr = `${colors.gray}${res.version.name}${colors.reset}`;
+		const latencyStr = res.type === "java" ? ` ${colors.magenta}${res.latency}ms${colors.reset}` : "";
+		console.log(` ${editionStr} ${colors.gray}•${colors.reset} ${versionStr}${latencyStr}`);
+		console.log(` ${colors.bright}${res.players.online}${colors.reset} ${colors.gray}/ ${res.players.max} players${colors.reset}`);
+		const cleanMotd = mcToAnsi(res.motd).trim().split("\n").map((line) => line.trim()).filter((line) => line.length > 0).join(`\n `);
+		console.log(`\n ${cleanMotd}${colors.reset}\n`);
+	} catch (err) {
+		console.error(`\n ${colors.yellow}Error:${colors.reset} ${err.message}\n`);
+		process.exit(1);
+	}
+}
+main();
+//#endregion
+export {};

package/dist/index.cjs

@@ -0,0 +1,3 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_src = require("./src-Baubd7mm.cjs");
+exports.ping = require_src.ping;

package/dist/index.mjs

@@ -0,0 +1,2 @@
+import { t as ping } from "./src-HHWxQmnZ.mjs";
+export { ping };