@tripoloski/find-process

A cross-platform Node.js library for finding running processes based on their open file paths. Supports Windows (using Sysinternals Handle), Linux, and macOS.

Features

• Find processes by matching fragments in their open file paths
• Cross-platform support (Windows, Linux, macOS)
• Case-sensitive or case-insensitive search
• Filter by process name
• Get detailed process information (PID, name, open files)
• Check if process is running and kill processes

Installation

npm install @tripoloski/find-process
# or
yarn add @tripoloski/find-process
# or
pnpm add @tripoloski/find-process

Usage

Basic Usage

import { ProcessFinder } from '@tripoloski/find-process';

const finder = new ProcessFinder();

// Find processes with 'lock' in their open file paths
const processes = await finder.findByPathFragment({
  fragment: 'lock'
});

console.log(processes);
// [
//   Process { pid: 1234, name: 'node', files: ['C:\\temp\\app.lock'] },
//   Process { pid: 5678, name: 'notepad', files: ['C:\\temp\\document.lock'] }
// ]

With Callback

finder.findByPathFragment(
  { fragment: 'lock' },
  (error, processes) => {
    if (error) {
      console.error('Error:', error.message);
    } else {
      console.log(processes);
    }
  }
);

Filter by Process Name

const processes = await finder.findByPathFragment({
  fragment: 'temp',
  processName: 'node' // Only find processes named 'node'
});

Case-Sensitive Search

const processes = await finder.findByPathFragment({
  fragment: 'Temp',
  caseSensitive: true
});

API

ProcessFinder

Main class for finding processes.

findByPathFragment(options: IOptions): Promise<Process[]>

Finds all running processes that have the given string matching any part of their open file paths.

Options:

• fragment (string, required): The string fragment to search for in file paths
• processName (string, optional): Filter results to only include processes with this name
• caseSensitive (boolean, optional): Whether the search should be case-sensitive (default: false)

findByPathFragment(options: IOptions, callback: ICallback): void

Same as above but uses a callback instead of a promise.

Callback signature: (error: Error | null, processes: Process[]) => void

Process

Represents a found process with its details.

getPid(): number

Returns the process ID.

getProcessName(): string

Returns the process name.

getOpenFiles(): readonly string[]

Returns an array of file paths that the process has open.

isRunning(): boolean

Checks if the process is still running.

kill(force = false): boolean

Kills the process.

• force (boolean): On Windows, uses taskkill /F. On Unix, sends SIGKILL instead of SIGTERM (default: false)

Returns true if the process was successfully killed or was already dead, false otherwise.

Platform Support

• Windows: Uses Sysinternals Handle tool (included in the package)
• Linux/macOS: Uses the lsof command

Follow me on Telegram: Tripoloski Channel