text-encoding/README.md

Text Encoding Component

UTF-8 text encoding/decoding utilities with automatic polyfill support for React Native.

Features

• Standard Compliance: Compatible with the standard TextEncoder/TextDecoder Web API
• React Native Support: Automatic polyfills for environments without native support
• UTF-8 Only: Focused implementation supporting only UTF-8 encoding for reliability
• Performance: Uses native implementations when available, falls back to efficient polyfills
• TypeScript: Full TypeScript support with comprehensive type definitions

Installation

This package is designed to be loaded via IOR (Interoperable Object Reference) from Gitea:

import { textEncoding } from 'ior:gitea:gitea.metatrom.net:universal-components/text-encoding@1.0.0';

Usage

Simple Text Encoding/Decoding

The easiest way to use this component is through the default service:

import { textEncoding } from 'ior:gitea:gitea.metatrom.net:universal-components/text-encoding@1.0.0';

// Encode string to bytes
const encoded = textEncoding.encode('Hello, 世界! 🌍');
console.log(encoded); // Uint8Array

// Decode bytes to string  
const decoded = textEncoding.decode(encoded);
console.log(decoded); // "Hello, 世界! 🌍"

Factory Functions

For more control, use the factory functions:

import { createTextEncoder, createTextDecoder } from 'ior:gitea:gitea.metatrom.net:universal-components/text-encoding@1.0.0';

const encoder = createTextEncoder();
const decoder = createTextDecoder();

const bytes = encoder.encode('Hello World');
const text = decoder.decode(bytes);

Advanced Usage

Create decoder instances with options:

import { createTextDecoder } from 'ior:gitea:gitea.metatrom.net:universal-components/text-encoding@1.0.0';

// Throw on invalid sequences instead of using replacement character
const fatalDecoder = createTextDecoder('utf-8', { fatal: true });

// Ignore byte order mark
const ignoreBomDecoder = createTextDecoder('utf-8', { ignoreBOM: true });

Direct Polyfill Usage

Access polyfill classes directly for advanced use cases:

import { TextEncoderPolyfill, TextDecoderPolyfill } from 'ior:gitea:gitea.metatrom.net:universal-components/text-encoding@1.0.0';

const encoder = new TextEncoderPolyfill();
const decoder = new TextDecoderPolyfill('utf-8', { fatal: false });

API Reference

textEncoding (Default Service)

The main service instance with convenient methods:

• encode(text: string): Uint8Array - Encode string to UTF-8 bytes
• decode(bytes: Uint8Array | ArrayBuffer | number[]): string - Decode bytes to string
• stringToUtf8(text: string): Uint8Array - Alias for encode()
• utf8ToString(bytes: Uint8Array | number[]): string - Alias for decode()

Factory Functions

• createTextEncoder(): ITextEncoder - Create encoder instance
• createTextDecoder(label?: string, options?: TextDecoderOptions): ITextDecoder - Create decoder instance
• installTextEncodingPolyfills(): void - Install global polyfills

Interfaces

ITextEncoder

• encoding: string - Always 'utf-8'
• encode(input?: string): Uint8Array - Encode string to bytes
• encodeInto(source: string, destination: Uint8Array): TextEncoderEncodeIntoResult - Encode into existing array

ITextDecoder

• encoding: string - Always 'utf-8'
• fatal: boolean - Whether to throw on invalid sequences
• ignoreBOM: boolean - Whether to ignore byte order mark
• decode(input?: ArrayBufferView | ArrayBuffer, options?: TextDecodeOptions): string - Decode bytes to string

Error Handling

The component handles various error conditions gracefully:

import { textEncoding } from 'ior:gitea:gitea.metatrom.net:universal-components/text-encoding@1.0.0';

// Invalid UTF-8 sequences are replaced with <20> (U+FFFD) by default
const invalidBytes = new Uint8Array([0xFF, 0xFE, 0xFD]);
const result = textEncoding.decode(invalidBytes);
console.log(result); // "<22><><EFBFBD>"

// Use fatal mode to throw on errors
import { createTextDecoder } from 'ior:gitea:gitea.metatrom.net:universal-components/text-encoding@1.0.0';
const fatalDecoder = createTextDecoder('utf-8', { fatal: true });
try {
  fatalDecoder.decode(invalidBytes);
} catch (error) {
  console.error('Invalid UTF-8 sequence:', error.message);
}

Platform Support

• React Native: Full support with automatic polyfills
• Node.js: Uses native TextEncoder/TextDecoder when available
• Browsers: Uses native implementations in modern browsers
• Automatic Fallback: Seamlessly falls back to polyfills when native support is unavailable

Performance Notes

• Native implementations are preferred when available for optimal performance
• Polyfills are optimized for correctness and reasonable performance
• UTF-8 validation is performed to ensure data integrity
• Surrogate pair handling for proper Unicode support

Unicode Support

This implementation fully supports the Unicode standard:

• All valid Unicode code points (U+0000 to U+10FFFF)
• Proper surrogate pair handling for characters above U+FFFF
• UTF-8 validation with proper error handling
• BOM (Byte Order Mark) support with optional ignoring

Version Information

• Version: 1.0.0
• Component Name: text-encoding
• IOR: ior:gitea:gitea.metatrom.net:universal-components/text-encoding@1.0.0