or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

ask.mdgetopt.mdindex.mdprogress-bar.mdread.mdreadLine.md
tile.json

tessl/npm-stdio

Standard input/output manager for Node.js with command-line parsing, async file reading, interactive terminal, and progress bars

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/stdio@2.1.x

To install, run

npx @tessl/cli install tessl/npm-stdio@2.1.0

index.mddocs/

stdio

stdio is a comprehensive standard input/output management library for Node.js applications, offering TypeScript-first development with promise-based APIs for terminal interactions. It provides command-line argument parsing, asynchronous file reading, interactive terminal capabilities, and visual progress bars.

Package Information

  • Package Name: stdio
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install stdio

Core Imports

import { getopt, read, readLine, ask, ProgressBar } from "stdio";

Default import:

import stdio from "stdio";
// Access as stdio.getopt, stdio.read, etc.

CommonJS:

const { getopt, read, readLine, ask, ProgressBar } = require("stdio");

Basic Usage

import { getopt, read, ask, ProgressBar } from "stdio";

// Parse command-line arguments
const options = getopt({
  verbose: { key: 'v', description: 'Verbose output' },
  output: { key: 'o', args: 1, description: 'Output file' }
});

// Read from stdin line by line
await read(async (line, index) => {
  console.log(`Line ${index}: ${line}`);
});

// Ask interactive questions
const name = await ask("What's your name?");
const choice = await ask("Choose option", { options: ['yes', 'no'] });

// Show progress bars
const progress = new ProgressBar(100);
progress.tick(); // Increment by 1
progress.setValue(50); // Set to 50%

Architecture

stdio is built around five core modules:

  • Command Line Parsing: UNIX-like getopt implementation with automatic help generation
  • Stream Processing: Asynchronous line-by-line reading without memory concerns
  • Terminal Interaction: Single-line reading and interactive question prompts
  • Visual Feedback: Configurable progress bars with ETA calculations
  • Promise-based API: All operations return promises for modern async/await workflows

Capabilities

Command Line Argument Parsing

UNIX-like command-line argument parser with automatic help generation and comprehensive configuration options.

function getopt(
  config: Config,
  command?: string[],
  options?: Options
): GetoptResponse | null;

interface Config {
  [key: string]: {
    key?: string;
    description?: string;
    multiple?: boolean;
    args?: number | string;
    required?: boolean;
    default?: string | string[] | boolean;
  } | boolean | undefined;
}

interface GetoptResponse {
  [key: string]: string | number | boolean | Array<string | number | boolean>;
}

Command Line Parsing

Asynchronous File Reading

Line-by-line processing of standard input or large files without memory concerns, with processing statistics.

function read(
  lineHandler: LineHandler,
  input?: NodeJS.ReadableStream
): Promise<Stats>;

type LineHandler = (line: string, index: number) => Promise<any>;

File Reading

Single Line Input

Read individual lines from standard input with stream management and automatic cleanup.

function readLine(options?: ReadLineOptions): Promise<string>;

interface ReadLineOptions {
  stream?: NodeJS.ReadableStream;
  close?: boolean;
}

Line Reading

Interactive Terminal Questions

Ask questions in terminal with option validation and retry mechanisms.

function ask(question: string, config?: AskConfig): Promise<string>;

interface AskConfig {
  options?: string[];
  maxRetries?: number;
  inputStream?: any;
}

Interactive Questions

Progress Bars

Visual command-line progress bars with automatic time calculations and customizable display.

class ProgressBar {
  constructor(
    size?: number,
    options?: {
      tickSize?: number;
      silent?: boolean;
      terminalWidth?: number;
    }
  );
  
  setValue(value: number): string;
  tick(): string;
  onFinish(callback: Function): void;
}

Progress Bars

Types

Core types used across multiple capabilities:

// Common option types
interface Options {
  exitOnFailure?: boolean;
  throwOnFailure?: boolean;
  printOnFailure?: boolean;
}

// Statistics tracking
interface Stats {
  length: number;
  times: number[];
  timeAverage: number;
}