0
# stdio
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: stdio
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install stdio`
10

11
## Core Imports
12

13
```typescript
14
import { getopt, read, readLine, ask, ProgressBar } from "stdio";
15
```
16

17
Default import:
18

19
```typescript
20
import stdio from "stdio";
21
// Access as stdio.getopt, stdio.read, etc.
22
```
23

24
CommonJS:
25

26
```javascript
27
const { getopt, read, readLine, ask, ProgressBar } = require("stdio");
28
```
29

30
## Basic Usage
31

32
```typescript
33
import { getopt, read, ask, ProgressBar } from "stdio";
34

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

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

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

50
// Show progress bars
51
const progress = new ProgressBar(100);
52
progress.tick(); // Increment by 1
53
progress.setValue(50); // Set to 50%
54
```
55

56
## Architecture
57

58
stdio is built around five core modules:
59

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

66
## Capabilities
67

68
### Command Line Argument Parsing
69

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

72
```typescript { .api }
73
function getopt(
74
  config: Config,
75
  command?: string[],
76
  options?: Options
77
): GetoptResponse | null;
78

79
interface Config {
80
  [key: string]: {
81
    key?: string;
82
    description?: string;
83
    multiple?: boolean;
84
    args?: number | string;
85
    required?: boolean;
86
    default?: string | string[] | boolean;
87
  } | boolean | undefined;
88
}
89

90
interface GetoptResponse {
91
  [key: string]: string | number | boolean | Array<string | number | boolean>;
92
}
93
```
94

95
[Command Line Parsing](./getopt.md)
96

97
### Asynchronous File Reading
98

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

101
```typescript { .api }
102
function read(
103
  lineHandler: LineHandler,
104
  input?: NodeJS.ReadableStream
105
): Promise<Stats>;
106

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

110
[File Reading](./read.md)
111

112
### Single Line Input
113

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

116
```typescript { .api }
117
function readLine(options?: ReadLineOptions): Promise<string>;
118

119
interface ReadLineOptions {
120
  stream?: NodeJS.ReadableStream;
121
  close?: boolean;
122
}
123
```
124

125
[Line Reading](./readLine.md)
126

127
### Interactive Terminal Questions
128

129
Ask questions in terminal with option validation and retry mechanisms.
130

131
```typescript { .api }
132
function ask(question: string, config?: AskConfig): Promise<string>;
133

134
interface AskConfig {
135
  options?: string[];
136
  maxRetries?: number;
137
  inputStream?: any;
138
}
139
```
140

141
[Interactive Questions](./ask.md)
142

143
### Progress Bars
144

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

147
```typescript { .api }
148
class ProgressBar {
149
  constructor(
150
    size?: number,
151
    options?: {
152
      tickSize?: number;
153
      silent?: boolean;
154
      terminalWidth?: number;
155
    }
156
  );
157
  
158
  setValue(value: number): string;
159
  tick(): string;
160
  onFinish(callback: Function): void;
161
}
162
```
163

164
[Progress Bars](./progress-bar.md)
165

166
## Types
167

168
Core types used across multiple capabilities:
169

170
```typescript { .api }
171
// Common option types
172
interface Options {
173
  exitOnFailure?: boolean;
174
  throwOnFailure?: boolean;
175
  printOnFailure?: boolean;
176
}
177

178
// Statistics tracking
179
interface Stats {
180
  length: number;
181
  times: number[];
182
  timeAverage: number;
183
}
184
```