node-os-utils

node-os-utils is a TypeScript-first operating-system monitoring library that provides a unified async API for reading CPU usage, memory stats, disk usage, network throughput, and running-process information, with platform adapters for Linux, macOS, and Windows so callers don’t need to shell out to platform-specific commands themselves. An OSUtils facade class lazily instantiates per-metric monitors (CPU, memory, disk, network, process, system) and layers a cache manager on top so repeated reads within a short window avoid re-executing expensive system calls.

The library is aimed at server-side Node.js monitoring — health-check endpoints, dashboards, and lightweight APM-style reporting — where you want current-machine metrics without spinning up a full observability agent.

What You Get

• A unified OSUtils class exposing cpu, memory, disk, network, process, and system monitors behind one async API
• Platform adapters (linux-adapter, macos-adapter, windows-adapter) selected automatically via an AdapterFactory
• A built-in CacheManager to avoid re-running expensive system calls on rapid repeated reads
• Full TypeScript types for all monitor results, published with generated .d.ts declarations
• Platform-specific test suites (Linux/macOS/Windows) plus unit and integration tests run in CI

Common Use Cases

• Building a /health or /metrics endpoint that reports live CPU, memory, and disk usage
• Powering a lightweight server-monitoring dashboard without deploying a full APM agent
• Alerting scripts that poll CPU/memory/disk thresholds and trigger notifications
• Inspecting running processes and network throughput from within a Node.js server process

Under The Hood

Architecture The library centers on an OSUtils facade class (src/index.ts) that lazily constructs monitor instances (CPUMonitor, MemoryMonitor, DiskMonitor, NetworkMonitor, ProcessMonitor, SystemMonitor from src/monitors/) on first access, backed by a PlatformAdapter chosen at construction time via AdapterFactory (src/adapters/adapter-factory.ts) which picks between linux-adapter.ts, macos-adapter.ts, and windows-adapter.ts based on the running OS; a CacheManager (src/core) sits between monitors and adapters to avoid redundant expensive OS calls (e.g. repeated ps/wmic//proc reads) within a configurable window.

Tech Stack Written entirely in TypeScript (~11,800 lines across src/), compiled with tsc to CommonJS (dist/), depending on Node’s built-in os/child_process modules for platform data rather than native bindings, targeting Node >=18.

Code Quality The test suite is unusually thorough for a systems-utility package: dedicated platform test files (test/platform/linux.test.ts, macos.test.ts, windows.test.ts), unit tests per monitor (cpu/memory/disk/network/process/system-monitor.test.ts), type tests, and even a Deno smoke test, run via Mocha with nyc coverage and per-platform npm scripts (test:linux/test:macos/test:windows). Code is organized into clear layers (adapters/core/monitors/types/utils) rather than one large file.

API Design The facade-plus-lazy-monitor pattern (os.cpu.usage(), os.mem.info(), etc.) keeps the common path simple while still exposing platform adapters directly for advanced use; full TypeScript types reduce guesswork about return shapes, though the async, promise-based API for what are ultimately synchronous OS reads on some platforms adds a small amount of ceremony to simple checks.