text-encoding/index.d.ts

/**
 * Type declarations for @metatrom/text-encoding
 * Self-contained for IOR type generation
 */

declare module '@metatrom/text-encoding' {
  /**
   * 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;
  }

  /**
   * TextEncoder Polyfill Implementation
   */
  export declare class TextEncoderPolyfill implements ITextEncoder {
    readonly encoding: string;
    encode(input?: string): Uint8Array;
    encodeInto(source: string, destination: Uint8Array): TextEncoderEncodeIntoResult;
  }

  /**
   * TextDecoder Polyfill Implementation
   */
  export declare class TextDecoderPolyfill implements ITextDecoder {
    readonly encoding: string;
    readonly fatal: boolean;
    readonly ignoreBOM: boolean;
    
    constructor(label?: string, options?: TextDecoderOptions);
    decode(input?: ArrayBufferView | ArrayBuffer | null, options?: TextDecodeOptions): string;
  }

  /**
   * Text Encoding Factory
   */
  export declare class TextEncodingFactory implements ITextEncodingFactory {
    static getInstance(): TextEncodingFactory;
    createEncoder(): ITextEncoder;
    createDecoder(label?: string, options?: TextDecoderOptions): ITextDecoder;
    isNativelySupported(): boolean;
  }

  /**
   * Text Encoding Service Implementation
   */
  export declare class TextEncodingService implements ITextEncodingService {
    readonly encoder: ITextEncoder;
    readonly decoder: ITextDecoder;
    
    encode(text: string): Uint8Array;
    decode(bytes: Uint8Array | ArrayBuffer | number[]): string;
    stringToUtf8(text: string): Uint8Array;
    utf8ToString(bytes: Uint8Array | number[]): string;
  }

  /**
   * Factory functions
   */
  export function createTextEncoder(): ITextEncoder;
  export function createTextDecoder(label?: string, options?: TextDecoderOptions): ITextDecoder;
  export function installTextEncodingPolyfills(): void;
  export function getTextEncodingService(): ITextEncodingService;

  /**
   * Default shared text encoding service
   * Use this for most encoding/decoding needs
   */
  export const textEncoding: ITextEncodingService;

  /**
   * Version information
   */
  export const VERSION: string;
  export const COMPONENT_NAME: string;
}