tinyps 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tinylibs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,76 @@
+# ⚙️ tinyps
+
+A cross-platform library of utilities for dealing with system processes.
+
+## Install
+
+```sh
+npm install tinyps
+```
+
+## Usage
+
+```ts
+import { killTree, getProcessTree } from 'tinyps';
+
+// kill a process and everything it spawned
+await killTree(child.pid);
+
+// or inspect the tree first
+const tree = await getProcessTree(child.pid);
+console.log(tree.get(child.pid)); // [ 1234, 1235 ]
+```
+
+## API
+
+### `killTree(pid, signal?)`
+
+- `pid` (`number`) - process to kill, along with all of its descendants
+- `signal` (`NodeJS.Signals`, optional) - signal to send, defaults to `SIGTERM`
+- Returns `Promise<void>`
+
+Note that `signal` is not supported on Windows, and will be ignored.
+
+### `getProcessTree(pid)`
+
+- `pid` (`number`) - process to build the tree from
+- Returns `Promise<ProcessTree>`
+
+### `isRunning(pid)`
+
+- `pid` (`number`) - process to check
+- Returns `boolean`
+
+### `getDescendants(pid)`
+
+- `pid` (`number`) - process to collect descendants of
+- Returns `Promise<number[]>`
+
+### `listProcesses()`
+
+- Returns `Promise<ProcessInfo[]>`
+
+### `getProcessInfo(pid)`
+
+- `pid` (`number`) - process to look up
+- Returns `Promise<ProcessInfo | undefined>`
+
+### `findProcessesByName(name, options?)`
+
+- `name` (`string`) - name to match against
+- `options.loose` (`boolean`, optional) - match any name containing `name`, ignoring case
+- Returns `Promise<ProcessInfo[]>`
+
+### `findProcessesByPort(port, options?)`
+
+- `port` (`number`) - local port to match against
+- `options.protocol` (`'tcp' | 'udp'`, optional) - only match sockets of this
+  protocol, defaults to matching both
+- Returns `Promise<ProcessInfo[]>`
+
+Matches any process holding a socket bound to `port` locally, whether it is
+listening or connected.
+
+## License
+
+MIT

package/lib/main.d.ts

@@ -0,0 +1,20 @@
+export type ProcessTree = Map<number, number[]>;
+export type Protocol = 'tcp' | 'udp';
+export interface ProcessInfo {
+    pid: number;
+    ppid: number;
+    name: string;
+    command: string;
+}
+export declare function killTree(pid: number, signal?: NodeJS.Signals): Promise<void>;
+export declare function listProcesses(): Promise<ProcessInfo[]>;
+export declare function getProcessInfo(pid: number): Promise<ProcessInfo | undefined>;
+export declare function findProcessesByName(name: string, options?: {
+    loose?: boolean;
+}): Promise<ProcessInfo[]>;
+export declare function findProcessesByPort(port: number, options?: {
+    protocol?: Protocol;
+}): Promise<ProcessInfo[]>;
+export declare function getProcessTree(pid: number): Promise<ProcessTree>;
+export declare function isRunning(pid: number): boolean;
+export declare function getDescendants(pid: number): Promise<number[]>;

package/lib/main.js

@@ -0,0 +1,240 @@
+import { spawn } from 'node:child_process';
+import { basename } from 'node:path';
+import { platform } from 'node:process';
+async function spawnAsync(command, args, allowedExitCodes) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args);
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (data) => {
+            stdout += data.toString();
+        });
+        child.stderr.on('data', (data) => {
+            stderr += data.toString();
+        });
+        child.on('close', (code) => {
+            const allowed = allowedExitCodes === undefined || code === null
+                ? code === 0
+                : allowedExitCodes.includes(code);
+            if (allowed) {
+                resolve({ stdout, stderr });
+            }
+            else {
+                reject(new Error(`Command failed with exit code ${code}: ${stderr}`));
+            }
+        });
+        child.on('error', (err) => {
+            reject(err);
+        });
+    });
+}
+function killAll(processTree, signal) {
+    for (const pid of processTree.keys()) {
+        try {
+            process.kill(pid, signal);
+        }
+        catch (err) {
+            if (err.code !== 'ESRCH') {
+                throw err;
+            }
+        }
+    }
+}
+function buildProcessTree(pid, processes) {
+    const childrenByParent = new Map();
+    for (const [childPid, parentPid] of processes) {
+        if (childPid === pid) {
+            continue;
+        }
+        const children = childrenByParent.get(parentPid) ?? [];
+        children.push(childPid);
+        childrenByParent.set(parentPid, children);
+    }
+    const processTree = new Map();
+    const queue = [pid];
+    for (const current of queue) {
+        const children = childrenByParent.get(current) ?? [];
+        processTree.set(current, children);
+        queue.push(...children);
+    }
+    return processTree;
+}
+// This matches `{ppid} {pid} {command}`, allowing spaces in the command
+const processListPattern = /^\s*(\d+)\s+(\d+)\s+(.*)$/gm;
+// `ss` reports socket owners as `users:(("name",pid=123,fd=4),...)`
+const socketOwnerPattern = /pid=(\d+)/g;
+// This matches the extensions windows includes in process names
+const executableExtensionPattern = /\.exe$/i;
+// Login shells are executed with a `-` prefixed to their argv[0]
+const loginShellPattern = /^-/;
+async function listProcessesUnix() {
+    const { stdout } = await spawnAsync('ps', [
+        '-A',
+        '-ww',
+        '-o',
+        'ppid=,pid=,args=',
+    ]);
+    return Array.from(stdout.matchAll(processListPattern), (match) => {
+        const command = match[3].trim();
+        const end = command.indexOf(' ');
+        const executable = end === -1 ? command : command.slice(0, end);
+        return {
+            pid: Number(match[2]),
+            ppid: Number(match[1]),
+            name: basename(executable.replace(loginShellPattern, '')),
+            command,
+        };
+    });
+}
+async function listProcessesWindows() {
+    const { stdout } = await spawnAsync('powershell.exe', [
+        '-NoProfile',
+        '-NonInteractive',
+        '-Command',
+        'Get-CimInstance Win32_Process | Select-Object ProcessId,ParentProcessId,Name,CommandLine | ConvertTo-Json -Compress',
+    ]);
+    const parsed = JSON.parse(stdout);
+    const processes = Array.isArray(parsed) ? parsed : [parsed];
+    return processes.map((proc) => ({
+        pid: proc.ProcessId,
+        ppid: proc.ParentProcessId,
+        name: proc.Name.replace(executableExtensionPattern, ''),
+        command: proc.CommandLine ?? proc.Name,
+    }));
+}
+async function findPidsByPortLinux(port, protocol) {
+    const protocolArgs = [];
+    if (protocol !== 'udp') {
+        protocolArgs.push('-t');
+    }
+    if (protocol !== 'tcp') {
+        protocolArgs.push('-u');
+    }
+    const { stdout } = await spawnAsync('ss', [
+        '-nHpa',
+        ...protocolArgs,
+        `sport = :${port}`,
+    ]);
+    return Array.from(stdout.matchAll(socketOwnerPattern), (match) => Number(match[1]));
+}
+async function findPidsByPortDarwin(port, protocol) {
+    const selector = protocol === undefined
+        ? `-i:${port}`
+        : `-i${protocol.toUpperCase()}:${port}`;
+    // lsof exits 1 when nothing matches
+    const { stdout } = await spawnAsync('lsof', ['-nP', '-Fpn', selector], [0, 1]);
+    const pids = [];
+    let currentPid;
+    // Field output is a `p{pid}` line followed by an `n{address}` line
+    for (const line of stdout.split('\n')) {
+        const value = line.slice(1);
+        if (line[0] === 'p') {
+            currentPid = Number(value);
+        }
+        else if (line[0] === 'n' && currentPid !== undefined) {
+            // Example connected output: 192.168.1.99:57253->1.2.3.4:443
+            // Example listening output: [::1]:57355
+            const separator = value.indexOf('->');
+            const local = separator === -1 ? value : value.slice(0, separator);
+            if (Number(local.slice(local.lastIndexOf(':') + 1)) === port) {
+                pids.push(currentPid);
+            }
+        }
+    }
+    return pids;
+}
+async function findPidsByPortWindows(port, protocol) {
+    const queries = [];
+    if (protocol !== 'udp') {
+        queries.push(`Get-NetTCPConnection -LocalPort ${port}`);
+    }
+    if (protocol !== 'tcp') {
+        queries.push(`Get-NetUDPEndpoint -LocalPort ${port}`);
+    }
+    const query = queries
+        .map((cmd) => `${cmd} -ErrorAction SilentlyContinue`)
+        .join('; ');
+    const { stdout } = await spawnAsync('powershell.exe', [
+        '-NoProfile',
+        '-NonInteractive',
+        '-Command',
+        `@(${query}) | Select-Object -ExpandProperty OwningProcess | ` +
+            'ConvertTo-Json -Compress',
+    ]);
+    if (stdout.trim() === '') {
+        return [];
+    }
+    const parsed = JSON.parse(stdout);
+    return Array.isArray(parsed) ? parsed : [parsed];
+}
+async function killTreeWindows(pid) {
+    // taskkill on windows exits 128 when its not found.
+    // unix/macos exit with 0 when the process is not found.
+    await spawnAsync('taskkill', ['/pid', String(pid), '/T', '/F'], [0, 128]);
+}
+async function killTreeUnix(pid, signal) {
+    const processTree = await getProcessTree(pid);
+    killAll(processTree, signal);
+}
+export async function killTree(pid, signal) {
+    if (platform === 'win32') {
+        return killTreeWindows(pid);
+    }
+    return killTreeUnix(pid, signal);
+}
+export async function listProcesses() {
+    if (platform === 'win32') {
+        return listProcessesWindows();
+    }
+    return listProcessesUnix();
+}
+export async function getProcessInfo(pid) {
+    const processes = await listProcesses();
+    return processes.find((proc) => proc.pid === pid);
+}
+export async function findProcessesByName(name, options) {
+    const processes = await listProcesses();
+    if (options?.loose) {
+        const needle = name.toLowerCase();
+        return processes.filter((proc) => proc.name.toLowerCase().includes(needle));
+    }
+    return processes.filter((proc) => proc.name === name);
+}
+export async function findProcessesByPort(port, options) {
+    let pids;
+    if (platform === 'win32') {
+        pids = await findPidsByPortWindows(port, options?.protocol);
+    }
+    else if (platform === 'linux') {
+        pids = await findPidsByPortLinux(port, options?.protocol);
+    }
+    else {
+        pids = await findPidsByPortDarwin(port, options?.protocol);
+    }
+    const matched = new Set(pids);
+    if (matched.size === 0) {
+        return [];
+    }
+    const processes = await listProcesses();
+    return processes.filter((proc) => matched.has(proc.pid));
+}
+export async function getProcessTree(pid) {
+    const processes = await listProcesses();
+    return buildProcessTree(pid, processes.map((proc) => [proc.pid, proc.ppid]));
+}
+export function isRunning(pid) {
+    if (pid <= 0) {
+        return false;
+    }
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === 'EPERM';
+    }
+}
+export async function getDescendants(pid) {
+    const tree = await getProcessTree(pid);
+    return Array.from(tree.keys()).filter((current) => current !== pid);
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "tinyps",
+  "version": "0.2.0",
+  "description": "A library of utilities for dealing with system processes.",
+  "main": "./lib/main.js",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./lib/main.d.ts",
+      "default": "./lib/main.js"
+    }
+  },
+  "files": [
+    "lib",
+    "!lib/**/*.test.js",
+    "!lib/**/*.test.d.ts"
+  ],
+  "scripts": {
+    "build:clean": "node -e \"require('fs').rmSync('./lib', { recursive: true, force: true })\"",
+    "build": "npm run build:clean && tsgo",
+    "lint:js": "oxlint src",
+    "lint:format": "oxfmt --check src",
+    "lint": "npm run lint:js && npm run lint:format",
+    "format": "oxfmt --write src",
+    "test": "vitest run"
+  },
+  "keywords": [
+    "proc",
+    "process",
+    "tree-kill",
+    "ps-tree",
+    "tiny",
+    "kill",
+    "tree"
+  ],
+  "author": "James Garbutt (https://github.com/43081j)",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://github.com/tinylibs/tinyps#readme",
+  "bugs": {
+    "url": "https://github.com/tinylibs/tinyps/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tinylibs/tinyps.git"
+  },
+  "devDependencies": {
+    "@types/node": "^26.5.1",
+    "@typescript/native-preview": "^7.0.0-dev.20260509.2",
+    "@vitest/coverage-v8": "^5.0.0",
+    "oxfmt": "^0.67.0",
+    "oxlint": "^1.63.0",
+    "vitest": "^5.0.0"
+  }
+}