text-encoding/interfaces.ts

/**
 * Text Encoding Interface Definitions
 *
 * Provides UTF-8 text encoding/decoding capabilities for React Native
 * Compatible with the standard TextEncoder/TextDecoder Web API
 *
 * @module text-encoding@1.0.0/interfaces
 */

/**
 * TextEncoder interface - encodes strings to UTF-8 byte arrays
 */
export interface ITextEncoder {
  /**
   * The encoding format (always 'utf-8' for this implementation)
   */
  readonly encoding: string;

  /**
   * Encode a string into a Uint8Array using UTF-8 encoding
   * @param input The string to encode
   * @returns UTF-8 encoded byte array
   */
  encode(input?: string): Uint8Array;

  /**
   * Encode a string into an existing Uint8Array (partial encoding)
   * @param source The string to encode
   * @param destination The array to write to
   * @returns Object with read (chars) and written (bytes) counts
   */
  encodeInto?(source: string, destination: Uint8Array): TextEncoderEncodeIntoResult;
}

/**
 * TextDecoder interface - decodes UTF-8 byte arrays to strings
 */
export interface ITextDecoder {
  /**
   * The encoding format (always 'utf-8' for this implementation)
   */
  readonly encoding: string;

  /**
   * Whether to throw on invalid sequences (vs replacement char)
   */
  readonly fatal: boolean;

  /**
   * Whether to ignore BOM (byte order mark)
   */
  readonly ignoreBOM: boolean;

  /**
   * Decode a byte array into a string using UTF-8 decoding
   * @param input The bytes to decode (Uint8Array or ArrayBuffer)
   * @param options Decoding options
   * @returns Decoded string
   */
  decode(input?: ArrayBufferView | ArrayBuffer, options?: TextDecodeOptions): string;
}

/**
 * Result of encodeInto operation
 */
export interface TextEncoderEncodeIntoResult {
  /**
   * Number of UTF-16 code units read from source
   */
  read: number;

  /**
   * Number of bytes written to destination
   */
  written: number;
}

/**
 * Options for text decoding
 */
export interface TextDecodeOptions {
  /**
   * Whether this is a streaming decode (more data coming)
   */
  stream?: boolean;
}

/**
 * Options for TextDecoder constructor
 */
export interface TextDecoderOptions {
  /**
   * If true, throw on invalid byte sequences
   */
  fatal?: boolean;

  /**
   * If true, ignore byte order mark
   */
  ignoreBOM?: boolean;
}

/**
 * Factory for creating encoder/decoder instances
 */
export interface ITextEncodingFactory {
  /**
   * Create a new TextEncoder instance
   */
  createEncoder(): ITextEncoder;

  /**
   * Create a new TextDecoder instance
   * @param label Encoding label (default 'utf-8')
   * @param options Decoder options
   */
  createDecoder(label?: string, options?: TextDecoderOptions): ITextDecoder;

  /**
   * Check if TextEncoder/TextDecoder are natively available
   */
  isNativelySupported(): boolean;
}

/**
 * Text encoding service for shared instances
 */
export interface ITextEncodingService {
  /**
   * Shared encoder instance
   */
  readonly encoder: ITextEncoder;

  /**
   * Shared decoder instance
   */
  readonly decoder: ITextDecoder;

  /**
   * Encode string to bytes
   */
  encode(text: string): Uint8Array;

  /**
   * Decode bytes to string
   */
  decode(bytes: Uint8Array | ArrayBuffer | number[]): string;

  /**
   * Convert string to UTF-8 byte array (convenience method)
   */
  stringToUtf8(text: string): Uint8Array;

  /**
   * Convert UTF-8 byte array to string (convenience method)
   */
  utf8ToString(bytes: Uint8Array | number[]): string;
}