find-process

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

Similar packages

Other packages similar to find-process

ps-node

ps-node is a package similar to find-process that allows for searching, looking up, and killing processes. It provides a broader API for process management compared to find-process, including the ability to kill processes.

pidusage

pidusage is another package that provides information about running processes, such as CPU and memory usage statistics. While it focuses more on performance metrics rather than just finding processes, it serves a complementary role to find-process.