tessl/npm-js-base64

Yet another Base64 transcoder in pure-JS with comprehensive UTF-8 support and cross-platform compatibility

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Prototype Extensions

Name: tessl/npm-js-base64
Author: tessl

Optional methods that can be added to String.prototype and Uint8Array.prototype for fluent method chaining and convenient Base64 operations directly on built-in types.

Capabilities

String Prototype Extensions

Add Base64 encoding and decoding methods directly to String.prototype.

/**
 * Extend String.prototype with Base64 methods
 * Adds: fromBase64, toBase64, toBase64URI, toBase64URL, toUint8Array
 */
function extendString(): void;

Once extendString() is called, these methods become available on all strings:

interface String {
  /** Decode this Base64 string to UTF-8 */
  fromBase64(): string;
  /** Encode this string to Base64 */
  toBase64(urlsafe?: boolean): string;
  /** Encode this string to URL-safe Base64 */
  toBase64URI(): string;
  /** Alias for toBase64URI */
  toBase64URL(): string;
  /** Convert this Base64 string to Uint8Array */
  toUint8Array(): Uint8Array;
}

Usage Examples:

import { extendString } from "js-base64";

// Enable string extensions
extendString();

// Now you can use Base64 methods on any string
const text = "Hello World!";
const encoded = text.toBase64();
console.log(encoded); // "SGVsbG8gV29ybGQh"

const decoded = encoded.fromBase64();
console.log(decoded); // "Hello World!"

// URL-safe encoding
const urlSafe = text.toBase64URI();
console.log(urlSafe); // "SGVsbG8gV29ybGQ" (no padding)

// Alternative URL-safe method
const urlSafe2 = text.toBase64URL();
console.log(urlSafe2); // Same as toBase64URI()

// UTF-8 support
const japanese = "小飼弾";
const japaneseEncoded = japanese.toBase64();
console.log(japaneseEncoded); // "5bCP6aO85by+"

const japaneseDecoded = japaneseEncoded.fromBase64();
console.log(japaneseDecoded); // "小飼弾"

// Convert Base64 string to binary data
const binaryData = encoded.toUint8Array();
console.log(binaryData); // Uint8Array representing "Hello World!"

// Method chaining
const result = "Test String"
  .toBase64()
  .fromBase64()
  .toBase64URI();
console.log(result); // "VGVzdCBTdHJpbmc"

Uint8Array Prototype Extensions

Add Base64 encoding methods directly to Uint8Array.prototype.

/**
 * Extend Uint8Array.prototype with Base64 methods
 * Adds: toBase64, toBase64URI, toBase64URL
 */
function extendUint8Array(): void;

Once extendUint8Array() is called, these methods become available on all Uint8Arrays:

interface Uint8Array {
  /** Encode this Uint8Array to Base64 */
  toBase64(urlsafe?: boolean): string;
  /** Encode this Uint8Array to URL-safe Base64 */
  toBase64URI(): string;
  /** Alias for toBase64URI */
  toBase64URL(): string;
}

Usage Examples:

import { extendUint8Array } from "js-base64";

// Enable Uint8Array extensions
extendUint8Array();

// Create some binary data
const bytes = new Uint8Array([72, 101, 108, 108, 111, 33]); // "Hello!"

// Convert to Base64
const encoded = bytes.toBase64();
console.log(encoded); // "SGVsbG8h"

// URL-safe encoding
const urlSafe = bytes.toBase64URI();
console.log(urlSafe); // "SGVsbG8h" (no padding)

// Alternative URL-safe method
const urlSafe2 = bytes.toBase64URL();
console.log(urlSafe2); // Same as toBase64URI()

// Working with file data
async function processFile(file: File) {
  extendUint8Array();
  
  const arrayBuffer = await file.arrayBuffer();
  const uint8Array = new Uint8Array(arrayBuffer);
  
  // Now you can directly encode the file data
  const base64 = uint8Array.toBase64();
  return `data:${file.type};base64,${base64}`;
}

// Image processing example
const pngHeader = new Uint8Array([137, 80, 78, 71, 13, 10, 26, 10]);
const headerB64 = pngHeader.toBase64();
console.log(headerB64); // "iVBORw0KGgo="

Extend All Built-ins

Convenience function to extend both String and Uint8Array prototypes at once.

/**
 * Extend both String.prototype and Uint8Array.prototype with Base64 methods
 * Equivalent to calling both extendString() and extendUint8Array()
 */
function extendBuiltins(): void;

Usage Examples:

import { extendBuiltins } from "js-base64";

// Enable all prototype extensions
extendBuiltins();

// Now both strings and Uint8Arrays have Base64 methods
const text = "Hello World!";
const encoded = text.toBase64(); // String method

const bytes = new Uint8Array([72, 101, 108, 108, 111]);
const binaryEncoded = bytes.toBase64(); // Uint8Array method

// Round-trip conversion
const original = "Test data";
const roundTrip = original
  .toBase64()           // String -> Base64
  .toUint8Array()       // Base64 -> Uint8Array
  .toBase64()           // Uint8Array -> Base64
  .fromBase64();        // Base64 -> String
console.log(roundTrip); // "Test data"

Complete Extension API Reference

String Methods Added

After calling extendString() or extendBuiltins():

"any string".fromBase64();        // Decode Base64 to UTF-8 string
"any string".toBase64();          // Encode to standard Base64
"any string".toBase64(true);      // Encode to URL-safe Base64 (no padding)
"any string".toBase64URI();       // Encode to URL-safe Base64
"any string".toBase64URL();       // Same as toBase64URI()
"base64string".toUint8Array();    // Convert Base64 string to Uint8Array

Uint8Array Methods Added

After calling extendUint8Array() or extendBuiltins():

uint8Array.toBase64();            // Encode to standard Base64
uint8Array.toBase64(true);        // Encode to URL-safe Base64 (no padding)
uint8Array.toBase64URI();         // Encode to URL-safe Base64
uint8Array.toBase64URL();         // Same as toBase64URI()

Important Considerations

Global Scope Impact

import { extendBuiltins } from "js-base64";

// This modifies global prototypes - affects ALL strings and Uint8Arrays
extendBuiltins();

// Every string now has these methods
console.log("test".toBase64); // [Function]

// This might conflict with other libraries or cause unexpected behavior
// Use with caution in shared codebases

Best Practices

import { extendBuiltins, encode, decode } from "js-base64";

// Option 1: Use extensions for convenience in applications
function initializeApp() {
  extendBuiltins();
  // Now use methods throughout the app
}

// Option 2: Use functional API for libraries
function myLibraryFunction(input: string) {
  // Don't modify global prototypes in library code
  return encode(input);
}

// Option 3: Conditional extension for compatibility
function safeExtendBuiltins() {
  if (typeof String.prototype.toBase64 === 'undefined') {
    extendBuiltins();
  }
}

TypeScript Integration

// If using TypeScript with extensions, you may need to declare the methods
declare global {
  interface String {
    fromBase64(): string;
    toBase64(urlsafe?: boolean): string;
    toBase64URI(): string;
    toBase64URL(): string;
    toUint8Array(): Uint8Array;
  }
  
  interface Uint8Array {
    toBase64(urlsafe?: boolean): string;
    toBase64URI(): string;
    toBase64URL(): string;
  }
}

// Or import the library's type extensions if provided