@ddunigma/node 2.0.1 → 2.1.1

package/dist/mjs/encoders/Ddu64.js

@@ -1,27 +1,163 @@
-import { BaseDdu } from "../base/BaseDdu";
-import { DduSetSymbol, dduDefaultConstructorOptions, } from "../types";
-import { getCharSet } from "../charSets";
+import { deflateSync } from "zlib";
+import { BaseDdu } from "../base/BaseDdu.js";
+import { DduSetSymbol, dduDefaultConstructorOptions, } from "../types/index.js";
+import { getCharSet } from "../charSets/index.js";
+import { deriveKey, encryptAes256Gcm, decryptAes256Gcm, inflateWithLimit as inflateWithLimitUtil, } from "../utils/crypto.js";
+// ============================================================================
+// 상수 정의
+// ============================================================================
+/** 바이트당 비트 수 */
+const BYTE_BITS = 8;
+/** 일반 정수 연산이 가능한 최대 비트 길이 (초과 시 BigInt 사용) */
+const MAX_FAST_BITS = 16;
+/** 바이트 마스크 (0xFF) */
+const BYTE_MASK = 0xff;
+/** 압축 데이터 식별 마커 */
+const COMPRESS_MARKER = "ELYSIA";
+/** 체크섬 마커 */
+const CHECKSUM_MARKER = "CHK";
+/** 암호화 마커 */
+const ENCRYPT_MARKER = "ENC";
+/** 기본 최대 디코딩 바이트 수 (64MB) */
+const DEFAULT_MAX_DECODED_BYTES = 64 * 1024 * 1024;
+/** 기본 최대 압축해제 바이트 수 (64MB) */
+const DEFAULT_MAX_DECOMPRESSED_BYTES = 64 * 1024 * 1024;
+/** CRC32 룩업 테이블 (바이트 단위 연산으로 비트 루프 대비 4~8배 빠름) */
+const CRC32_TABLE = (() => {
+    const table = new Uint32Array(256);
+    for (let i = 0; i < 256; i++) {
+        let crc = i;
+        for (let j = 0; j < 8; j++) {
+            crc = (crc >>> 1) ^ (crc & 1 ? 0xedb88320 : 0);
+        }
+        table[i] = crc;
+    }
+    return table;
+})();
+/** URL-Safe 문자 매핑 */
+const URL_SAFE_MAP = {
+    "+": "-",
+    "/": "_",
+    "=": ".",
+};
+/** URL-Safe 역방향 매핑 */
+const URL_SAFE_REVERSE_MAP = {
+    "-": "+",
+    "_": "/",
+    ".": "=",
+};
+/** 인코딩 진행률 단계별 퍼센트 */
+const ENCODE_PROGRESS = {
+    START: 0,
+    ENCRYPT: 15,
+    CHECKSUM: 20,
+    COMPRESS: 40,
+    ENCODE: 50,
+    DONE: 100,
+};
+/** 디코딩 진행률 단계별 퍼센트 */
+const DECODE_PROGRESS = {
+    START: 0,
+    DECODE: 20,
+    DECOMPRESS: 50,
+    CHECKSUM: 70,
+    DECRYPT: 85,
+    DONE: 100,
+};
+// ============================================================================
+// Ddu64 클래스
+// ============================================================================
+/**
+ * 커스텀 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 class Ddu64 extends BaseDdu {
-    // =========================================================================================
-    // Properties
-    // =========================================================================================
+    // --------------------------------------------------------------------------
+    // 멤버 변수
+    // --------------------------------------------------------------------------
+    /** 인코딩에 사용할 문자 배열 */
     dduChar;
+    /** 패딩 문자 */
     paddingChar;
+    /** 각 charset 문자의 길이 */
     charLength;
+    /** 비트 길이 (log2) */
     bitLength;
+    /** 2의 제곱수 charset 여부 */
     usePowerOfTwo;
+    /** 문자열 인코딩 방식 */
     encoding;
+    /** 기본 압축 사용 여부 */
+    defaultCompress;
+    /** 기본 최대 디코딩 바이트 수 */
+    defaultMaxDecodedBytes;
+    /** 기본 최대 압축해제 바이트 수 */
+    defaultMaxDecompressedBytes;
+    /** 문자 → 인덱스 역방향 룩업 맵 */
     dduBinaryLookup = new Map();
+    /** 미리 정의된 charset 사용 여부 */
     isPredefinedCharSet;
+    /** 실제 사용되는 비트 길이 */
     effectiveBitLength;
+    /** 최대 바이너리 값 */
     maxBinaryValue;
-    // =========================================================================================
-    // Constructor
-    // =========================================================================================
+    /** ASCII 문자 빠른 룩업 테이블 */
+    fastAsciiLookup = null;
+    /** ASCII 룩업 사용 여부 */
+    useAsciiLookup = false;
+    /** URL-Safe 모드 여부 */
+    urlSafe;
+    /** 암호화 키 해시 (AES-256용 32바이트) */
+    encryptionKeyHash;
+    /** 기본 체크섬 사용 여부 */
+    defaultChecksum;
+    /** 기본 청크 크기 */
+    defaultChunkSize;
+    /** 기본 청크 구분자 */
+    defaultChunkSeparator;
+    /** 기본 압축 레벨 (1~9) */
+    defaultCompressionLevel;
+    // --------------------------------------------------------------------------
+    // 생성자
+    // --------------------------------------------------------------------------
+    /**
+     * 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, paddingChar, dduOptions) {
         super();
-        const shouldThrow = dduOptions?.useBuildErrorReturn ?? false;
-        // 1. CharSet 초기화 및 검증
+        // throwOnError 우선, useBuildErrorReturn은 하위 호환
+        const shouldThrow = dduOptions?.throwOnError ?? dduOptions?.useBuildErrorReturn ?? false;
+        // charset 초기화
         const initial = this.resolveInitialCharSet(dduChar, paddingChar, dduOptions, shouldThrow);
         const normalized = this.normalizeCharSet(initial, shouldThrow, dduOptions);
         this.dduChar = normalized.charSet;
@@ -29,48 +165,259 @@ export class Ddu64 extends BaseDdu {
         this.charLength = normalized.charLength;
         this.isPredefinedCharSet = normalized.isPredefined;
         this.encoding = dduOptions?.encoding ?? this.defaultEncoding;
-        // 2. 비트 연산 상수 계산
+        this.defaultCompress = dduOptions?.compress ?? false;
+        // 제한값 설정
+        this.defaultMaxDecodedBytes = this.normalizeLimit(dduOptions?.maxDecodedBytes, DEFAULT_MAX_DECODED_BYTES, shouldThrow, "maxDecodedBytes");
+        this.defaultMaxDecompressedBytes = this.normalizeLimit(dduOptions?.maxDecompressedBytes, DEFAULT_MAX_DECOMPRESSED_BYTES, shouldThrow, "maxDecompressedBytes");
+        // 비트 길이 계산
         const dduLength = this.dduChar.length;
-        this.usePowerOfTwo = dduLength > 0 && (dduLength & (dduLength - 1)) === 0;
+        this.usePowerOfTwo =
+            dduLength > 0 && (dduLength & (dduLength - 1)) === 0;
         const computedBitLength = this.getBitLength(dduLength);
-        this.bitLength = this.usePowerOfTwo ? this.getLargestPowerOfTwoExponent(dduLength) : computedBitLength;
-        this.effectiveBitLength = this.usePowerOfTwo ? this.bitLength : computedBitLength;
-        this.maxBinaryValue = 2 ** this.effectiveBitLength;
-        // 3. Lookup Table 생성 (Decoding용)
+        this.bitLength = this.usePowerOfTwo
+            ? this.getLargestPowerOfTwoExponent(dduLength)
+            : computedBitLength;
+        this.effectiveBitLength = this.usePowerOfTwo
+            ? this.bitLength
+            : computedBitLength;
+        this.maxBinaryValue =
+            this.effectiveBitLength < 31
+                ? 1 << this.effectiveBitLength
+                : Math.pow(2, this.effectiveBitLength);
+        // ASCII 룩업 테이블 초기화 (성능 최적화)
+        if (this.charLength === 1) {
+            let allAscii = true;
+            for (let i = 0; i < dduLength; i++) {
+                if (this.dduChar[i].charCodeAt(0) >= 128) {
+                    allAscii = false;
+                    break;
+                }
+            }
+            if (allAscii) {
+                this.fastAsciiLookup = new Int16Array(128).fill(-1);
+                for (let i = 0; i < dduLength; i++) {
+                    this.fastAsciiLookup[this.dduChar[i].charCodeAt(0)] = i;
+                }
+                this.useAsciiLookup = true;
+            }
+        }
+        // 역방향 룩업 맵 생성
         for (let i = 0; i < dduLength; i++) {
             this.dduBinaryLookup.set(this.dduChar[i], i);
         }
-        // 4. 안전성 검사
+        // 커스텀 charset 중복 조합 검증
         if (this.charLength === 1 && !this.isPredefinedCharSet) {
             this.validateCombinationDuplicates(this.dduChar, this.paddingChar, dduLength);
         }
+        // 새로운 옵션들 초기화
+        const requestUrlSafe = dduOptions?.urlSafe ?? false;
+        this.urlSafe = requestUrlSafe
+            ? this.isUrlSafeCompatible(this.dduChar, this.paddingChar, shouldThrow)
+            : false;
+        this.encryptionKeyHash = dduOptions?.encryptionKey
+            ? deriveKey(dduOptions.encryptionKey)
+            : undefined;
+        this.defaultChecksum = dduOptions?.checksum ?? false;
+        this.defaultChunkSize = dduOptions?.chunkSize;
+        this.defaultChunkSeparator = dduOptions?.chunkSeparator ?? "\n";
+        this.defaultCompressionLevel = Math.min(9, Math.max(1, Math.floor(dduOptions?.compressionLevel ?? 6)));
+    }
+    // --------------------------------------------------------------------------
+    // 공개 메서드
+    // --------------------------------------------------------------------------
+    /**
+     * 입력 데이터를 인코딩합니다.
+     *
+     * @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, options) {
+        return this.encodeInternal(input, options).encoded;
     }
-    // =========================================================================================
-    // Public API
-    // =========================================================================================
     /**
-     * 데이터를 DDU 포맷으로 인코딩합니다.
-     * 성능을 위해 24비트 이하는 Fast Path(number 연산)를 사용합니다.
+     * 인코딩 핵심 로직. encode()와 getStats()가 공유합니다.
+     * 압축 크기 등 메타데이터도 함께 반환하여 중복 deflateSync 호출을 방지합니다.
      */
-    encode(input, _options) {
-        const bufferInput = typeof input === "string" ? Buffer.from(input, this.encoding) : input;
-        if (this.effectiveBitLength <= 24) {
-            return this.encodeFast(bufferInput);
+    encodeInternal(input, options) {
+        const shouldCompress = options?.compress ?? this.defaultCompress;
+        const shouldChecksum = options?.checksum ?? this.defaultChecksum;
+        const chunkSize = options?.chunkSize ?? this.defaultChunkSize;
+        const chunkSeparator = options?.chunkSeparator ?? this.defaultChunkSeparator;
+        const onProgress = options?.onProgress;
+        let workingBuffer = typeof input === "string" ? Buffer.from(input, this.encoding) : input;
+        const totalBytes = workingBuffer.length;
+        // 진행률 콜백 호출 (시작)
+        if (onProgress) {
+            onProgress({ processedBytes: 0, totalBytes, percent: ENCODE_PROGRESS.START, stage: "start" });
         }
-        return this.encodeBigInt(bufferInput);
+        // 암호화 처리
+        let isEncrypted = false;
+        if (this.encryptionKeyHash) {
+            workingBuffer = this.encryptData(workingBuffer);
+            isEncrypted = true;
+            if (onProgress) {
+                onProgress({ processedBytes: 0, totalBytes, percent: ENCODE_PROGRESS.ENCRYPT, stage: "encrypt" });
+            }
+        }
+        // 체크섬 계산
+        let checksum = "";
+        if (shouldChecksum) {
+            checksum = this.calculateCRC32(workingBuffer);
+            if (onProgress) {
+                onProgress({ processedBytes: 0, totalBytes, percent: ENCODE_PROGRESS.CHECKSUM, stage: "checksum" });
+            }
+        }
+        // 압축 처리
+        let useCompression = false;
+        let compressedSize;
+        if (shouldCompress) {
+            const level = options?.compressionLevel ?? this.defaultCompressionLevel;
+            const compressedBuffer = deflateSync(workingBuffer, { level: Math.min(9, Math.max(1, level)) });
+            compressedSize = compressedBuffer.length;
+            if (compressedBuffer.length < workingBuffer.length) {
+                workingBuffer = compressedBuffer;
+                useCompression = true;
+            }
+            if (onProgress) {
+                onProgress({ processedBytes: Math.floor(totalBytes * 0.4), totalBytes, percent: ENCODE_PROGRESS.COMPRESS, stage: "compress" });
+            }
+        }
+        // 인코딩 수행
+        if (onProgress) {
+            onProgress({ processedBytes: Math.floor(totalBytes * 0.5), totalBytes, percent: ENCODE_PROGRESS.ENCODE, stage: "encode" });
+        }
+        let result = this.effectiveBitLength <= MAX_FAST_BITS
+            ? this.encodeFast(workingBuffer, useCompression, isEncrypted)
+            : this.encodeBigInt(workingBuffer, useCompression, isEncrypted);
+        // 체크섬 추가
+        if (shouldChecksum && checksum) {
+            result = result + CHECKSUM_MARKER + checksum;
+        }
+        // URL-Safe 변환
+        if (this.urlSafe) {
+            result = this.toUrlSafe(result);
+        }
+        // 청크 분할
+        if (chunkSize && chunkSize > 0) {
+            result = this.splitIntoChunks(result, chunkSize, chunkSeparator);
+        }
+        // 진행률 콜백 호출 (완료)
+        if (onProgress) {
+            onProgress({ processedBytes: totalBytes, totalBytes, percent: ENCODE_PROGRESS.DONE, stage: "done" });
+        }
+        return { encoded: result, compressedSize };
     }
     /**
-     * DDU 포맷 문자열을 버퍼로 디코딩합니다.
+     * 인코딩된 문자열을 Buffer로 디코딩합니다.
+     *
+     * @param input - 디코딩할 인코딩된 문자열
+     * @param options - 디코딩 옵션
+     * @param options.maxDecodedBytes - 최대 디코딩 바이트 수
+     * @param options.maxDecompressedBytes - 최대 압축해제 바이트 수
+     * @param options.onProgress - 진행률 콜백
+     * @returns 디코딩된 Buffer
+     *
+     * @throws 잘못된 문자가 포함된 경우
+     * @throws 패딩 형식이 잘못된 경우
+     * @throws 크기 제한 초과 시
+     * @throws 체크섬 불일치 시
      */
-    decodeToBuffer(input, _options) {
-        if (this.effectiveBitLength <= 24) {
-            return this.decodeFast(input);
+    decodeToBuffer(input, options) {
+        const shouldChecksum = options?.checksum ?? this.defaultChecksum;
+        const onProgress = options?.onProgress;
+        let workingInput = input;
+        const inputLength = input.length;
+        // 진행률 콜백 호출 (시작)
+        if (onProgress) {
+            onProgress({ processedBytes: 0, totalBytes: inputLength, percent: DECODE_PROGRESS.START, stage: "start" });
+        }
+        // 청크 제거 (줄바꿈 등 구분자 제거)
+        workingInput = this.removeChunks(workingInput);
+        // URL-Safe 역변환
+        if (this.urlSafe) {
+            workingInput = this.fromUrlSafe(workingInput);
+        }
+        // 체크섬 추출 (체크섬이 활성화된 경우에만 수행하여 오탐지 방지)
+        let extractedChecksum = null;
+        if (shouldChecksum) {
+            const result = this.extractChecksum(workingInput);
+            extractedChecksum = result.checksum;
+            workingInput = result.data;
+        }
+        const { cleanedInput, paddingBits, isCompressed, isEncrypted } = this.parseFooter(workingInput);
+        this.assertEncodedInputAligned(cleanedInput);
+        // 디코딩 크기 검증
+        const maxDecodedBytes = this.normalizeLimit(options?.maxDecodedBytes, this.defaultMaxDecodedBytes, true, "maxDecodedBytes");
+        const estimatedDecodedBytes = this.estimateDecodedBytes(cleanedInput.length, paddingBits);
+        if (estimatedDecodedBytes > maxDecodedBytes) {
+            throw new Error(`[Ddu64 decode] Decoded output exceeds limit. Estimated: ${estimatedDecodedBytes} bytes, Limit: ${maxDecodedBytes} bytes`);
+        }
+        // 디코딩 수행
+        if (onProgress) {
+            onProgress({ processedBytes: Math.floor(inputLength * 0.2), totalBytes: inputLength, percent: DECODE_PROGRESS.DECODE, stage: "decode" });
+        }
+        let decoded = this.effectiveBitLength <= MAX_FAST_BITS
+            ? this.decodeFast(cleanedInput, paddingBits)
+            : this.decodeBigInt(cleanedInput, paddingBits);
+        // 압축 해제
+        if (isCompressed) {
+            if (onProgress) {
+                onProgress({ processedBytes: Math.floor(inputLength * 0.5), totalBytes: inputLength, percent: DECODE_PROGRESS.DECOMPRESS, stage: "decompress" });
+            }
+            const maxDecompressedBytes = this.normalizeLimit(options?.maxDecompressedBytes, this.defaultMaxDecompressedBytes, true, "maxDecompressedBytes");
+            decoded = this.inflateWithLimit(decoded, maxDecompressedBytes);
+        }
+        // 체크섬 검증
+        if (extractedChecksum) {
+            if (onProgress) {
+                onProgress({ processedBytes: Math.floor(inputLength * 0.7), totalBytes: inputLength, percent: DECODE_PROGRESS.CHECKSUM, stage: "checksum" });
+            }
+            const calculatedChecksum = this.calculateCRC32(decoded);
+            if (calculatedChecksum !== extractedChecksum) {
+                throw new Error(`[Ddu64 decode] Checksum mismatch. Expected: ${extractedChecksum}, Got: ${calculatedChecksum}`);
+            }
         }
-        return this.decodeBigInt(input);
+        // 복호화
+        if (isEncrypted && this.encryptionKeyHash) {
+            if (onProgress) {
+                onProgress({ processedBytes: Math.floor(inputLength * 0.85), totalBytes: inputLength, percent: DECODE_PROGRESS.DECRYPT, stage: "decrypt" });
+            }
+            decoded = this.decryptData(decoded);
+        }
+        // 진행률 콜백 호출 (완료)
+        if (onProgress) {
+            onProgress({ processedBytes: inputLength, totalBytes: inputLength, percent: DECODE_PROGRESS.DONE, stage: "done" });
+        }
+        return decoded;
     }
-    decode(input, _options) {
-        return this.decodeToBuffer(input, _options).toString(this.encoding);
+    /**
+     * 인코딩된 문자열을 원본 문자열로 디코딩합니다.
+     *
+     * @param input - 디코딩할 인코딩된 문자열
+     * @param options - 디코딩 옵션
+     * @returns 디코딩된 문자열
+     *
+     * @throws 잘못된 문자나 패딩 형식일 경우 에러
+     */
+    decode(input, options) {
+        return this.decodeToBuffer(input, options).toString(this.encoding);
     }
+    /**
+     * 현재 인코더의 charset 정보를 반환합니다.
+     *
+     * @returns charset 설정 정보 객체
+     */
     getCharSetInfo() {
         return {
             charSet: [...this.dduChar],
@@ -79,335 +426,805 @@ export class Ddu64 extends BaseDdu {
             bitLength: this.bitLength,
             usePowerOfTwo: this.usePowerOfTwo,
             encoding: this.encoding,
+            defaultCompress: this.defaultCompress,
+            defaultMaxDecodedBytes: this.defaultMaxDecodedBytes,
+            defaultMaxDecompressedBytes: this.defaultMaxDecompressedBytes,
+            urlSafe: this.urlSafe,
+            hasEncryptionKey: !!this.encryptionKeyHash,
+            defaultChecksum: this.defaultChecksum,
+            defaultChunkSize: this.defaultChunkSize,
+        };
+    }
+    /**
+     * 인코딩 통계 정보를 반환합니다.
+     *
+     * @param input - 분석할 데이터
+     * @param options - 인코딩 옵션
+     * @returns 통계 정보 객체
+     */
+    getStats(input, options) {
+        const shouldCompress = options?.compress ?? this.defaultCompress;
+        const originalBuffer = typeof input === "string" ? Buffer.from(input, this.encoding) : input;
+        const originalSize = originalBuffer.length;
+        // encodeInternal을 통해 인코딩과 압축 크기를 한 번에 얻어 중복 deflateSync 방지
+        const { encoded, compressedSize } = this.encodeInternal(input, options);
+        const encodedSize = encoded.length;
+        const expansionRatio = originalSize > 0 ? encodedSize / originalSize : 0;
+        const compressionRatio = shouldCompress && compressedSize !== undefined && originalSize > 0
+            ? compressedSize / originalSize
+            : undefined;
+        return {
+            originalSize,
+            encodedSize,
+            compressedSize,
+            compressionRatio,
+            expansionRatio,
+            charsetSize: this.dduChar.length,
+            bitLength: this.bitLength,
+        };
+    }
+    /**
+     * 비동기 인코딩을 수행합니다.
+     *
+     * 내부적으로 동기 encode()를 setImmediate로 이벤트 루프에 양보한 뒤 실행합니다.
+     * 호출자가 즉시 블로킹되지 않도록 보장하지만, 인코딩 자체는 단일 동기 작업으로
+     * 수행되므로 대용량 데이터(수 MB 이상) 처리 시 이벤트 루프가 블로킹될 수 있습니다.
+     * 대용량 처리가 필요한 경우 스트림 API(createEncodeStream) 사용을 권장합니다.
+     *
+     * @param input - 인코딩할 데이터
+     * @param options - 인코딩 옵션
+     * @returns 인코딩된 문자열 Promise
+     */
+    async encodeAsync(input, options) {
+        return new Promise((resolve, reject) => {
+            setImmediate(() => {
+                try {
+                    resolve(this.encode(input, options));
+                }
+                catch (e) {
+                    reject(e);
+                }
+            });
+        });
+    }
+    /**
+     * 비동기 디코딩을 수행합니다.
+     *
+     * 내부적으로 동기 decode()를 setImmediate로 이벤트 루프에 양보한 뒤 실행합니다.
+     * 대용량 처리가 필요한 경우 스트림 API(createDecodeStream) 사용을 권장합니다.
+     *
+     * @param input - 디코딩할 인코딩된 문자열
+     * @param options - 디코딩 옵션
+     * @returns 디코딩된 문자열 Promise
+     */
+    async decodeAsync(input, options) {
+        return new Promise((resolve, reject) => {
+            setImmediate(() => {
+                try {
+                    resolve(this.decode(input, options));
+                }
+                catch (e) {
+                    reject(e);
+                }
+            });
+        });
+    }
+    /**
+     * 비동기 디코딩을 Buffer로 수행합니다.
+     *
+     * 내부적으로 동기 decodeToBuffer()를 setImmediate로 이벤트 루프에 양보한 뒤 실행합니다.
+     * 대용량 처리가 필요한 경우 스트림 API(createDecodeStream) 사용을 권장합니다.
+     *
+     * @param input - 디코딩할 인코딩된 문자열
+     * @param options - 디코딩 옵션
+     * @returns 디코딩된 Buffer Promise
+     */
+    async decodeToBufferAsync(input, options) {
+        return new Promise((resolve, reject) => {
+            setImmediate(() => {
+                try {
+                    resolve(this.decodeToBuffer(input, options));
+                }
+                catch (e) {
+                    reject(e);
+                }
+            });
+        });
+    }
+    // --------------------------------------------------------------------------
+    // URL-Safe 메서드
+    // --------------------------------------------------------------------------
+    /**
+     * 문자열을 URL-Safe 형식으로 변환합니다.
+     * 단일 정규식 패스로 처리하여 split/join 3회 반복 대비 메모리/속도 개선
+     */
+    toUrlSafe(input) {
+        return input.replace(/[+/=]/g, (c) => URL_SAFE_MAP[c]);
+    }
+    /**
+     * URL-Safe 형식에서 원래 형식으로 복원합니다.
+     */
+    fromUrlSafe(input) {
+        return input.replace(/[-_.]/g, (c) => URL_SAFE_REVERSE_MAP[c]);
+    }
+    // --------------------------------------------------------------------------
+    // 체크섬 메서드
+    // --------------------------------------------------------------------------
+    /**
+     * CRC32 체크섬을 계산합니다. (룩업 테이블 사용)
+     */
+    calculateCRC32(data) {
+        let crc = 0xffffffff;
+        for (let i = 0; i < data.length; i++) {
+            crc = (crc >>> 8) ^ CRC32_TABLE[(crc ^ data[i]) & 0xff];
+        }
+        return ((crc ^ 0xffffffff) >>> 0).toString(16).padStart(8, "0");
+    }
+    /**
+     * 인코딩된 문자열에서 체크섬을 추출합니다.
+     */
+    extractChecksum(input) {
+        const markerIndex = input.lastIndexOf(CHECKSUM_MARKER);
+        if (markerIndex === -1) {
+            return { data: input, checksum: null };
+        }
+        const checksum = input.slice(markerIndex + CHECKSUM_MARKER.length);
+        if (checksum.length !== 8 || !/^[0-9a-f]+$/i.test(checksum)) {
+            return { data: input, checksum: null };
+        }
+        return {
+            data: input.slice(0, markerIndex),
+            checksum: checksum.toLowerCase(),
         };
     }
-    // =========================================================================================
-    // Fast Engine (Optimized for Speed)
-    // Uses standard JS numbers (safe up to ~24 bits per chunk) to avoid BigInt GC overhead.
-    // =========================================================================================
-    encodeFast(bufferInput) {
-        const resultParts = [];
+    // --------------------------------------------------------------------------
+    // 청크 분할 메서드
+    // --------------------------------------------------------------------------
+    /**
+     * 문자열을 청크로 분할합니다.
+     */
+    splitIntoChunks(input, chunkSize, separator) {
+        if (chunkSize <= 0)
+            return input;
+        const chunks = [];
+        for (let i = 0; i < input.length; i += chunkSize) {
+            chunks.push(input.slice(i, i + chunkSize));
+        }
+        return chunks.join(separator);
+    }
+    /**
+     * 청크 구분자를 제거합니다.
+     * 줄바꿈(\r, \n)과 인스턴스에 설정된 청크 구분자만 제거합니다.
+     * 공백/탭 등은 charset에 포함될 수 있으므로 제거하지 않습니다.
+     */
+    removeChunks(input) {
+        // 줄바꿈 문자(\r, \n)는 항상 제거 (기본 구분자 및 일반적 라인 구분)
+        let result = input.replace(/[\r\n]/g, "");
+        // 커스텀 구분자가 줄바꿈이 아닌 경우 추가로 제거
+        const sep = this.defaultChunkSeparator;
+        if (sep && sep !== "\n" && sep !== "\r\n" && sep !== "\r") {
+            result = result.split(sep).join("");
+        }
+        return result;
+    }
+    // --------------------------------------------------------------------------
+    // 암호화 메서드
+    // --------------------------------------------------------------------------
+    /**
+     * 데이터를 AES-256-GCM으로 암호화합니다.
+     */
+    encryptData(data) {
+        if (!this.encryptionKeyHash) {
+            throw new Error("[Ddu64 encrypt] Encryption key is not set");
+        }
+        return encryptAes256Gcm(data, this.encryptionKeyHash);
+    }
+    /**
+     * AES-256-GCM으로 암호화된 데이터를 복호화합니다.
+     */
+    decryptData(data) {
+        if (!this.encryptionKeyHash) {
+            throw new Error("[Ddu64 decrypt] Encryption key is not set");
+        }
+        return decryptAes256Gcm(data, this.encryptionKeyHash);
+    }
+    // --------------------------------------------------------------------------
+    // 유틸리티 메서드
+    // --------------------------------------------------------------------------
+    /**
+     * 옵션 값을 정규화합니다.
+     */
+    normalizeLimit(value, fallback, shouldThrow, name) {
+        if (value === undefined)
+            return fallback;
+        if (value === Number.POSITIVE_INFINITY)
+            return Number.POSITIVE_INFINITY;
+        if (!Number.isFinite(value) || value <= 0) {
+            if (shouldThrow) {
+                throw new Error(`[Ddu64 options] Invalid ${name}. Must be a positive finite number or Infinity.`);
+            }
+            return fallback;
+        }
+        return Math.floor(value);
+    }
+    /**
+     * 디코딩 결과 바이트 수를 추정합니다.
+     */
+    estimateDecodedBytes(cleanedInputLen, paddingBits) {
+        if (cleanedInputLen === 0)
+            return 0;
+        if (paddingBits < 0 || paddingBits >= this.effectiveBitLength) {
+            throw new Error(`[Ddu64 decode] Invalid padding bits: ${paddingBits}`);
+        }
+        const chunkSize = this.usePowerOfTwo ? this.charLength : this.charLength * 2;
+        const numChunks = Math.ceil(cleanedInputLen / chunkSize);
+        const bits = numChunks * this.effectiveBitLength - paddingBits;
+        if (bits < 0)
+            throw new Error(`[Ddu64 decode] Invalid decoded bit length`);
+        return Math.ceil(bits / BYTE_BITS);
+    }
+    /**
+     * 인코딩된 입력의 정렬을 검증합니다.
+     */
+    assertEncodedInputAligned(cleanedInput) {
+        const { charLength } = this;
+        if (charLength <= 0)
+            return;
+        if (cleanedInput.length % charLength !== 0) {
+            throw new Error(`[Ddu64 decode] Invalid encoded length. Expected multiple of ${charLength}, got ${cleanedInput.length}`);
+        }
+        if (!this.usePowerOfTwo) {
+            const chunkSize = charLength * 2;
+            if (cleanedInput.length % chunkSize !== 0) {
+                throw new Error(`[Ddu64 decode] Invalid encoded length for variable charset. Expected multiple of ${chunkSize}, got ${cleanedInput.length}`);
+            }
+        }
+    }
+    /**
+     * 크기 제한을 적용하여 압축을 해제합니다.
+     */
+    inflateWithLimit(data, maxBytes) {
+        return inflateWithLimitUtil(data, maxBytes, "Ddu64 decode");
+    }
+    // --------------------------------------------------------------------------
+    // 푸터 파싱
+    // --------------------------------------------------------------------------
+    /**
+     * 인코딩된 문자열의 푸터(패딩 정보)를 파싱합니다.
+     *
+     * 푸터 형식: {encodedData}{paddingChar}[ELYSIA][ENC]{digits}
+     * 끝에서부터 역순으로 파싱하여 paddingChar가 숫자인 경우도 안전하게 처리합니다.
+     */
+    parseFooter(input) {
+        const inputLen = input.length;
+        const pad = this.paddingChar;
+        const padLen = pad.length;
+        const noFooter = { cleanedInput: input, paddingBits: 0, isCompressed: false, isEncrypted: false };
+        if (inputLen < padLen)
+            return noFooter;
+        const maxPaddingBits = Math.max(0, this.effectiveBitLength - 1);
+        const maxDigits = maxPaddingBits.toString().length;
+        // 끝에서부터 역순 파싱: digits → ENC → ELYSIA → paddingChar
+        for (let digitCount = Math.min(maxDigits, inputLen); digitCount >= 1; digitCount--) {
+            const digitsStart = inputLen - digitCount;
+            // 1) trailing digits 확인
+            let allDigits = true;
+            for (let i = digitsStart; i < inputLen; i++) {
+                const c = input.charCodeAt(i);
+                if (c < 48 || c > 57) {
+                    allDigits = false;
+                    break;
+                }
+            }
+            if (!allDigits)
+                continue;
+            const digitStr = input.substring(digitsStart);
+            const paddingBits = parseInt(digitStr, 10);
+            if (Number.isNaN(paddingBits) ||
+                paddingBits < 0 ||
+                paddingBits >= this.effectiveBitLength ||
+                digitStr !== paddingBits.toString())
+                continue;
+            // 2) digits 앞에서 마커들 역순 확인
+            let pos = digitsStart;
+            let isEncrypted = false;
+            let isCompressed = false;
+            if (pos >= ENCRYPT_MARKER.length && input.substring(pos - ENCRYPT_MARKER.length, pos) === ENCRYPT_MARKER) {
+                isEncrypted = true;
+                pos -= ENCRYPT_MARKER.length;
+            }
+            if (pos >= COMPRESS_MARKER.length && input.substring(pos - COMPRESS_MARKER.length, pos) === COMPRESS_MARKER) {
+                isCompressed = true;
+                pos -= COMPRESS_MARKER.length;
+            }
+            // 3) 마커 앞에서 padding 문자 확인
+            const padStart = pos - padLen;
+            if (padStart >= 0 && input.substring(padStart, pos) === pad) {
+                if (padStart % this.charLength !== 0) {
+                    throw new Error(`[Ddu64 decode] Invalid padding format. Misaligned padding marker`);
+                }
+                return {
+                    cleanedInput: input.substring(0, padStart),
+                    paddingBits,
+                    isCompressed,
+                    isEncrypted,
+                };
+            }
+        }
+        // Fallback: 역순 탐색이 유효한 패딩을 찾지 못한 경우,
+        // padding 문자가 존재하지만 tail이 잘못된 형식인지 확인하여 에러 보고
+        const lastPadIdx = input.lastIndexOf(pad);
+        if (lastPadIdx >= 0 && lastPadIdx % this.charLength === 0) {
+            const tailStart = lastPadIdx + padLen;
+            if (tailStart >= inputLen) {
+                throw new Error(`[Ddu64 decode] Invalid padding format. Missing padding length`);
+            }
+            const tail = input.substring(tailStart);
+            throw new Error(`[Ddu64 decode] Invalid padding format. Got: "${tail}"`);
+        }
+        return noFooter;
+    }
+    // --------------------------------------------------------------------------
+    // 인코딩 (Fast 모드 - 16비트 이하)
+    // --------------------------------------------------------------------------
+    /**
+     * 일반 정수 연산을 사용한 빠른 인코딩
+     */
+    encodeFast(bufferInput, compress, encrypt) {
+        const inputLen = bufferInput.length;
+        if (inputLen === 0)
+            return "";
         const { dduChar, effectiveBitLength: bitLength, paddingChar } = this;
         const dduLength = dduChar.length;
+        const totalBits = inputLen * BYTE_BITS;
+        const estimatedChunks = Math.ceil(totalBits / bitLength);
+        const estimatedSymbols = this.usePowerOfTwo
+            ? estimatedChunks
+            : estimatedChunks * 2;
+        const resultParts = new Array(estimatedSymbols + 3);
+        let resultIdx = 0;
         let accumulator = 0;
         let accumulatorBits = 0;
-        // Loop Unswitching: 조건문을 루프 밖으로 빼서 CPU 분기 예측 효율 향상
         if (this.usePowerOfTwo) {
-            for (const byte of bufferInput) {
-                accumulator = (accumulator << 8) | byte;
-                accumulatorBits += 8;
+            const mask = (1 << bitLength) - 1;
+            for (let i = 0; i < inputLen; i++) {
+                accumulator = (accumulator << BYTE_BITS) | bufferInput[i];
+                accumulatorBits += BYTE_BITS;
                 while (accumulatorBits >= bitLength) {
-                    const shift = accumulatorBits - bitLength;
-                    const index = accumulator >> shift;
-                    resultParts.push(dduChar[index]);
                     accumulatorBits -= bitLength;
+                    resultParts[resultIdx++] =
+                        dduChar[(accumulator >> accumulatorBits) & mask];
                     accumulator &= (1 << accumulatorBits) - 1;
                 }
             }
         }
         else {
-            for (const byte of bufferInput) {
-                accumulator = (accumulator << 8) | byte;
-                accumulatorBits += 8;
+            for (let i = 0; i < inputLen; i++) {
+                accumulator = (accumulator << BYTE_BITS) | bufferInput[i];
+                accumulatorBits += BYTE_BITS;
                 while (accumulatorBits >= bitLength) {
-                    const shift = accumulatorBits - bitLength;
-                    const index = accumulator >> shift;
-                    // 비 2의 제곱수는 나눗셈으로 인덱스 계산
-                    const div = (index / dduLength) | 0;
-                    const mod = index % dduLength;
-                    resultParts.push(dduChar[div] + dduChar[mod]);
                     accumulatorBits -= bitLength;
+                    const index = accumulator >> accumulatorBits;
+                    const div = (index / dduLength) | 0;
+                    resultParts[resultIdx++] = dduChar[div];
+                    resultParts[resultIdx++] = dduChar[index - div * dduLength];
                     accumulator &= (1 << accumulatorBits) - 1;
                 }
             }
         }
-        // 남은 비트 패딩 처리
+        // 남은 비트 처리 (패딩)
         if (accumulatorBits > 0) {
             const paddingBits = bitLength - accumulatorBits;
             const index = accumulator << paddingBits;
             if (this.usePowerOfTwo) {
-                resultParts.push(dduChar[index]);
+                resultParts[resultIdx++] = dduChar[index];
             }
             else {
                 const div = (index / dduLength) | 0;
-                const mod = index % dduLength;
-                resultParts.push(dduChar[div] + dduChar[mod]);
+                resultParts[resultIdx++] = dduChar[div];
+                resultParts[resultIdx++] = dduChar[index - div * dduLength];
             }
-            return resultParts.join("") + paddingChar + paddingBits.toString();
+            resultParts[resultIdx++] = paddingChar;
+            resultParts[resultIdx++] = (compress ? COMPRESS_MARKER : "") + (encrypt ? ENCRYPT_MARKER : "") + paddingBits.toString();
+        }
+        else if (compress || encrypt) {
+            resultParts[resultIdx++] = paddingChar;
+            resultParts[resultIdx++] = (compress ? COMPRESS_MARKER : "") + (encrypt ? ENCRYPT_MARKER : "") + "0";
         }
+        resultParts.length = resultIdx;
         return resultParts.join("");
     }
-    decodeFast(input) {
-        const { cleanedInput, paddingBits } = this.parsePaddingAndGetInput(input);
+    // --------------------------------------------------------------------------
+    // 디코딩 (Fast 모드 - 16비트 이하)
+    // --------------------------------------------------------------------------
+    /**
+     * 일반 정수 연산을 사용한 빠른 디코딩
+     */
+    decodeFast(cleanedInput, paddingBits) {
         const inputLen = cleanedInput.length;
-        const buffer = [];
+        if (inputLen === 0)
+            return Buffer.alloc(0);
+        const { effectiveBitLength: bitLength, charLength } = this;
+        const dduLength = this.dduChar.length;
+        const chunkSize = this.usePowerOfTwo ? charLength : charLength * 2;
+        const numChunks = Math.ceil(inputLen / chunkSize);
+        const estimatedBytes = Math.ceil((numChunks * bitLength - paddingBits) / BYTE_BITS);
+        const buffer = new Uint8Array(estimatedBytes + 1);
+        let bufIdx = 0;
         let accumulator = 0;
         let accumulatorBits = 0;
-        const { effectiveBitLength: bitLength, dduBinaryLookup: lookup, charLength, maxBinaryValue } = this;
-        const dduLength = this.dduChar.length;
         if (this.usePowerOfTwo) {
-            const chunkSize = charLength;
+            if (this.useAsciiLookup && this.fastAsciiLookup) {
+                // ASCII 최적화 경로
+                const lookup = this.fastAsciiLookup;
+                for (let i = 0; i < inputLen; i += chunkSize) {
+                    const code = cleanedInput.charCodeAt(i);
+                    const val = code < 128 ? lookup[code] : -1;
+                    if (val < 0) {
+                        throw new Error(`[Ddu64 decode] Invalid character "${cleanedInput[i]}" at ${i}`);
+                    }
+                    accumulator = (accumulator << bitLength) | val;
+                    accumulatorBits += bitLength;
+                    if (i + chunkSize >= inputLen && paddingBits > 0) {
+                        accumulator >>= paddingBits;
+                        accumulatorBits -= paddingBits;
+                    }
+                    while (accumulatorBits >= BYTE_BITS) {
+                        accumulatorBits -= BYTE_BITS;
+                        buffer[bufIdx++] = (accumulator >> accumulatorBits) & BYTE_MASK;
+                        accumulator &= (1 << accumulatorBits) - 1;
+                    }
+                }
+            }
+            else {
+                // 일반 룩업 경로
+                const lookup = this.dduBinaryLookup;
+                for (let i = 0; i < inputLen; i += chunkSize) {
+                    const chunk = cleanedInput.slice(i, i + charLength);
+                    const val = lookup.get(chunk);
+                    if (val === undefined) {
+                        throw new Error(`[Ddu64 decode] Invalid character "${chunk}" at ${i}`);
+                    }
+                    accumulator = (accumulator << bitLength) | val;
+                    accumulatorBits += bitLength;
+                    if (i + chunkSize >= inputLen && paddingBits > 0) {
+                        accumulator >>= paddingBits;
+                        accumulatorBits -= paddingBits;
+                    }
+                    while (accumulatorBits >= BYTE_BITS) {
+                        accumulatorBits -= BYTE_BITS;
+                        buffer[bufIdx++] = (accumulator >> accumulatorBits) & BYTE_MASK;
+                        accumulator &= (1 << accumulatorBits) - 1;
+                    }
+                }
+            }
+        }
+        else if (this.useAsciiLookup && this.fastAsciiLookup && charLength === 1) {
+            // 가변 길이 charset - ASCII 최적화 경로
+            const asciiLookup = this.fastAsciiLookup;
+            const maxVal = this.maxBinaryValue;
             for (let i = 0; i < inputLen; i += chunkSize) {
-                const chunk = cleanedInput.slice(i, i + charLength);
-                const val = lookup.get(chunk);
-                if (val === undefined)
-                    throw new Error(`[Ddu64 decode] Invalid character "${chunk}" at ${i}`);
-                if (val >= maxBinaryValue)
-                    throw new Error(`[Ddu64 decode] Value ${val} exceeds range`);
-                accumulator = (accumulator << bitLength) | val;
+                const code1 = cleanedInput.charCodeAt(i);
+                const code2 = cleanedInput.charCodeAt(i + 1);
+                const v1 = code1 < 128 ? asciiLookup[code1] : -1;
+                const v2 = code2 < 128 ? asciiLookup[code2] : -1;
+                if (v1 < 0) {
+                    throw new Error(`[Ddu64 decode] Invalid character "${cleanedInput[i]}" at ${i}`);
+                }
+                if (v2 < 0) {
+                    throw new Error(`[Ddu64 decode] Invalid character "${cleanedInput[i + 1]}" at ${i + charLength}`);
+                }
+                const value = v1 * dduLength + v2;
+                if (value >= maxVal) {
+                    throw new Error(`[Ddu64 decode] Value ${value} exceeds range`);
+                }
+                accumulator = (accumulator << bitLength) | value;
                 accumulatorBits += bitLength;
-                // 마지막 청크 패딩 비트 제거
                 if (i + chunkSize >= inputLen && paddingBits > 0) {
                     accumulator >>= paddingBits;
                     accumulatorBits -= paddingBits;
                 }
-                while (accumulatorBits >= 8) {
-                    const shift = accumulatorBits - 8;
-                    buffer.push((accumulator >> shift) & 0xFF);
-                    accumulatorBits -= 8;
+                while (accumulatorBits >= BYTE_BITS) {
+                    accumulatorBits -= BYTE_BITS;
+                    buffer[bufIdx++] = (accumulator >> accumulatorBits) & BYTE_MASK;
                     accumulator &= (1 << accumulatorBits) - 1;
                 }
             }
         }
         else {
-            const chunkSize = charLength * 2;
+            // 가변 길이 charset - 일반 룩업 경로
+            const lookup = this.dduBinaryLookup;
             for (let i = 0; i < inputLen; i += chunkSize) {
                 const c1 = cleanedInput.slice(i, i + charLength);
                 const c2 = cleanedInput.slice(i + charLength, i + chunkSize);
                 const v1 = lookup.get(c1);
                 const v2 = lookup.get(c2);
-                if (v1 === undefined)
+                if (v1 === undefined) {
                     throw new Error(`[Ddu64 decode] Invalid character "${c1}" at ${i}`);
-                if (v2 === undefined)
+                }
+                if (v2 === undefined) {
                     throw new Error(`[Ddu64 decode] Invalid character "${c2}" at ${i + charLength}`);
+                }
                 const value = v1 * dduLength + v2;
-                if (value >= maxBinaryValue)
+                if (value >= this.maxBinaryValue) {
                     throw new Error(`[Ddu64 decode] Value ${value} exceeds range`);
+                }
                 accumulator = (accumulator << bitLength) | value;
                 accumulatorBits += bitLength;
                 if (i + chunkSize >= inputLen && paddingBits > 0) {
                     accumulator >>= paddingBits;
                     accumulatorBits -= paddingBits;
                 }
-                while (accumulatorBits >= 8) {
-                    const shift = accumulatorBits - 8;
-                    buffer.push((accumulator >> shift) & 0xFF);
-                    accumulatorBits -= 8;
+                while (accumulatorBits >= BYTE_BITS) {
+                    accumulatorBits -= BYTE_BITS;
+                    buffer[bufIdx++] = (accumulator >> accumulatorBits) & BYTE_MASK;
                     accumulator &= (1 << accumulatorBits) - 1;
                 }
             }
         }
-        return Buffer.from(buffer);
+        return Buffer.from(buffer.subarray(0, bufIdx));
     }
-    // =========================================================================================
-    // Safe Engine (BigInt)
-    // Fallback for huge charsets (> 24 bits per chunk) where 32-bit integers overflow.
-    // =========================================================================================
-    encodeBigInt(bufferInput) {
-        const resultParts = [];
+    // --------------------------------------------------------------------------
+    // 인코딩 (BigInt 모드 - 17비트 이상)
+    // --------------------------------------------------------------------------
+    /**
+     * BigInt를 사용한 대형 비트 인코딩
+     */
+    encodeBigInt(bufferInput, compress, encrypt) {
+        const inputLen = bufferInput.length;
+        if (inputLen === 0)
+            return "";
         const { dduChar, effectiveBitLength: bitLength } = this;
         const dduLength = dduChar.length;
-        const bigBitLength = BigInt(bitLength);
+        const estimatedChunks = Math.ceil((inputLen * BYTE_BITS) / bitLength);
+        const estimatedSymbols = this.usePowerOfTwo
+            ? estimatedChunks
+            : estimatedChunks * 2;
+        const resultParts = new Array(estimatedSymbols + 3);
+        let resultIdx = 0;
         let accumulator = 0n;
         let accumulatorBits = 0;
         if (this.usePowerOfTwo) {
-            for (const byte of bufferInput) {
-                accumulator = (accumulator << 8n) | BigInt(byte);
-                accumulatorBits += 8;
+            for (let i = 0; i < inputLen; i++) {
+                accumulator = (accumulator << 8n) | BigInt(bufferInput[i]);
+                accumulatorBits += BYTE_BITS;
                 while (accumulatorBits >= bitLength) {
                     const shift = accumulatorBits - bitLength;
-                    const value = accumulator >> BigInt(shift);
-                    resultParts.push(dduChar[Number(value)]);
-                    accumulator &= ((1n << BigInt(shift)) - 1n);
+                    resultParts[resultIdx++] =
+                        dduChar[Number(accumulator >> BigInt(shift))];
+                    accumulator &= (1n << BigInt(shift)) - 1n;
                     accumulatorBits -= bitLength;
                 }
             }
         }
         else {
-            for (const byte of bufferInput) {
-                accumulator = (accumulator << 8n) | BigInt(byte);
-                accumulatorBits += 8;
+            for (let i = 0; i < inputLen; i++) {
+                accumulator = (accumulator << 8n) | BigInt(bufferInput[i]);
+                accumulatorBits += BYTE_BITS;
                 while (accumulatorBits >= bitLength) {
                     const shift = accumulatorBits - bitLength;
-                    const value = accumulator >> BigInt(shift);
-                    const idx = Number(value);
-                    resultParts.push(dduChar[Math.floor(idx / dduLength)] + dduChar[idx % dduLength]);
-                    accumulator &= ((1n << BigInt(shift)) - 1n);
+                    const idx = Number(accumulator >> BigInt(shift));
+                    const div = Math.floor(idx / dduLength);
+                    resultParts[resultIdx++] = dduChar[div];
+                    resultParts[resultIdx++] = dduChar[idx - div * dduLength];
+                    accumulator &= (1n << BigInt(shift)) - 1n;
                     accumulatorBits -= bitLength;
                 }
             }
         }
+        // 남은 비트 처리 (패딩)
         if (accumulatorBits > 0) {
             const paddingBits = bitLength - accumulatorBits;
             const index = Number(accumulator << BigInt(paddingBits));
             if (this.usePowerOfTwo) {
-                resultParts.push(dduChar[index]);
+                resultParts[resultIdx++] = dduChar[index];
             }
             else {
-                resultParts.push(dduChar[Math.floor(index / dduLength)] + dduChar[index % dduLength]);
+                const div = Math.floor(index / dduLength);
+                resultParts[resultIdx++] = dduChar[div];
+                resultParts[resultIdx++] = dduChar[index - div * dduLength];
             }
-            return resultParts.join("") + this.paddingChar + paddingBits.toString();
+            resultParts[resultIdx++] = this.paddingChar;
+            resultParts[resultIdx++] = (compress ? COMPRESS_MARKER : "") + (encrypt ? ENCRYPT_MARKER : "") + paddingBits.toString();
         }
+        else if (compress || encrypt) {
+            resultParts[resultIdx++] = this.paddingChar;
+            resultParts[resultIdx++] = (compress ? COMPRESS_MARKER : "") + (encrypt ? ENCRYPT_MARKER : "") + "0";
+        }
+        resultParts.length = resultIdx;
         return resultParts.join("");
     }
-    decodeBigInt(input) {
-        const { cleanedInput, paddingBits } = this.parsePaddingAndGetInput(input);
-        const buffer = [];
-        let accumulator = 0n;
-        let accumulatorBits = 0;
-        const { effectiveBitLength: bitLength, dduBinaryLookup: lookup } = this;
+    // --------------------------------------------------------------------------
+    // 디코딩 (BigInt 모드 - 17비트 이상)
+    // --------------------------------------------------------------------------
+    /**
+     * BigInt를 사용한 대형 비트 디코딩
+     */
+    decodeBigInt(cleanedInput, paddingBits) {
+        const inputLen = cleanedInput.length;
+        if (inputLen === 0)
+            return Buffer.alloc(0);
+        const { effectiveBitLength: bitLength, dduBinaryLookup: lookup, charLength, } = this;
         const bigBitLength = BigInt(bitLength);
         const dduLength = this.dduChar.length;
-        const chunkSize = this.usePowerOfTwo ? this.charLength : this.charLength * 2;
+        const chunkSize = this.usePowerOfTwo ? charLength : charLength * 2;
+        const numChunks = Math.ceil(inputLen / chunkSize);
+        const estimatedBytes = Math.ceil((numChunks * bitLength - paddingBits) / BYTE_BITS);
+        const buffer = new Uint8Array(estimatedBytes + 1);
+        let bufIdx = 0;
+        let accumulator = 0n;
+        let accumulatorBits = 0;
         if (this.usePowerOfTwo) {
-            for (let i = 0; i < cleanedInput.length; i += chunkSize) {
-                const chunk = cleanedInput.slice(i, i + this.charLength);
+            for (let i = 0; i < inputLen; i += chunkSize) {
+                const chunk = cleanedInput.slice(i, i + charLength);
                 const val = lookup.get(chunk);
-                if (val === undefined)
+                if (val === undefined) {
                     throw new Error(`[Ddu64 decode] Invalid character "${chunk}" at ${i}`);
+                }
                 accumulator = (accumulator << bigBitLength) | BigInt(val);
                 accumulatorBits += bitLength;
-                if (i + chunkSize >= cleanedInput.length && paddingBits > 0) {
+                if (i + chunkSize >= inputLen && paddingBits > 0) {
                     accumulator >>= BigInt(paddingBits);
                     accumulatorBits -= paddingBits;
                 }
-                while (accumulatorBits >= 8) {
-                    const shift = accumulatorBits - 8;
-                    buffer.push(Number((accumulator >> BigInt(shift)) & 0xffn));
-                    accumulator &= ((1n << BigInt(shift)) - 1n);
-                    accumulatorBits -= 8;
+                while (accumulatorBits >= BYTE_BITS) {
+                    const shift = accumulatorBits - BYTE_BITS;
+                    buffer[bufIdx++] = Number((accumulator >> BigInt(shift)) & 0xffn);
+                    accumulator &= (1n << BigInt(shift)) - 1n;
+                    accumulatorBits -= BYTE_BITS;
                 }
             }
         }
         else {
-            for (let i = 0; i < cleanedInput.length; i += chunkSize) {
-                const c1 = cleanedInput.slice(i, i + this.charLength);
-                const c2 = cleanedInput.slice(i + this.charLength, i + chunkSize);
+            for (let i = 0; i < inputLen; i += chunkSize) {
+                const c1 = cleanedInput.slice(i, i + charLength);
+                const c2 = cleanedInput.slice(i + charLength, i + chunkSize);
                 const v1 = lookup.get(c1);
                 const v2 = lookup.get(c2);
-                if (v1 === undefined)
+                if (v1 === undefined) {
                     throw new Error(`[Ddu64 decode] Invalid character "${c1}" at ${i}`);
-                if (v2 === undefined)
-                    throw new Error(`[Ddu64 decode] Invalid character "${c2}" at ${i + this.charLength}`);
+                }
+                if (v2 === undefined) {
+                    throw new Error(`[Ddu64 decode] Invalid character "${c2}" at ${i + charLength}`);
+                }
                 const value = v1 * dduLength + v2;
-                if (value >= this.maxBinaryValue)
+                if (value >= this.maxBinaryValue) {
                     throw new Error(`[Ddu64 decode] Value ${value} exceeds range`);
+                }
                 accumulator = (accumulator << bigBitLength) | BigInt(value);
                 accumulatorBits += bitLength;
-                if (i + chunkSize >= cleanedInput.length && paddingBits > 0) {
+                if (i + chunkSize >= inputLen && paddingBits > 0) {
                     accumulator >>= BigInt(paddingBits);
                     accumulatorBits -= paddingBits;
                 }
-                while (accumulatorBits >= 8) {
-                    const shift = accumulatorBits - 8;
-                    buffer.push(Number((accumulator >> BigInt(shift)) & 0xffn));
-                    accumulator &= ((1n << BigInt(shift)) - 1n);
-                    accumulatorBits -= 8;
+                while (accumulatorBits >= BYTE_BITS) {
+                    const shift = accumulatorBits - BYTE_BITS;
+                    buffer[bufIdx++] = Number((accumulator >> BigInt(shift)) & 0xffn);
+                    accumulator &= (1n << BigInt(shift)) - 1n;
+                    accumulatorBits -= BYTE_BITS;
                 }
             }
         }
-        return Buffer.from(buffer);
-    }
-    // =========================================================================================
-    // Internal Helpers (Normalization & Validation)
-    // =========================================================================================
-    parsePaddingAndGetInput(input) {
-        const padLen = this.paddingChar.length;
-        if (input.length < padLen)
-            return { cleanedInput: input, paddingBits: 0 };
-        const padIdx = input.lastIndexOf(this.paddingChar);
-        // 패딩 문자가 존재하고, 위치가 올바른지(chunk 단위) 확인
-        if (padIdx >= 0 && padIdx % this.charLength === 0 && padIdx + padLen <= input.length) {
-            const paddingSection = input.slice(padIdx + padLen);
-            if (!paddingSection)
-                throw new Error(`[Ddu64 decode] Invalid padding format. Missing padding length`);
-            const paddingBits = parseInt(paddingSection, 10);
-            if (isNaN(paddingBits) || paddingSection !== paddingBits.toString() || paddingBits < 0 || paddingBits >= this.effectiveBitLength) {
-                throw new Error(`[Ddu64 decode] Invalid padding format. Got: "${paddingSection}"`);
-            }
-            return { cleanedInput: input.substring(0, padIdx), paddingBits };
-        }
-        return { cleanedInput: input, paddingBits: 0 };
+        return Buffer.from(buffer.subarray(0, bufIdx));
     }
+    // --------------------------------------------------------------------------
+    // Charset 초기화 메서드
+    // --------------------------------------------------------------------------
     /**
-     * 입력된 CharSet을 검증하고 정리(Normalization)합니다.
-     * 문제가 발생하면 옵션에 따라 Error를 던지거나 Fallback CharSet을 반환합니다.
+     * Charset을 정규화합니다.
      */
     normalizeCharSet(current, shouldThrow, dduOptions) {
-        let state = { ...current };
-        // 재시도 루프 (Fallback 로직 포함)
-        while (true) {
+        // 1차 시도: 주어진 charset으로 정규화
+        // 실패 시 1회만 fallback 시도 (동일 fallback을 반복해도 결과는 동일)
+        const attempts = [current, null];
+        for (const attempt of attempts) {
+            const state = attempt ? { ...attempt } : this.getFallbackCharSet(dduOptions);
             try {
-                // 1. 중복 제거
-                const uniqueChars = Array.from(new Set(state.charSet));
-                if (uniqueChars.length !== state.charSet.length) {
+                // 중복 문자 제거
+                let charSet = state.charSet;
+                let requiredLength = state.requiredLength;
+                const uniqueChars = Array.from(new Set(charSet));
+                if (uniqueChars.length !== charSet.length) {
                     if (shouldThrow) {
-                        const duplicates = state.charSet.filter((c, i) => state.charSet.indexOf(c) !== i);
+                        const duplicates = charSet.filter((c, i) => charSet.indexOf(c) !== i);
                         throw new Error(`[Ddu64 normalizeCharSet] Character set contains duplicate characters: [${[...new Set(duplicates)].join(", ")}]`);
                     }
-                    state.charSet = uniqueChars;
+                    charSet = uniqueChars;
                     if (!state.isPredefined)
-                        state.requiredLength = state.charSet.length;
+                        requiredLength = charSet.length;
+                }
+                // 문자 수 검증
+                if (charSet.length < requiredLength) {
+                    throw new Error(`[Ddu64 normalizeCharSet] Insufficient characters. Required: ${requiredLength}, Has: ${charSet.length}`);
                 }
-                // 2. 기본 조건 검사
-                if (state.charSet.length < state.requiredLength)
-                    throw new Error(`[Ddu64 normalizeCharSet] Insufficient characters. Required: ${state.requiredLength}, Has: ${state.charSet.length}`);
-                if (state.requiredLength < 2)
+                if (requiredLength < 2) {
                     throw new Error(`[Ddu64 normalizeCharSet] At least 2 unique characters required.`);
-                if (state.charSet.length === 0)
+                }
+                if (charSet.length === 0) {
                     throw new Error(`[Ddu64 normalizeCharSet] Empty charset.`);
-                // 3. 문자 길이 일관성 검사
-                const charLength = state.charSet[0].length;
-                const invalidChar = state.charSet.find(c => c.length !== charLength);
+                }
+                // 문자 길이 일관성 검증
+                const charLength = charSet[0].length;
+                const invalidChar = charSet.find((c) => c.length !== charLength);
                 if (invalidChar) {
-                    if (shouldThrow)
+                    if (shouldThrow) {
                         throw new Error(`[Ddu64 normalizeCharSet] Inconsistent char length. Expected ${charLength}, found "${invalidChar}" (${invalidChar.length})`);
-                    // 필터링 후 재검증을 위해 예외 발생시켜 Fallback 또는 재시도 유도
-                    throw new Error("Filtered inconsistent chars (internal retry)");
+                    }
+                    continue; // fallback으로 재시도
                 }
-                // 4. 패딩 충돌 검사
-                if (state.padding.length !== charLength)
+                // 패딩 검증
+                if (state.padding.length !== charLength) {
                     throw new Error(`[Ddu64 normalizeCharSet] Padding length mismatch. Expected ${charLength}, got ${state.padding.length}`);
-                if (state.charSet.includes(state.padding)) {
-                    if (shouldThrow)
+                }
+                if (charSet.includes(state.padding)) {
+                    if (shouldThrow) {
                         throw new Error(`[Ddu64 normalizeCharSet] Padding character "${state.padding}" conflicts with charset.`);
-                    state.charSet = state.charSet.filter(c => c !== state.padding);
+                    }
+                    charSet = charSet.filter((c) => c !== state.padding);
                 }
+                // 불필요한 배열 복사 방지
+                const finalSet = charSet.length === requiredLength
+                    ? charSet
+                    : charSet.slice(0, requiredLength);
                 return {
-                    charSet: state.charSet.slice(0, state.requiredLength),
+                    charSet: finalSet,
                     padding: state.padding,
                     charLength,
                     isPredefined: state.isPredefined,
                 };
             }
             catch (e) {
-                // 사용자가 명시적으로 에러를 요청했거나, 복구 불가능한 에러인 경우
-                if (shouldThrow && !e.message.includes("internal retry"))
+                if (shouldThrow)
                     throw e;
-                // 그 외에는 Fallback CharSet 사용
-                state = this.getFallbackCharSet(dduOptions);
+                // fallback 시도로 continue
             }
         }
+        // 최종 fallback (이론상 도달 불가, 방어 코드)
+        const fallback = this.getFallbackCharSet(dduOptions);
+        return {
+            charSet: fallback.charSet.slice(0, fallback.requiredLength),
+            padding: fallback.padding,
+            charLength: fallback.charSet[0]?.length ?? 1,
+            isPredefined: true,
+        };
     }
+    /**
+     * 초기 charset을 결정합니다.
+     */
     resolveInitialCharSet(dduChar, paddingChar, dduOptions, shouldThrow) {
-        // 내부 헬퍼: 길이와 옵션에 따라 최종 메타데이터 생성
         const buildMeta = (set, padding, length, isPredefined) => {
             const usePow2 = this.shouldUsePowerOfTwo(length, dduOptions?.usePowerOfTwo);
             if (usePow2 && length > 0) {
                 const exponent = this.getLargestPowerOfTwoExponent(length);
                 const pow2Length = 1 << exponent;
-                return { charSet: set.slice(0, pow2Length), padding, requiredLength: pow2Length, bitLength: exponent, isPredefined };
+                const selected = set.length === pow2Length ? set : set.slice(0, pow2Length);
+                return {
+                    charSet: selected,
+                    padding,
+                    requiredLength: pow2Length,
+                    bitLength: exponent,
+                    isPredefined,
+                };
             }
-            return { charSet: set.slice(0, length), padding, requiredLength: length, bitLength: length > 0 ? this.getBitLength(length) : 0, isPredefined };
+            const selected = set.length === length ? set : set.slice(0, length);
+            return {
+                charSet: selected,
+                padding,
+                requiredLength: length,
+                bitLength: length > 0 ? this.getBitLength(length) : 0,
+                isPredefined,
+            };
         };
         try {
             const finalDduChar = dduChar ?? dduOptions?.dduChar;
             const finalPadding = paddingChar ?? dduOptions?.paddingChar;
-            // Case A: 사용자 제공 CharSet
             if (finalDduChar) {
-                if (!finalPadding)
+                if (!finalPadding) {
                     throw new Error(`[Ddu64 Constructor] paddingChar is required when dduChar is provided.`);
-                const arr = typeof finalDduChar === "string" ? [...finalDduChar.trim()] : [...finalDduChar];
+                }
+                const arr = typeof finalDduChar === "string"
+                    ? [...finalDduChar.trim()]
+                    : [...finalDduChar];
                 if (shouldThrow) {
                     const uniqueSize = new Set(arr).size;
                     if (uniqueSize !== arr.length) {
@@ -416,12 +1233,14 @@ export class Ddu64 extends BaseDdu {
                     }
                 }
                 const reqLen = dduOptions?.requiredLength ?? arr.length;
-                if (arr.length < reqLen)
+                if (arr.length < reqLen) {
                     throw new Error(`[Ddu64 Constructor] Insufficient characters.`);
+                }
                 return buildMeta(arr, finalPadding, reqLen, false);
             }
-            // Case B: 심볼(Enum)로 지정된 CharSet
-            const symbol = dduOptions?.dduSetSymbol ?? dduDefaultConstructorOptions.dduSetSymbol ?? DduSetSymbol.DDU;
+            const symbol = dduOptions?.dduSetSymbol ??
+                dduDefaultConstructorOptions.dduSetSymbol ??
+                DduSetSymbol.DDU;
             const cs = this.getCharSetOrThrow(symbol);
             return buildMeta(cs.charSet, cs.paddingChar, cs.maxRequiredLength, true);
         }
@@ -431,26 +1250,72 @@ export class Ddu64 extends BaseDdu {
             return this.getFallbackCharSet(dduOptions);
         }
     }
+    /**
+     * Fallback charset을 반환합니다.
+     */
     getFallbackCharSet(dduOptions) {
-        const symbol = dduOptions?.dduSetSymbol ?? dduDefaultConstructorOptions.dduSetSymbol ?? DduSetSymbol.ONECHARSET;
+        const symbol = dduOptions?.dduSetSymbol ??
+            dduDefaultConstructorOptions.dduSetSymbol ??
+            DduSetSymbol.ONECHARSET;
         const cs = getCharSet(symbol) ?? getCharSet(DduSetSymbol.ONECHARSET);
         if (!cs)
             throw new Error(`Critical: No fallback CharSet available`);
-        return { charSet: cs.charSet, padding: cs.paddingChar, requiredLength: cs.maxRequiredLength, bitLength: cs.bitLength, isPredefined: true };
+        return {
+            charSet: cs.charSet,
+            padding: cs.paddingChar,
+            requiredLength: cs.maxRequiredLength,
+            bitLength: cs.bitLength,
+            isPredefined: true,
+        };
     }
+    /**
+     * 2의 제곱수 사용 여부를 결정합니다.
+     */
     shouldUsePowerOfTwo(length, preference) {
         if (preference !== undefined)
             return preference ? length > 0 : false;
         return length > 0 && (length & (length - 1)) === 0;
     }
+    /**
+     * charset을 가져오거나 에러를 발생시킵니다.
+     */
     getCharSetOrThrow(symbol) {
         const cs = getCharSet(symbol);
         if (!cs)
             throw new Error(`CharSet with symbol ${symbol} not found`);
         return cs;
     }
+    /**
+     * URL-Safe 모드 시 charset/padding이 역변환 대상 문자를 포함하지 않는지 검증합니다.
+     * 역변환 대상 문자("-", "_", ".")가 charset이나 padding에 있으면
+     * fromUrlSafe 시 해당 문자가 "+", "/", "="로 변환되어 데이터가 손상됩니다.
+     *
+     * @returns URL-Safe 모드를 활성화해도 안전한 경우 true
+     */
+    isUrlSafeCompatible(charSet, paddingChar, shouldThrow) {
+        const conflictChars = Object.keys(URL_SAFE_REVERSE_MAP); // ["-", "_", "."]
+        for (const ch of conflictChars) {
+            for (const c of charSet) {
+                if (c.includes(ch)) {
+                    const msg = `[Ddu64 Constructor] URL-Safe mode conflict: charset character "${c}" contains "${ch}" which would be transformed to "${URL_SAFE_REVERSE_MAP[ch]}" during decoding.`;
+                    if (shouldThrow)
+                        throw new Error(msg);
+                    return false;
+                }
+            }
+            if (paddingChar.includes(ch)) {
+                const msg = `[Ddu64 Constructor] URL-Safe mode conflict: padding character "${paddingChar}" contains "${ch}" which would be transformed to "${URL_SAFE_REVERSE_MAP[ch]}" during decoding.`;
+                if (shouldThrow)
+                    throw new Error(msg);
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * 커스텀 charset의 조합 중복을 검증합니다.
+     */
     validateCombinationDuplicates(charSet, paddingChar, requiredLength) {
-        // 작은 크기의 단일 문자 집합에 대해서만 '조합 충돌' 검사를 수행 (안전장치)
         if (charSet[0].length !== 1 || requiredLength > 256)
             return;
         const limit = Math.min(charSet.length, requiredLength);
@@ -461,11 +1326,15 @@ export class Ddu64 extends BaseDdu {
                 throw new Error(`Combination conflict: ${context}`);
             combinations.add(s);
         };
-        targetChars.forEach(c => combinations.add(c));
+        for (let i = 0; i < targetChars.length; i++) {
+            combinations.add(targetChars[i]);
+        }
         combinations.add(paddingChar);
-        for (const c1 of targetChars) {
-            for (const c2 of targetChars)
-                add(c1 + c2, `"${c1}" + "${c2}"`);
+        for (let i = 0; i < targetChars.length; i++) {
+            const c1 = targetChars[i];
+            for (let j = 0; j < targetChars.length; j++) {
+                add(c1 + targetChars[j], `"${c1}" + "${targetChars[j]}"`);
+            }
             add(c1 + paddingChar, `"${c1}" + padding`);
             add(paddingChar + c1, `padding + "${c1}"`);
         }