Askzen

A lightweight, TypeScript-ready library for interactive command-line prompts in Node.js, with support for validation, passwords, and confirmations.

Features ✨

• 🔹 Simple API for interactive prompts.
• ✅ Input validation with custom rules.
• 🔒 Password prompts with hidden input.
• ✅ Yes/no confirmation prompts.
• 🌐 TypeScript-ready with strong typings.
• ⚡ Minimal dependencies, lightweight core.
• 🛠️ Flexible options for defaults and retries.

Installation 💿

pnpm add askzen
# or
npm install askzen
# or
yarn add askzen

Quick Start 🚀

import { ask, askConfirm, askNumber, askPassword } from 'askzen';

// Prompt for input
const name = await ask('Enter your name: ', { required: true });
console.log(`Hello, ${name}!`);

// Confirm action
const confirmed = await askConfirm('Proceed? (y/n): ');
console.log(confirmed ? 'Confirmed!' : 'Cancelled');

// Prompt for a number
const age = await askNumber('Enter your age: ', { required: true });
console.log(`Age: ${age}`);

// Prompt for a password
const password = await askPassword('Enter password: ');
console.log(`Password: ${password}`);

API

ask

Prompts the user for input with optional validation.

async function ask(
  message: string = '> ',
  options: AskOptions = {},
): Promise<string>;

• Parameters:
  • message: Prompt message (default: '> ').
  • options:
    • silent: Hides input (shows asterisks).
    • required: Requires non-empty input.
    • defaultValue: Fallback if input is empty.
    • validate: Validation function.
    • maxAttempts: Max retries for validation.
• Returns: User input or default value.
• Example:

  const name = await ask('Name: ', { required: true });

AskOptions

Options for ask function.

interface AskOptions {
  silent?: boolean;
  required?: boolean;
  defaultValue?: string;
  validate?: (input: string) => string | boolean | Promise<string | boolean>;
  maxAttempts?: number;
}

askConfirm

Prompts for yes/no confirmation.

async function askConfirm(
  message: string = 'Are you sure? (y/n): ',
  options: Omit<AskOptions, 'validate'> = {},
): Promise<boolean>;

• Parameters:
  • message: Prompt message (default: 'Are you sure? (y/n): ').
  • options: Options excluding validate.
• Returns: true for 'y'/'yes', false for 'n'/'no'.
• Example:

  const ok = await askConfirm('Delete? (y/n): ', { defaultValue: 'n' });

askNumber

Prompts for a numeric input.

async function askNumber(
  message: string = 'Enter a number: ',
  options: Omit<AskOptions, 'validate'> = {},
): Promise<number>;

• Parameters:
  • message: Prompt message (default: 'Enter a number: ').
  • options: Options excluding validate.
• Returns: Numeric value.
• Example:

  const age = await askNumber('Age: ', { required: true });

askPassword

Prompts for a password with hidden input.

async function askPassword(
  message: string = 'Password: ',
  options: Omit<AskOptions, 'silent'> = {},
): Promise<string>;

• Parameters:
  • message: Prompt message (default: 'Password: ').
  • options: Options excluding silent.
• Returns: Password as a string.
• Example:

  const pwd = await askPassword('Password: ', { required: true });

prompt

Low-level function for user input.

async function prompt(
  message: string = '> ',
  silent: boolean = false,
): Promise<string>;

• Parameters:
  • message: Prompt message (default: '> ').
  • silent: Hides input (shows asterisks).
• Returns: User input as a string.
• Example:

  const input = await prompt('Name: ');

Examples 📚

Validated Input

const email = await ask('Enter email: ', {
  required: true,
  validate: (input) => input.includes('@') || 'Invalid email',
  maxAttempts: 3,
});
console.log(`Email: ${email}`);

Confirmation Prompt

const proceed = await askConfirm('Continue? (y/n): ', { defaultValue: 'n' });
console.log(proceed ? 'Proceeding...' : 'Aborted');

Numeric Input

const quantity = await askNumber('Quantity: ', { required: true });
console.log(`Quantity: ${quantity}`);

Password Prompt

const password = await askPassword('Enter password: ', { required: true });
console.log(`Password entered: ${password}`);

Best Practices 📝

1. Use clear prompt messages for user clarity.
2. Set sensible defaults for optional inputs.
3. Validate inputs with validate or use askConfirm/askNumber.
4. Use required: true for critical inputs.
5. Limit maxAttempts for validation to prevent infinite loops.
6. Handle errors with try/catch and handleError.

License 📄

MIT License – see LICENSE. Author: Estarlin R (estarlincito.com)