@hyperfrontend/questions§

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

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}!`)
}

// Text input with a live label; `renderMessage` is recomputed on every keystroke
import { style } from '@hyperfrontend/questions'

await text({
  message: 'Title:',
  renderMessage: (value) => {
    const left = 72 - value.length
    return `Title (${left >= 0 ? style.green(`${left} left`) : style.red(`${-left} over`)}):`
  },
})

// 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

Four prompts, one shape. text, confirm, select and multiselect each take a config object and resolve to the same discriminated union, so the code that reads an answer is the same code whichever question asked it:

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

Two things sit beside them. style is the ANSI colour helper the prompts use on their own labels, exposed so yours can match. And every config takes input and output streams, which is what makes a prompt testable without a TTY: hand it a pair of PassThroughs, write keystrokes into one and read frames out of the other.

Every config, option and outcome type is in the API reference.

Compatibility