Updated May 2026Edit this page ↗

@termuijs/data

Real-time system statistics for terminal apps — CPU usage, memory, disk, network throughput, running processes, and HTTP endpoint health.

No native dependencies. Works on macOS, Linux, and Windows (where supported by the underlying Node.js os module).

Installation

○TYPESCRIPT
npm install @termuijs/data

Two layers

The package provides two ways to access metrics:

Raw collectors — synchronous functions you call whenever you want a snapshot. No cleanup needed, but you manage the polling yourself.

Reactive hooks — use inside JSX components. They poll automatically at a configurable interval and clean up their timers when the component unmounts.

Raw API

○TYPESCRIPT
import { cpu, memory, disk, network } from '@termuijs/data'
 
const cpuSnap  = cpu.metrics()     // CpuMetrics
const memSnap  = memory.metrics()  // MemoryMetrics
const diskSnap = disk.metrics()    // DiskMetrics
const netSnap  = network.metrics() // NetworkMetrics

Types

TypeFields
CpuMetricsusage: number (0–100), cores: number[], model: string
MemoryMetricsused: number, total: number, free: number (bytes)
DiskMetricsused: number, total: number, free: number, path: string (bytes)
NetworkMetricsrx: number, tx: number (bytes/s), interface: string
SystemInfohostname: string, platform: string, arch: string, uptime: number

Reactive hooks

Call these inside JSX components. They poll at intervalMs and return the latest value each time they fire. Timer cleanup happens automatically on component unmount.

useCpu

○TYPESCRIPT
import { useCpu } from '@termuijs/data'
 
function CpuMonitor() {
    const metrics = useCpu(500)   // refresh every 500ms
 
    return (
        <col>
            <gauge label="CPU" value={metrics.usage / 100} />
            <Text dim>{metrics.model}</Text>
        </col>
    )
}

useMemory

○TYPESCRIPT
const mem = useMemory(1000)
const pct = mem.used / mem.total
return <gauge label="MEM" value={pct} />

useDisk

○TYPESCRIPT
const disk = useDisk(5000)   // disk doesn't change fast — 5s is fine
return <gauge label="Disk" value={disk.used / disk.total} />

useNetwork

○TYPESCRIPT
const net = useNetwork(1000)
return (
    <col>
        <Text>↑ {formatBytes(net.tx)}/s</Text>
        <Text>↓ {formatBytes(net.rx)}/s</Text>
    </col>
)

useTopProcesses

Returns the top n processes sorted by CPU usage:

○TYPESCRIPT
import { useTopProcesses } from '@termuijs/data'
 
function ProcessTable() {
    const procs = useTopProcesses(10, 2000)  // top 10, refresh every 2s
 
    return (
        <table
            columns={['pid', 'name', 'cpu', 'mem']}
            rows={procs.map((p) => ({ ...p, cpu: `${p.cpu.toFixed(1)}%` }))}
        />
    )
}

useSystemInfo

Static system information — fetched once on mount, no polling:

○TYPESCRIPT
import { useSystemInfo } from '@termuijs/data'
 
function SystemHeader() {
    const info = useSystemInfo()
 
    return (
        <row>
            <Text>{info.hostname}</Text>
            <Text dim>{info.platform} {info.arch}</Text>
        </row>
    )
}

useHttpHealth

Pings one or more URLs and returns their status and latency:

○TYPESCRIPT
import { useHttpHealth } from '@termuijs/data'
 
function HealthDashboard() {
    const checks = useHttpHealth(
        ['https://api.example.com/health', 'https://db.example.com/ping'],
        5000   // check every 5s
    )
 
    return (
        <col>
            {checks.map((c) => (
                <row key={c.url}>
                    <status label={c.url} isUp={c.status < 400} />
                    <Text dim>{c.latencyMs}ms</Text>
                </row>
            ))}
        </col>
    )
}

Return type: Array<{ url: string, status: number, latencyMs: number, error?: string }>

Hook reference

HookSignatureReturns
useCpu(intervalMs?: number)CpuMetrics
useMemory(intervalMs?: number)MemoryMetrics
useDisk(intervalMs?: number)DiskMetrics
useNetwork(intervalMs?: number)NetworkMetrics
useTopProcesses(n: number, intervalMs?: number)ProcessInfo[]
useSystemInfo()SystemInfo
useHttpHealth(urls: string[], intervalMs?: number)HealthResult[]

All interval hooks default to 1000ms if intervalMs is not provided.

Memory leak note

Hooks clean up their useInterval timers automatically when the component unmounts. Raw collector functions do not start any timers — they're pure reads, no cleanup needed.

See also

  • Widgets: Charts — LineChart, HeatMap, BarChart, Sparkline for visualizing metrics
  • @termuijs/quick — useCpu, useMemory etc. are re-exported from quick for rapid prototyping
← PreviousOverviewNext →Springs