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 if the server chooses to do so.

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);
  }
})();