minestat-es v2.3.0

minestat-es

features

• Written in TypeScript
• Less than 6kB 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
});

ping

This library can optionally return the ping time in milliseconds. This is defined as the time between sending the ping packet and receiving a response. Pinging is possible for both legacy and modern query protocols.

import { fetchServerInfo } from 'minestat-es';

fetchServerInfo({
  hostname: 'example.com',
  ping: true
});

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

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

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

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