-
Notifications
You must be signed in to change notification settings - Fork 88
Command Handlers
Command handlers "do the work". Handlers are where you place the logic for your command and produce the console output.
Suppose we have a command definition in our imperative configuration:
"definitions": [{
"name": "hello",
"description": "A sample command",
"type": "command",
"handler": "/path/to/handler",
}]
The handler, should be placed in directory /path/to/
with filename handler.ts
.
The handler
module must be a valid Node.js require()
-able module that uses export default
and implements the ICommandHandler interface:
export default class Handler implements ICommandHandler {
public async process(params: IHandlerParameters): Promise<void> {
params.response.console.log("Hello World!");
}
}
Imperative invokes the handler's process method with IHandlerParameters. See the interface for detailed typedoc.
In summary, the handler parameter object contains:
- arguments object (keyword value pairs that contain the values for the options specified by the user)
- command response APIs (for producing messages)
- Loaded profiles
- The command definition document
Suppose our command definition was formatted as such:
"definitions": [{
"name": "hello",
"description": "A sample command",
"type": "command",
"handler": "/path/to/handler",
"options": [{
"name": "my-opt",
"description": "My option",
"type": "string"
}]
}]
We can access the value of my-opt
in our handler through the arguments
object:
export default class Handler implements ICommandHandler {
public async process(params: IHandlerParameters): Promise<void> {
params.response.console.log(params.arguments.myOpt);
}
}
Notice that the option was transformed from kebab case to camel case. This is for programmer convenience, but the my-opt
property is also present on the arguments object:
{
"$0": "main.js",
"_": ["hello"],
"myOpt": "the value supplied by the user",
"my-opt": "the value supplied by the user"
}
If we look at our example handler:
export default class Handler implements ICommandHandler {
public async process(params: IHandlerParameters): Promise<void> {
params.response.console.log("Hello World!");
}
}
We can see a console log message being issued. In order for imperative to properly format/handle command responses, you must use the response API provided to the handler. Do NOT use console directly. The response API contains methods for printing log, error, headers, and more. See the IHandlerResponseApi interface for detailed typedoc.
Imperative will automatically append the --response-format-json
boolean option to every command. Users can specify this option to instruct imperative to produce the response in JSON format:
{
"success": true,
"message": "Some data is provided!",
"stdout": "",
"stderr": "",
"data": {
"moreData": "hello world!"
}
}
You can populate the data
and message
properties via the IHandlerResponseApi See the interface for detailed typedoc.
Handlers can create progress bars to display status/progress information to the user. For more information, see IHandlerProgressApi
.
See Implementing Progress Bars for details and examples of creating progress bars.
-
Core Features
- Imperative Configuration
- Defining Commands
- Command Handlers
- Command Option Precedence
- Environment Variables
- Help Generator
- Experimental Commands
- Creating Commands Using Chained Handlers
- Configuring Logging
- Working with Team Configuration
- Defining and Programming Profiles
- Managing Secure Properties
- Deprecated User Profiles
- Consuming REST APIs Using the REST Client
- Implementing Progress Bars
- Plugins