HyperFrontend
@hyperfrontend/questionsView on npm →API Reference →

@hyperfrontend/questions

Terminal prompting library with composable, functional API for text, select, confirm, and multiselect prompts

What is @hyperfrontend/questions?

A terminal prompting library built on functional programming principles. Create interactive CLI experiences with composable, type-safe prompts that return structured outcomes.

Key Features

  • Pure Functions — Every prompt is a pure function returning Promise<PromptOutcome<T>>, making results predictable and easily testable
  • Composable API — Build complex interactive flows by combining simple prompt functions
  • Type-Safe — Full TypeScript support with discriminated unions for prompt outcomes
  • Zero External Dependencies — Uses only Node.js built-ins and @hyperfrontend utilities
  • Searchable Multiselect — Type-to-filter functionality for large option lists

Architecture Highlights

Each prompt follows a functional state machine pattern:

  • Immutable State — All prompt state is frozen; updates create new state objects
  • Explicit Outcomes — Prompts return either { result: 'submitted', value: T } or { result: 'cancelled', value: undefined }
  • Terminal Abstraction — Low-level I/O is encapsulated in a Terminal interface for testability

Why Use @hyperfrontend/questions?

When building CLI tools, you need interactive prompts that are:

  1. Predictable — Know exactly what a prompt returns, always
  2. Composable — Chain prompts without callback hell
  3. Cancellable — Handle Ctrl+C gracefully with structured cancellation
  4. Lightweight — No large dependency trees for simple prompts

This library provides all four while staying true to functional programming principles.

Installation

npm install @hyperfrontend/questions

Quick Start

import { text, confirm, select, multiselect, PromptResult } from '@hyperfrontend/questions'

// Text input
const nameResult = await text({
  message: 'What is your name?',
  validate: (value) => (value.length < 2 ? 'Name too short' : undefined),
})

if (nameResult.result === PromptResult.Submitted) {
  console.log(`Hello, ${nameResult.value}!`)
}

// Confirmation
const continueResult = await confirm({
  message: 'Continue?',
  initial: true,
})

// Single select
const colorResult = await select({
  message: 'Pick a color:',
  choices: [
    { label: 'Red', value: 'red' },
    { label: 'Green', value: 'green', hint: 'recommended' },
    { label: 'Blue', value: 'blue' },
  ],
})

// Multiselect with search
const featuresResult = await multiselect({
  message: 'Select features:',
  choices: [
    { label: 'TypeScript', value: 'ts' },
    { label: 'ESLint', value: 'eslint' },
    { label: 'Prettier', value: 'prettier' },
  ],
  searchable: true,
  min: 1,
})

API Overview

Function Description
text Free-form text input with optional validation
confirm Yes/no confirmation prompt
select Single selection from a list of choices
multiselect Multiple selections with optional search
PromptResult Discriminated union: 'submitted' | 'cancelled'

All prompts return Promise<PromptOutcome<T>> where:

type PromptOutcome<T> = { result: 'submitted'; value: T } | { result: 'cancelled'; value: undefined }

Compatibility

Environment Supported
Node.js >= 18 ✅
TTY Terminal ✅
Tree Shakeable ✅

License

MIT

API Reference§

Filter:

ƒFunctions

§function

confirm(config: ConfirmConfig): Promise<PromptOutcome<boolean>>

Prompts for yes/no confirmation.
Pure functional prompt that asks a yes/no question and returns a boolean. Supports default values and responds to y/Y/n/N keys.

Parameters

NameTypeDescription
§config
ConfirmConfig
Confirm prompt configuration

Returns

Promise<PromptOutcome<boolean>>
Promise resolving to boolean value or cancellation

Examples

Basic confirmation

const outcome = await confirm({ message: 'Continue?' })
if (outcome.result === 'submitted' && outcome.value) {
  console.log('Proceeding...')
}

With default value

const outcome = await confirm({
  message: 'Enable feature?',
  initial: true, // Default to yes
})
§function

multiselect<T>(config: MultiselectConfig<T>): Promise<PromptOutcome<unknown>>

Prompts for multiple selections from a list of choices.
Pure functional prompt with arrow key navigation, space to toggle, scrolling support, min/max constraints, and optional type-to-filter search.

Parameters

NameTypeDescription
§config
MultiselectConfig<T>
Multiselect prompt configuration

Returns

Promise<PromptOutcome<unknown>>
Promise resolving to array of selected values or cancellation

Examples

Basic multiselect

const outcome = await multiselect({
  message: 'Select toppings:',
  choices: [
    { label: 'Cheese', value: 'cheese' },
    { label: 'Pepperoni', value: 'pepperoni' },
    { label: 'Mushrooms', value: 'mushrooms' },
  ],
})
if (outcome.result === 'submitted') {
  console.log(`You selected: ${outcome.value.join(', ')}`)
}

With search and constraints

const outcome = await multiselect({
  message: 'Select features:',
  choices: features.map((f) => ({ label: f.name, value: f.id })),
  searchable: true,
  min: 1,
  max: 5,
})

Pre-selected values

const outcome = await multiselect({
  message: 'Select permissions:',
  choices: permissions,
  initial: [0, 2], // First and third choices pre-selected
})
§function

select<T>(config: SelectConfig<T>): Promise<PromptOutcome<T>>

Prompts for single selection from a list of choices.
Pure functional prompt with arrow key navigation, scrolling support, and optional disabled choices.

Parameters

NameTypeDescription
§config
SelectConfig<T>
Select prompt configuration

Returns

Promise<PromptOutcome<T>>
Promise resolving to selected value or cancellation

Examples

Basic select

const outcome = await select({
  message: 'Choose a color:',
  choices: [
    { label: 'Red', value: 'red' },
    { label: 'Green', value: 'green' },
    { label: 'Blue', value: 'blue' },
  ],
})
if (outcome.result === 'submitted') {
  console.log(`You chose: ${outcome.value}`)
}

With hints and disabled options

const outcome = await select({
  message: 'Select plan:',
  choices: [
    { label: 'Free', value: 'free', hint: '$0/month' },
    { label: 'Pro', value: 'pro', hint: '$10/month' },
    { label: 'Enterprise', value: 'enterprise', disabled: true },
  ],
  initial: 1, // Start on Pro
})
§function

text(config: TextConfig): Promise<PromptOutcome<string>>

Prompts for text input with optional validation.
Pure functional prompt that reads text from the user with support for default values, input validation, and display formatting.

Parameters

NameTypeDescription
§config
TextConfig
Text prompt configuration

Returns

Promise<PromptOutcome<string>>
Promise resolving to submitted value or cancellation

Examples

Basic text input

const outcome = await text({ message: 'What is your name?' })
if (outcome.result === 'submitted') {
  console.log(`Hello, ${outcome.value}!`)
}

With validation

const outcome = await text({
  message: 'Enter email:',
  validate: (value) => {
    if (!value.includes('@')) return 'Must be a valid email'
    return undefined
  },
})

Password input with masking

const outcome = await text({
  message: 'Password:',
  format: (value) => '*'.repeat(value.length),
})

◈Interfaces

§interface

Choice

Choice item for select/multiselect prompts.

Properties

§readonly disabled?:boolean—
Whether this choice is disabled
§readonly hint?:string—
Optional hint text shown after label
§readonly label:string—
Display label
§readonly value:T—
Value returned when selected
§interface

ConfirmConfig

Configuration for confirmation prompts.

Properties

§readonly initial?:boolean—
Default value if user just presses enter
§readonly input?:ReadStream—
Stream to read input from (defaults to stdin)
§readonly message:string—
The question message to display
§readonly output?:WriteStream—
Stream to write output to (defaults to stdout)
§interface

MultiselectConfig

Configuration for multi-select prompts.

Properties

§readonly choices:unknown—
Available choices
§readonly initial?:unknown—
Indices of initially selected choices
§readonly input?:ReadStream—
Stream to read input from (defaults to stdin)
§readonly max?:number—
Maximum allowed selections
§readonly maxVisible?:number—
Maximum number of visible choices (enables scrolling)
§readonly message:string—
The question message to display
§readonly min?:number—
Minimum required selections
§readonly output?:WriteStream—
Stream to write output to (defaults to stdout)
§readonly searchable?:boolean—
Enable type-to-filter
§interface

PromptCancelledOutcome

Outcome when user cancels the prompt.

Properties

§readonly result:"cancelled"—
Cancellation result indicator
§readonly value:undefined—
No value on cancellation
§interface

PromptConfig

Base configuration shared by all prompts.

Properties

§readonly input?:ReadStream—
Stream to read input from (defaults to stdin)
§readonly message:string—
The question message to display
§readonly output?:WriteStream—
Stream to write output to (defaults to stdout)
§interface

PromptSubmittedOutcome

Outcome when user submits a value.

Properties

§readonly result:"submitted"—
Submission result indicator
§readonly value:T—
The submitted value
§interface

SelectConfig

Configuration for single-select prompts.

Properties

§readonly choices:unknown—
Available choices
§readonly initial?:number—
Index of initially selected choice
§readonly input?:ReadStream—
Stream to read input from (defaults to stdin)
§readonly maxVisible?:number—
Maximum number of visible choices (enables scrolling)
§readonly message:string—
The question message to display
§readonly output?:WriteStream—
Stream to write output to (defaults to stdout)
§interface

TextConfig

Configuration for text input prompts.

Properties

§readonly format?:(value: string) => string—
Transform display of input (e.g., for password masking)
§readonly initial?:string—
Default value if user submits empty input
§readonly input?:ReadStream—
Stream to read input from (defaults to stdin)
§readonly message:string—
The question message to display
§readonly output?:WriteStream—
Stream to write output to (defaults to stdout)
§readonly validate?:(value: string) => string—
Validator function - return error message string to reject, undefined to accept

◆Types

§type

PromptFunction

A prompt function that asks a question and returns a value.
type PromptFunction = (config: TConfig) => Promise<PromptOutcome<TValue>>
§type

PromptOutcome

Outcome of a prompt interaction.
type PromptOutcome = PromptSubmittedOutcome<T> | PromptCancelledOutcome
§type

PromptResult

Result state of a prompt interaction.
type PromptResult = indexedAccess

●Variables

constPromptResult
Type: Readonly
Value: ...

Related

Getting Started

Learn how to set up hyperfrontend.

Architecture Guide

Understand how the libraries work together.