feat: add commandHandler to action callback and add ts section to readme

hongaar · Jul 7, 2020 · 2c34c21 · 2c34c21
1 parent 5e7f986
commit 2c34c21
Show file tree

Hide file tree

Showing 3 changed files with 76 additions and 38 deletions.
diff --git a/README.md b/README.md
@@ -25,40 +25,42 @@ intuitive to work with.
 
 ## Table of contents
 
-<!-- START doctoc generated TOC please keep comment here to allow auto update -->
-<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
-
-- [Getting started](#getting-started)
-  - [Installation](#installation)
-  - [Simple example](#simple-example)
-  - [REPL example](#repl-example)
-  - [Prompt](#prompt)
-- [API](#api)
-  - [`program(options)`](#programoptions)
-    - [`program.description(description)`](#programdescriptiondescription)
-    - [`program.prompt(prompt)`](#programpromptprompt)
-    - [`program.add(command)`](#programaddcommand)
-    - [`program.default(command)`](#programdefaultcommand)
-    - [`program.run(command)`](#programruncommand)
-    - [`program.repl()`](#programrepl)
-    - [`program.runOrRepl()`](#programrunorrepl)
-    - [`program.isRepl()`](#programisrepl)
-    - [`program.on(event, listener)`](#programonevent-listener)
-  - [`command(name, options)`](#commandname-options)
-    - [`command.argument(name, options)`](#commandargumentname-options)
-    - [`command.option(name, options)`](#commandoptionname-options)
-    - [`command.command(command)`](#commandcommandcommand)
-    - [`command.default()`](#commanddefault)
-    - [`command.action(function)`](#commandactionfunction)
-- [Design principles](#design-principles)
-  - [Errors](#errors)
-  - [Output](#output)
-- [Bundle](#bundle)
-- [Todo](#todo)
-- [Contributing](#contributing)
-- [License](#license)
-
-<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+
+- [Getting started](#getting-started)
+  - [Installation](#installation)
+  - [Simple example](#simple-example)
+  - [REPL example](#repl-example)
+  - [Prompt](#prompt)
+  - [TypeScript](#typescript)
+- [API](#api)
+  - [`program(options)`](#programoptions)
+    - [`program.description(description)`](#programdescriptiondescription)
+    - [`program.prompt(prompt)`](#programpromptprompt)
+    - [`program.add(command)`](#programaddcommand)
+    - [`program.default(command)`](#programdefaultcommand)
+    - [`program.run(command)`](#programruncommand)
+    - [`program.repl()`](#programrepl)
+    - [`program.runOrRepl()`](#programrunorrepl)
+    - [`program.isRepl()`](#programisrepl)
+    - [`program.on(event, listener)`](#programonevent-listener)
+  - [`command(name, options)`](#commandname-options)
+    - [`command.argument(name, options)`](#commandargumentname-options)
+    - [`command.option(name, options)`](#commandoptionname-options)
+    - [`command.command(command)`](#commandcommandcommand)
+    - [`command.default()`](#commanddefault)
+    - [`command.action(function)`](#commandactionfunction)
+- [Design principles](#design-principles)
+  - [Errors](#errors)
+  - [Output](#output)
+- [Bundle](#bundle)
+- [Todo](#todo)
+- [Contributing](#contributing)
+- [License](#license)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
 ## Getting started
 
@@ -257,6 +259,42 @@ it was still being prompted. This is a known issue. In this case, the default
 value was the same as the input, in which case bandersnatch doesn't know whether
 a value was explicitly passed in or inherited from the default value.
 
+### TypeScript
+
+Bandersnatch works perfectly well with non-TypeScript codebases. However, when
+you do use TypeScript the command arguments are fully typed.
+
+Let's slightly improve the example program above to illustrate this:
+
+```diff
+   .option('size', {
+     description: 'Choose pizza size',
+-    choices: ['small', 'medium', 'large'],
++    choices: ['small', 'medium', 'large'] as const,
+     default: 'medium',
+     prompt: true,
+   })
+   .option('toppings', {
+     description: 'Pick some toppings',
+-    choices: ['mozzarella', 'pepperoni', 'veggies'],
++    choices: ['mozzarella', 'pepperoni', 'veggies'] as const,
+     default: ['mozzarella'],
+     prompt: true,
+   })
+```
+
+The first argument passed to the action handler function is now typed like this:
+
+```ts
+type Args = {
+  address: string
+  name: string
+  size: 'small' | 'medium' | 'large'
+  toppings: ('mozzarella' | 'pepperoni' | 'veggies')[]
+  confirmed: boolean
+}
+```
+
 ---
 
 ℹ More examples in the

diff --git a/examples/pizza.ts b/examples/pizza.ts
@@ -11,13 +11,13 @@ const cmd = command()
   })
   .option('size', {
     description: 'Choose pizza size',
-    choices: ['small', 'medium', 'large'],
+    choices: ['small', 'medium', 'large'] as const,
     default: 'medium',
     prompt: true,
   })
   .option('toppings', {
     description: 'Pick some toppings',
-    choices: ['mozzarella', 'pepperoni', 'veggies'],
+    choices: ['mozzarella', 'pepperoni', 'veggies'] as const,
     default: ['mozzarella'],
     prompt: true,
   })

diff --git a/src/command.ts b/src/command.ts
@@ -22,7 +22,7 @@ type CommandOptions = {
 type CommandRunner = (command: string) => Promise<unknown>
 
 export interface HandlerFn<T> {
-  (args: Omit<T, '_' | '$0'>): Promise<any> | any
+  (args: Omit<T, '_' | '$0'>, commandRunner: CommandRunner): Promise<any> | any
 }
 
 function isArgument(obj: Argument | Option | Command): obj is Argument {
@@ -258,7 +258,7 @@ export class Command<T = {}> {
 
       promise = promise.then((args) => {
         if (this.handler) {
-          return this.handler(args)
+          return this.handler(args, commandRunner)
         }
 
         // Display help this command contains sub-commands