tinyps 0.2.0 → 0.5.0

package/README.md

@@ -41,6 +41,9 @@ Note that `signal` is not supported on Windows, and will be ignored.
 - `pid` (`number`) - process to check
 - Returns `boolean`
 
+A zombie process is still in the process table, so this returns `true` for a
+process which has exited but has not yet been released by its parent.
+
 ### `getDescendants(pid)`
 
 - `pid` (`number`) - process to collect descendants of
@@ -61,6 +64,9 @@ Note that `signal` is not supported on Windows, and will be ignored.
 - `options.loose` (`boolean`, optional) - match any name containing `name`, ignoring case
 - Returns `Promise<ProcessInfo[]>`
 
+Names come from the process' `argv[0]`, so a process which has renamed itself
+(e.g. via `process.title`) matches its new name rather than its executable.
+
 ### `findProcessesByPort(port, options?)`
 
 - `port` (`number`) - local port to match against

package/lib/main.d.ts

@@ -1,11 +1,7 @@
+import { type ProcessInfo } from './parse.js';
+export type { ProcessInfo };
 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>;

package/lib/main.js

@@ -1,16 +1,18 @@
 import { spawn } from 'node:child_process';
-import { basename } from 'node:path';
 import { platform } from 'node:process';
+import { parseLsofOutput, parseOwningProcessJson, parsePsOutput, parseSsOutput, parseWin32ProcessJson, } from './parse.js';
 async function spawnAsync(command, args, allowedExitCodes) {
     return new Promise((resolve, reject) => {
         const child = spawn(command, args);
         let stdout = '';
         let stderr = '';
+        child.stdout.setEncoding('utf8');
+        child.stderr.setEncoding('utf8');
         child.stdout.on('data', (data) => {
-            stdout += data.toString();
+            stdout += data;
         });
         child.stderr.on('data', (data) => {
-            stderr += data.toString();
+            stderr += data;
         });
         child.on('close', (code) => {
             const allowed = allowedExitCodes === undefined || code === null
@@ -29,21 +31,31 @@ async function spawnAsync(command, args, allowedExitCodes) {
     });
 }
 function killAll(processTree, signal) {
-    for (const pid of processTree.keys()) {
+    const errors = [];
+    const pids = Array.from(processTree.keys()).reverse();
+    for (const pid of pids) {
         try {
             process.kill(pid, signal);
         }
         catch (err) {
             if (err.code !== 'ESRCH') {
-                throw err;
+                errors.push(err);
             }
         }
     }
+    if (errors.length > 0) {
+        throw new AggregateError(errors, 'Failed to kill one or more processes');
+    }
 }
 function buildProcessTree(pid, processes) {
     const childrenByParent = new Map();
+    let exists = false;
     for (const [childPid, parentPid] of processes) {
         if (childPid === pid) {
+            exists = true;
+            continue;
+        }
+        if (childPid <= 0) {
             continue;
         }
         const children = childrenByParent.get(parentPid) ?? [];
@@ -51,6 +63,9 @@ function buildProcessTree(pid, processes) {
         childrenByParent.set(parentPid, children);
     }
     const processTree = new Map();
+    if (!exists) {
+        return processTree;
+    }
     const queue = [pid];
     for (const current of queue) {
         const children = childrenByParent.get(current) ?? [];
@@ -59,14 +74,6 @@ function buildProcessTree(pid, processes) {
     }
     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',
@@ -74,33 +81,17 @@ async function listProcessesUnix() {
         '-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,
-        };
-    });
+    return parsePsOutput(stdout);
 }
 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',
+        '[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new(); ' +
+            '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,
-    }));
+    return parseWin32ProcessJson(stdout);
 }
 async function findPidsByPortLinux(port, protocol) {
     const protocolArgs = [];
@@ -115,7 +106,7 @@ async function findPidsByPortLinux(port, protocol) {
         ...protocolArgs,
         `sport = :${port}`,
     ]);
-    return Array.from(stdout.matchAll(socketOwnerPattern), (match) => Number(match[1]));
+    return parseSsOutput(stdout);
 }
 async function findPidsByPortDarwin(port, protocol) {
     const selector = protocol === undefined
@@ -123,25 +114,7 @@ async function findPidsByPortDarwin(port, protocol) {
         : `-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;
+    return parseLsofOutput(stdout, port);
 }
 async function findPidsByPortWindows(port, protocol) {
     const queries = [];
@@ -158,14 +131,11 @@ async function findPidsByPortWindows(port, protocol) {
         '-NoProfile',
         '-NonInteractive',
         '-Command',
-        `@(${query}) | Select-Object -ExpandProperty OwningProcess | ` +
+        '[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new(); ' +
+            `@(${query}) | Select-Object -ExpandProperty OwningProcess | ` +
             'ConvertTo-Json -Compress',
     ]);
-    if (stdout.trim() === '') {
-        return [];
-    }
-    const parsed = JSON.parse(stdout);
-    return Array.isArray(parsed) ? parsed : [parsed];
+    return parseOwningProcessJson(stdout);
 }
 async function killTreeWindows(pid) {
     // taskkill on windows exits 128 when its not found.
@@ -177,6 +147,9 @@ async function killTreeUnix(pid, signal) {
     killAll(processTree, signal);
 }
 export async function killTree(pid, signal) {
+    if (pid <= 0) {
+        throw new TypeError(`Expected a positive pid, received: ${pid}`);
+    }
     if (platform === 'win32') {
         return killTreeWindows(pid);
     }

package/lib/parse.d.ts

@@ -0,0 +1,11 @@
+export interface ProcessInfo {
+    pid: number;
+    ppid: number;
+    name: string;
+    command: string;
+}
+export declare function parsePsOutput(stdout: string): ProcessInfo[];
+export declare function parseWin32ProcessJson(stdout: string): ProcessInfo[];
+export declare function parseSsOutput(stdout: string): number[];
+export declare function parseLsofOutput(stdout: string, port: number): number[];
+export declare function parseOwningProcessJson(stdout: string): number[];

package/lib/parse.js

@@ -0,0 +1,63 @@
+import { basename } from 'node:path';
+// 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 = /^-/;
+export function parsePsOutput(stdout) {
+    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,
+        };
+    });
+}
+export function parseWin32ProcessJson(stdout) {
+    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,
+    }));
+}
+export function parseSsOutput(stdout) {
+    return Array.from(stdout.matchAll(socketOwnerPattern), (match) => Number(match[1]));
+}
+export function parseLsofOutput(stdout, port) {
+    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;
+}
+export function parseOwningProcessJson(stdout) {
+    if (stdout.trim() === '') {
+        return [];
+    }
+    const parsed = JSON.parse(stdout);
+    return Array.isArray(parsed) ? parsed : [parsed];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tinyps",
-  "version": "0.2.0",
+  "version": "0.5.0",
   "description": "A library of utilities for dealing with system processes.",
   "main": "./lib/main.js",
   "type": "module",