npm package: @popovmp/base64
Description: Base64 encoding / decoding for NodeJS
Latest version: 1.1.0

# Base64 Encoder / Decoder

A high-performance, TypeScript-ready Base64 and Base64URL encoding/decoding library for Node.js with comprehensive validation and error handling.

## Features

- ✅ **Fast & Lightweight** - Optimized algorithms with minimal validation overhead
- ✅ **Full Base64 & Base64URL Support** - Complete RFC 4648 compliance
- ✅ **TypeScript Ready** - Full type definitions included
- ✅ **Input Validation** - Format validation with clear error messages
- ✅ **Unicode Safe** - Proper handling of international characters
- ✅ **Binary Data Support** - Direct Uint8Array conversion
- ✅ **Zero Dependencies** - Pure JavaScript implementation
- ✅ **Comprehensive Tests** - 14 test suites with edge case coverage

## Installation

```bash
npm install @popovmp/base64
```

## API Reference

### String ↔ Base64URL

#### `stringToBase64Url(str: string): string`

Converts a string to a Base64URL string (URL-safe, no padding).

```javascript
import { stringToBase64Url } from "@popovmp/base64";
const base64Url = stringToBase64Url("foo"); //=> "Zm9v"
const unicode = stringToBase64Url("Hello 世界"); //=> "SGVsbG8g5LiW55WM"
```

#### `base64UrlToString(strB64Url: string): string`

Converts a Base64URL string back to the original string.

```javascript
import { base64UrlToString } from "@popovmp/base64";
const text = base64UrlToString("Zm9v"); //=> "foo"
const unicode = base64UrlToString("SGVsbG8g5LiW55WM"); //=> "Hello 世界"
```

### String ↔ Base64

#### `stringToBase64(str: string): string`

Converts a string to a standard Base64 string (with padding).

```javascript
import { stringToBase64 } from "@popovmp/base64";
const base64 = stringToBase64("foo"); //=> "Zm9v"
const withPadding = stringToBase64("f"); //=> "Zg=="
```

#### `base64ToString(strB64: string): string`

Converts a Base64 string back to the original string.

```javascript
import { base64ToString } from "@popovmp/base64";
const text = base64ToString("Zm9v"); //=> "foo"
const withPadding = base64ToString("Zg=="); //=> "f"
```

### Binary Data Support

#### `bytesToBase64(input: Uint8Array): string`

Converts a Uint8Array to a Base64 string.

```javascript
import { bytesToBase64 } from "@popovmp/base64";
const bytes = new Uint8Array([102, 111, 111]); // "foo"
const base64 = bytesToBase64(bytes); //=> "Zm9v"
```

#### `base64ToBytes(strB64: string): Uint8Array`

Converts a Base64 string to a Uint8Array.

```javascript
import { base64ToBytes } from "@popovmp/base64";
const bytes = base64ToBytes("Zm9v"); //=> Uint8Array [102, 111, 111]
```

### Format Conversion

#### `base64ToBase64Url(strB64: string): string`

Converts a Base64 string to Base64URL format (removes padding, replaces +/- with -/_).

```javascript
import { base64ToBase64Url } from "@popovmp/base64";
const base64Url = base64ToBase64Url("foo++/=="); //=> "foo--_"
```

#### `base64UrlToBase64(strB64Url: string): string`

Converts a Base64URL string to standard Base64 format (adds padding, replaces -/_ with +/-).

```javascript
import { base64UrlToBase64 } from "@popovmp/base64";
const base64 = base64UrlToBase64("foo--_"); //=> "foo++/=="
```

### Validation Functions

#### `isValidBase64(str: string): boolean`

Validates if a string is properly formatted Base64.

```javascript
import { isValidBase64 } from "@popovmp/base64";
console.log(isValidBase64("Zm9v")); //=> true
console.log(isValidBase64("Zm9vYg==")); //=> true
console.log(isValidBase64("invalid@")); //=> false
```

#### `isValidBase64Url(str: string): boolean`

Validates if a string is properly formatted Base64URL.

```javascript
import { isValidBase64Url } from "@popovmp/base64";
console.log(isValidBase64Url("Zm9v")); //=> true
console.log(isValidBase64Url("foo--_")); //=> true
console.log(isValidBase64Url("has+slash")); //=> false
```

## Error Handling

The library throws descriptive errors for invalid input:

```javascript
import { base64ToString, base64UrlToString } from "@popovmp/base64";

try {
  base64ToString("invalid@base64");
} catch (error) {
  console.log(error.message); //=> "Invalid base64 string"
}

try {
  base64UrlToString("invalid+base64url");
} catch (error) {
  console.log(error.message); //=> "Invalid base64url string"
}
```

## Performance

This library uses minimal validation for optimal performance:

- **Format validation** catches encoding/decoding errors
- **No type checking overhead** in hot paths  
- **Native JavaScript errors** for type mismatches
- **Optimized algorithms** for binary operations

## Unicode Support

Full Unicode support with proper UTF-8 encoding:

```javascript
import { stringToBase64, base64ToString } from "@popovmp/base64";

const unicode = "🎉 Hello 世界! αβγ مرحبا こんにちは";
const encoded = stringToBase64(unicode);
const decoded = base64ToString(encoded);
console.log(decoded === unicode); //=> true
```

## TypeScript

Full TypeScript support with comprehensive type definitions:

```typescript
import { stringToBase64, base64ToBytes, isValidBase64 } from "@popovmp/base64";

const result: string = stringToBase64("hello");
const bytes: Uint8Array = base64ToBytes("aGVsbG8=");
const isValid: boolean = isValidBase64("Zm9v");
```

## License

MIT