/choicebrew

Primary LanguageTypeScript

Simple interactive menus using inquirer.

Version Downloads/week License

Geenee Template

📋 Why

The inquirer package is great for directed interactive sequences, but a CLI menu requires looping and maintaining some context. It's easy to end up with spaghetti code trying to handle nested submenus.

✅ What

A pair of functions and some types to organize your ts code.

  • A Choice is fundamentally a named ChoiceCallback (any function you'd like to execute when the user chooses it.)
  • a ChoiceGenerator takes in a context (any object you'd like) and returns a Choice.
  • menu() takes as a parameter your own ChoiceGenerator.
  • Every menu will automatically add a choice to exit the menu if you don't add it yourself. But you can override it yourself by offering a Choice with flow set to FlowType.back.

💡 Sample

See geenee for a sample CLI using choiceBrew.

🌀 API

General Constants and Commands

Functions

functions for working with menus

  • menu: takes a ChoiceGenerator and continuously prompts the user for choices until a choice with the FlowType BACK is selected. When a choice with FlowType BACK is selected, the menu exits. You can also call setFlow in the callback for a choice to set the FlowType to BACK dynamically, thereby exiting the menu after execution of the callback.
  • getValue: returns the value entered or selected by a user. This is useful in the callback for a ChoiceCallback
  • setFlow: sets the flow for a Choice to be a FlowType. Normally, this is only useful for setting flow to BACK in a ChoiceCallback. Doing that will result in the menu exiting after the ChoiceCallback executes. For instance, it will exit a submenu and return to the menu above.

Types

The following types and interfaces are exposed by choicebrew.

Constants

Interfaces and enums used with choicebrew menus

  • FlowType: Options for a flow in a Choice. Currently just BACK (exit the menu or submenu) and COMMAND (execute a command). Almost always you will want to set a Choice to COMMAND, because by default a BACK Choice is created for you automatically unless you override that with your own. But see the setFlow function, which allows you to dynamically change a flow to BACK inside of an executing ChoiceCallback.
  • SelectedInfo: specifying a selection. Consists of a FlowType enum value 'flow' and any 'value' assigned to the choice.
  • MenuAnswers: consists of simply 'selected', which is an instance of SelectedInfo.
  • SelectedInfo: specifying a selection. Consists of a FlowType enum value 'flow' and any 'value' assigned to the choice.
  • Choice: The information for a choice, including the 'flow' (a FlowType, almost always COMMAND), a 'name' string, and a number of options. You can assign the following inquirer fields for a choice: description, value, short version. Also, a callback function.

FunctionTypes

type declarations for the functions used in menus

  • ChoicesGenerator: a function that generates a set of choices for a given menu
  • ChoiceCallback: a function called when a menu option is chosen