npm package: @piresfernando/base64-cli
Description: A Node.js utility to generate base64 from strings
Author: Fernando Pires
Latest version: 1.0.1

# Base64 String Converter

A simple Node.js utility to encode strings to base64 and decode base64 back to strings.

## Features

- ✅ Convert strings to base64 encoding
- ✅ Decode base64 strings back to original text
- ✅ Command-line interface (CLI)
- ✅ Interactive mode
- ✅ Module exports for use in other projects
- ✅ Error handling for invalid inputs
- ✅ Support for Unicode characters

## Installation

1. Clone or download this project
2. Navigate to the project directory:
   ```bash
   cd base64
   ```

3. (Optional) Install globally to use CLI anywhere:
   ```bash
   npm install -g .
   ```

## Usage

### As a Node.js Module

```javascript
const { stringToBase64, base64ToString } = require('./index.js');

// Encode string to base64
const encoded = stringToBase64('Hello, World!');
console.log(encoded); // SGVsbG8sIFdvcmxkIQ==

// Decode base64 to string
const decoded = base64ToString('SGVsbG8sIFdvcmxkIQ==');
console.log(decoded); // Hello, World!
```

### Command Line Interface

#### Basic Commands

```bash
# Encode a string to base64
node cli.js encode 'Hello, World!'
# Output: SGVsbG8sIFdvcmxkIQ==

# Decode base64 to string
node cli.js decode 'SGVsbG8sIFdvcmxkIQ=='
# Output: Hello, World!

# Show help
node cli.js help
```

#### Interactive Mode

```bash
# Run interactive mode
node cli.js

# Then use commands like:
encode Hello World
decode SGVsbG8gV29ybGQ=
help
quit
```

#### If Installed Globally

```bash
# Encode
base64 encode 'Hello, World!'

# Decode
base64 decode 'SGVsbG8sIFdvcmxkIQ=='

# Interactive mode
base64
```

### Running Examples

```bash
# Run the demonstration
node index.js
```

This will show several examples of encoding and decoding strings, including Unicode characters.

## API Reference

### `stringToBase64(input)`

Converts a string to base64 encoding.

- **Parameters:**
  - `input` (string): The string to encode
- **Returns:** (string) The base64 encoded string
- **Throws:** Error if input is not a string

### `base64ToString(base64Input)`

Converts a base64 string back to the original string.

- **Parameters:**
  - `base64Input` (string): The base64 string to decode
- **Returns:** (string) The decoded string
- **Throws:** Error if input is not a string or is invalid base64

### `demonstrateConversion()`

Runs a demonstration showing various encoding/decoding examples.

## Examples

### Basic Usage

```javascript
const { stringToBase64, base64ToString } = require('./index.js');

// Simple text
console.log(stringToBase64('Hello')); // SGVsbG8=

// Text with spaces
console.log(stringToBase64('Hello World')); // SGVsbG8gV29ybGQ=

// Special characters
console.log(stringToBase64('Hello, World!')); // SGVsbG8sIFdvcmxkIQ==

// Unicode characters
console.log(stringToBase64('🚀 Node.js')); // 8J+agSBOb2RlLmpz
```

### Error Handling

```javascript
try {
    const result = stringToBase64(123); // This will throw an error
} catch (error) {
    console.log(error.message); // "Input must be a string"
}

try {
    const result = base64ToString('invalid-base64!'); // This will throw an error
} catch (error) {
    console.log(error.message); // "Invalid base64 string"
}
```

## Testing

Run the test file to verify functionality:

```bash
node test.js
```

## Dependencies

This project uses only Node.js built-in modules:
- `Buffer` - for base64 encoding/decoding
- `readline` - for interactive CLI mode

## License

MIT License