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:

$ npm install find-process -g

Usage:

  Usage: find-process [options] <keyword>


  Options:

    -V, --version      output the version number
    -t, --type <type>  find process by keyword type (pid|port|name)
    -p, --port         find process by port
    -h, --help         output usage information

  Examples:

    $ find-process node          # find by name "node"
    $ find-process 111           # find by pid "111"
    $ find-process -p 80         # find by port "80"
    $ find-process -t port 80    # find by port "80"

Example:

Node API

You can use npm to install:

$ npm install find-process --save

TypeScript Usage

import find, { ProcessInfo, FindConfig } from "find-process";

// Find process by PID
find('pid', 12345)
  .then((list: ProcessInfo[]) => {
    console.log(list);
  })
  .catch((err: Error) => {
    console.log(err.stack || err);
  });

// With configuration options
const config: FindConfig = {
  strict: true,
  logLevel: 'warn'
};

find('name', 'nginx', config)
  .then((list: ProcessInfo[]) => {
    console.log(`Found ${list.length} nginx processes`);
  });

JavaScript Usage

const find = require('find-process');

find('pid', 12345)
  .then(function (list) {
    console.log(list);
  }, function (err) {
    console.log(err.stack || err);
  })

API Reference

Function Signature

function 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):

interface ProcessInfo {
  pid: number;           // Process ID
  ppid: number;          // Parent process ID
  uid?: number;          // User ID (Unix systems)
  gid?: number;          // Group ID (Unix systems)
  name: string;          // Command/process name
  bin?: string;          // Executable path (Unix systems)
  cmd: string;           // Full command with arguments
}

Type Definitions

The package includes complete TypeScript definitions:

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

Examples

Find process listening on port 80

import find from 'find-process';

find('port', 80)
  .then((list) => {
    if (!list.length) {
      console.log('Port 80 is free now');
    } else {
      console.log(`${list[0].name} is listening on port 80`);
    }
  });

Find process by PID

import find from 'find-process';

find('pid', 12345)
  .then((list) => {
    console.log(list);
  })
  .catch((err) => {
    console.log(err.stack || err);
  });

Find all nginx processes

import find from 'find-process';

find('name', 'nginx', true)
  .then((list) => {
    console.log(`There are ${list.length} nginx process(es)`);
  });

Find processes with configuration options

import find from 'find-process';

find('name', 'nginx', { strict: true, logLevel: 'error' })
  .then((list) => {
    console.log(`Found ${list.length} nginx process(es)`);
  });

Using async/await

import find from 'find-process';

async function findNodeProcesses() {
  try {
    const processes = await find('name', 'node');
    console.log(`Found ${processes.length} Node.js processes`);
    
    processes.forEach(proc => {
      console.log(`PID: ${proc.pid}, Name: ${proc.name}, CMD: ${proc.cmd}`);
    });
  } catch (error) {
    console.error('Error finding processes:', error);
  }
}

Development

Prerequisites

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

Setup

# Clone the repository
git clone https://github.com/yibn2008/find-process.git
cd find-process

# Install dependencies
pnpm install

# Build the project
pnpm run build

# Run tests
pnpm test

# Run linting
pnpm 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