🔐 @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 doruk.karaboncuk@interaktifis.com

---

📄 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: doruk.karaboncuk@interaktifis.com
• GitHub Issues: Create an issue

---

Made with ❤️ by @chaisser