{"id":16049247,"url":"https://github.com/ayan4m1/minestat-es","last_synced_at":"2025-07-17T03:09:01.537Z","repository":{"id":48327101,"uuid":"516852911","full_name":"ayan4m1/minestat-es","owner":"ayan4m1","description":"Minecraft server status library for Node.js","archived":false,"fork":false,"pushed_at":"2025-07-05T17:03:52.000Z","size":1778,"stargazers_count":9,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-07-05T17:09:12.390Z","etag":null,"topics":["library","minecraft","nodejs","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ayan4m1.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-07-22T18:36:32.000Z","updated_at":"2025-07-05T17:03:32.000Z","dependencies_parsed_at":"2022-08-26T02:23:02.746Z","dependency_job_id":"c74872b6-c3ab-4ed9-8369-044d83538387","html_url":"https://github.com/ayan4m1/minestat-es","commit_stats":{"total_commits":62,"total_committers":1,"mean_commits":62.0,"dds":0.0,"last_synced_commit":"5818121bdf45c30e56124497b206f2f2dee41412"},"previous_names":[],"tags_count":29,"template":false,"template_full_name":null,"purl":"pkg:github/ayan4m1/minestat-es","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ayan4m1%2Fminestat-es","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ayan4m1%2Fminestat-es/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ayan4m1%2Fminestat-es/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ayan4m1%2Fminestat-es/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ayan4m1","download_url":"https://codeload.github.com/ayan4m1/minestat-es/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ayan4m1%2Fminestat-es/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265562356,"owners_count":23788512,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["library","minecraft","nodejs","typescript"],"created_at":"2024-10-09T00:15:21.909Z","updated_at":"2025-07-17T03:09:01.531Z","avatar_url":"https://github.com/ayan4m1.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# minestat-es\n\nGet the status of any Minecraft server from JavaScript.\n\n[![Package Version](https://badge.fury.io/js/minestat-es.svg?2)](https://www.npmjs.com/package/minestat-es)\n[![Code Coverage](https://codecov.io/gh/ayan4m1/minestat-es/branch/main/graph/badge.svg?token=UKTTU7XNAM)](https://codecov.io/gh/ayan4m1/minestat-es)\n\n![Build Status](https://img.shields.io/github/actions/workflow/status/ayan4m1/minestat-es/publish.yml)\n![Node Support](https://img.shields.io/node/v/minestat-es.svg?2)\n![Last Build](https://img.shields.io/npm/last-update/minestat-es)\n\n## features\n\n- Written in TypeScript\n- Less than 6kB of code\n- One runtime dependency\n- Supports ESM and CommonJS\n- Comprehensive unit tests\n\n## requirements\n\n- Node 22+\n\n## usage\n\n**NOTE**: This library does not support the browser. Polyfills are available for [net](https://www.npmjs.com/package/net-browserify) and [process.hrtime()](https://github.com/kumavis/browser-process-hrtime), but not for `dns`.\n\n### by address/port\n\nTo query a Minecraft server using an IP/hostname and a port, use:\n\n```ts\nimport { fetchServerInfo } from 'minestat-es';\n\nfetchServerInfo({\n  address: '1.2.3.4',\n  port: 25565,\n  timeout: 1000\n});\n```\n\n### by hostname\n\nTo perform an SRV record lookup and query a Minecraft server using only a hostname, use:\n\n```ts\nimport { fetchServerInfo } from 'minestat-es';\n\n// makes an SRV lookup for _minecraft._tcp.example.com\nfetchServerInfo({\n  hostname: 'example.com',\n  timeout: 1000\n});\n```\n\n### query protocols\n\nThis 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.\n\nTo specify the modern protocol, pass it as the `protocol` option:\n\n```ts\nimport { fetchServerInfo, QueryProtocols } from 'minestat-es';\n\nfetchServerInfo({\n  hostname: 'example.com',\n  protocol: QueryProtocols.Modern\n});\n```\n\n### ping\n\nThis 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.\n\n```ts\nimport { fetchServerInfo } from 'minestat-es';\n\nfetchServerInfo({\n  hostname: 'example.com',\n  ping: true\n});\n```\n\nRegardless of the way it was invoked, `fetchServerInfo` returns a promise which will resolve with an object containing the following properties:\n\n| Key    | Type      | Description                         |\n| ------ | --------- | ----------------------------------- |\n| online | `boolean` | Whether the server is online or not |\n\nIf the server is offline, the object will also contain the properties:\n\n| Key   | Type    | Description                                           |\n| ----- | ------- | ----------------------------------------------------- |\n| error | `Error` | A communications or validation error, if one occurred |\n\nIf the server is online, the object will also contain the following properties:\n\n| Key        | Type       | Description                                                             |\n| ---------- | ---------- | ----------------------------------------------------------------------- |\n| version    | `string`   | The server's version string                                             |\n| motd       | `string`   | The server's Message of the Day                                         |\n| players    | `number`   | The number of players on the server                                     |\n| maxPlayers | `number`   | The maximum number of players the server supports                       |\n| playerInfo | `object[]` | An aray of { id, name } objects for each connected player               |\n| pingMs     | `number`   | The number of milliseconds between sending and receiving a ping packet. |\n\n**NOTE**: playerInfo is only populated when using the modern query protocol and the server chooses to send it.\n\n`fetchServerInfo` rejects if an error occurs during SRV record resolution.\n\n## example\n\n```ts\nimport { fetchServerInfo } from 'minestat-es';\n\n(async () =\u003e {\n  try {\n    // query by hostname (SRV lookup)\n    // _minecraft._tcp. will be prepended unless you supply it\n    const { online, error, players } = await fetchServerInfo({\n      hostname: 'mc.example.com'\n    });\n\n    // OR\n\n    // query by address/port\n    const { online, error, players } = await fetchServerInfo({\n      address: 'example.com', // could also be an IP address\n      port: 25565\n    });\n\n    // interpret the results\n    console.log(`Server is ${online ? 'Online' : 'Offline'}`);\n    if (online) {\n      console.log(`There are ${players} player(s) online.`);\n    } else if (error) {\n      // either the SRV record failed to resolve, a socket error occurred,\n      // or the response from the server was invalid\n      console.error(error);\n    }\n  } catch (error) {\n    // an unexpected error occurred\n    console.error(error);\n  }\n})();\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fayan4m1%2Fminestat-es","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fayan4m1%2Fminestat-es","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fayan4m1%2Fminestat-es/lists"}