@ddunigma/node 2.0.0 → 2.0.2

package/dist/cjs/encoders/Ddu64.d.ts

@@ -1,27 +1,116 @@
 import { BaseDdu } from "../base/BaseDdu";
 import { DduConstructorOptions, DduOptions } from "../types";
+/**
+ * 커스텀 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);
+ */
 export 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;
+    /**
+     * 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);
     /**
-     * 데이터를 DDU 포맷으로 인코딩합니다.
-     * 성능을 위해 24비트 이하는 Fast Path(number 연산)를 사용합니다.
+     * 입력 데이터를 인코딩합니다.
+     *
+     * @param input - 인코딩할 문자열 또는 Buffer
+     * @param options - 인코딩 옵션
+     * @param options.compress - 압축 사용 여부 (기본값: 생성자 설정)
+     * @returns 인코딩된 문자열
+     *
+     * @example
+     * encoder.encode("Hello World!");
+     * encoder.encode(buffer, { compress: true });
      */
-    encode(input: Buffer | string, _options?: DduOptions): string;
+    encode(input: Buffer | string, options?: DduOptions): string;
     /**
-     * DDU 포맷 문자열을 버퍼로 디코딩합니다.
+     * 인코딩된 문자열을 Buffer로 디코딩합니다.
+     *
+     * @param input - 디코딩할 인코딩된 문자열
+     * @param options - 디코딩 옵션
+     * @param options.maxDecodedBytes - 최대 디코딩 바이트 수
+     * @param options.maxDecompressedBytes - 최대 압축해제 바이트 수
+     * @returns 디코딩된 Buffer
+     *
+     * @throws 잘못된 문자가 포함된 경우
+     * @throws 패딩 형식이 잘못된 경우
+     * @throws 크기 제한 초과 시
+     */
+    decodeToBuffer(input: string, options?: DduOptions): Buffer;
+    /**
+     * 인코딩된 문자열을 원본 문자열로 디코딩합니다.
+     *
+     * @param input - 디코딩할 인코딩된 문자열
+     * @param options - 디코딩 옵션
+     * @returns 디코딩된 문자열
+     *
+     * @throws 잘못된 문자나 패딩 형식일 경우 에러
+     */
+    decode(input: string, options?: DduOptions): string;
+    /**
+     * 현재 인코더의 charset 정보를 반환합니다.
+     *
+     * @returns charset 설정 정보 객체
      */
-    decodeToBuffer(input: string, _options?: DduOptions): Buffer;
-    decode(input: string, _options?: DduOptions): string;
     getCharSetInfo(): {
         charSet: string[];
         paddingChar: string;
@@ -29,20 +118,68 @@ export declare class Ddu64 extends BaseDdu {
         bitLength: number;
         usePowerOfTwo: boolean;
         encoding: BufferEncoding;
+        defaultCompress: boolean;
+        defaultMaxDecodedBytes: number;
+        defaultMaxDecompressedBytes: number;
     };
+    /**
+     * 옵션 값을 정규화합니다.
+     */
+    private normalizeLimit;
+    /**
+     * 디코딩 결과 바이트 수를 추정합니다.
+     */
+    private estimateDecodedBytes;
+    /**
+     * 인코딩된 입력의 정렬을 검증합니다.
+     */
+    private assertEncodedInputAligned;
+    /**
+     * 크기 제한을 적용하여 압축을 해제합니다.
+     */
+    private inflateWithLimit;
+    /**
+     * 인코딩된 문자열의 푸터(패딩 정보)를 파싱합니다.
+     */
+    private parseFooter;
+    /**
+     * 일반 정수 연산을 사용한 빠른 인코딩
+     */
     private encodeFast;
+    /**
+     * 일반 정수 연산을 사용한 빠른 디코딩
+     */
     private decodeFast;
+    /**
+     * BigInt를 사용한 대형 비트 인코딩
+     */
     private encodeBigInt;
+    /**
+     * BigInt를 사용한 대형 비트 디코딩
+     */
     private decodeBigInt;
-    private parsePaddingAndGetInput;
     /**
-     * 입력된 CharSet을 검증하고 정리(Normalization)합니다.
-     * 문제가 발생하면 옵션에 따라 Error를 던지거나 Fallback CharSet을 반환합니다.
+     * Charset을 정규화합니다.
      */
     private normalizeCharSet;
+    /**
+     * 초기 charset을 결정합니다.
+     */
     private resolveInitialCharSet;
+    /**
+     * Fallback charset을 반환합니다.
+     */
     private getFallbackCharSet;
+    /**
+     * 2의 제곱수 사용 여부를 결정합니다.
+     */
     private shouldUsePowerOfTwo;
+    /**
+     * charset을 가져오거나 에러를 발생시킵니다.
+     */
     private getCharSetOrThrow;
+    /**
+     * 커스텀 charset의 조합 중복을 검증합니다.
+     */
     private validateCombinationDuplicates;
 }