getos

getos is a small Node.js module that answers a question Node’s built-in os.platform() can’t: which Linux distribution is this? Where os.platform() stops at a generic string like linux, getos walks a table of distro-specific release files (/etc/redhat-release, /etc/lsb-release, /etc/debian_version, and dozens more), figures out which one exists on the current machine, and returns a structured object with os, dist, codename, and release fields.

For non-Linux platforms it simply defers to os.platform() and returns immediately, so it’s safe to call unconditionally in cross-platform code. On Linux it optionally shells out to lsb_release for extra precision (codename, exact release string), falling back to parsing the release file directly when that binary isn’t available. The result is cached after the first call since a running OS doesn’t change underneath a live process.

What You Get

• A single async function, getos(cb), that returns { os, dist, codename, release }
• Coverage for dozens of Linux distributions via a maintained os.json signature table
• Automatic fallback to os.platform() on macOS, Windows, and other non-Linux platforms
• Per-distro enrichment modules (logic/debian.js, logic/ubuntu.js, logic/fedora.js, etc.) that call lsb_release for codename/release detail when available
• In-process result caching so repeated calls don’t re-stat the filesystem

Common Use Cases

• CLI tools and installers that need to pick the right package-manager command (apt vs. yum vs. apk) for the host distro
• Diagnostic and bug-report tooling that wants to include the exact OS/distro/version a user is running
• Provisioning and DevOps scripts that branch setup steps by Linux flavor
• Cross-platform Node applications that want a normalized OS descriptor without shelling out manually

Under The Hood

Architecture getos is a single-file CommonJS module (index.js) exporting one function, getOs(cb). It short-circuits on non-Linux platforms by returning os.platform() directly; on Linux it delegates to getLinuxDistro(), which checks an in-memory cachedDistro before doing any work. Distro detection itself is written in continuation-passing style: getReleaseFile() recursively fs.stats candidate paths (the keys of os.json) until one exists, then fs.readFiles it, matches candidate distro names against the file contents (case-insensitively, via getName()), and — when a match is found — hands off to an optional per-distro module loaded dynamically from logic/<name>.js (wrapped in a try/catch so a missing module is a no-op rather than a failure). This keeps the core small, but the CPS-style callback threading and the tight coupling between os.json’s file-to-distro-array shape and the matching logic in index.js mean a change to os.json’s structure would ripple through most of logic/*.js.

Tech Stack Plain Node.js with no build step and no TypeScript. The only runtime dependency is async (^3.2.4), used for iterating distro candidates with async.each. Distro-specific modules (e.g. logic/debian.js, logic/ubuntu.js) shell out to lsb_release -a via Node’s child_process.exec for codename/release detail, falling back to regex-parsing the raw release file when the binary isn’t present. Dev tooling includes tape for tests, standard as a zero-config linter run as a posttest step, and a Dockerfile apparently used to exercise the code against real distro filesystems; .travis.yml reflects an older, since-deprecated CI setup.

Code Quality Tests live in tests/mocktests.js and use tape, monkey-patching os.platform, fs.stat, and fs.readFile to replay fixture data from tests/mockdata.json covering distros like Ubuntu, Debian, Alpine, and Fedora, reloading the module fresh for each case to avoid cross-test caching. Linting is enforced via standard with no bespoke config. Error handling follows plain Node err-first callback conventions throughout — no typed errors, no async/await, no TypeScript — which is consistent with the module’s age but dated by current conventions.

What Makes It Unique getos isn’t attempting anything novel — distro detection by release-file sniffing is a well-worn technique — but its value is breadth and pluggability: an extensive table of release-file-to-distro mappings in os.json covering dozens of lesser-known distributions, paired with a small per-distro plugin mechanism (logic/*.js) for squeezing out extra detail like codename via lsb_release where it’s available.