find-process

With find-process, you can:

• find the process which is listening specified port
• find the process by pid
• find the process by given name or name pattern

We have covered the difference of main OS platform, including macOS, Linux, Windows and Android (with Termux).

Features

• ✅ Full TypeScript Support - Written in TypeScript with complete type definitions
• ✅ Cross-platform - Works on macOS, Linux, Windows, and Android
• ✅ CLI Tool - Command-line interface for quick process lookup
• ✅ Node.js API - Programmatic access with Promise-based API
• ✅ Modern Build - ES2020 target with source maps and declaration files

CLI

Install find-process as a CLI tool:

1$ npm install find-process -g

Usage:

1
2  Usage: find-process [options] <keyword>
3
4
5  Options:
6
7    -V, --version      output the version number
8    -t, --type <type>  find process by keyword type (pid|port|name)
9    -p, --port         find process by port
10    -h, --help         output usage information
11
12  Examples:
13
14    $ find-process node          # find by name "node"
15    $ find-process 111           # find by pid "111"
16    $ find-process -p 80         # find by port "80"
17    $ find-process -t port 80    # find by port "80"
18

Example:

Node API

You can use npm to install:

1$ npm install find-process --save

TypeScript Usage

1import find, { ProcessInfo, FindConfig } from "find-process";
2
3// Find process by PID
4find('pid', 12345)
5  .then((list: ProcessInfo[]) => {
6    console.log(list);
7  })
8  .catch((err: Error) => {
9    console.log(err.stack || err);
10  });
11
12// With configuration options
13const config: FindConfig = {
14  strict: true,
15  logLevel: 'warn'
16};
17
18find('name', 'nginx', config)
19  .then((list: ProcessInfo[]) => {
20    console.log(`Found ${list.length} nginx processes`);
21  });

JavaScript Usage

1const find = require('find-process');
2
3find('pid', 12345)
4  .then(function (list) {
5    console.log(list);
6  }, function (err) {
7    console.log(err.stack || err);
8  })

API Reference

Function Signature

1function find(type: 'port' | 'pid' | 'name', value: string | number, options?: FindConfig | boolean): Promise<ProcessInfo[]>

Arguments

• type - The type of search, supports: 'port' | 'pid' | 'name'
• value - The value to search for. Can be RegExp if type is 'name'
• options - Optional configuration object or boolean for strict mode
  • options.strict - Optional strict mode for exact matching of port, pid, or name (on Windows, .exe can be omitted)
  • options.logLevel - Set logging level to 'trace' | 'debug' | 'info' | 'warn' | 'error'. Useful for silencing netstat warnings on Linux
  • options.skipSelf - Skip the current process when searching by name

Return Value

Returns a Promise that resolves to an array of process information ([] means no processes found):

1interface ProcessInfo {
2  pid: number;           // Process ID
3  ppid: number;          // Parent process ID
4  uid?: number;          // User ID (Unix systems)
5  gid?: number;          // Group ID (Unix systems)
6  name: string;          // Command/process name
7  bin?: string;          // Executable path (Unix systems)
8  cmd: string;           // Full command with arguments
9}

Type Definitions

The package includes complete TypeScript definitions:

1import { ProcessInfo, FindConfig, FindMethod } from 'find-process';

Examples

Find process listening on port 80

1import find from 'find-process';
2
3find('port', 80)
4  .then((list) => {
5    if (!list.length) {
6      console.log('Port 80 is free now');
7    } else {
8      console.log(`${list[0].name} is listening on port 80`);
9    }
10  });

Find process by PID

1import find from 'find-process';
2
3find('pid', 12345)
4  .then((list) => {
5    console.log(list);
6  })
7  .catch((err) => {
8    console.log(err.stack || err);
9  });

Find all nginx processes

1import find from 'find-process';
2
3find('name', 'nginx', true)
4  .then((list) => {
5    console.log(`There are ${list.length} nginx process(es)`);
6  });

Find processes with configuration options

1import find from 'find-process';
2
3find('name', 'nginx', { strict: true, logLevel: 'error' })
4  .then((list) => {
5    console.log(`Found ${list.length} nginx process(es)`);
6  });

Using async/await

1import find from 'find-process';
2
3async function findNodeProcesses() {
4  try {
5    const processes = await find('name', 'node');
6    console.log(`Found ${processes.length} Node.js processes`);
7    
8    processes.forEach(proc => {
9      console.log(`PID: ${proc.pid}, Name: ${proc.name}, CMD: ${proc.cmd}`);
10    });
11  } catch (error) {
12    console.error('Error finding processes:', error);
13  }
14}

Development

Prerequisites

• Node.js 16+
• pnpm (recommended) or npm

Setup

1# Clone the repository
2git clone https://github.com/yibn2008/find-process.git
3cd find-process
4
5# Install dependencies
6pnpm install
7
8# Build the project
9pnpm run build
10
11# Run tests
12pnpm test
13
14# Run linting
15pnpm run lint

Available Scripts

• pnpm run build - Compile TypeScript to JavaScript
• pnpm run dev - Watch mode for development
• pnpm test - Run tests
• pnpm run lint - Run linting and fix issues
• pnpm run type-check - TypeScript type checking
• pnpm run check-version - Verify version consistency
• pnpm run update-history - Update HISTORY.md with recent commits

Contributing

We welcome Pull Requests for bug fixes and new features. Please check the following before submitting a PR:

• Coding Style - Follow the Standard Style
• TypeScript - Ensure proper typing and no type errors
• Documentation - Add documentation for every API change
• Unit Tests - Add unit tests for bug fixes or new features
• Build - Ensure pnpm run build completes successfully

License

MIT