pot-js


Process management module

!logger

Table of Contents

* pot-js
* Table of Contents
* Motivation
* Features
* Installing
* CLI Reference
* Node.js module API Reference
* [exec([options])](#execoptions) - Options
* Connection
* Operators
* Schemas
* Commands
* createCli(pkg, commands)
* License

Motivation

forever and pm2 are great third-party process management tools, but they are not module friendly. Saying if you are writing a CLI service tool, you may need to built-in a process management module for handling process monitor, run as a daemon, stop, scale, reload, and then you could just focus on developing your service logic. So I created this module.

Features

* Automatically restart process if it crashes. Like forever
* Able to scale or reload instances with zero down time. Like pm2
* Provides both CLI and Node.js module API
* Supports isolated workspaces
* User friendly interactive CLI
* Easy to extend
* Built-in powerful logger system

Installing

``bash
$ npm install pot-js
`

For global CLI command, please add -g option

`bash
$ npm install -g pot-js
`

CLI Reference

`bash
pot [options]

Commands:
pot start [entry] Spawn and monitor a process
pot restart [name] Restart a process
pot restartall Restart all processes
pot reload [name] Reload a process
pot reloadall Reload all processes
pot stop [name] Stop a process
pot stopall Stop all processes
pot scale [name] [instances] Scale up/down a process
pot list List processes [aliases: ls]
pot log [name] [category] Show log
pot show [name] Show process information
pot flush [name] Remove log files
pot flushall Remove all log files

Options:
--version Show version number [boolean]
-h, --help Show help [boolean]
`

Node.js module API Reference

$3

Spawn and monitor a process.

###### Options

* args (String|String[]): List of string arguments. Defaults to [].
* baseDir (String): The base directory for resolving modules or directories. Defaults to the current working directory.
* cluster (Boolean): Enforce using cluster mode. If not set, it will automatically set to true when spawning a Node.js related process.
* config (String): Path to the config file. Defaults to .potrc.
* cwd (String): Current working directory. Defaults to process.cwd().
* daemon (Boolean): Run as a daemon. Defaults to false.
* entry (String): Entry script path. Defaults to ./index.js.
* env (Object): Environment variables object. Defaults to process.env.
* events (Object): Defining scripts by event hooks. Like scripts in package.json. Here are available event hooks:
* spawn: New child process has been spawned
* start: The monitor has started
* stop: The monitor has fully stopped and the process is killed
* crash: The monitor has crashed (too many restarts or spawn error)
* sleep: The monitor is sleeping
* exit: Child process has exited
* stdout: Child process stdout has emitted data
* stderr: Child process stderr has emitted data
* warn: Child process has emitted an error
* execArgs (String|String[]): Execution arguments. Defaults to [].
* execPath (String): Execution Path. Defaults to process.execPath, which returns the absolute pathname of the executable that started the Node.js process. i.e. /usr/local/bin/node.
* force (Boolean): Enforce restart even if the process is exists. Defaults to false.
* inspect (Boolean|String|Object): Enable node inspector. Require Node.js >= v6.3.0. Defaults to false.
* instances (Number): Cluster instances. Defaults to 1.
* logLevel (String|Object): Log level. See pot-logger for detail. Here are available levels:
* ALL
* TRACE
* DEBUG (default in development mode)
* INFO (default in production mode)
* WARN
* ERROR
* FATAL
* OFF
* logsDir (String): Log files directory. In daemon mode, log messages will write to some .log files.
* maxRestarts (Number): How many restarts are allowed within 60s.
* monitorProcessTitle (String): Monitor process title. Defaults to "node".
* name (String): Process monitor name. Should be unique. Defaults to the basename of baseDir.
* production (Boolean): Production mode. Short hand for setting NODE_ENV="production" env. Defaults to true.
* watch (Boolean|Object): Enable watch mode. Defaults to false. Here are available props for object config:
* enable (Boolean): Enable watch. Defaults to true.
* dirs (String|String[]): Defining watching directories.
ignoreDotFiles (Boolean): Ignore watching . files. Defaults to true.
* ignoreNodeModulesDir (Boolean): Ignore watching node_modules directory. Defaults to true.
* workspace (String): Workspace.

---

$3

API to communicate with monitors

_(TODO)_

* Connection.getNames(options)
* Connection.getByName(name, options)
* Connection.getState(name, options)
* Connection.getAllInstances(options)
* Connection.flushOffline()
* connection#getState(instanceId)
* connection#restart()
* connection#reload(options)
* connection#scale(number)
* connection#flush()
* connection#disconnect()
* connection#requestStopServer(options)

---

$3

Command lines interface helper functions

_(TODO)_

* Operators.start(options)
* Operators.restart(options)
* Operators.restartAll(options)
* Operators.reload(options)
* Operators.reloadAll(options)
* Operators.stop(options)
* Operators.stopAll(options)
* Operators.scale(options)
* Operators.list(options)
* Operators.show(options)
* Operators.log(options)
* Operators.flush(options)
* Operators.flushAll(options)

---

$3

Config and CLI json schemas

_(TODO)_

---

$3

pot-js commands descriptor. Useful to extend or modify command via createCli()

A command may contain these props:

* command (String): A string representing the command. eg: stop [name]
* description (String): Command description
* schema (Object): The JSON schema of options and positional arguments
* operator` (Function): The operator function of the command

_(TODO)_

---

$3

A helper function to create CLI, built on top of yargs

_(TODO)_

---

License

MIT