@studnicky/system

Static host-system inspection: CPU topology, GPU detection (Metal/CUDA/ROCm), memory, and platform info.

Install

pnpm add @studnicky/system

Requires @studnicky:registry=https://npm.pkg.github.com in .npmrc.

Usage

CPU, memory, and platform

Read CPU topology, memory usage, and platform info synchronously, plus computed shorthands for common worker-pool decisions:

import { System } from '../src/index.js';

const cpu = System.cpu;
console.log('CPU:');
console.log(`  cpu.arch          = ${cpu.arch}`);
console.log(`  cpu.model         = ${cpu.model}`);
console.log(`  cpu.logicalCount  = ${cpu.logicalCount}`);
console.log(`  cpu.physicalCount = ${cpu.physicalCount}`);

console.log('Shorthands:');
console.log(`  logicalCpuCount    = ${System.logicalCpuCount}`);
console.log(`  optimalWorkerCount = ${System.optimalWorkerCount}`);

const mem = System.memory;
console.log('Memory:');
console.log(`  memory.totalMb = ${mem.totalMb}`);
console.log(`  memory.freeMb  = ${mem.freeMb}`);

const plat = System.platform;
console.log('Platform:');
console.log(`  platform.os             = ${plat.os}`);
console.log(`  platform.nodeVersion    = ${plat.nodeVersion}`);
console.log(`  platform.isAppleSilicon = ${plat.isAppleSilicon}`);
console.log(`  System.isAppleSilicon   = ${System.isAppleSilicon}`);

GPU detection and full snapshot

GPU detection is async: it shells out to system_profiler (macOS), nvidia-smi (Linux NVIDIA), or rocm-smi (Linux AMD). Results are cached after the first call. System.snapshot() returns all four info objects together:

import { System } from '../src/index.js';

const VALID_COMPUTE_APIS = new Set(['cuda', 'metal', 'opencl', 'software']);

console.log('GPU:');
const gpu = System.gpu();

if (gpu === null) {
  console.log('  gpu = null (no hardware GPU detected)');
} else {
  console.log(`  gpu.name        = ${gpu.name}`);
  console.log(`  gpu.computeApi  = ${gpu.computeApi}`);
  console.log(`  gpu.vramMb      = ${gpu.vramMb ?? 'null'}`);
}

console.log('Snapshot:');
const info = System.snapshot();

console.log(`  snapshot.cpu.logicalCount  = ${info.cpu.logicalCount}`);
console.log(`  snapshot.memory.totalMb    = ${info.memory.totalMb}`);
console.log(`  snapshot.platform.os       = ${info.platform.os}`);
console.log(`  snapshot.gpu               = ${info.gpu === null ? 'null' : info.gpu.name}`);

Try it

CPU topology, memory, and platform info

/** cpuMemoryPlatform — CPU topology, memory, and platform accessors. Run: npx tsx examples/cpuMemoryPlatform.ts */

import assert from 'node:assert/strict';

// #region usage
import { System } from '../src/index.js';

const cpu = System.cpu;
console.log('CPU:');
console.log(`  cpu.arch          = ${cpu.arch}`);
console.log(`  cpu.model         = ${cpu.model}`);
console.log(`  cpu.logicalCount  = ${cpu.logicalCount}`);
console.log(`  cpu.physicalCount = ${cpu.physicalCount}`);

console.log('Shorthands:');
console.log(`  logicalCpuCount    = ${System.logicalCpuCount}`);
console.log(`  optimalWorkerCount = ${System.optimalWorkerCount}`);

const mem = System.memory;
console.log('Memory:');
console.log(`  memory.totalMb = ${mem.totalMb}`);
console.log(`  memory.freeMb  = ${mem.freeMb}`);

const plat = System.platform;
console.log('Platform:');
console.log(`  platform.os             = ${plat.os}`);
console.log(`  platform.nodeVersion    = ${plat.nodeVersion}`);
console.log(`  platform.isAppleSilicon = ${plat.isAppleSilicon}`);
console.log(`  System.isAppleSilicon   = ${System.isAppleSilicon}`);
// #endregion usage

assert.ok(Number.isInteger(cpu.logicalCount) && cpu.logicalCount > 0, 'logicalCount must be a positive integer');
assert.ok(Number.isInteger(cpu.physicalCount) && cpu.physicalCount > 0, 'physicalCount must be a positive integer');
assert.ok(cpu.physicalCount <= cpu.logicalCount, 'physicalCount must be <= logicalCount');
assert.ok(typeof cpu.arch === 'string' && cpu.arch.length > 0, 'arch must be a non-empty string');
assert.ok(typeof cpu.model === 'string' && cpu.model.length > 0, 'model must be a non-empty string');
assert.equal(System.logicalCpuCount, cpu.logicalCount, 'logicalCpuCount must equal cpu.logicalCount');
assert.ok(System.optimalWorkerCount >= 1, 'optimalWorkerCount must be >= 1');
assert.ok(System.optimalWorkerCount <= System.logicalCpuCount, 'optimalWorkerCount must be <= logicalCpuCount');
assert.ok(mem.totalMb > 0, 'totalMb must be > 0');
assert.ok(mem.freeMb >= 0, 'freeMb must be >= 0');
assert.ok(mem.freeMb <= mem.totalMb, 'freeMb must be <= totalMb');
assert.ok(typeof plat.os === 'string' && plat.os.length > 0, 'os must be a non-empty string');
assert.ok(plat.nodeVersion.startsWith('v'), 'nodeVersion must start with "v"');
assert.equal(typeof System.isAppleSilicon, 'boolean', 'isAppleSilicon must be boolean');

console.log('cpuMemoryPlatform: all assertions passed');

Output

Press Execute to run this example against the real library.

The output shows live CPU architecture, model, logical and physical counts, optimalWorkerCount, total and free memory in megabytes, OS name, runtime version string, and the Apple Silicon flag — all read from navigator in-browser.

API

Export	Type	Description
System	class	Static-only system introspection API
CpuInfoType	type	{ arch, logicalCount, physicalCount, model }
MemoryInfoType	type	{ totalMb, freeMb }
PlatformInfoType	type	{ os, isAppleSilicon, nodeVersion }
GpuInfoType	type	{ name, computeApi, vramMb }
SystemInfoType	type	Aggregates all four info types

System

Member	Signature	Description
cpu	static get cpu(): CpuInfoType	CPU model, arch, logical and physical count
memory	static get memory(): MemoryInfoType	Total and free memory in megabytes
platform	static get platform(): PlatformInfoType	OS, Node.js version, Apple Silicon flag
gpu	static gpu(): Promise<GpuInfoType | null>	Detects GPU; returns null when unavailable; cached after first call
logicalCpuCount	static get logicalCpuCount(): number	Shorthand for System.cpu.logicalCount
optimalWorkerCount	static get optimalWorkerCount(): number	max(1, logicalCpuCount - 1) (leaves one core for the event loop)
isAppleSilicon	static get isAppleSilicon(): boolean	True on darwin/arm64
snapshot	static snapshot(): Promise<SystemInfoType>	Returns all info as a single object

GpuInfoType.computeApi values

Value	Platform	Detector
'metal'	macOS	system_profiler SPDisplaysDataType
'cuda'	Linux (NVIDIA)	nvidia-smi
'opencl'	Linux (AMD)	rocm-smi
'software'	fallback	reported when no hardware accelerator found

Source on GitHub