@aws-sdk/util-utf8-browser

A browser-compatible UTF-8 string encoding and decoding utility that provides automatic fallback between the WHATWG Encoding API and pure JavaScript implementations. This utility ensures cross-browser compatibility for UTF-8 operations in web environments.

Package Information

• Package Name: @aws-sdk/util-utf8-browser
• Package Type: npm
• Language: TypeScript
• Installation: npm install @aws-sdk/util-utf8-browser
• Status: Deprecated in favor of @aws-sdk/util-utf8

Core Imports

import { fromUtf8, toUtf8 } from "@aws-sdk/util-utf8-browser";

For CommonJS:

const { fromUtf8, toUtf8 } = require("@aws-sdk/util-utf8-browser");

Basic Usage

import { fromUtf8, toUtf8 } from "@aws-sdk/util-utf8-browser";

// Convert string to UTF-8 byte array
const text = "Hello, World! 🌍";
const bytes = fromUtf8(text);
console.log(bytes); // Uint8Array(15) [72, 101, 108, 108, 111, 44, 32, 87, 111, 114, 108, 100, 33, 32, 240, 159, 140, 141]

// Convert UTF-8 byte array back to string
const restored = toUtf8(bytes);
console.log(restored); // "Hello, World! 🌍"

// Handle complex Unicode characters including surrogate pairs
const complexText = "🚀💻🌟";
const complexBytes = fromUtf8(complexText);
const restoredComplex = toUtf8(complexBytes);
console.log(restoredComplex === complexText); // true

// Works with international text and scripts
const arabicText = "دست‌نوشته‌ها نمی‌سوزند";
const cyrillicText = "Рукописи не горят";
const arabicBytes = fromUtf8(arabicText);
const cyrillicBytes = fromUtf8(cyrillicText);
console.log(toUtf8(arabicBytes) === arabicText); // true
console.log(toUtf8(cyrillicBytes) === cyrillicText); // true

Architecture

The package uses feature detection to automatically select the best available UTF-8 conversion method:

• WHATWG Encoding API: Prefers TextEncoder/TextDecoder when available (modern browsers)
• Pure JavaScript Fallback: Uses manual UTF-8 conversion for compatibility with older browsers
• Automatic Selection: Runtime detection ensures optimal performance while maintaining compatibility
• Unicode Handling: Properly handles complex Unicode scenarios including surrogate pairs and astral plane characters

Capabilities

String to UTF-8 Encoding

Converts JavaScript strings to UTF-8 encoded byte arrays with automatic implementation selection.

/**
 * Converts a JavaScript string to a UTF-8 encoded Uint8Array
 * @param input - The string to encode
 * @returns UTF-8 encoded byte array
 */
function fromUtf8(input: string): Uint8Array;

Implementation Details:

• Uses TextEncoder when available for optimal performance
• Falls back to pure JavaScript implementation for compatibility
• Handles Unicode surrogate pairs correctly
• Supports all valid JavaScript string characters

UTF-8 to String Decoding

Converts UTF-8 encoded byte arrays back to JavaScript strings with automatic implementation selection.

/**
 * Converts a UTF-8 encoded Uint8Array to a JavaScript string
 * @param input - The UTF-8 encoded byte array to decode
 * @returns Decoded JavaScript string
 */
function toUtf8(input: Uint8Array): string;

Implementation Details:

• Uses TextDecoder when available for optimal performance
• Falls back to pure JavaScript implementation for compatibility
• Correctly decodes astral plane characters
• Handles multi-byte UTF-8 sequences properly

Types

// Core functions use native JavaScript types
type Uint8Array = Uint8Array;
type string = string;

Error Handling

The functions handle malformed input gracefully:

• fromUtf8: Accepts any valid JavaScript string
• toUtf8: Expects valid UTF-8 encoded byte sequences; invalid sequences may produce replacement characters

Browser Compatibility

• Modern Browsers: Uses WHATWG Encoding API (TextEncoder/TextDecoder) for optimal performance
• Legacy Browsers: Falls back to pure JavaScript implementation
• Feature Detection: Automatically selects the best available method at runtime
• No External Dependencies: Self-contained implementation with only TypeScript helper dependency

Migration Notice

This package is deprecated in favor of @aws-sdk/util-utf8 which provides unified UTF-8 utilities for both Node.js and browser environments. Consider migrating to the newer package for new projects.