🔐 @chaisser/base64-url

URL-safe base64 encoding and decoding — encode, decode, validate, JSON, hex, buffers

✨ Features

• 🎯 Type-safe - Full TypeScript support
• 🔗 URL-safe - No +, /, or = characters in output
• 📦 Buffer support - Encode/decode Uint8Array and Buffer
• ✅ Validation - Check and validate base64url strings
• 📋 JSON helpers - Encode/decode JSON objects directly
• 🔧 Hex helpers - Encode/decode hex strings
• 🔄 Escape/unescape - Convert between standard and URL-safe base64
• 🪶 Zero dependencies - Lightweight and tree-shakeable
• 🏎️ ESM + CJS - Dual module format support

📦 Installation

npm install @chaisser/base64-url
# or
yarn add @chaisser/base64-url
# or
pnpm add @chaisser/base64-url

🚀 Quick Start

import { encode, decode, encodeJSON, decodeJSON } from '@chaisser/base64-url';

// Encode/decode strings
encode('hello world');   // 'aGVsbG8gd29ybGQ'
decode('aGVsbG8gd29ybGQ'); // 'hello world'

// JSON round-trip
const token = encodeJSON({ userId: 42, role: 'admin' });
// 'eyJ1c2VySWQiOjQyLCJyb2xlIjoiYWRtaW4ifQ'
const data = decodeJSON(token);
// { userId: 42, role: 'admin' }

📖 What It Does

This package provides URL-safe base64 encoding and decoding utilities for JavaScript and TypeScript. It replaces + with -, / with _, and strips trailing = padding per RFC 4648 §5. Supports strings, buffers, hex, JSON, and validation.

💡 Usage Examples

String Encode / Decode

import { encode, decode } from '@chaisser/base64-url';

encode('hello');         // 'aGVsbG8'
decode('aGVsbG8');       // 'hello'

// Unicode
encode('héllo wörld 🌍'); // URL-safe output

Buffer / Uint8Array

import { encodeBuffer, decodeToBuffer, decodeToUint8Array } from '@chaisser/base64-url';

const bytes = new Uint8Array([104, 101, 108, 108, 111]);
encodeBuffer(bytes);          // 'aGVsbG8'

const buf = decodeToBuffer('aGVsbG8');
buf.toString('utf-8');        // 'hello'

const arr = decodeToUint8Array('aGVsbG8');
// Uint8Array [104, 101, 108, 108, 111]

Escape / Unescape (convert formats)

import { escape, unescape } from '@chaisser/base64-url';

// Standard base64 → URL-safe
escape('a+b/c==');  // 'a-b_c'

// URL-safe → Standard base64 (with padding)
unescape('a-b_c');  // 'a+b/c=='

Validation

import { isBase64Url, validate } from '@chaisser/base64-url';

isBase64Url('aGVsbG8');   // true
isBase64Url('a+b/c=');    // false

validate('aGVsbG8');      // ok
validate('a+b/c=');       // throws Error

JSON Helpers

import { encodeJSON, decodeJSON } from '@chaisser/base64-url';

const token = encodeJSON({ sub: 'user123', exp: 1700000000 });
const payload = decodeJSON<{ sub: string; exp: number }>(token);

Hex Helpers

import { encodeHex, decodeHex } from '@chaisser/base64-url';

encodeHex('68656c6c6f');  // 'aGVsbG8'
decodeHex('aGVsbG8');     // '68656c6c6f'

📚 API Reference

String Encoding

| Function | Signature | Description | |---|---|---| | encode(input) | (string) → string | Encode UTF-8 string to base64url | | decode(input) | (string) → string | Decode base64url to UTF-8 string |

Buffer Encoding

| Function | Signature | Description | |---|---|---| | encodeBuffer(input) | (Uint8Array \| Buffer) → string | Encode bytes to base64url | | decodeToBuffer(input) | (string) → Buffer | Decode to Buffer | | decodeToUint8Array(input) | (string) → Uint8Array | Decode to Uint8Array |

Format Conversion

| Function | Signature | Description | |---|---|---| | escape(input) | (string) → string | Standard base64 → URL-safe | | unescape(input) | (string) → string | URL-safe → standard base64 |

Validation

| Function | Signature | Description | |---|---|---| | isBase64Url(input) | (string) → boolean | Check if string is valid base64url | | validate(input) | (string) → void | Throw if not valid base64url |

JSON

| Function | Signature | Description | |---|---|---| | encodeJSON(obj) | (unknown) → string | JSON.stringify → base64url | | decodeJSON(input) | (string) → T | base64url → JSON.parse |

Hex

| Function | Signature | Description | |---|---|---| | encodeHex(hex) | (string) → string | Hex string → base64url | | decodeHex(input) | (string) → string | base64url → hex string |

🔗 Related Packages

Explore our other utility packages in the @chaisser namespace:

• @chaisser/base64-url (this package) - URL-safe base64 encoding/decoding
• @chaisser/chunk-array - Split arrays into chunks
• @chaisser/string-wizard - Advanced string manipulation
• @chaisser/type-guard - Runtime type guards and validators
• @chaisser/uuid-v7 - Time-ordered UUID v7 generator
• @chaisser/wait-for - Promise-based wait utilities
• @chaisser/regex-humanizer - Regex to human-readable descriptions
• @chaisser/password-strength - Password strength checker
• @chaisser/human-time - Human-readable time formatting
• @chaisser/obj-path - Safe dot-notation object access
• @chaisser/debounce-throttle - Rate limiting utilities
• @chaisser/color-utils - Color conversion utilities
• @chaisser/deep-clone - Deep cloning functions
• @chaisser/array-group-by - Array grouping utilities
• @chaisser/merge-objects - Object merge utilities
• @chaisser/event-emitter - Typed event emitter
• @chaisser/unique-by - Array uniqueness utilities
• @chaisser/memoize - Function memoization with TTL and cache size limit

🔒 License

MIT - Free to use in personal and commercial projects

👨 Developed by

Doruk Karaboncuk [email protected]

📄 Repository

• GitHub: @Chaisser
• NPM: @chaisser/base64-url

🤝 Contributing

Contributions are welcome! Feel free to:

• Report bugs
• Suggest new features
• Submit pull requests
• Improve documentation

📞 Support

For issues, questions, or suggestions, please reach out through:

• Email: [email protected]
• GitHub Issues: Create an issue

Made with ❤️ by @chaisser