npm package: @siener/visualizer
Description: terminal visualization
Author: Jason Sie
Latest version: 1.0.0

# Fibonacci Visualizer

Generate and visualize Fibonacci sequences in the terminal with both numeric values and curved line representation.

## Features

-  🔢 Generate mathematically correct Fibonacci sequences
-  📊 Visual curved line representation using asterisks (\*)
-  ✅ Input validation with clear error messages
-  ⚡ Fast performance (< 1 second for 50 numbers)
-  🎯 Zero dependencies (vanilla JavaScript)
-  📦 Can be used as CLI tool or Node.js module

## Installation

### Global Installation (Recommended for CLI use)

```bash
npm install -g @jasons/visualizer
```

### Local Installation (For programmatic use)

```bash
npm install @jasons/visualizer
```

## Usage

### Command Line Interface

Generate the first N Fibonacci numbers:

```bash
# Using global installation
fibonacci 10

# Or with Node.js directly
node visualizer.js 10
```

#### Example Output

```bash
$ fibonacci 8
F(0) = 0
F(1) = 1       ****
F(2) = 1       ****
F(3) = 2       *********
F(4) = 3       *************
F(5) = 5       ***********************
F(6) = 8       ************************************
F(7) = 13      ************************************************************
```

### Programmatic API

You can also use the Visualizer as a Node.js module:

```javascript
const Visualizer = require('@jasons/visualizer');

// Create instance
const viz = new Visualizer();

// Generate Fibonacci sequence
const sequence = viz.generate(10);
console.log(sequence);
// Output: [0, 1, 1, 2, 3, 5, 8, 13, 21, 34]

// Visualize the sequence
const output = viz.visualize(sequence);
console.log(output);
```

#### Step-by-Step Usage

```javascript
const Visualizer = require('@jasons/visualizer');
const viz = new Visualizer();

// 1. Validate input
const validation = viz.validate('10');
if (!validation.valid) {
   console.error(validation.error);
   process.exit(1);
}

// 2. Generate sequence
const sequence = viz.generate(validation.value);

// 3. Visualize
const output = viz.visualize(sequence);
console.log(output);
```

#### Custom Configuration

```javascript
const Visualizer = require('@jasons/visualizer');
const viz = new Visualizer();

// Customize display width (default: 60)
viz.maxDisplayWidth = 40;

// Customize curve character (default: '*')
viz.curveChar = '█';

const sequence = viz.generate(10);
const output = viz.visualize(sequence);
console.log(output);
```

## API Reference

### Constructor

#### `new Visualizer()`

Creates a new Visualizer instance with default configuration.

**Returns:** `Visualizer` instance

### Methods

#### `validate(input)`

Validates user input for Fibonacci sequence generation.

**Parameters:**

-  `input` (String|Number|undefined) - User-provided count value

**Returns:** `ValidationResult` object

```javascript
{
  valid: Boolean,      // true if valid, false otherwise
  value: Number | null, // parsed number or null
  error: String | null  // error message or null
}
```

**Example:**

```javascript
const result = viz.validate('10');
// → { valid: true, value: 10, error: null }
```

#### `generate(count)`

Generates a Fibonacci sequence of specified length.

**Parameters:**

-  `count` (Number) - Number of Fibonacci numbers to generate (must be positive)

**Returns:** `Array<Number>` - Fibonacci sequence starting from 0

**Example:**

```javascript
const sequence = viz.generate(5);
// → [0, 1, 1, 2, 3]
```

#### `visualize(sequence)`

Creates a visual representation of a Fibonacci sequence.

**Parameters:**

-  `sequence` (Array<Number>) - Array of Fibonacci numbers to visualize

**Returns:** `String` - Multi-line formatted visualization

**Example:**

```javascript
const output = viz.visualize([0, 1, 1, 2, 3]);
// Returns formatted string with asterisk visualization
```

#### `fibonacci(input)`

Main execution method that orchestrates validation, generation, and visualization.

**Parameters:**

-  `input` (String) - Command-line argument (count value)

**Returns:** `void` (outputs to console and may exit process)

**Example:**

```javascript
viz.fibonacci('10');
// Outputs visualization to console
```

### Properties

#### `maxDisplayWidth`

Maximum width for asterisk visualization (default: 60).

**Type:** `Number`

#### `curveChar`

Character used for visualization curve (default: '\*').

**Type:** `String`

## Input Validation

The tool validates all inputs and provides clear error messages:

| Input                        | Result                          |
| ---------------------------- | ------------------------------- |
| No input                     | Shows usage instructions        |
| Non-numeric (e.g., "abc")    | Error: Input must be a number   |
| Negative number (e.g., "-5") | Error: Must be positive integer |
| Zero                         | Error: Must be positive integer |
| Decimal (e.g., "5.5")        | Converted to integer (5)        |
| Large number (> 50)          | Warning but processes           |

## Examples

### Generate Different Counts

```bash
# Small sequence
$ fibonacci 3
F(0) = 0
F(1) = 1       ************************************************************
F(2) = 1       ************************************************************

# Medium sequence
$ fibonacci 10
[Output shows first 10 Fibonacci numbers with visualization]

# Edge case: single number
$ fibonacci 1
F(0) = 0
```

### Error Handling

```bash
# No input
$ fibonacci
Usage: node visualizer.js <count>
Example: node visualizer.js 10

# Invalid input
$ fibonacci abc
Error: Input must be a number

# Negative number
$ fibonacci -5
Error: Input must be a positive integer (greater than 0)
```

## Algorithm

The implementation uses an **iterative algorithm** for optimal performance:

-  **Time Complexity:** O(n)
-  **Space Complexity:** O(n)
-  **Performance:** Generates up to 50 numbers in < 100ms

Fibonacci sequence definition:

-  F(0) = 0
-  F(1) = 1
-  F(n) = F(n-1) + F(n-2) for n ≥ 2

## Testing

Run the test suite:

```bash
npm test
```

The test suite includes:

-  ✅ Input validation tests (8 test cases)
-  ✅ Fibonacci generation tests (6 test cases)
-  ✅ Visualization tests (5 test cases)
-  ✅ Integration tests (2 test cases)

**Total: 21 tests, 100% passing**

## Requirements

-  Node.js 18.0.0 or higher
-  No external dependencies

## Architecture

The implementation follows the **IIFE (Immediately Invoked Function Expression)** pattern with **prototype-based design**:

-  Single-file implementation (`visualizer.js`)
-  Namespace isolation via IIFE
-  Prototype methods for memory efficiency
-  Works as both CLI tool and importable module

## License

MIT

## Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass (`npm test`)
5. Submit a pull request

## Support

For issues, questions, or suggestions, please open an issue on GitHub.

## Changelog

### Version 1.0.0 (Initial Release)

-  ✅ Core Fibonacci generation
-  ✅ Terminal visualization with asterisks
-  ✅ Input validation with error messages
-  ✅ CLI and programmatic API
-  ✅ Comprehensive test suite
-  ✅ Zero dependencies

## Author

Jason Sie

## Acknowledgments

-  Implementation follows lodash IIFE pattern
-  Educational tool for learning Fibonacci sequences and JavaScript design patterns