@ddunigma/node 2.1.1 → 2.2.0

package/dist/index.d.cts

@@ -0,0 +1,813 @@
+import { Transform, TransformCallback, TransformOptions } from 'stream';
+
+declare enum DduSetSymbol {
+    DDU = "ddu",
+    ONECHARSET = "oneCharSet",
+    TWOCHARSET = "twoCharSet",
+    THREECHARSET = "threeCharSet"
+}
+
+interface CharSetConfig {
+    /** charset 식별 심볼 */
+    symbol: DduSetSymbol;
+    /** 인코딩에 사용할 문자 배열 */
+    charSet: string[];
+    /** 최대 필요 문자 수 */
+    maxRequiredLength: number;
+    /** 비트 길이 (log2) */
+    bitLength: number;
+    /** 패딩 문자 */
+    paddingChar: string;
+}
+/** 진행률 콜백 정보 */
+interface DduProgressInfo {
+    /** 현재 처리된 바이트 수 (근사값) */
+    processedBytes: number;
+    /** 전체 바이트 수 */
+    totalBytes: number;
+    /** 진행률 (0-100, 단계별 근사값) */
+    percent: number;
+    /** 현재 처리 단계 */
+    stage?: "start" | "encrypt" | "compress" | "encode" | "decode" | "decompress" | "checksum" | "decrypt" | "done";
+}
+/** 인코딩 통계 정보 */
+interface DduEncodeStats {
+    /** 원본 데이터 크기 (바이트) */
+    originalSize: number;
+    /** 인코딩된 문자열 길이 */
+    encodedSize: number;
+    /** 압축된 크기 (압축 사용시) */
+    compressedSize?: number;
+    /** 압축률 (0-1, 낮을수록 효율적) */
+    compressionRatio?: number;
+    /** 인코딩 확장 비율 */
+    expansionRatio: number;
+    /** 사용된 charset 크기 */
+    charsetSize: number;
+    /** 비트 길이 */
+    bitLength: number;
+}
+interface DduOptions {
+    /** 압축 사용 여부 (zlib deflate 또는 brotli) */
+    compress?: boolean;
+    /** decode stream에서 footer 기반 자동 감지 사용 여부 (기본값: true) */
+    streamAutoDetect?: boolean;
+    /** 내부 암/복호화 사용 여부 (기본값: true, 스트림 파이프라인 내부 제어용) */
+    encrypt?: boolean;
+    /** 압축 알고리즘 (기본값: "deflate") */
+    compressionAlgorithm?: "deflate" | "brotli";
+    /** 압축 레벨 (deflate 기본값: 6, brotli도 기본값 6을 사용하며 전달값은 0~11 범위로 보정) */
+    compressionLevel?: number;
+    /** 최대 디코딩 바이트 수 (Zip Bomb 방어) */
+    maxDecodedBytes?: number;
+    /** 최대 압축해제 바이트 수 (Zip Bomb 방어) */
+    maxDecompressedBytes?: number;
+    /** 체크섬 추가 여부 (CRC32) */
+    checksum?: boolean;
+    /** 청크 분할 크기 */
+    chunkSize?: number;
+    /** 청크 구분자 (기본값: '\n') */
+    chunkSeparator?: string;
+    /** 중간 스트림 청크처럼 푸터를 생략해야 할 때 사용 */
+    omitFooter?: boolean;
+    /** 진행률 콜백 */
+    onProgress?: (info: DduProgressInfo) => void;
+}
+interface DduConstructorOptions extends DduOptions {
+    /** 미리 정의된 charset 심볼 */
+    dduSetSymbol?: DduSetSymbol;
+    /** 커스텀 charset 문자 배열 또는 문자열 */
+    dduChar?: string[] | string;
+    /** 패딩 문자 */
+    paddingChar?: string;
+    /** 필요 문자 수 */
+    requiredLength?: number;
+    /** 비트 길이 */
+    bitLength?: number;
+    /** 2의 제곱수 강제 여부 */
+    usePowerOfTwo?: boolean;
+    /**
+     * true이면 초기화 오류 시 throw합니다. false이면 fallback charset으로 대체합니다.
+     * @default false
+     * @deprecated throwOnError를 사용하세요. 이 옵션은 하위 호환성을 위해 유지됩니다.
+     */
+    useBuildErrorReturn?: boolean;
+    /**
+     * true이면 초기화 오류 시 throw합니다. false이면 fallback charset으로 대체합니다.
+     * useBuildErrorReturn과 동일한 동작이며, 둘 다 지정 시 throwOnError가 우선합니다.
+     * @default false
+     */
+    throwOnError?: boolean;
+    /** Buffer 인코딩 방식 */
+    encoding?: BufferEncoding;
+    /** URL-Safe 모드 (특수문자를 URL 안전 문자로 변환) */
+    urlSafe?: boolean;
+    /** 암호화 키 (AES-256-GCM) */
+    encryptionKey?: string;
+}
+
+declare abstract class BaseDdu {
+    protected readonly defaultEncoding: BufferEncoding;
+    /**
+     * 주어진 숫자보다 작거나 같은 가장 큰 2의 제곱수의 지수를 반환합니다.
+     * @param n - 대상 숫자
+     * @returns 2의 제곱수 지수 (예: n=8 → 3, n=64 → 6)
+     * @example getLargestPowerOfTwoExponent(8) // 3
+     * @example getLargestPowerOfTwoExponent(100) // 6
+     */
+    protected getLargestPowerOfTwoExponent(n: number): number;
+    /**
+     * charset 크기에 필요한 비트 길이를 계산합니다.
+     * @param setLength - charset 문자 수
+     * @returns 필요한 비트 수
+     * @example getBitLength(64) // 6
+     * @example getBitLength(100) // 7
+     */
+    protected getBitLength(setLength: number): number;
+    /**
+     * 입력 데이터를 인코딩합니다.
+     * @param input - 인코딩할 문자열 또는 Buffer
+     * @param options - 인코딩 옵션
+     * @returns 인코딩된 문자열
+     */
+    abstract encode(input: Buffer | string, options?: DduOptions): string;
+    /**
+     * 인코딩된 문자열을 Buffer로 디코딩합니다.
+     * @param input - 인코딩된 문자열
+     * @param options - 디코딩 옵션
+     * @returns 디코딩된 Buffer
+     */
+    abstract decodeToBuffer(input: string, options?: DduOptions): Buffer;
+    /**
+     * 인코딩된 문자열을 원본 문자열로 디코딩합니다.
+     * @param input - 인코딩된 문자열
+     * @param options - 디코딩 옵션
+     * @returns 디코딩된 문자열
+     */
+    abstract decode(input: string, options?: DduOptions): string;
+    /**
+     * 현재 인코더의 charset 정보를 반환합니다.
+     * @returns charset 설정 정보 객체
+     */
+    abstract getCharSetInfo(): {
+        charSet: string[];
+        paddingChar: string;
+        charLength: number;
+        bitLength: number;
+        usePowerOfTwo: boolean;
+        encoding: BufferEncoding;
+    };
+}
+
+/**
+ * AES-256-GCM 스트림 암호화 (Node.js Transform)
+ */
+declare class GcmEncryptStream extends Transform {
+    private cipher;
+    constructor(keyHash: Buffer);
+    _transform(chunk: Buffer, enc: BufferEncoding, cb: TransformCallback): void;
+    _flush(cb: TransformCallback): void;
+}
+/**
+ * AES-256-GCM 스트림 복호화 (Node.js Transform)
+ */
+declare class GcmDecryptStream extends Transform {
+    private keyHash;
+    private iv;
+    private decipher;
+    private tail;
+    constructor(keyHash: Buffer);
+    _transform(chunk: Buffer, enc: BufferEncoding, cb: TransformCallback): void;
+    _flush(cb: TransformCallback): void;
+}
+
+/**
+ * 커스텀 charset을 사용하는 Base64 스타일 인코더
+ *
+ * @description
+ * 바이너리 데이터를 지정된 charset으로 인코딩/디코딩합니다.
+ * 2의 제곱수 charset과 가변 길이 charset 모두 지원하며,
+ * 압축 옵션을 통해 데이터 크기를 줄일 수 있습니다.
+ *
+ * @example
+ * // 기본 사용
+ * const encoder = new Ddu64("우따야", "뭐");
+ * const encoded = encoder.encode("Hello");
+ * const decoded = encoder.decode(encoded);
+ *
+ * @example
+ * // 압축 사용
+ * const encoder = new Ddu64(undefined, undefined, { compress: true });
+ * const encoded = encoder.encode(longText);
+ */
+declare class Ddu64 extends BaseDdu {
+    /** 인코딩에 사용할 문자 배열 */
+    protected readonly dduChar: string[];
+    /** 패딩 문자 */
+    protected readonly paddingChar: string;
+    /** 각 charset 문자의 길이 */
+    protected readonly charLength: number;
+    /** 비트 길이 (log2) */
+    protected readonly bitLength: number;
+    /** 2의 제곱수 charset 여부 */
+    protected readonly usePowerOfTwo: boolean;
+    /** 문자열 인코딩 방식 */
+    protected readonly encoding: BufferEncoding;
+    /** 기본 압축 사용 여부 */
+    protected readonly defaultCompress: boolean;
+    /** 기본 최대 디코딩 바이트 수 */
+    private readonly defaultMaxDecodedBytes;
+    /** 기본 최대 압축해제 바이트 수 */
+    private readonly defaultMaxDecompressedBytes;
+    /** 문자 → 인덱스 역방향 룩업 맵 */
+    protected readonly dduBinaryLookup: Map<string, number>;
+    /** 미리 정의된 charset 사용 여부 */
+    private readonly isPredefinedCharSet;
+    /** 실제 사용되는 비트 길이 */
+    private readonly effectiveBitLength;
+    /** 최대 바이너리 값 */
+    private readonly maxBinaryValue;
+    /** ASCII 문자 빠른 룩업 테이블 */
+    private readonly fastAsciiLookup;
+    /** ASCII 룩업 사용 여부 */
+    private readonly useAsciiLookup;
+    /** URL-Safe 모드 여부 */
+    private readonly urlSafe;
+    /** 암호화 키 해시 (AES-256용 32바이트) */
+    private readonly encryptionKeyHash;
+    /** 기본 체크섬 사용 여부 */
+    private readonly defaultChecksum;
+    /** 기본 청크 크기 */
+    private readonly defaultChunkSize;
+    /** 기본 청크 구분자 */
+    private readonly defaultChunkSeparator;
+    /** 기본 압축 레벨 (1~9) */
+    private readonly defaultCompressionLevel;
+    /** 기본 압축 알고리즘 */
+    private readonly defaultCompressionAlgorithm;
+    /**
+     * Ddu64 인코더 인스턴스를 생성합니다.
+     *
+     * @param dduChar - charset 문자열 또는 배열 (미지정 시 옵션의 dduSetSymbol 사용)
+     * @param paddingChar - 패딩 문자 (dduChar 지정 시 필수)
+     * @param dduOptions - 생성자 옵션
+     *
+     * @throws dduChar 지정 시 paddingChar가 없으면 에러
+     * @throws charset 문자 수가 부족하면 에러
+     *
+     * @example
+     * // 커스텀 charset
+     * new Ddu64("우따야", "뭐");
+     *
+     * @example
+     * // 미리 정의된 charset
+     * new Ddu64(undefined, undefined, { dduSetSymbol: DduSetSymbol.ONECHARSET });
+     */
+    constructor(dduChar?: string[] | string, paddingChar?: string, dduOptions?: DduConstructorOptions);
+    /**
+     * 입력 데이터를 인코딩합니다.
+     *
+     * @param input - 인코딩할 문자열 또는 Buffer
+     * @param options - 인코딩 옵션
+     * @param options.compress - 압축 사용 여부 (기본값: 생성자 설정)
+     * @param options.checksum - 체크섬 추가 여부
+     * @param options.chunkSize - 청크 분할 크기
+     * @param options.chunkSeparator - 청크 구분자
+     * @param options.onProgress - 진행률 콜백
+     * @returns 인코딩된 문자열
+     *
+     * @example
+     * encoder.encode("Hello World!");
+     * encoder.encode(buffer, { compress: true });
+     * encoder.encode(data, { checksum: true, chunkSize: 76 });
+     */
+    encode(input: Buffer | string, options?: DduOptions): string;
+    /**
+     * 인코딩 핵심 로직. encode()와 getStats()가 공유합니다.
+     * 압축 크기 등 메타데이터도 함께 반환하여 중복 deflateSync 호출을 방지합니다.
+     */
+    private encodeInternal;
+    /**
+     * 인코딩된 문자열을 Buffer로 디코딩합니다.
+     *
+     * @param input - 디코딩할 인코딩된 문자열
+     * @param options - 디코딩 옵션
+     * @param options.maxDecodedBytes - 최대 디코딩 바이트 수
+     * @param options.maxDecompressedBytes - 최대 압축해제 바이트 수
+     * @param options.onProgress - 진행률 콜백
+     * @returns 디코딩된 Buffer
+     *
+     * @throws 잘못된 문자가 포함된 경우
+     * @throws 패딩 형식이 잘못된 경우
+     * @throws 크기 제한 초과 시
+     * @throws 체크섬 불일치 시
+     */
+    decodeToBuffer(input: string, options?: DduOptions): Buffer;
+    /**
+     * 인코딩된 문자열을 원본 문자열로 디코딩합니다.
+     *
+     * @param input - 디코딩할 인코딩된 문자열
+     * @param options - 디코딩 옵션
+     * @returns 디코딩된 문자열
+     *
+     * @throws 잘못된 문자나 패딩 형식일 경우 에러
+     */
+    decode(input: string, options?: DduOptions): string;
+    /**
+     * 공개 스트림 API의 auto-detect 경로에서 사용하는 전용 디코더입니다.
+     * 스트림 인코딩은 compress -> encrypt -> encode 순서를 사용하므로,
+     * 복원은 decode -> decrypt -> decompress 순서로 수행합니다.
+     */
+    decodeStreamToBuffer(input: string, options?: DduOptions): Buffer;
+    /**
+     * 현재 인코더의 charset 정보를 반환합니다.
+     *
+     * @returns charset 설정 정보 객체
+     */
+    getCharSetInfo(): {
+        charSet: string[];
+        paddingChar: string;
+        charLength: number;
+        bitLength: number;
+        usePowerOfTwo: boolean;
+        encoding: BufferEncoding;
+        defaultCompress: boolean;
+        defaultMaxDecodedBytes: number;
+        defaultMaxDecompressedBytes: number;
+        urlSafe: boolean;
+        hasEncryptionKey: boolean;
+        defaultChecksum: boolean;
+        defaultChunkSize: number | undefined;
+        defaultChunkSeparator: string;
+        defaultCompressionLevel: number;
+        defaultCompressionAlgorithm: "deflate" | "brotli";
+    };
+    /**
+     * 외부 스트림 파이프라인에서 전처리된 Buffer를 그대로 인코딩합니다.
+     * 압축/암호화는 수행하지 않고, 마지막 푸터에만 메타데이터를 반영합니다.
+     */
+    encodeRawBuffer(input: Buffer, options?: {
+        compressionAlgorithm?: "deflate" | "brotli";
+        encrypted?: boolean;
+        omitFooter?: boolean;
+    }): string;
+    /**
+     * 인코딩 통계 정보를 반환합니다.
+     *
+     * @param input - 분석할 데이터
+     * @param options - 인코딩 옵션
+     * @returns 통계 정보 객체
+     */
+    getStats(input: Buffer | string, options?: DduOptions): DduEncodeStats;
+    /**
+     * 비동기 인코딩을 수행합니다.
+     *
+     * 가능한 경우 청크 단위로 Event Loop를 양보(Yield)하여 스타베이션을 줄입니다.
+     * 다만 압축, 체크섬, 암호화, URL-safe가 개입되는 큰 입력은 정확성을 위해
+     * 안전한 단일 페이로드 경로로 fallback 됩니다.
+     *
+     * @param input - 인코딩할 데이터
+     * @param options - 인코딩 옵션
+     * @returns 인코딩된 문자열 Promise
+     */
+    encodeAsync(input: Buffer | string, options?: DduOptions): Promise<string>;
+    /**
+     * 비동기 디코딩을 수행합니다.
+     *
+     * 대용량 데이터를 처리할 때 Event Loop를 양보하여 블로킹을 방지합니다.
+     *
+     * @param input - 디코딩할 인코딩된 문자열
+     * @param options - 디코딩 옵션
+     * @returns 디코딩된 문자열 Promise
+     */
+    decodeAsync(input: string, options?: DduOptions): Promise<string>;
+    /**
+     * 비동기 디코딩을 Buffer로 수행합니다.
+     *
+     * @param input - 디코딩할 인코딩된 문자열
+     * @param options - 디코딩 옵션
+     * @returns 디코딩된 Buffer Promise
+     *
+     * @description
+     * 큰 입력 중에서도 압축, 암호화, 체크섬, 청크 구분자 해석이 필요한 경우에는
+     * 안전성을 위해 내부적으로 전체 페이로드 단위 디코딩으로 fallback 될 수 있습니다.
+     */
+    decodeToBufferAsync(input: string, options?: DduOptions): Promise<Buffer>;
+    /**
+     * 데이터를 AES-256-GCM으로 암호화합니다.
+     */
+    private encryptData;
+    /**
+     * AES-256-GCM으로 암호화된 데이터를 복호화합니다.
+     */
+    private decryptData;
+    /**
+     * 공개 스트림 API의 암호화 포맷(iv + encrypted + authTag)을 복호화합니다.
+     */
+    private decryptStreamData;
+    /**
+     * 공개 스트림 API에서 사용할 암호화 Transform을 생성합니다.
+     */
+    createEncryptionStream(): GcmEncryptStream | undefined;
+    /**
+     * 공개 스트림 API에서 사용할 복호화 Transform을 생성합니다.
+     */
+    createDecryptionStream(): GcmDecryptStream | undefined;
+    /**
+     * 옵션 값을 정규화합니다.
+     */
+    private normalizeLimit;
+    /**
+     * 압축 레벨을 알고리즘별 지원 범위에 맞춰 정규화합니다.
+     */
+    private normalizeCompressionLevel;
+    /**
+     * 디코딩 결과 바이트 수를 추정합니다.
+     */
+    private estimateDecodedBytes;
+    /**
+     * 인코딩된 입력의 정렬을 검증합니다.
+     */
+    private assertEncodedInputAligned;
+    /**
+     * 크기 제한을 적용하여 압축을 해제합니다.
+     */
+    private inflateWithLimit;
+    /**
+     * 인코딩된 문자열의 푸터(패딩 정보)를 파싱합니다.
+     *
+     * 푸터 형식: {encodedData}{paddingChar}[ELYSIA][ENC]{digits}
+     * 끝에서부터 역순으로 파싱하여 paddingChar가 숫자인 경우도 안전하게 처리합니다.
+     */
+    private parseFooter;
+    /**
+     * 일반 정수 연산을 사용한 빠른 인코딩
+     */
+    private encodeFast;
+    /**
+     * 일반 정수 연산을 사용한 빠른 디코딩
+     */
+    private decodeFast;
+    /**
+     * BigInt를 사용한 대형 비트 인코딩
+     */
+    private encodeBigInt;
+    /**
+     * 인코딩 파트 배열을 최종 문자열로 직렬화합니다.
+     * 청크 옵션이 있으면 join 후 split하는 대신 한 번에 separator를 삽입합니다.
+     */
+    private serializeEncodedParts;
+    /**
+     * BigInt를 사용한 대형 비트 디코딩
+     */
+    private decodeBigInt;
+    /**
+     * Charset을 정규화합니다.
+     */
+    private normalizeCharSet;
+    /**
+     * 초기 charset을 결정합니다.
+     */
+    private resolveInitialCharSet;
+    /**
+     * Fallback charset을 반환합니다.
+     */
+    private getFallbackCharSet;
+    /**
+     * 2의 제곱수 사용 여부를 결정합니다.
+     */
+    private shouldUsePowerOfTwo;
+    /**
+     * charset을 가져오거나 에러를 발생시킵니다.
+     */
+    private getCharSetOrThrow;
+    /**
+     * URL-Safe 모드 시 charset/padding이 역변환 대상 문자를 포함하지 않는지 검증합니다.
+     * 역변환 대상 문자("-", "_", ".")가 charset이나 padding에 있으면
+     * fromUrlSafe 시 해당 문자가 "+", "/", "="로 변환되어 데이터가 손상됩니다.
+     *
+     * @returns URL-Safe 모드를 활성화해도 안전한 경우 true
+     */
+    private isUrlSafeCompatible;
+    /**
+     * 커스텀 charset의 조합 중복을 검증합니다.
+     */
+    private validateCombinationDuplicates;
+}
+
+/**
+ * 커스텀 Charset을 쉽게 생성하기 위한 빌더 클래스
+ *
+ * @example
+ * const chars = CharsetBuilder
+ *   .fromUnicodeRange(0x4E00, 0x4E3F)
+ *   .excludeConfusing()
+ *   .shuffle()
+ *   .build();
+ */
+declare class CharsetBuilder {
+    private chars;
+    private constructor();
+    /**
+     * 빈 빌더를 생성합니다.
+     */
+    static create(): CharsetBuilder;
+    /**
+     * 유니코드 범위에서 문자들을 추가합니다.
+     *
+     * @param start - 시작 유니코드 코드포인트
+     * @param end - 끝 유니코드 코드포인트 (포함)
+     */
+    static fromUnicodeRange(start: number, end: number): CharsetBuilder;
+    /**
+     * 문자열에서 문자들을 추가합니다.
+     *
+     * @param chars - 문자열 또는 문자 배열
+     */
+    static fromString(chars: string | string[]): CharsetBuilder;
+    /**
+     * Base64 표준 문자셋으로 시작합니다.
+     */
+    static base64(): CharsetBuilder;
+    /**
+     * Base32 표준 문자셋으로 시작합니다.
+     */
+    static base32(): CharsetBuilder;
+    /**
+     * 영문 대문자만 포함합니다.
+     */
+    static uppercase(): CharsetBuilder;
+    /**
+     * 영문 소문자만 포함합니다.
+     */
+    static lowercase(): CharsetBuilder;
+    /**
+     * 숫자만 포함합니다.
+     */
+    static digits(): CharsetBuilder;
+    /**
+     * 한글 자모를 포함합니다.
+     */
+    static hangulJamo(): CharsetBuilder;
+    /**
+     * 유니코드 범위에서 문자들을 추가합니다.
+     */
+    addUnicodeRange(start: number, end: number): CharsetBuilder;
+    /**
+     * 문자열에서 문자들을 추가합니다.
+     */
+    addString(chars: string | string[]): CharsetBuilder;
+    /**
+     * 특정 문자들을 추가합니다.
+     */
+    add(...chars: string[]): CharsetBuilder;
+    /**
+     * 혼동하기 쉬운 문자들을 제거합니다.
+     * (0, O, o, 1, l, I, i 등)
+     */
+    excludeConfusing(): CharsetBuilder;
+    /**
+     * 특정 문자들을 제거합니다.
+     */
+    exclude(...chars: string[]): CharsetBuilder;
+    /**
+     * URL에서 안전하지 않은 문자들을 제거합니다.
+     */
+    excludeUrlUnsafe(): CharsetBuilder;
+    /**
+     * 중복 문자를 제거합니다.
+     */
+    unique(): CharsetBuilder;
+    /**
+     * 문자셋을 무작위로 섞습니다.
+     */
+    shuffle(seed?: number): CharsetBuilder;
+    /**
+     * 시드 기반 난수 생성기 (xorshift32)
+     */
+    private seededRandom;
+    /**
+     * 특정 길이로 자릅니다.
+     */
+    limit(length: number): CharsetBuilder;
+    /**
+     * 2의 제곱수 길이로 자릅니다.
+     */
+    limitToPowerOfTwo(): CharsetBuilder;
+    /**
+     * 문자셋을 정렬합니다.
+     */
+    sort(): CharsetBuilder;
+    /**
+     * 역순으로 정렬합니다.
+     */
+    reverse(): CharsetBuilder;
+    /**
+     * 현재 문자 수를 반환합니다.
+     */
+    get length(): number;
+    /**
+     * 문자셋을 문자열로 빌드합니다.
+     */
+    buildString(): string;
+    /**
+     * 문자셋을 배열로 빌드합니다.
+     */
+    build(): string[];
+    /**
+     * 문자셋과 패딩 문자를 함께 빌드합니다.
+     *
+     * @param paddingChar - 패딩 문자 (기본값: charset에서 제외된 첫 번째 문자)
+     */
+    buildWithPadding(paddingChar?: string): {
+        charset: string[];
+        padding: string;
+    };
+}
+
+/**
+ * 다중 인코딩/암호화/압축을 파이프라인으로 조합할 수 있는 빌더 클래스
+ *
+ * @example
+ * const pipeline = new DduPipeline()
+ *   .compress()
+ *   .encrypt('secret-key')
+ *   .encode(new Ddu64(chars, pad));
+ *
+ * const encoded = pipeline.process('Hello World');
+ * const decoded = pipeline.reverse().process(encoded);
+ */
+declare class DduPipeline {
+    private steps;
+    /**
+     * 압축 단계를 추가합니다.
+     *
+     * @param level - 압축 레벨 (0-9, 기본값: 9)
+     * @param algorithm - 압축 알고리즘 (기본값: "deflate")
+     */
+    compress(level?: number, algorithm?: "deflate" | "brotli"): DduPipeline;
+    /**
+     * 압축 해제 단계를 추가합니다.
+     *
+     * @param maxDecompressedBytes - 최대 압축해제 바이트 수 (Zip Bomb 방어용)
+     * @param algorithm - 압축 알고리즘 (기본값: "deflate")
+     */
+    decompress(maxDecompressedBytes?: number, algorithm?: "deflate" | "brotli"): DduPipeline;
+    /**
+     * AES-256-GCM 암호화 단계를 추가합니다.
+     *
+     * @param key - 암호화 키
+     */
+    encrypt(key: string): DduPipeline;
+    /**
+     * AES-256-GCM 복호화 단계를 추가합니다.
+     *
+     * @param key - 복호화 키
+     */
+    decrypt(key: string): DduPipeline;
+    /**
+     * Ddu64 인코딩 단계를 추가합니다.
+     *
+     * @param encoder - Ddu64 인코더 인스턴스
+     */
+    encode(encoder: Ddu64): DduPipeline;
+    /**
+     * Ddu64 디코딩 단계를 추가합니다.
+     *
+     * @param encoder - Ddu64 인코더 인스턴스
+     */
+    decode(encoder: Ddu64): DduPipeline;
+    /**
+     * 새 인코더를 생성하여 인코딩 단계를 추가합니다.
+     *
+     * @param dduChar - charset 문자열 또는 배열
+     * @param paddingChar - 패딩 문자
+     * @param options - 인코더 옵션
+     */
+    encodeWith(dduChar?: string[] | string, paddingChar?: string, options?: DduConstructorOptions): DduPipeline;
+    /**
+     * 커스텀 Buffer 변환 단계를 추가합니다.
+     *
+     * @param fn - 변환 함수
+     */
+    transform(fn: (data: Buffer) => Buffer): DduPipeline;
+    /**
+     * 커스텀 문자열 변환 단계를 추가합니다.
+     *
+     * @param fn - 변환 함수
+     */
+    transformString(fn: (data: string) => string): DduPipeline;
+    /**
+     * 파이프라인을 역순으로 실행할 새 파이프라인을 생성합니다.
+     */
+    reverse(): DduPipeline;
+    /**
+     * 파이프라인을 실행합니다.
+     *
+     * @param input - 입력 데이터 (문자열 또는 Buffer)
+     * @returns 처리된 결과 (문자열 또는 Buffer)
+     */
+    process(input: string | Buffer): string | Buffer;
+    /**
+     * 파이프라인을 실행하고 문자열로 반환합니다.
+     */
+    processToString(input: string | Buffer, encoding?: BufferEncoding): string;
+    /**
+     * 파이프라인을 실행하고 Buffer로 반환합니다.
+     */
+    processToBuffer(input: string | Buffer, encoding?: BufferEncoding): Buffer;
+    /**
+     * 개별 단계를 실행합니다.
+     */
+    private executeStep;
+    private toBuffer;
+    private toString;
+    private compressData;
+    private decompressData;
+    private encryptData;
+    private decryptData;
+    /**
+     * 현재 파이프라인의 단계 수를 반환합니다.
+     */
+    get stepCount(): number;
+    /**
+     * 파이프라인을 복제합니다.
+     */
+    clone(): DduPipeline;
+    /**
+     * 파이프라인을 초기화합니다.
+     */
+    clear(): DduPipeline;
+}
+
+/**
+ * Ddu64 인코딩을 위한 Transform 스트림
+ * (내부적으로 청크 단위 인코딩을 수행합니다. 압축이 필요한 경우
+ * `createEncodeStream` 팩토리 함수를 사용하는 것을 권장합니다.)
+ *
+ * @example
+ * const encoder = new Ddu64(chars, pad);
+ * const stream = new DduEncodeStream(encoder);
+ * fs.createReadStream('input.bin')
+ *   .pipe(stream)
+ *   .pipe(fs.createWriteStream('output.txt'));
+ */
+declare class DduEncodeStream extends Transform {
+    private encoder;
+    private buffers;
+    private bufferOffset;
+    private totalLength;
+    private chunkSize;
+    private footerCompressionAlgorithm;
+    private footerEncrypted;
+    constructor(encoder: Ddu64, options?: DduOptions & TransformOptions);
+    /**
+     * 비트 길이에 맞는 최적의 청크 크기를 계산합니다.
+     */
+    private calculateChunkSize;
+    _transform(chunk: Buffer, _encoding: BufferEncoding, callback: TransformCallback): void;
+    _flush(callback: TransformCallback): void;
+    private encodeChunk;
+    private readBytes;
+}
+/**
+ * Ddu64 디코딩을 위한 Transform 스트림
+ * (내부적으로 청크 단위 디코딩을 수행합니다. 압축 해제가 필요한 경우
+ * `createDecodeStream` 팩토리 함수를 사용하는 것을 권장합니다.)
+ *
+ * @example
+ * const encoder = new Ddu64(chars, pad);
+ * const stream = new DduDecodeStream(encoder);
+ * fs.createReadStream('input.txt')
+ *   .pipe(stream)
+ *   .pipe(fs.createWriteStream('output.bin'));
+ */
+declare class DduDecodeStream extends Transform {
+    private encoder;
+    private options;
+    private normalizedBuffer;
+    private charLength;
+    private chunkSize;
+    private chunkSeparator;
+    private separatorTail;
+    constructor(encoder: Ddu64, options?: DduOptions & TransformOptions);
+    private calculateChunkSize;
+    _transform(chunk: Buffer, _encoding: BufferEncoding, callback: TransformCallback): void;
+    _flush(callback: TransformCallback): void;
+    private appendNormalizedChunk;
+}
+/**
+ * Ddu64 인코더에서 스트림을 생성하는 팩토리 함수
+ * 옵션에 따라 압축 스트림을 자동으로 연결합니다.
+ */
+declare function createEncodeStream(encoder: Ddu64, options?: DduOptions & TransformOptions): NodeJS.ReadWriteStream;
+/**
+ * Ddu64 인코더에서 디코드 스트림을 생성하는 팩토리 함수
+ * 옵션에 따라 압축 해제 스트림을 자동으로 연결합니다.
+ * 기본적으로 footer를 끝까지 읽어 압축/암호화를 자동 감지합니다.
+ * 진짜 스트리밍 복원을 원하면 `streamAutoDetect: false`와 함께 encode 측과 동일한
+ * compress/encryption 설정 또는 같은 encoder 기본값을 사용해야 합니다.
+ */
+declare function createDecodeStream(encoder: Ddu64, options?: DduOptions & TransformOptions): NodeJS.ReadWriteStream;
+
+export { BaseDdu, type CharSetConfig, CharsetBuilder, Ddu64, type DduConstructorOptions, DduDecodeStream, type DduEncodeStats, DduEncodeStream, type DduOptions, DduPipeline, type DduProgressInfo, DduSetSymbol, createDecodeStream, createEncodeStream };