minestat-es

features

• Written in TypeScript
• Less than 5kB of code
• No runtime dependencies
• Supports ESM and CommonJS
• Comprehensive unit tests

requirements

• Node 16+

usage

by address/port

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

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:

fetchServerInfo({
  hostname: 'example.com',
  timeout: 1000
});

Regardless of which 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 |

fetchServerInfo rejects if an error occurs during SRV record resolution.

example

import { fetchServerInfo } from 'minestat-es';

(async () => {
  try {
    // query by hostname (SRV lookup)
    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);
  }
})();