@ddunigma/node 1.1.7 → 2.0.0

package/dist/mjs/encoders/Ddu64.js

@@ -2,6 +2,9 @@ import { BaseDdu } from "../base/BaseDdu";
 import { DduSetSymbol, dduDefaultConstructorOptions, } from "../types";
 import { getCharSet } from "../charSets";
 export class Ddu64 extends BaseDdu {
+    // =========================================================================================
+    // Properties
+    // =========================================================================================
     dduChar;
     paddingChar;
     charLength;
@@ -12,310 +15,460 @@ export class Ddu64 extends BaseDdu {
     isPredefinedCharSet;
     effectiveBitLength;
     maxBinaryValue;
-    binaryChunkToIntFn;
-    indexToBinaryCache;
+    // =========================================================================================
+    // Constructor
+    // =========================================================================================
     constructor(dduChar, paddingChar, dduOptions) {
         super();
-        const shouldThrowError = dduOptions?.useBuildErrorReturn ?? false;
-        const getCharSetFromSymbol = (symbol) => {
-            const cs = getCharSet(symbol);
-            if (!cs)
-                throw new Error(`CharSet with symbol ${symbol} not found`);
-            return cs;
-        };
-        // charset 초기화
-        let charSet, padding, requiredLength, bitLength, isPredefined;
-        try {
-            const finalDduChar = dduChar ?? dduOptions?.dduChar;
-            const finalPadding = paddingChar ?? dduOptions?.paddingChar;
-            if (finalDduChar) {
-                // 커스텀 charset
-                if (!finalPadding) {
-                    throw new Error(`[Ddu64 Constructor] paddingChar is required when dduChar is provided. Received: dduChar=${typeof finalDduChar}, paddingChar=${finalPadding}`);
-                }
-                // 문자열을 배열로 변환 (중복 제거 없이)
-                const arr = typeof finalDduChar === "string" ? [...finalDduChar.trim()] : finalDduChar;
-                // 중복 검사 (useBuildErrorReturn이 true일 때만)
-                if (shouldThrowError) {
-                    const uniqueChars = new Set(arr);
-                    if (uniqueChars.size !== arr.length) {
-                        const duplicates = arr.filter((char, index) => arr.indexOf(char) !== index);
-                        throw new Error(`[Ddu64 Constructor] Character set contains duplicate characters. Total: ${arr.length}, Unique: ${uniqueChars.size}, Duplicates: [${[...new Set(duplicates)].join(', ')}]`);
-                    }
-                }
-                const len = dduOptions?.requiredLength ?? arr.length;
-                if (arr.length < len) {
-                    throw new Error(`[Ddu64 Constructor] Insufficient characters in charset. Required: ${len}, Provided: ${arr.length}`);
-                }
-                const usePow2 = dduOptions?.usePowerOfTwo === true || (dduOptions?.usePowerOfTwo === undefined && len > 0 && (len & (len - 1)) === 0);
-                if (usePow2) {
-                    const exp = this.getLargestPowerOfTwoExponent(len);
-                    const pow2Len = 1 << exp;
-                    [charSet, padding, requiredLength, bitLength, isPredefined] = [arr.slice(0, pow2Len), finalPadding, pow2Len, exp, false];
-                }
-                else {
-                    [charSet, padding, requiredLength, bitLength, isPredefined] = [arr.slice(0, len), finalPadding, len, this.getBitLength(len), false];
-                }
-            }
-            else if (dduOptions?.dduSetSymbol) {
-                // 미리 정의된 charset
-                const cs = getCharSetFromSymbol(dduOptions.dduSetSymbol);
-                const usePow2 = dduOptions?.usePowerOfTwo === true || (dduOptions?.usePowerOfTwo === undefined && cs.maxRequiredLength > 0 && (cs.maxRequiredLength & (cs.maxRequiredLength - 1)) === 0);
-                if (usePow2) {
-                    const exp = this.getLargestPowerOfTwoExponent(cs.maxRequiredLength);
-                    const pow2Len = 1 << exp;
-                    [charSet, padding, requiredLength, bitLength, isPredefined] = [cs.charSet.slice(0, pow2Len), cs.paddingChar, pow2Len, exp, true];
-                }
-                else {
-                    [charSet, padding, requiredLength, bitLength, isPredefined] = [cs.charSet, cs.paddingChar, cs.maxRequiredLength, cs.bitLength, true];
-                }
-            }
-            else {
-                // 기본 charset
-                const cs = getCharSetFromSymbol(dduDefaultConstructorOptions.dduSetSymbol ?? DduSetSymbol.DDU);
-                [charSet, padding, requiredLength, bitLength, isPredefined] = [cs.charSet, cs.paddingChar, cs.maxRequiredLength, cs.bitLength, true];
-            }
-        }
-        catch (error) {
-            if (shouldThrowError)
-                throw error;
-            // fallback
-            const fallbackSymbol = dduOptions?.dduSetSymbol ?? dduDefaultConstructorOptions.dduSetSymbol ?? DduSetSymbol.ONECHARSET;
-            const cs = getCharSet(fallbackSymbol) ?? getCharSet(DduSetSymbol.ONECHARSET);
-            if (!cs)
-                throw new Error(`Critical: No fallback CharSet available`);
-            [charSet, padding, requiredLength, bitLength, isPredefined] = [cs.charSet, cs.paddingChar, cs.maxRequiredLength, cs.bitLength, true];
-        }
-        // 정규화 및 검증
-        const normalized = this.normalizeCharSet(charSet, padding, requiredLength, bitLength, isPredefined, shouldThrowError, dduOptions);
+        const shouldThrow = dduOptions?.useBuildErrorReturn ?? false;
+        // 1. CharSet 초기화 및 검증
+        const initial = this.resolveInitialCharSet(dduChar, paddingChar, dduOptions, shouldThrow);
+        const normalized = this.normalizeCharSet(initial, shouldThrow, dduOptions);
         this.dduChar = normalized.charSet;
         this.paddingChar = normalized.padding;
         this.charLength = normalized.charLength;
         this.isPredefinedCharSet = normalized.isPredefined;
         this.encoding = dduOptions?.encoding ?? this.defaultEncoding;
+        // 2. 비트 연산 상수 계산
         const dduLength = this.dduChar.length;
-        const recalculatedBitLength = this.getBitLength(dduLength);
         this.usePowerOfTwo = dduLength > 0 && (dduLength & (dduLength - 1)) === 0;
-        this.bitLength = this.usePowerOfTwo
-            ? this.getLargestPowerOfTwoExponent(dduLength)
-            : recalculatedBitLength;
-        this.effectiveBitLength = this.usePowerOfTwo ? this.bitLength : recalculatedBitLength;
+        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;
-        // 성능 최적화: 단일 구현 사용 (벤치마크 결과 Method2가 더 빠르고 안정적)
-        // Method2는 32비트 이상에서도 오버플로우 없이 정확한 결과 제공
-        this.binaryChunkToIntFn = (chunk) => chunk.split('').reduce((v, c) => v * 2 + (c.charCodeAt(0) & 1), 0);
-        this.dduChar.forEach((char, index) => this.dduBinaryLookup.set(char, index));
+        // 3. Lookup Table 생성 (Decoding용)
+        for (let i = 0; i < dduLength; i++) {
+            this.dduBinaryLookup.set(this.dduChar[i], i);
+        }
+        // 4. 안전성 검사
         if (this.charLength === 1 && !this.isPredefinedCharSet) {
             this.validateCombinationDuplicates(this.dduChar, this.paddingChar, dduLength);
         }
-        if (this.effectiveBitLength <= 16) {
-            this.indexToBinaryCache = Array.from({ length: this.maxBinaryValue }, (_, i) => i.toString(2).padStart(this.effectiveBitLength, "0"));
+    }
+    // =========================================================================================
+    // Public API
+    // =========================================================================================
+    /**
+     * 데이터를 DDU 포맷으로 인코딩합니다.
+     * 성능을 위해 24비트 이하는 Fast Path(number 연산)를 사용합니다.
+     */
+    encode(input, _options) {
+        const bufferInput = typeof input === "string" ? Buffer.from(input, this.encoding) : input;
+        if (this.effectiveBitLength <= 24) {
+            return this.encodeFast(bufferInput);
         }
-        else {
-            this.indexToBinaryCache = null;
+        return this.encodeBigInt(bufferInput);
+    }
+    /**
+     * DDU 포맷 문자열을 버퍼로 디코딩합니다.
+     */
+    decodeToBuffer(input, _options) {
+        if (this.effectiveBitLength <= 24) {
+            return this.decodeFast(input);
         }
+        return this.decodeBigInt(input);
     }
-    normalizeCharSet(charSet, padding, requiredLength, bitLength, isPredefined, shouldThrowError, dduOptions) {
-        const applyFallback = () => {
-            const fallbackSymbol = dduOptions?.dduSetSymbol ?? dduDefaultConstructorOptions.dduSetSymbol ?? DduSetSymbol.ONECHARSET;
-            const cs = getCharSet(fallbackSymbol) ?? 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 };
-        };
-        const validate = (condition, message) => {
-            if (condition) {
-                if (shouldThrowError)
-                    throw new Error(message);
-                const fb = applyFallback();
-                [charSet, padding, requiredLength, bitLength, isPredefined] = [fb.charSet, fb.padding, fb.requiredLength, fb.bitLength, fb.isPredefined];
-                return true;
-            }
-            return false;
+    decode(input, _options) {
+        return this.decodeToBuffer(input, _options).toString(this.encoding);
+    }
+    getCharSetInfo() {
+        return {
+            charSet: [...this.dduChar],
+            paddingChar: this.paddingChar,
+            charLength: this.charLength,
+            bitLength: this.bitLength,
+            usePowerOfTwo: this.usePowerOfTwo,
+            encoding: this.encoding,
         };
-        // 중복 제거 (모든 charset에 적용)
-        const uniqueChars = new Set(charSet);
-        if (uniqueChars.size !== charSet.length) {
-            const duplicates = charSet.filter((char, index) => charSet.indexOf(char) !== index);
-            const errorMsg = `[Ddu64 normalizeCharSet] Character set contains duplicate characters. Total: ${charSet.length}, Unique: ${uniqueChars.size}, Duplicates: [${[...new Set(duplicates)].join(', ')}]`;
-            if (shouldThrowError)
-                throw new Error(errorMsg);
-            // 중복 제거 후 계속 진행
-            charSet = Array.from(uniqueChars);
-            if (!isPredefined) {
-                requiredLength = charSet.length;
+    }
+    // =========================================================================================
+    // 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 = [];
+        const { dduChar, effectiveBitLength: bitLength, paddingChar } = this;
+        const dduLength = dduChar.length;
+        let accumulator = 0;
+        let accumulatorBits = 0;
+        // Loop Unswitching: 조건문을 루프 밖으로 빼서 CPU 분기 예측 효율 향상
+        if (this.usePowerOfTwo) {
+            for (const byte of bufferInput) {
+                accumulator = (accumulator << 8) | byte;
+                accumulatorBits += 8;
+                while (accumulatorBits >= bitLength) {
+                    const shift = accumulatorBits - bitLength;
+                    const index = accumulator >> shift;
+                    resultParts.push(dduChar[index]);
+                    accumulatorBits -= bitLength;
+                    accumulator &= (1 << accumulatorBits) - 1;
+                }
             }
         }
-        // 검증
-        if (validate(charSet.length < requiredLength, `[Ddu64 normalizeCharSet] Insufficient characters. Required: ${requiredLength}, Provided: ${charSet.length}`)) {
-            return this.normalizeCharSet(charSet, padding, requiredLength, bitLength, isPredefined, shouldThrowError, dduOptions);
-        }
-        if (validate(requiredLength < 2, `[Ddu64 normalizeCharSet] At least 2 unique characters are required. Provided: ${requiredLength}`)) {
-            return this.normalizeCharSet(charSet, padding, requiredLength, bitLength, isPredefined, shouldThrowError, dduOptions);
-        }
-        if (validate(bitLength <= 0, `[Ddu64 normalizeCharSet] Invalid bit length (${bitLength}) for charset size ${requiredLength}`)) {
-            return this.normalizeCharSet(charSet, padding, requiredLength, bitLength, isPredefined, shouldThrowError, dduOptions);
-        }
-        let charLength = charSet[0]?.length ?? 0;
-        validate(charLength === 0, `[Ddu64 normalizeCharSet] Empty charset. Required: ${requiredLength} characters`);
-        const invalidIndex = charSet.findIndex(char => char.length !== charLength);
-        if (invalidIndex !== -1) {
-            if (shouldThrowError) {
-                throw new Error(`[Ddu64 normalizeCharSet] Inconsistent character length. Expected: ${charLength}, but character at index ${invalidIndex} ("${charSet[invalidIndex]}") has length ${charSet[invalidIndex].length}`);
+        else {
+            for (const byte of bufferInput) {
+                accumulator = (accumulator << 8) | byte;
+                accumulatorBits += 8;
+                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;
+                    accumulator &= (1 << accumulatorBits) - 1;
+                }
             }
-            charSet = charSet.filter(char => char.length === charLength);
-            validate(charSet.length < requiredLength, `[Ddu64 normalizeCharSet] Insufficient characters after filtering. Required: ${requiredLength}, Remaining: ${charSet.length}`);
-            charLength = charSet[0]?.length ?? 0;
         }
-        validate(!charSet.length, `[Ddu64 normalizeCharSet] Empty charset after validation`);
-        validate(padding.length !== charLength, `[Ddu64 normalizeCharSet] Padding character length mismatch. Expected: ${charLength}, Got: ${padding.length} (padding: "${padding}")`);
-        if (new Set(charSet).has(padding)) {
-            if (shouldThrowError) {
-                throw new Error(`[Ddu64 normalizeCharSet] Padding character "${padding}" conflicts with charset. Padding must not be in the character set.`);
+        // 남은 비트 패딩 처리
+        if (accumulatorBits > 0) {
+            const paddingBits = bitLength - accumulatorBits;
+            const index = accumulator << paddingBits;
+            if (this.usePowerOfTwo) {
+                resultParts.push(dduChar[index]);
             }
-            charSet = charSet.filter(char => char !== padding);
-            validate(charSet.length < requiredLength, `[Ddu64 normalizeCharSet] Insufficient characters after removing padding conflict. Required: ${requiredLength}, Remaining: ${charSet.length}`);
-            charLength = charSet[0]?.length ?? 0;
-        }
-        return { charSet: charSet.slice(0, requiredLength), padding, requiredLength, bitLength, isPredefined, charLength };
-    }
-    getBinaryFromIndex(index) {
-        if (index < 0 || index >= this.maxBinaryValue) {
-            throw new Error(`[Ddu64] Binary index overflow. Received: ${index}, Allowed range: 0-${this.maxBinaryValue - 1}`);
+            else {
+                const div = (index / dduLength) | 0;
+                const mod = index % dduLength;
+                resultParts.push(dduChar[div] + dduChar[mod]);
+            }
+            return resultParts.join("") + paddingChar + paddingBits.toString();
         }
-        return this.indexToBinaryCache?.[index] ?? index.toString(2).padStart(this.effectiveBitLength, "0");
+        return resultParts.join("");
     }
-    validateCombinationDuplicates(charSet, paddingChar, requiredLength) {
-        const charLength = charSet[0].length;
-        // 조합 충돌 검사는 단일 문자 집합이면서 비교적 작은 경우(<=256)에만 적용한다.
-        if (charLength !== 1 || requiredLength > 256) {
-            return;
-        }
-        const allStrings = new Set([...charSet.slice(0, requiredLength), paddingChar]);
-        const limit = Math.min(charSet.length, requiredLength);
-        for (let i = 0; i < limit; i++) {
-            for (let j = 0; j < limit; j++) {
-                const combo = charSet[i] + charSet[j];
-                if (allStrings.has(combo)) {
-                    throw new Error(`Combination conflict: "${charSet[i]}" + "${charSet[j]}" = "${combo}" already exists`);
+    decodeFast(input) {
+        const { cleanedInput, paddingBits } = this.parsePaddingAndGetInput(input);
+        const inputLen = cleanedInput.length;
+        const buffer = [];
+        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;
+            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;
+                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;
+                    accumulator &= (1 << accumulatorBits) - 1;
                 }
             }
-            const charPad = charSet[i] + paddingChar;
-            const padChar = paddingChar + charSet[i];
-            if (allStrings.has(charPad)) {
-                throw new Error(`Combination conflict: "${charSet[i]}" + padding "${paddingChar}" = "${charPad}"`);
+        }
+        else {
+            const chunkSize = charLength * 2;
+            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)
+                    throw new Error(`[Ddu64 decode] Invalid character "${c1}" at ${i}`);
+                if (v2 === undefined)
+                    throw new Error(`[Ddu64 decode] Invalid character "${c2}" at ${i + charLength}`);
+                const value = v1 * dduLength + v2;
+                if (value >= 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;
+                    accumulator &= (1 << accumulatorBits) - 1;
+                }
             }
-            if (allStrings.has(padChar)) {
-                throw new Error(`Combination conflict: padding "${paddingChar}" + "${charSet[i]}" = "${padChar}"`);
+        }
+        return Buffer.from(buffer);
+    }
+    // =========================================================================================
+    // Safe Engine (BigInt)
+    // Fallback for huge charsets (> 24 bits per chunk) where 32-bit integers overflow.
+    // =========================================================================================
+    encodeBigInt(bufferInput) {
+        const resultParts = [];
+        const { dduChar, effectiveBitLength: bitLength } = this;
+        const dduLength = dduChar.length;
+        const bigBitLength = BigInt(bitLength);
+        let accumulator = 0n;
+        let accumulatorBits = 0;
+        if (this.usePowerOfTwo) {
+            for (const byte of bufferInput) {
+                accumulator = (accumulator << 8n) | BigInt(byte);
+                accumulatorBits += 8;
+                while (accumulatorBits >= bitLength) {
+                    const shift = accumulatorBits - bitLength;
+                    const value = accumulator >> BigInt(shift);
+                    resultParts.push(dduChar[Number(value)]);
+                    accumulator &= ((1n << BigInt(shift)) - 1n);
+                    accumulatorBits -= bitLength;
+                }
             }
         }
-        const doublePad = paddingChar + paddingChar;
-        if (allStrings.has(doublePad)) {
-            throw new Error(`Combination conflict: double padding "${doublePad}" already exists`);
+        else {
+            for (const byte of bufferInput) {
+                accumulator = (accumulator << 8n) | BigInt(byte);
+                accumulatorBits += 8;
+                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);
+                    accumulatorBits -= bitLength;
+                }
+            }
         }
-    }
-    encode(input, _options) {
-        // options는 구버전 호환성을 위해 유지하지만 사용하지 않음
-        const bufferInput = typeof input === "string" ? Buffer.from(input, this.encoding) : input;
-        // 생성자에서 설정된 값 사용
-        const dduLength = this.dduChar.length;
-        const effectiveBitLength = this.effectiveBitLength;
-        const { dduBinary, padding } = this.bufferToDduBinary(bufferInput, effectiveBitLength);
-        // 문자열 연결 최적화: Array + join 사용
-        const resultParts = new Array(dduBinary.length);
-        // 각 비트 청크를 변환
-        for (let i = 0; i < dduBinary.length; i++) {
-            const binaryChunk = dduBinary[i];
-            const charInt = this.binaryChunkToIntFn(binaryChunk);
-            if (!this.usePowerOfTwo) {
-                // 가변 길이 조합 인코딩 (멀티바이트 문자도 지원)
-                const quotient = Math.floor(charInt / dduLength);
-                const remainder = charInt % dduLength;
-                resultParts[i] = this.dduChar[quotient] + this.dduChar[remainder];
+        if (accumulatorBits > 0) {
+            const paddingBits = bitLength - accumulatorBits;
+            const index = Number(accumulator << BigInt(paddingBits));
+            if (this.usePowerOfTwo) {
+                resultParts.push(dduChar[index]);
             }
             else {
-                // 고정 길이 직접 매핑
-                resultParts[i] = this.dduChar[charInt];
+                resultParts.push(dduChar[Math.floor(index / dduLength)] + dduChar[index % dduLength]);
             }
+            return resultParts.join("") + this.paddingChar + paddingBits.toString();
         }
-        let resultString = resultParts.join("");
-        // 패딩 비트 정보를 padChar + 패딩비트수 형태로 추가
-        if (padding > 0) {
-            resultString += this.paddingChar + padding;
-        }
-        return resultString;
+        return resultParts.join("");
     }
-    decodeToBuffer(input, _options) {
-        let paddingBits = 0;
-        if (input.length >= this.paddingChar.length) {
-            const padCharIndex = input.lastIndexOf(this.paddingChar);
-            if (padCharIndex >= 0 &&
-                padCharIndex % this.charLength === 0 &&
-                padCharIndex + this.paddingChar.length <= input.length) {
-                const paddingSection = input.slice(padCharIndex + this.paddingChar.length);
-                if (paddingSection.length === 0) {
-                    throw new Error(`[Ddu64 decode] Invalid padding format. Missing padding length after "${this.paddingChar}"`);
-                }
-                paddingBits = parseInt(paddingSection, 10);
-                if (isNaN(paddingBits) ||
-                    paddingSection !== paddingBits.toString() ||
-                    paddingBits < 0 ||
-                    paddingBits >= this.effectiveBitLength) {
-                    throw new Error(`[Ddu64 decode] Invalid padding format. Expected integer between 0 and ${this.effectiveBitLength - 1}, Got: "${paddingSection}"`);
-                }
-                input = input.substring(0, padCharIndex);
-            }
-        }
-        let dduBinary = "";
+    decodeBigInt(input) {
+        const { cleanedInput, paddingBits } = this.parsePaddingAndGetInput(input);
+        const buffer = [];
+        let accumulator = 0n;
+        let accumulatorBits = 0;
+        const { effectiveBitLength: bitLength, dduBinaryLookup: lookup } = this;
+        const bigBitLength = BigInt(bitLength);
         const dduLength = this.dduChar.length;
-        if (!this.usePowerOfTwo) {
-            const chunkSize = this.charLength * 2;
-            for (let i = 0; i < input.length; i += chunkSize) {
-                const firstChar = input.slice(i, i + this.charLength);
-                const secondChar = input.slice(i + this.charLength, i + chunkSize);
-                const firstIndex = this.dduBinaryLookup.get(firstChar);
-                const secondIndex = this.dduBinaryLookup.get(secondChar);
-                if (firstIndex === undefined || secondIndex === undefined) {
-                    const invalidChar = firstIndex === undefined ? firstChar : secondChar;
-                    throw new Error(`[Ddu64 decode] Invalid character in encoded string. Character: "${invalidChar}", Position: ${i}, Expected charset size: ${dduLength}`);
+        const chunkSize = this.usePowerOfTwo ? this.charLength : this.charLength * 2;
+        if (this.usePowerOfTwo) {
+            for (let i = 0; i < cleanedInput.length; i += chunkSize) {
+                const chunk = cleanedInput.slice(i, i + this.charLength);
+                const val = lookup.get(chunk);
+                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) {
+                    accumulator >>= BigInt(paddingBits);
+                    accumulatorBits -= paddingBits;
                 }
-                const value = firstIndex * dduLength + secondIndex;
-                if (value >= this.maxBinaryValue) {
-                    throw new Error(`[Ddu64 decode] Invalid character combination detected. Calculated value ${value} exceeds binary range ${this.maxBinaryValue - 1}.`);
+                while (accumulatorBits >= 8) {
+                    const shift = accumulatorBits - 8;
+                    buffer.push(Number((accumulator >> BigInt(shift)) & 0xffn));
+                    accumulator &= ((1n << BigInt(shift)) - 1n);
+                    accumulatorBits -= 8;
                 }
-                dduBinary += this.getBinaryFromIndex(value);
             }
         }
         else {
-            for (let i = 0; i < input.length; i += this.charLength) {
-                const charChunk = input.slice(i, i + this.charLength);
-                const charIndex = this.dduBinaryLookup.get(charChunk);
-                if (charIndex === undefined) {
-                    throw new Error(`[Ddu64 decode] Invalid character in encoded string. Character: "${charChunk}", Position: ${i}, Charset size: ${dduLength}, Character length: ${this.charLength}`);
+            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);
+                const v1 = lookup.get(c1);
+                const v2 = lookup.get(c2);
+                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}`);
+                const value = v1 * dduLength + v2;
+                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) {
+                    accumulator >>= BigInt(paddingBits);
+                    accumulatorBits -= paddingBits;
                 }
-                if (charIndex >= this.maxBinaryValue) {
-                    throw new Error(`[Ddu64 decode] Invalid binary index ${charIndex}. Allowed range: 0-${this.maxBinaryValue - 1}`);
+                while (accumulatorBits >= 8) {
+                    const shift = accumulatorBits - 8;
+                    buffer.push(Number((accumulator >> BigInt(shift)) & 0xffn));
+                    accumulator &= ((1n << BigInt(shift)) - 1n);
+                    accumulatorBits -= 8;
                 }
-                dduBinary += this.getBinaryFromIndex(charIndex);
             }
         }
-        return this.dduBinaryToBuffer(dduBinary, paddingBits);
+        return Buffer.from(buffer);
     }
-    decode(input, _options) {
-        return this.decodeToBuffer(input, _options).toString(this.encoding);
+    // =========================================================================================
+    // 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 };
     }
     /**
-     * 테스트 및 디버깅용 getter 메서드
-     * 인코더의 내부 상태 정보를 반환
+     * 입력된 CharSet을 검증하고 정리(Normalization)합니다.
+     * 문제가 발생하면 옵션에 따라 Error를 던지거나 Fallback CharSet을 반환합니다.
      */
-    getCharSetInfo() {
-        return {
-            charSet: [...this.dduChar],
-            paddingChar: this.paddingChar,
-            charLength: this.charLength,
-            bitLength: this.bitLength,
-            usePowerOfTwo: this.usePowerOfTwo,
-            encoding: this.encoding,
+    normalizeCharSet(current, shouldThrow, dduOptions) {
+        let state = { ...current };
+        // 재시도 루프 (Fallback 로직 포함)
+        while (true) {
+            try {
+                // 1. 중복 제거
+                const uniqueChars = Array.from(new Set(state.charSet));
+                if (uniqueChars.length !== state.charSet.length) {
+                    if (shouldThrow) {
+                        const duplicates = state.charSet.filter((c, i) => state.charSet.indexOf(c) !== i);
+                        throw new Error(`[Ddu64 normalizeCharSet] Character set contains duplicate characters: [${[...new Set(duplicates)].join(", ")}]`);
+                    }
+                    state.charSet = uniqueChars;
+                    if (!state.isPredefined)
+                        state.requiredLength = state.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)
+                    throw new Error(`[Ddu64 normalizeCharSet] At least 2 unique characters required.`);
+                if (state.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);
+                if (invalidChar) {
+                    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)");
+                }
+                // 4. 패딩 충돌 검사
+                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)
+                        throw new Error(`[Ddu64 normalizeCharSet] Padding character "${state.padding}" conflicts with charset.`);
+                    state.charSet = state.charSet.filter(c => c !== state.padding);
+                }
+                return {
+                    charSet: state.charSet.slice(0, state.requiredLength),
+                    padding: state.padding,
+                    charLength,
+                    isPredefined: state.isPredefined,
+                };
+            }
+            catch (e) {
+                // 사용자가 명시적으로 에러를 요청했거나, 복구 불가능한 에러인 경우
+                if (shouldThrow && !e.message.includes("internal retry"))
+                    throw e;
+                // 그 외에는 Fallback CharSet 사용
+                state = this.getFallbackCharSet(dduOptions);
+            }
+        }
+    }
+    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 };
+            }
+            return { charSet: set.slice(0, length), 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)
+                    throw new Error(`[Ddu64 Constructor] paddingChar is required when dduChar is provided.`);
+                const arr = typeof finalDduChar === "string" ? [...finalDduChar.trim()] : [...finalDduChar];
+                if (shouldThrow) {
+                    const uniqueSize = new Set(arr).size;
+                    if (uniqueSize !== arr.length) {
+                        const duplicates = arr.filter((c, i) => arr.indexOf(c) !== i);
+                        throw new Error(`[Ddu64 Constructor] Character set contains duplicate characters: [${[...new Set(duplicates)].join(", ")}]`);
+                    }
+                }
+                const reqLen = dduOptions?.requiredLength ?? arr.length;
+                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 cs = this.getCharSetOrThrow(symbol);
+            return buildMeta(cs.charSet, cs.paddingChar, cs.maxRequiredLength, true);
+        }
+        catch (error) {
+            if (shouldThrow)
+                throw error;
+            return this.getFallbackCharSet(dduOptions);
+        }
+    }
+    getFallbackCharSet(dduOptions) {
+        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 };
+    }
+    shouldUsePowerOfTwo(length, preference) {
+        if (preference !== undefined)
+            return preference ? length > 0 : false;
+        return length > 0 && (length & (length - 1)) === 0;
+    }
+    getCharSetOrThrow(symbol) {
+        const cs = getCharSet(symbol);
+        if (!cs)
+            throw new Error(`CharSet with symbol ${symbol} not found`);
+        return cs;
+    }
+    validateCombinationDuplicates(charSet, paddingChar, requiredLength) {
+        // 작은 크기의 단일 문자 집합에 대해서만 '조합 충돌' 검사를 수행 (안전장치)
+        if (charSet[0].length !== 1 || requiredLength > 256)
+            return;
+        const limit = Math.min(charSet.length, requiredLength);
+        const targetChars = charSet.slice(0, limit);
+        const combinations = new Set();
+        const add = (s, context) => {
+            if (combinations.has(s))
+                throw new Error(`Combination conflict: ${context}`);
+            combinations.add(s);
         };
+        targetChars.forEach(c => combinations.add(c));
+        combinations.add(paddingChar);
+        for (const c1 of targetChars) {
+            for (const c2 of targetChars)
+                add(c1 + c2, `"${c1}" + "${c2}"`);
+            add(c1 + paddingChar, `"${c1}" + padding`);
+            add(paddingChar + c1, `padding + "${c1}"`);
+        }
+        add(paddingChar + paddingChar, "double padding");
     }
 }