@studnicky/system

Portable runtime facts with Node host inspection and browser capability reporting.

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 the computed worker-pool recommendation:

import { System } from '../src/node/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(`Optimal worker count = ${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;
const nodeVersion = plat.nodeVersion;
if (nodeVersion === undefined) {
  throw new Error('Node System adapter must report nodeVersion');
}
console.log('Platform:');
console.log(`  platform.os             = ${plat.os}`);
console.log(`  platform.nodeVersion    = ${nodeVersion}`);
console.log(`  platform.isAppleSilicon = ${plat.isAppleSilicon}`);

GPU detection

System.gpu() synchronously detects and caches GPU information, then returns a defensive copy. The Node adapter invokes system_profiler on macOS, nvidia-smi for Linux NVIDIA systems, or rocm-smi for Linux AMD systems, returning null when detection is unavailable. Import the Node adapter from @studnicky/system/node and use the canonical System.cpu, System.gpu(), System.memory, and System.platform APIs.

Try it

Loading example…

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
CpuInfoEntity.Type	entity type	{ arch, logicalCount, physicalCount, model }
MemoryInfoEntity.Type	entity type	{ totalMb, freeMb }
PlatformInfoEntity.Type	entity type	{ os, isAppleSilicon, nodeVersion }
GpuInfoEntity.Type	entity type	{ name, computeApi, vramMb }
SystemInfoEntity.Type	entity type	Canonical composition of CPU, GPU, memory, and platform data
SystemProviderInterface	interface	Runtime provider contract used by platform implementations

System

Member	Signature	Description
cpu	static get cpu(): CpuInfoEntity.Type	CPU model, architecture, logical count, and physical count
memory	static get memory(): MemoryInfoEntity.Type	Total and free memory in megabytes
platform	static get platform(): PlatformInfoEntity.Type	OS, Node.js version, and Apple Silicon flag
gpu	static gpu(): GpuInfoEntity.Type | null	Detects and caches GPU information; returns a defensive copy or null when unavailable
optimalWorkerCount	static get optimalWorkerCount(): number	max(1, System.cpu.logicalCount - 1)

GpuInfoEntity.Type.computeApi values

Value	Platform	Detector
'metal'	macOS	system_profiler SPDisplaysDataType
'cuda'	Linux (NVIDIA)	nvidia-smi
'opencl'	Linux (AMD)	rocm-smi
'software'	software renderer	reported by providers that identify a software-backed renderer

Source on GitHub

Entities

@studnicky/system/entities exports every schema namespace in src/entities.

import { SystemInfoEntity } from '@studnicky/system/entities';

Interfaces

@studnicky/system/interfaces exports every TypeScript interface in src/interfaces, including configuration and state contracts.

import type { SystemProviderInterface } from '@studnicky/system/interfaces';

Exports

Symbol	Purpose	Import path
System	Provides Node runtime facts.	@studnicky/system/node
SystemInterface	Defines shared Node and browser runtime facts.	@studnicky/system
System	Provides browser runtime facts.	@studnicky/system/browser