@hyperfrontend/string-utils/browser

Browser Module

Browser-optimized implementations of the @hyperfrontend/string-utils encoding API, built on TextEncoder / TextDecoder and atob / btoa.

Overview

This entry point delivers the same UTF-8 and base64 helpers as the Node submodule, but routes them through the platform's native Web APIs. Multi-byte UTF-8 input is encoded with TextEncoder before being handed to btoa, sidestepping the Latin-1 limitation that would otherwise make btoa('こんにちは') throw. Decoding mirrors the path: atob produces a binary string, which is converted to a Uint8Array and then decoded with TextDecoder.

The built-in references (btoa, atob, TextEncoder, TextDecoder) are pulled from @hyperfrontend/immutable-api-utils so consumers cannot break the library by overwriting globals.

Usage

import { toBase64, fromBase64, utf8StringToUint8Array, uint8ArrayToBase64 } from '@hyperfrontend/string-utils/browser'

// UTF-8 safe base64 (works for any code point)
toBase64('こんにちは') // => '44GT44KT44Gr44Gh44Gv'

// URL-safe base64 without padding (suitable for tokens / query strings)
toBase64('{"userId":123}', true, false) // => 'eyJ1c2VySWQiOjEyM30'

// Round-trip through bytes for crypto workflows
const bytes = utf8StringToUint8Array('Hello')
const restored = fromBase64(uint8ArrayToBase64(bytes))

Use this entry point in browsers, Web Workers, Deno, Bun, and Cloudflare Workers — anywhere the Web Encoding APIs are available. For Node.js processes, import from @hyperfrontend/string-utils/node instead so the Buffer-based implementations are picked up by the bundler.

API Reference

ƒ Functions

§function

arrayBufferToUtf8String(uint8Array: ArrayBuffer): string

Converts an ArrayBuffer to a UTF-8 encoded string.

Parameters

Name	Type	Description
§uint8Array	`ArrayBuffer`	The ArrayBuffer to convert

Returns

string

The decoded UTF-8 string

Example

Converting ArrayBuffer to string

const encoder = new TextEncoder()
const buffer = encoder.encode('Hello, World!').buffer
const decoded = arrayBufferToUtf8String(buffer)
// => 'Hello, World!'

§function

base64ToUint8Array(base64: string): Uint8Array

Converts a base64 encoded string to a Uint8Array (browser implementation). Supports both standard and URL-safe base64 encoding.

Parameters

Name	Type	Description
§base64	`string`	The base64 encoded string to convert

Returns

Uint8Array

The decoded Uint8Array

Examples

Standard base64

const bytes = base64ToUint8Array('SGVsbG8=')
// => Uint8Array([72, 101, 108, 108, 111]) // 'Hello'

URL-safe base64 (without padding)

const bytes = base64ToUint8Array('SGVsbG8')
// => Uint8Array([72, 101, 108, 108, 111]) // 'Hello'

§function

fromBase64(base64: string): string

Decodes a base64 encoded string to a UTF-8 string (browser implementation). Supports both standard and URL-safe base64 encoding.

Parameters

Name	Type	Description
§base64	`string`	The base64 encoded string to decode

Returns

string

The decoded UTF-8 string

Examples

Standard base64

const message = fromBase64('SGVsbG8sIFdvcmxkIQ==')
// => 'Hello, World!'

URL-safe base64

const token = fromBase64('eyJ1c2VySWQiOjEyM30')
// => '{"userId":123}'

§function

toBase64(text: string, urlSafe: boolean, keepPadding: boolean): string

Encodes a UTF-8 string to base64 format (browser implementation). Supports optional URL-safe encoding and padding control.

Parameters

Name	Type	Description
§text	`string`	The UTF-8 string to encode
§urlSafe	`boolean`	Whether to use URL-safe base64 encoding (replaces + and / with - and _) (default: `false`)
§keepPadding	`boolean`	Whether to keep padding characters (=) in the output (default: `false`)

Returns

string

The base64 encoded string

Examples

Standard base64

const encoded = toBase64('Hello, World!')
// => 'SGVsbG8sIFdvcmxkIQ=='

URL-safe without padding (for URLs/tokens)

const token = toBase64('{"userId":123}', true, false)
// => 'eyJ1c2VySWQiOjEyM30'

§function

uint8ArrayToBase64(bytes: Uint8Array, urlSafe: boolean, keepPadding: boolean): string

Converts a Uint8Array to a base64 encoded string (browser implementation). Supports optional URL-safe encoding and padding control.

Parameters

Name	Type	Description
§bytes	`Uint8Array`	The Uint8Array to encode
§urlSafe	`boolean`	Whether to use URL-safe base64 encoding (replaces + and / with - and _) (default: `false`)
§keepPadding	`boolean`	Whether to keep padding characters (=) in the output (default: `false`)

Returns

string

The base64 encoded string

Examples

Standard base64

const bytes = new Uint8Array([72, 101, 108, 108, 111])
const encoded = uint8ArrayToBase64(bytes)
// => 'SGVsbG8='

URL-safe without padding

const bytes = new Uint8Array([72, 101, 108, 108, 111])
const token = uint8ArrayToBase64(bytes, true, false)
// => 'SGVsbG8'

§function

uint8ArrayToUtf8String(uint8Array: Uint8Array): string

Converts a Uint8Array to a UTF-8 encoded string.

Parameters

Name	Type	Description
§uint8Array	`Uint8Array`	The Uint8Array to convert

Returns

string

The decoded UTF-8 string

Example

Converting Uint8Array to string

const bytes = new Uint8Array([72, 101, 108, 108, 111])
const text = uint8ArrayToUtf8String(bytes)
// => 'Hello'

§function

utf8StringToUint8Array(text: string): Uint8Array

Converts a UTF-8 string to a Uint8Array (browser implementation).

Parameters

Name	Type	Description
§text	`string`	The UTF-8 string to convert

Returns

Uint8Array

The encoded Uint8Array

Example

Encoding string to bytes (browser)

const bytes = utf8StringToUint8Array('Hello')
// => Uint8Array([72, 101, 108, 108, 111])