mutf-8/dist/index.d.ts

An encoder and decoder for Modified UTF-8 which is used in the Java platform such as the class file format and object serialization.

/**
 * The options for the decoder.
 */
export interface TextDecoderOptions {
    /**
     * If `true`, the decoder will throw an error upon encountering invalid bytes.
     *
     * @defaultValue `false`
     */
    fatal?: boolean;
    /**
     * If `true`, the decoder will ignore the Byte Order Mark (BOM).
     *
     * @defaultValue `false`
     */
    ignoreBOM?: boolean;
}
/**
 * The options for decoding.
 */
export interface TextDecodeOptions {
    /**
     * If `true`, the decoder will process the input as a stream, allowing partial decoding.
     *
     * @defaultValue `false`
     */
    stream?: boolean;
}
/**
 * The result of encoding.
 */
export interface TextEncoderEncodeIntoResult {
    /** The number of converted code units of the source. */
    read: number;
    /** The number of bytes modified in the destination. */
    written: number;
}
/**
 * The type of buffer source that can be used in the decoder.
 */
export type AllowSharedBufferSource = ArrayBuffer | SharedArrayBuffer | ArrayBufferView;
/**
 * The decoder for Modified UTF-8.
 *
 * @example
 * ```ts
 * const src = new Uint8Array([
 *   0x48, 0x65, 0x6c, 0x6c, 0x6f, 0x20, 0xe4, 0xb8,
 *   0x96, 0xe7, 0x95, 0x8c, 0x21,
 * ]);
 * const decoder = new MUtf8Decoder();
 * const text = decoder.decode(src);
 * // Hello 世界!
 * ```
 *
 * @see {@link https://encoding.spec.whatwg.org/#interface-textdecoder}
 */
export declare class MUtf8Decoder {
    #private;
    /**
     * @returns Always `"mutf-8"`.
     */
    get encoding(): string;
    /**
     * @returns `true` if error mode is fatal, otherwise `false`.
     */
    get fatal(): boolean;
    /**
     * @returns Whether to ignore the BOM or not.
     */
    get ignoreBOM(): boolean;
    /**
     * @param label   - The label of the decoder. Must be `"mutf-8"` or `"mutf8"`.
     * @param options - The options for the decoder.
     * @throws `RangeError` If the `label` is an invalid value.
     */
    constructor(label?: string, options?: TextDecoderOptions);
    /**
     * Decodes the specified bytes into a string.
     *
     * @param input   - The bytes to be decoded.
     * @param options - The options for decoding.
     * @returns The resultant string after decoding.
     * @throws `TypeError` If {@link fatal} is `true` and the `input` contains invalid bytes.
     */
    decode(input: AllowSharedBufferSource, options?: TextDecodeOptions): string;
}
/**
 * The encoder for Modified UTF-8.
 *
 * @example
 * ```ts
 * const encoder = new MUtf8Encoder();
 * const code = encoder.encode("Hello 世界!");
 * // Uint8Array [
 * //   0x48, 0x65, 0x6c, 0x6c, 0x6f, 0x20, 0xe4, 0xb8,
 * //   0x96, 0xe7, 0x95, 0x8c, 0x21,
 * // ]
 * ```
 *
 * @see {@link https://encoding.spec.whatwg.org/#interface-textencoder}
 */
export declare class MUtf8Encoder {
    /**
     * @returns Always `"mutf-8"`.
     */
    get encoding(): string;
    /**
     * Encodes the specified string in Modified UTF-8.
     *
     * @param input - The string to be encoded.
     * @returns The resultant bytes.
     */
    encode(input?: string): Uint8Array;
    /**
     * Encodes the specified string in Modified UTF-8 and stores the result in the specified array.
     *
     * @param source      - The string to be encoded.
     * @param destination - The array to store the encoded bytes.
     * @returns The progress of the encoding operation.
     */
    encodeInto(source: string, destination: Uint8Array): TextEncoderEncodeIntoResult;
}