{"id":43409995,"url":"https://github.com/cyqlelabs/pidman","last_synced_at":"2026-02-02T16:45:59.358Z","repository":{"id":40773230,"uuid":"259618213","full_name":"cyqlelabs/pidman","owner":"cyqlelabs","description":"A rock solid process orchestration library for Node","archived":false,"fork":false,"pushed_at":"2023-03-04T15:01:05.000Z","size":2036,"stargazers_count":4,"open_issues_count":13,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-11-02T10:05:21.809Z","etag":null,"topics":["child-process","childprocess","events","node","nodejs","processes","threading"],"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/cyqlelabs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2020-04-28T11:31:43.000Z","updated_at":"2025-02-06T20:34:29.000Z","dependencies_parsed_at":"2024-10-23T23:05:27.286Z","dependency_job_id":"a59245ba-434e-4bfc-ab3a-159adba0d77a","html_url":"https://github.com/cyqlelabs/pidman","commit_stats":{"total_commits":121,"total_committers":1,"mean_commits":121.0,"dds":0.0,"last_synced_commit":"bff8ee3230aaefcd5eed3f6394e6af683b9c755f"},"previous_names":["cyqlelabs/pidman","qalfy/pidman"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/cyqlelabs/pidman","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyqlelabs%2Fpidman","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyqlelabs%2Fpidman/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyqlelabs%2Fpidman/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyqlelabs%2Fpidman/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cyqlelabs","download_url":"https://codeload.github.com/cyqlelabs/pidman/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyqlelabs%2Fpidman/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29015384,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-02T16:17:30.374Z","status":"ssl_error","status_checked_at":"2026-02-02T15:58:50.469Z","response_time":58,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["child-process","childprocess","events","node","nodejs","processes","threading"],"created_at":"2026-02-02T16:45:58.259Z","updated_at":"2026-02-02T16:45:59.353Z","avatar_url":"https://github.com/cyqlelabs.png","language":"TypeScript","readme":"\u003ch1 align=\"center\"\u003eWelcome to Pidman 👋\u003c/h1\u003e\n\u003cp\u003e\n  \u003cimg alt=\"Version\" src=\"https://img.shields.io/badge/version-2.0.1-blue.svg?cacheSeconds=2592000\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/npm-%3E%3D5.8.0-blue.svg\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/node-%3E%3D9.3.0-blue.svg\" /\u003e\n  \u003ca href=\"https://pidman.qalfy.com\" target=\"_blank\"\u003e\n    \u003cimg alt=\"Documentation\" src=\"https://img.shields.io/badge/documentation-yes-brightgreen.svg\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"Copyright \u003cYEAR\u003e \u003cCOPYRIGHT HOLDER\u003e\" target=\"_blank\"\u003e\n    \u003cimg alt=\"License: MIT\" src=\"https://img.shields.io/badge/License-MIT-yellow.svg\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003e A rock solid process orchestration library for Node\n\n### 🏠 [Homepage](https://pidman.qalfy.com)\n\n## About\n\nPidman is a library designed to make external processes management an easy task.\n\nIt avoids the typical callback hell where you get into when using native API while at the same time enhances the default language functionality by allowing you to create groups of processes, monitor their activity and gives you the option to manage their statuses at any given time, whether there is data flowing, an error occurs or whenever the process closes or exits. If the later, you'll be provided with all the required information and metadata to help you react accordingly.\n\nGrouping a serie of external commands or programs is useful when they depend on each other. Obviously, you can run an individual process if you don't need to manage a group.\n\n### Goal\n\nThe goal of Pidman is to provide the most reliable process management tool without entering into dark territories. It has to remain simple to use and be easy to setup. In a matter of seconds, you should be able to orchestrate a series of programs or external commands while ensuring you won't loose their traces.\n\n### Persistence\n\nPidman stores your groups and processes' metadata using _Connectors_. Currently, there is a single connector called _MemoryConnector_ which can be persisted locally. You'll be always in sync with the processes that run over Pidman.\n\nThere are plans to add more connectors (NoSQL, MySQL, etc). Contributors are welcome.\n\n### Logging\n\nPidman offers a vast set of logging targets to keep you informed. Thanks to the use of [Winston transports](https://github.com/winstonjs/winston/blob/master/docs/transports.md#winston-core), the output of this library can be redirected to either console, Slack, MongoDB, Sentry, New Relic, a file, a stream and dozens of other popular destinations.\n\nJust include the preferred one when initializing the `Pidman` instance:\n\n```js\nconst SlackHook = require(\"winston-slack-webhook-transport\");\n\nconst pm = new Pidman({\n  logger: {\n    transport: new SlackHook({\n      webhookUrl: \"https://hooks.slack.com/services/xxx/xxx/xxx\",\n    }),\n  },\n});\n```\n\n### Thread Behavior\n\nPidman run processes in forked mode. This means, your program's event loop won't be locked. This is a pseudo-thread mechanism that allows running commands and programs on the background while you keep listening for any event that might arise during execution of these commands.\n\n### Daemons and Background Processes\n\nIf you run a command that spawns itself as a background process or daemon, Pidman will not be able to kill it properly. This is because the program will detach itself from its parent hence the new daemonized/background process will run unattached from the main Node's process running your code.\n\n## Prerequisites\n\n- npm \u003e=5.8.0\n- node \u003e=9.3.0\n\n## Install\n\n```sh\nnpm i pidman\n```\n\nor\n\n```sh\nyarn add pidman\n```\n\n### Typescript Setup\n\nIf you use Typescript, don't forget to target ES2015 or higher in your `tsconfig.json`:\n\n```json\n  \"compilerOptions\": {\n    ...\n    \"target\": [\"ES2015\"],\n    ...\n  }\n```\n\n## API / Documentation\n\nThere is a detailed [API Documentation](https://pidman.qalfy.com/).\n\n## Usage\n\nFor a quick hands-on usage explanation, check out the [basic demo](https://github.com/QAlfy/pidman/blob/master/basic.demo.js) and read the comments in there.\n\nFirst, instantiate the main Pidman's class:\n\n```js\nimport { Pidman } from \"pidman\";\n\nconst pm = new Pidman();\n```\n\nYou can optionally provide a [PidmanOptions](https://pidman.qalfy.com/interfaces/_core_pidman_.pidmanoptions.html) to the [Pidman](https://pidman.qalfy.com/classes/_core_pidman_.pidman.html) constructor. An example would be specifying a [logging transport](#Logging).\n\n### Group\n\nLet's start adding a [PidmanGroup](https://pidman.qalfy.com/classes/_core_group_.pidmangroup.html) which will contain one or more [PidmanProcess](https://pidman.qalfy.com/classes/_core_process_.pidmanprocess.html).\n\nA group simplifies the management of multiple commands and programs which relate to each other within a specific domain or context in your application. For example, if you need to run some maintenance commands when a user removes a document or triggers some action, then you can have a group do this job.\n\nA `PidmanGroup` accepts a [GroupOptions](https://pidman.qalfy.com/interfaces/_core_group_.groupoptions.html) as unique argument on construction. The meaning of these options are explained [here](https://pidman.qalfy.com/interfaces/_core_group_.groupoptions.html). You can choose to initialize the processes using the `processes` array in the options or by later using the [addProcess](https://pidman.qalfy.com/classes/_core_group_.pidmangroup.html#addprocess) method:\n\n```js\nimport { Pidman, PidmanGroup } from \"pidman\";\n\nconst pm = new Pidman();\nconst group = new PidmanGroup();\n\ngroup.addProcess({\n  path: \"/home/someuser\",\n  command: \"rm -rf ./docs\",\n});\n\npm.addProcessGroup(group);\n\npm.run();\n```\n\nThe only required property is `command`, otherwise nothing runs. You can see a description of the different options [here](https://pidman.qalfy.com/interfaces/_core_process_.processoptions.html). You can optionally identify this group using a unique `id` string or let Pidman choose a random one.\n\n### Process\n\nA [PidmanProcess](https://pidman.qalfy.com/classes/_core_process_.pidmanprocess.html) can be run inside a group or isolated. Although, you can join a process to any group whenever you need to. It's a flexible mechanism.\n\n```js\nimport { someEvent } from './events';\nimport { Pidman, PidmanGroup, PidmanProcess } from \"pidman\";\n\nconst pm = new Pidman();\nconst group = new PidmanGroup();\n\ngroup.addProcess({\n  path: \"/home/someuser\",\n  command: \"rm -rf ./docs\",\n});\n\npm.addProcessGroup(group);\n\nconst lockProcess = new PidmanProcess({\n  user: \"www\",\n  group: \"www\",\n  path: \"/var/www\",\n  command: \"touch\",\n  arguments: [\"lock\"],\n});\n\ngroup.addProcess(lockProcess);\n\nsomeEvent.on('doit', () =\u003e {\n  group.run();\n});\n\npm.run();\n```\n\n### Monitor Groups and Process\n\nYou can choose to monitor special events coming from a group's children processes or individually on each process. The callback signatures are detailed [here](https://pidman.qalfy.com/interfaces/_core_pidman_.pidmanmonitor.html):\n\n```js\nconst group = new PidmanGroup({\n  monitor: {\n    onData: (data) =\u003e {\n      // data.output is the process' stdout and stderr\n      console.log(data.output)\n    },\n    onClose: (event) =\u003e {\n      if (event.exitCode \u0026\u0026 event.exitCode !== 0) {\n        console.error('ouch! something is wrong: ');\n        console.error(event.process.output);\n      } else {\n        console.info(`process ${event.process.options.id} closed at ${event.time}`);\n      }\n    }\n  }\n});\n```\n\n### Kill 'Em All\n\nBy providing (**or not**) a valid [program termination signal](https://nodejs.org/api/process.html#process_signal_events), you can choose to kill all processes in a group at once or individually:\n\n```js\nconst killed = await group.kill();\n```\n\nor\n\n```js\nconst killed = await lockProcess.kill('SIGKILL');\n```\n\n## Author\n\n👤 **Nicolas Iglesias**\n\n- Website: https://pidman.qalfy.com\n- Github: [@webpolis](https://github.com/webpolis)\n\n## 🤝 Contributing\n\nContributions, issues and feature requests are welcome!\u003cbr /\u003eFeel free to check [issues page](https://github.com/QAlfy/pidman/issues).\n\n## Show your support\n\nGive a ⭐️ if this project helped you!\n\n## 📝 License\n\nCopyright © 2020 [Nicolas Iglesias](https://github.com/webpolis).\u003cbr /\u003e\nThis project is [MIT](https://github.com/QAlfy/pidman/blob/master/LICENSE) licensed.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcyqlelabs%2Fpidman","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcyqlelabs%2Fpidman","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcyqlelabs%2Fpidman/lists"}