bun-promptx

The createSelection function creates a terminal single-selection list prompt. It supports keyboard navigation (arrow keys, page up/down) and allows for custom rendering.

It accepts an array of objects containing text and description fields, along with an options object. The options object can include:

• headerText: A string displayed at the top of the prompt.
• perPage: The number of items to show per page.
• footerText: A string displayed at the bottom of the prompt.

Returns an object containing selectedIndex (the index of the chosen item) and error.

import { createSelection } from 'bun-promptx'

const result = createSelection([
  { text: 'feat', description: 'Introducing new features' },
  { text: 'fix', description: 'Bug fix' },
  { text: 'docs', description: 'Writing docs' },
  { text: 'style', description: 'Improving structure/format of the code' },
  { text: 'refactor', description: 'Refactoring code' },
  { text: 'test', description: 'Refactoring code' },
  { text: 'chore', description: 'When adding missing tests' },
  { text: 'perf', description: 'Improving performance'
}], {
  headerText: 'Select Commit Type: ',
  perPage: 5,
  footerText: 'Footer here'
})

console.log(result)
// { selectedIndex: 2, error: null }

Use createSelection to display an interactive selection menu in the terminal. You provide an array of SelectionItem objects and an optional SelectionOptions configuration. The function returns a SelectionReturn object containing either the selectedIndex of the chosen item or an error string if the operation failed.

Types

SelectionItem

An object representing an entry in the list:

• text: (string) The primary text displayed for the item.
• description: (string, optional) Additional information displayed for the item.

SelectionOptions

Configuration for the prompt UI:

• perPage: (number, optional) The number of items to show at once. Defaults to 5.
• headerText: (string, optional) Text displayed at the top of the prompt. Defaults to 'Select an item: '.
• footerText: (string, optional) Text displayed at the bottom of the prompt. Defaults to ''.

SelectionReturn

The result of the prompt:

• selectedIndex: (number | null) The index of the selected item in the original array, or null if no selection was made or an error occurred.
• error: (string | null) An error message if the selection failed, otherwise null.

import { createSelection } from 'promptx';

const items = [
  { text: 'Option 1', description: 'First choice' },
  { text: 'Option 2', description: 'Second choice' },
  { text: 'Option 3' }
];

const result = createSelection(items, {
  headerText: 'Please choose:',
  perPage: 3
});

if (result.error) {
  console.error('Error:', result.error);
} else if (result.selectedIndex !== null) {
  console.log('Selected index:', result.selectedIndex);
  console.log('Selected item:', items[result.selectedIndex]);
}

When calling createPrompt, you can pass a PromptOptions object to customize the interaction:

• charLimit (number, optional): Limits the number of characters the user can input.
• required (boolean, optional): If true (default), the prompt will likely fail or retry if no input is provided. Defaults to true.
• echoMode ('normal' | 'password' | 'none', optional): Controls how input is displayed.
  • 'normal': Standard input visibility.
  • 'password': Masks input (useful for sensitive data).
  • 'none': No input is echoed to the terminal.
• validateOkPrefix (string, optional): A prefix used for successful validation messages.
• validateErrPrefix (string, optional): A prefix used for error messages during validation.

const options = {
  charLimit: 10,
  required: true,
  echoMode: 'password' as const,
  validateOkPrefix: 'OK: ',
  validateErrPrefix: 'ERROR: '
}

const result = createPrompt("Enter password: ", options)