Skip to content

v0.1.5

Choose a tag to compare

View all tags
@github-actions github-actions released this 24 Jan 22:43
· 194 commits to main since this release
v0.1.5
1893c31

sysprims v0.1.5

Release Date: 2026-01-24
Status: TypeScript Bindings Parity Release

Summary

Node.js developers now have access to process inspection, port mapping, and signal APIs. This release achieves parity with Go bindings for these core surfaces (proc/ports/signals).

Highlights

  • TypeScript Parity: Process listing, port inspection, and signal operations
  • Full Type Definitions: All schemas have corresponding TypeScript interfaces
  • Windows Stability: Signal tests no longer flaky on Windows CI
  • CI Improvements: Separated binding validation from release validation

TypeScript API

Installation

npm install @3leaps/sysprims

New Functions

Function Description
processList(filter?) List running processes with optional filtering
listeningPorts(filter?) Map listening ports to owning processes
signalSend(pid, signal) Send signal to a process
signalSendGroup(pgid, signal) Send signal to a process group (Unix only)
terminate(pid) Graceful termination (SIGTERM on Unix; TerminateProcess on Windows - immediate, not graceful)
forceKill(pid) Immediate kill (SIGKILL on Unix; TerminateProcess on Windows)

Existing Functions (from v0.1.4)

Function Description
procGet(pid) Get process info by PID
selfPGID() Get current process group ID (Unix only)
selfSID() Get current session ID (Unix only)

Usage Examples

import {
  processList,
  listeningPorts,
  terminate,
  forceKill,
  signalSend
} from '@3leaps/sysprims';

// List all processes
const all = processList();
console.log(`Found ${all.processes.length} processes`);

// Filter by name (case-insensitive substring match)
const nginx = processList({ name_contains: "nginx" });
for (const proc of nginx.processes) {
  console.log(`${proc.pid}: ${proc.name} (${proc.cpu_percent}% CPU)`);
}

// Filter by multiple criteria (AND logic)
const heavy = processList({
  cpu_above: 50,
  memory_above_kb: 100000
});

// Find what's listening on port 8080
const http = listeningPorts({ local_port: 8080 });
for (const binding of http.bindings) {
  console.log(`Port ${binding.local_port}: PID ${binding.pid} (${binding.process?.name})`);
}

// Filter by protocol
const tcpPorts = listeningPorts({ protocol: "tcp" });

// Gracefully terminate a process
terminate(1234);

// Force kill if graceful termination doesn't work
forceKill(1234);

// Send specific signal (Unix semantics; limited support on Windows)
signalSend(1234, 15);  // SIGTERM

Filter Options

ProcessFilter (for processList):

  • name_contains: Substring match (case-insensitive)
  • name_equals: Exact name match
  • user_equals: Filter by username
  • pid_in: Array of PIDs to include
  • state_in: Array of process states ("running", "sleeping", "stopped", "zombie", "unknown")
  • cpu_above: Minimum CPU percentage (0-100)
  • memory_above_kb: Minimum memory in KB

PortFilter (for listeningPorts):

  • protocol: "tcp" or "udp"
  • local_port: Specific port number

Requirements

  • Node.js 18+
  • glibc-based Linux (musl/Alpine not supported)

Changes

Added

  • TypeScript Bindings Parity (bindings/typescript/sysprims/)

    • processList(filter?) - list processes with optional filtering
    • listeningPorts(filter?) - port-to-PID mapping
    • signalSend(pid, signal) - send signal to process
    • signalSendGroup(pgid, signal) - send signal to process group (Unix)
    • terminate(pid) - graceful termination
    • forceKill(pid) - immediate kill
    • Full TypeScript type definitions for ProcessFilter, PortFilter, ProcessSnapshot, PortBindingsSnapshot

  • CI Improvements

    • Separated binding validation from release validation (validate-release.yml)
    • Clarified Go module tagging requirements in release validation

Changed

  • Go Prebuilt Libraries
    • Updated all 7 platform libraries for v0.1.5

Fixed

  • Windows Signal Tests
    • Signal tests now use deterministic patterns: reject pid=0, spawn-and-kill for terminate/forceKill
    • Eliminates flakiness where arbitrary PIDs may exist on CI runners

Platforms

Platform CLI Go Bindings TypeScript Bindings
Linux x64 (glibc) yes yes yes
Linux x64 (musl) yes yes no
Linux arm64 (glibc) yes yes yes
Linux arm64 (musl) yes yes no
macOS x64 yes yes yes
macOS arm64 yes yes yes
Windows x64 yes yes yes

Note: TypeScript bindings require glibc. Linux musl (Alpine) is not supported.

Verification

Verify this release with the signed checksums:

# Download release and verification files
curl -LO https://github.com/3leaps/sysprims/releases/download/v0.1.5/SHA256SUMS
curl -LO https://github.com/3leaps/sysprims/releases/download/v0.1.5/SHA256SUMS.minisig
curl -LO https://github.com/3leaps/sysprims/releases/download/v0.1.5/sysprims-minisign.pub

# Verify signature
minisign -Vm SHA256SUMS -p sysprims-minisign.pub

# Verify checksums
shasum -a 256 -c SHA256SUMS --ignore-missing

Next Release

v0.1.6+ will continue toward:

  • Extended self-introspection surface (self_info API)
  • Python bindings (cffi + wheel packaging)
  • Timeout API for TypeScript (complex config struct)
Assets 23
Loading