{"id":20648691,"url":"https://github.com/webpod/ps","last_synced_at":"2025-04-16T18:52:08.545Z","repository":{"id":229845589,"uuid":"774499778","full_name":"webpod/ps","owner":"webpod","description":"A Node.js module for looking up running processes","archived":false,"fork":false,"pushed_at":"2025-04-01T10:54:41.000Z","size":369,"stargazers_count":12,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-01T11:34:16.009Z","etag":null,"topics":["nodejs","pid","ps","spawn"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/webpod.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-03-19T16:50:54.000Z","updated_at":"2025-04-01T10:54:45.000Z","dependencies_parsed_at":"2024-06-12T23:44:53.399Z","dependency_job_id":"0c7f44e3-8996-47a5-88d1-db75255019d2","html_url":"https://github.com/webpod/ps","commit_stats":null,"previous_names":["webpod/ps"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webpod%2Fps","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webpod%2Fps/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webpod%2Fps/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webpod%2Fps/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/webpod","download_url":"https://codeload.github.com/webpod/ps/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249266647,"owners_count":21240792,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["nodejs","pid","ps","spawn"],"created_at":"2024-11-16T17:09:59.492Z","updated_at":"2025-04-16T18:52:08.524Z","avatar_url":"https://github.com/webpod.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @webpod/ps\n\n\u003e A Node.js module for looking up running processes. Originated from [neekey/ps](https://github.com/neekey/ps), [UmbraEngineering/ps](https://github.com/UmbraEngineering/ps) and completely reforged.\n\n## Differences\n* [x] Rewritten in TypeScript\n* [x] CJS and ESM package entry points\n* [x] `table-parser` replaced with `@webpod/ingrid` to handle some issues: [neekey/ps#76](https://github.com/neekey/ps/issues/76), [neekey/ps#62](https://github.com/neekey/ps/issues/62), [neekey/table-parser#11](https://github.com/neekey/table-parser/issues/11), [neekey/table-parser#18](https://github.com/neekey/table-parser/issues/18)\n* [x] Provides promisified responses\n* [x] Brings sync API\n* [x] Builds a process tree\n\n## Install\n```bash\n$ npm install @webpod/ps\n```\n\n## Internals\nThis module invokes different tools to get process list:\n\n* `ps` for unix/mac: `ps -lx`\n* [`wmic` for win runtimes](https://learn.microsoft.com/en-us/windows/win32/wmisdk/wmic): `wmic process get ProcessId,CommandLine`.\n\n## Usage\n\n### lookup()\nSearches for the process by the specified `pid`.\n```ts\nimport {lookup} from '@webpod/ps'\n\n// Both callback and promise styles are supported\nconst list = await lookup({pid: 12345})\n\n// or\nlookup({pid: 12345}, (err, list) =\u003e {\n  if (err) {\n    throw new Error(err)\n  }\n\n  const [found] = list\n  if (found) {\n    console.log('PID: %s, COMMAND: %s, ARGUMENTS: %s', found.pid, found.command, found.arguments)\n  } else {\n    console.log('No such process found!')\n  }\n})\n\n// or syncronously\nconst _list = lookup.sync({pid: 12345})\n```\n\nDefine a query opts to filter the results by `command` and/or `arguments` predicates:\n```ts\nconst list = await lookup({\n  command: 'node', // it will be used to build a regex \n  arguments: '--debug',\n})\n\nlist.forEach(entry =\u003e {\n  console.log('PID: %s, COMMAND: %s, ARGUMENTS: %s', entry.pid, entry.command, entry.arguments);\n})\n```\n\nUnix users can override the default `ps` arguments:\n```ts\nlookup({\n  command: 'node',\n  psargs: 'ux'\n}, (err, resultList) =\u003e {\n// ...\n})\n```\n\nSpecify the `ppid` option to filter the results by the parent process id (make sure that your custom `psargs` provides this output: `-l` or `-j` for instance)\n```ts\nlookup({\n  command: 'mongod',\n  psargs: '-l',\n  ppid: 82292\n}, (err, resultList) =\u003e {\n // ...\n})\n```\n\n### tree()\nReturns a child processes list by the specified parent `pid`. Some kind of shortcut for `lookup({ppid: pid})`.\n```ts\nimport { tree } from '@webpod/ps'\n\nconst children = await tree(123) \n/**\n[\n  {pid: 124, ppid: 123},\n  {pid: 125, ppid: 123}\n] \n*/\n```\n\nTo obtain all nested children, set `recursive` option to `true`:\n```ts\nconst children = await tree({pid: 123, recursive: true}) \n/**\n[\n  {pid: 124, ppid: 123},\n  {pid: 125, ppid: 123},\n\n  {pid: 126, ppid: 124},\n  {pid: 127, ppid: 124},\n  {pid: 128, ppid: 124},\n  \n  {pid: 129, ppid: 125},\n  {pid: 130, ppid: 125},\n] \n*/\n\n// or syncronously\nconst list = tree.sync({pid: 123, recursive: true}) \n```\n\n### kill()\nEliminates the process by its `pid`.\n\n```ts\nimport { kill } from '@webpod/ps'\n\nkill('12345', (err, pid) =\u003e {\n  if (err) {\n    throw new Error(err)\n  } else {\n    console.log('Process %s has been killed!', pid)\n  }\n})\n```\n\nMethod `kill` also supports a `signal` option to be passed. It's only a wrapper of `process.kill()` with checking of that killing is finished after the method is called.\n\n```ts\nimport { kill } from '@webpod/ps'\n\n// Pass signal SIGKILL for killing the process without allowing it to clean up\nkill('12345', 'SIGKILL', (err, pid) =\u003e {\n  if (err) {\n    throw new Error(err)\n  } else {\n    console.log('Process %s has been killed without a clean-up!', pid)\n  }\n})\n```\n\nYou can also use object notation to specify more opts:\n```ts\nkill( '12345', {\n  signal: 'SIGKILL',\n  timeout: 10,  // will set up a ten seconds timeout if the killing is not successful\n}, () =\u003e {})\n```\n\nNotice that the nodejs build-in `process.kill()` does not accept number as a signal, you will have to use string format.\n\n## License\n[MIT](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebpod%2Fps","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwebpod%2Fps","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebpod%2Fps/lists"}