minestat-es

features

Written in TypeScript
Less than 5kB of code
One runtime dependency
Supports ESM and CommonJS
Comprehensive unit tests

requirements

Node 18+

usage

by address/port

To query a Minecraft server using an IP/hostname and a port, use:

import { fetchServerInfo } from 'minestat-es';

fetchServerInfo({
  address: '1.2.3.4',
  port: 25565,
  timeout: 1000
});

by hostname

To perform an SRV record lookup and query a Minecraft server using only a hostname, use:

import { fetchServerInfo } from 'minestat-es';

// makes an SRV lookup for _minecraft._tcp.example.com
fetchServerInfo({
  hostname: 'example.com',
  timeout: 1000
});

query protocols

This library supports two methods of querying the server. The legacy protocol works with any Minecraft server. The modern protocol is only compatible with Minecraft v1.6 and higher. The default protocol is the legacy protocol.

To specify the modern protocol, pass it as the protocol option:

import { fetchServerInfo, QueryProtocols } from 'minestat-es';

fetchServerInfo({
  hostname: 'example.com',
  protocol: QueryProtocols.Modern
});

Regardless of the way it was invoked, fetchServerInfo returns a promise which will resolve with an object containing the following properties:

Key	Type	Description
online	`boolean`	Whether the server is online or not

If the server is offline, the object will also contain the properties:

Key	Type	Description
error	`Error`	A communications or validation error, if one occurred

If the server is online, the object will also contain the following properties:

Key	Type	Description
version	`string`	The server's version string
motd	`string`	The server's Message of the Day
players	`number`	The number of players on the server
maxPlayers	`number`	The maximum number of players the server supports
playerInfo	`object[]`	An aray of { id, name } objects for each connected player

NOTE: playerInfo is only populated when using the modern query protocol and the server chooses to send it.

fetchServerInfo rejects if an error occurs during SRV record resolution.

example

import { fetchServerInfo } from 'minestat-es';

(async () => {
  try {
    // query by hostname (SRV lookup)
    // _minecraft._tcp. will be prepended unless you supply it
    const { online, error, players } = await fetchServerInfo({
      hostname: 'mc.example.com'
    });

    // OR

    // query by address/port
    const { online, error, players } = await fetchServerInfo({
      address: 'example.com', // could also be an IP address
      port: 25565
    });

    // interpret the results
    console.log(`Server is ${online ? 'Online' : 'Offline'}`);
    if (online) {
      console.log(`There are ${players} player(s) online.`);
    } else if (error) {
      // either the SRV record failed to resolve, a socket error occurred,
      // or the response from the server was invalid
      console.error(error);
    }
  } catch (error) {
    // an unexpected error occurred
    console.error(error);
  }
})();

ayan4m1/minestat-es