@ddunigma/node 2.0.2 → 2.1.1

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

@@ -1,5 +1,5 @@
 import { BaseDdu } from "../base/BaseDdu";
-import { DduConstructorOptions, DduOptions } from "../types";
+import { DduConstructorOptions, DduOptions, DduEncodeStats } from "../types";
 /**
  * 커스텀 charset을 사용하는 Base64 스타일 인코더
  *
@@ -50,6 +50,18 @@ export declare class Ddu64 extends BaseDdu {
     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;
     /**
      * Ddu64 인코더 인스턴스를 생성합니다.
      *
@@ -75,13 +87,23 @@ export declare class Ddu64 extends BaseDdu {
      * @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로 디코딩합니다.
      *
@@ -89,11 +111,13 @@ export declare class Ddu64 extends BaseDdu {
      * @param options - 디코딩 옵션
      * @param options.maxDecodedBytes - 최대 디코딩 바이트 수
      * @param options.maxDecompressedBytes - 최대 압축해제 바이트 수
+     * @param options.onProgress - 진행률 콜백
      * @returns 디코딩된 Buffer
      *
      * @throws 잘못된 문자가 포함된 경우
      * @throws 패딩 형식이 잘못된 경우
      * @throws 크기 제한 초과 시
+     * @throws 체크섬 불일치 시
      */
     decodeToBuffer(input: string, options?: DduOptions): Buffer;
     /**
@@ -121,7 +145,89 @@ export declare class Ddu64 extends BaseDdu {
         defaultCompress: boolean;
         defaultMaxDecodedBytes: number;
         defaultMaxDecompressedBytes: number;
+        urlSafe: boolean;
+        hasEncryptionKey: boolean;
+        defaultChecksum: boolean;
+        defaultChunkSize: number | undefined;
     };
+    /**
+     * 인코딩 통계 정보를 반환합니다.
+     *
+     * @param input - 분석할 데이터
+     * @param options - 인코딩 옵션
+     * @returns 통계 정보 객체
+     */
+    getStats(input: Buffer | string, options?: DduOptions): DduEncodeStats;
+    /**
+     * 비동기 인코딩을 수행합니다.
+     *
+     * 내부적으로 동기 encode()를 setImmediate로 이벤트 루프에 양보한 뒤 실행합니다.
+     * 호출자가 즉시 블로킹되지 않도록 보장하지만, 인코딩 자체는 단일 동기 작업으로
+     * 수행되므로 대용량 데이터(수 MB 이상) 처리 시 이벤트 루프가 블로킹될 수 있습니다.
+     * 대용량 처리가 필요한 경우 스트림 API(createEncodeStream) 사용을 권장합니다.
+     *
+     * @param input - 인코딩할 데이터
+     * @param options - 인코딩 옵션
+     * @returns 인코딩된 문자열 Promise
+     */
+    encodeAsync(input: Buffer | string, options?: DduOptions): Promise<string>;
+    /**
+     * 비동기 디코딩을 수행합니다.
+     *
+     * 내부적으로 동기 decode()를 setImmediate로 이벤트 루프에 양보한 뒤 실행합니다.
+     * 대용량 처리가 필요한 경우 스트림 API(createDecodeStream) 사용을 권장합니다.
+     *
+     * @param input - 디코딩할 인코딩된 문자열
+     * @param options - 디코딩 옵션
+     * @returns 디코딩된 문자열 Promise
+     */
+    decodeAsync(input: string, options?: DduOptions): Promise<string>;
+    /**
+     * 비동기 디코딩을 Buffer로 수행합니다.
+     *
+     * 내부적으로 동기 decodeToBuffer()를 setImmediate로 이벤트 루프에 양보한 뒤 실행합니다.
+     * 대용량 처리가 필요한 경우 스트림 API(createDecodeStream) 사용을 권장합니다.
+     *
+     * @param input - 디코딩할 인코딩된 문자열
+     * @param options - 디코딩 옵션
+     * @returns 디코딩된 Buffer Promise
+     */
+    decodeToBufferAsync(input: string, options?: DduOptions): Promise<Buffer>;
+    /**
+     * 문자열을 URL-Safe 형식으로 변환합니다.
+     * 단일 정규식 패스로 처리하여 split/join 3회 반복 대비 메모리/속도 개선
+     */
+    private toUrlSafe;
+    /**
+     * URL-Safe 형식에서 원래 형식으로 복원합니다.
+     */
+    private fromUrlSafe;
+    /**
+     * CRC32 체크섬을 계산합니다. (룩업 테이블 사용)
+     */
+    private calculateCRC32;
+    /**
+     * 인코딩된 문자열에서 체크섬을 추출합니다.
+     */
+    private extractChecksum;
+    /**
+     * 문자열을 청크로 분할합니다.
+     */
+    private splitIntoChunks;
+    /**
+     * 청크 구분자를 제거합니다.
+     * 줄바꿈(\r, \n)과 인스턴스에 설정된 청크 구분자만 제거합니다.
+     * 공백/탭 등은 charset에 포함될 수 있으므로 제거하지 않습니다.
+     */
+    private removeChunks;
+    /**
+     * 데이터를 AES-256-GCM으로 암호화합니다.
+     */
+    private encryptData;
+    /**
+     * AES-256-GCM으로 암호화된 데이터를 복호화합니다.
+     */
+    private decryptData;
     /**
      * 옵션 값을 정규화합니다.
      */
@@ -140,6 +246,9 @@ export declare class Ddu64 extends BaseDdu {
     private inflateWithLimit;
     /**
      * 인코딩된 문자열의 푸터(패딩 정보)를 파싱합니다.
+     *
+     * 푸터 형식: {encodedData}{paddingChar}[ELYSIA][ENC]{digits}
+     * 끝에서부터 역순으로 파싱하여 paddingChar가 숫자인 경우도 안전하게 처리합니다.
      */
     private parseFooter;
     /**
@@ -178,6 +287,14 @@ export declare class Ddu64 extends BaseDdu {
      * charset을 가져오거나 에러를 발생시킵니다.
      */
     private getCharSetOrThrow;
+    /**
+     * URL-Safe 모드 시 charset/padding이 역변환 대상 문자를 포함하지 않는지 검증합니다.
+     * 역변환 대상 문자("-", "_", ".")가 charset이나 padding에 있으면
+     * fromUrlSafe 시 해당 문자가 "+", "/", "="로 변환되어 데이터가 손상됩니다.
+     *
+     * @returns URL-Safe 모드를 활성화해도 안전한 경우 true
+     */
+    private isUrlSafeCompatible;
     /**
      * 커스텀 charset의 조합 중복을 검증합니다.
      */