Question and Answer Library Integration

You are helping developers integrate the

question-and-answer

library into their Node.js projects. This library provides command-line question and answer functionality for building interactive CLI interrogations.

When to Use This Skill

Use this skill when the user wants to:

• Create interactive CLI questionnaires or wizards
• Build user onboarding flows
• Generate configuration files interactively
• Collect user input with validation
• Create surveys or forms in CLI applications
• Implement conditional question flows

Installation

npm install question-and-answer

Core Architecture

The library centers on the

Questioner

class, which processes an interrogation bundle - an array of actions that execute sequentially. Each action is one of four types:

1. Question - Prompts user for input and stores in a parameter
2. Statement - Displays text to the user
3. Map - Derives new parameters from existing ones using expressions
4. Review - Allows user to review and modify previous answers

Basic Implementation Pattern

import { Questioner } from 'question-and-answer'

const interactions = [
  // Array of action objects
]

const questioner = new Questioner({ interactions })
await questioner.question()

// Access results
const value = questioner.get('PARAMETER_NAME')

Action Types

Question Actions

Questions MUST have:

• prompt

  - The question text

• parameter

  - Variable name to store the answer

Questions MAY have:

• type

  - "boolean", "integer", "numeric", or "string" (default)

• default

  - Default value

• options

  - Array of choices (creates selection menu)

• multiValue

  - Boolean, allows multiple comma-separated answers

• separator

  - Custom separator for multiValue (default: comma)

• condition

  - Expression; skip if falsy

• validations

  - Object with validation rules

• noSkipDefined

  - Boolean, ask even if parameter already defined

{
  prompt: "What is your name?",
  parameter: "USER_NAME"
}

{
  prompt: "Choose a color",
  options: ["red", "blue", "green"],
  parameter: "COLOR"
}

{
  prompt: "Enable debug mode?",
  type: "boolean",
  parameter: "DEBUG",
  default: false
}

Statement Actions

Statements display text without user input:

{
  statement: "Welcome to the configuration wizard!"
}

{
  statement: "<warn>Warning:<rst> This will overwrite existing files",
  condition: "FILES_EXIST === true"
}

Map Actions

Maps derive new parameters from existing ones:

{
  maps: [
    {
      source: "AGE >= 18",
      parameter: "IS_ADULT",
      type: "boolean"
    },
    {
      source: "PRICE * QUANTITY",
      parameter: "TOTAL",
      type: "numeric"
    },
    {
      value: "literal-value",
      parameter: "CONSTANT"
    }
  ]
}

Maps use condition-eval syntax for

source

expressions.

Review Actions

Reviews let users verify and modify answers:

{
  review: "questions"  // Only review questions
}

{
  review: "maps"  // Only review maps
}

{
  review: "all"  // Review both
}

During review:

• Press ENTER to accept current value
• Enter new value to change
• Enter

  -

  to clear value
• If rejected, interrogation restarts

Validation

Use the

validations

object with specify-string format:

{
  prompt: "Enter email",
  parameter: "EMAIL",
  validations: {
    "match-regexp": "^[^@]+@[^@]+\\.[^@]+$"
  }
}

{
  prompt: "Rate 1-10",
  type: "integer",
  parameter: "RATING",
  validations: {
    "min-value": 1,
    "max-value": 10
  }
}

{
  prompt: "Select 2-3 options",
  multiValue: true,
  options: ["A", "B", "C", "D"],
  parameter: "CHOICES",
  validations: {
    "min-count": 2,
    "max-count": 3
  }
}

Common validation keys:

• min-length

  ,

  max-length

  - String length

• min-value

  ,

  max-value

  - Numeric range

• min-count

  ,

  max-count

  - Multi-value count

• require-exact

  - Exact match required

• require-truthy

  ,

  require-falsy

  - Boolean validation

• match-regexp

  - Regular expression pattern

Conditional Logic

Any action can have a

condition

field with an expression:

{
  prompt: "Enter API key",
  parameter: "API_KEY",
  condition: "ENVIRONMENT === 'production'"
}

{
  statement: "Debug mode is enabled",
  condition: "DEBUG === true"
}

Conditions use condition-eval syntax and can reference any previously set parameter.

Type System

The

type

field coerces answers:

• "boolean"

  or

  "bool"

  - Accepts: y/yes/true/n/no/false (case-insensitive)

• "integer"

  or

  "int"

  - Whole numbers only

• "numeric"

  or

  "float"

  - Decimal numbers

• "string"

  - Default, no coercion

Accessing Results

// Single value
const name = questioner.get('USER_NAME')

// Full result object (includes metadata)
const result = questioner.getResult('USER_NAME')

// Check existence
if (questioner.has('EMAIL')) { ... }

// All values as object
const values = questioner.values

// All results (with metadata)
const results = questioner.results

// Interrogation with dispositions
const interactions = questioner.interactions

Constructor Options

const questioner = new Questioner({
  interactions,              // Required: array of actions
  initialParameters: {},     // Optional: pre-populated values
  noSkipDefined: false,      // Optional: ask defined questions
  input: process.stdin,      // Optional: custom input stream
  output: customOutput,      // Optional: custom output handler
  printOptions: {}          // Optional: magic-print options
})

Implementation Guidelines

1. Start Simple

Begin with basic questions, add complexity incrementally:

const interactions = [
  { prompt: "Project name", parameter: "NAME" },
  { prompt: "Version", parameter: "VERSION", default: "1.0.0" }
]

2. Add Validation

Layer in validation for data quality:

{
  prompt: "Project name",
  parameter: "NAME",
  validations: {
    "min-length": 1,
    "max-length": 50,
    "match-regexp": "^[a-z0-9-]+$"
  }
}

3. Use Options for Fixed Choices

When answers are constrained, use

options

:

{
  prompt: "License",
  options: ["MIT", "Apache-2.0", "GPL-3.0", "ISC"],
  parameter: "LICENSE"
}

4. Add Conditional Logic

Build dynamic flows with conditions:

{
  prompt: "Use TypeScript?",
  type: "boolean",
  parameter: "USE_TS"
},
{
  prompt: "TypeScript version",
  parameter: "TS_VERSION",
  default: "latest",
  condition: "USE_TS === true"
}

5. Derive Computed Values

Use maps for calculated parameters:

{
  maps: [
    {
      source: "USE_TS === true",
      parameter: "FILE_EXTENSION",
      value: "ts"
    },
    {
      source: "USE_TS === false",
      parameter: "FILE_EXTENSION",
      value: "js"
    }
  ]
}

6. End with Review

Let users verify their answers:

{ review: "questions" }

Common Patterns

See

patterns.md

for detailed examples of:

• User onboarding flows
• Configuration wizards
• Surveys with validation
• Conditional branching
• Multi-value inputs

Testing Interrogations

Test bundles using the CLI:

npx qna path/to/interrogation.json

Important Notes

1. Action Order Matters - Actions execute sequentially; parameters must be defined before use in conditions/maps
2. Parameter Skipping - Questions/maps skip if parameter already defined (unless

   noSkipDefined: true

   )
3. Condition Evaluation - Uses condition-eval library; supports comparisons, arithmetic, logical operators
4. Type Safety - Always specify

   type

   for non-string data to ensure proper coercion
5. Review Behavior - Reviews collect all non-skipped questions/maps since last review
6. Validation Timing - Validations run immediately; invalid answers re-prompt

Reference Materials

When you need detailed information, refer to:

• reference.md

  - Complete API reference

• patterns.md

  - Common implementation patterns

• examples/

  - Working interrogation bundles

Code Generation

When generating interrogation bundles:

1. Wrap in proper structure:

   { "actions": [...] }

2. Use consistent parameter naming (UPPER_SNAKE_CASE recommended)
3. Add validations for data quality
4. Include review step for important flows
5. Test with

   npx qna bundle.json

   before integration

Error Handling

The library throws standard errors:

• ArgumentInvalidError

  - Validation failed

• ArgumentMissingError

  - Required field missing

• ArgumentTypeError

  - Type mismatch

Always wrap

questioner.question()

in try-catch for production use.