or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-base64url

For encoding to/from base64urls implementing RFC 4648 base64url standard

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/base64url@3.0.x

To install, run

npx @tessl/cli install tessl/npm-base64url@3.0.0

index.mddocs/

base64url

base64url provides comprehensive base64url encoding and decoding functions implementing the RFC 4648 base64url standard. It offers utilities for converting strings and buffers to/from base64url format, converting between standard base64 and base64url formats, and creating buffers from base64url encoded strings.

Package Information

  • Package Name: base64url
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install base64url

Core Imports

import base64url from "base64url";

For CommonJS:

const base64url = require("base64url");

Basic Usage

import base64url from "base64url";

// Encode string to base64url
const encoded = base64url("hello world");
console.log(encoded); // "aGVsbG8gd29ybGQ"

// Decode base64url to string
const decoded = base64url.decode("aGVsbG8gd29ybGQ");
console.log(decoded); // "hello world"

// Convert between formats
const b64 = "aGVsbG8gd29ybGQ=";
const b64url = base64url.fromBase64(b64);
console.log(b64url); // "aGVsbG8gd29ybGQ"

// Convert back to standard base64
const backToB64 = base64url.toBase64(b64url);
console.log(backToB64); // "aGVsbG8gd29ybGQ="

Capabilities

Encoding

Encode strings or buffers to base64url format.

/**
 * Encode input to base64url format (default function)
 * @param input - String or Buffer to encode
 * @param encoding - Text encoding for string input (default: "utf8")
 * @returns base64url encoded string
 */
function base64url(input: string | Buffer, encoding?: string): string;

/**
 * Encode input to base64url format (explicit method)
 * @param input - String or Buffer to encode
 * @param encoding - Text encoding for string input (default: "utf8")
 * @returns base64url encoded string
 */
function encode(input: string | Buffer, encoding?: string): string;

Usage Examples:

// String encoding with default UTF-8
const result1 = base64url("hello world");
const result2 = base64url.encode("hello world");

// Buffer encoding
const buffer = Buffer.from("hello world", "utf8");
const result3 = base64url(buffer);

// String with specific encoding
const result4 = base64url("hello world", "ascii");

Decoding

Decode base64url strings back to original strings.

/**
 * Decode base64url string to original string
 * @param base64url - base64url encoded string to decode
 * @param encoding - Text encoding for output string (default: "utf8")
 * @returns decoded string
 */
function decode(base64url: string, encoding?: string): string;

Usage Examples:

// Basic decoding
const decoded = base64url.decode("aGVsbG8gd29ybGQ");
console.log(decoded); // "hello world"

// Decoding with specific encoding
const decoded2 = base64url.decode("aGVsbG8gd29ybGQ", "ascii");

Format Conversion

Convert between standard base64 and base64url formats.

/**
 * Convert base64url string to standard base64 format
 * @param base64url - base64url string or Buffer to convert
 * @returns standard base64 string with padding
 */
function toBase64(base64url: string | Buffer): string;

/**
 * Convert standard base64 string to base64url format
 * @param base64 - standard base64 string to convert
 * @returns base64url string without padding
 */
function fromBase64(base64: string): string;

Usage Examples:

// Convert base64url to base64
const b64url = "aGVsbG8gd29ybGQ";
const b64 = base64url.toBase64(b64url);
console.log(b64); // "aGVsbG8gd29ybGQ="

// Convert base64 to base64url
const standardB64 = "aGVsbG8gd29ybGQ=";
const urlSafe = base64url.fromBase64(standardB64);
console.log(urlSafe); // "aGVsbG8gd29ybGQ"

Buffer Operations

Convert base64url strings directly to Buffer objects.

/**
 * Convert base64url string to Buffer containing decoded bytes
 * @param base64url - base64url string to convert
 * @returns Buffer with decoded byte data
 */
function toBuffer(base64url: string): Buffer;

Usage Examples:

// Convert base64url to Buffer
const b64url = "aGVsbG8gd29ybGQ";
const buffer = base64url.toBuffer(b64url);
console.log(buffer); // <Buffer 68 65 6c 6c 6f 20 77 6f 72 6c 64>
console.log(buffer.toString("utf8")); // "hello world"

Types

/**
 * Main interface combining callable function with utility methods
 */
interface Base64Url {
  /** Callable function for encoding (same as encode method) */
  (input: string | Buffer, encoding?: string): string;
  /** Encode input to base64url format */
  encode(input: string | Buffer, encoding?: string): string;
  /** Decode base64url string to original string */
  decode(base64url: string, encoding?: string): string;
  /** Convert base64url to standard base64 format */
  toBase64(base64url: string | Buffer): string;
  /** Convert standard base64 to base64url format */
  fromBase64(base64: string): string;
  /** Convert base64url string to Buffer */
  toBuffer(base64url: string): Buffer;
}

Error Handling

The library validates input types and will throw errors for invalid inputs:

  • Functions expect string or Buffer inputs where specified
  • Invalid input types (e.g., numbers) will throw runtime errors during encoding
  • All string inputs support configurable encoding (defaults to UTF-8)

Implementation Notes

  • Uses only Node.js built-in modules (no external dependencies)
  • Implements RFC 4648 base64url standard
  • URL-safe encoding replaces + with - and / with _
  • Removes padding characters (=) from base64url output
  • Full TypeScript support with complete type definitions