@ddunigma/node 2.0.0 → 2.0.2

package/README.md

@@ -1,7 +1,8 @@
-## ddunigma Node 
+## ddunigma Node
+
 [![npm version](https://badge.fury.io/js/@ddunigma%2Fnode.svg)](https://www.npmjs.com/package/@ddunigma/node)
 
-## Overview 
+## Overview
 
 Node.js implementation of [ddunigma](https://github.com/i3l3/ddunigma) (Python original)
 
@@ -46,23 +47,23 @@ console.log(decoded); // "Hello World!"
 import { Ddu64, DduSetSymbol } from "@ddunigma/node";
 
 // ONECHARSET (64개 문자)
-const encoder1 = new Ddu64(undefined, undefined, { 
-  dduSetSymbol: DduSetSymbol.ONECHARSET 
+const encoder1 = new Ddu64(undefined, undefined, {
+  dduSetSymbol: DduSetSymbol.ONECHARSET,
 });
 
 // DDU (8개 문자)
-const encoder2 = new Ddu64(undefined, undefined, { 
-  dduSetSymbol: DduSetSymbol.DDU 
+const encoder2 = new Ddu64(undefined, undefined, {
+  dduSetSymbol: DduSetSymbol.DDU,
 });
 
 // TWOCHARSET (1024개 문자)
-const encoder3 = new Ddu64(undefined, undefined, { 
-  dduSetSymbol: DduSetSymbol.TWOCHARSET 
+const encoder3 = new Ddu64(undefined, undefined, {
+  dduSetSymbol: DduSetSymbol.TWOCHARSET,
 });
 
 // THREECHARSET (32768개 문자)
-const encoder4 = new Ddu64(undefined, undefined, { 
-  dduSetSymbol: DduSetSymbol.THREECHARSET 
+const encoder4 = new Ddu64(undefined, undefined, {
+  dduSetSymbol: DduSetSymbol.THREECHARSET,
 });
 
 const text = "안녕하세요";
@@ -77,8 +78,10 @@ const decodedBuffer = encoder1.decodeToBuffer(encoded);
 import { Ddu64 } from "@ddunigma/node";
 
 const koreanChars = [
-  "뜌", "뜍", "뜎", "뜏", "뜐", "뜑", "뜒", "뜓", "뜔", "뜕", "뜖", "뜗", "뜘", "뜙", "뜚", "뜛",
-  "뜜", "뜝", "뜞", "뜟", "뜠", "뜡", "뜢", "뜣", "뜤", "뜥", "뜦", "뜧", "뜨", "뜩", "뜪", "뜫",
+  "뜌", "뜍", "뜎", "뜏", "뜐", "뜑", "뜒", "뜓",
+  "뜔", "뜕", "뜖", "뜗", "뜘", "뜙", "뜚", "뜛",
+  "뜜", "뜝", "뜞", "뜟", "뜠", "뜡", "뜢", "뜣",
+  "뜨", "뜩", "뜪", "뜫",
   // ... 256개 문자
 ];
 
@@ -90,6 +93,39 @@ const decoded = encoder.decode(encoded);
 const decodedBuffer = encoder.decodeToBuffer(encoded);
 ```
 
+### 압축 인코딩 사용
+
+```typescript
+import { Ddu64 } from "@ddunigma/node";
+
+// 생성자에서 기본 압축 활성화
+const encoder = new Ddu64(undefined, undefined, {
+  compress: true,
+});
+
+// 또는 encode 호출 시 압축 옵션 지정
+const text = "반복되는 긴 텍스트...".repeat(100);
+const encoded = encoder.encode(text, { compress: true });
+const decoded = encoder.decode(encoded); // 자동으로 압축 해제
+```
+
+### Zip Bomb 방어 설정
+
+```typescript
+import { Ddu64 } from "@ddunigma/node";
+
+// 디코딩/압축해제 크기 제한 설정 (기본값: 64MB)
+const encoder = new Ddu64(undefined, undefined, {
+  maxDecodedBytes: 10 * 1024 * 1024, // 10MB
+  maxDecompressedBytes: 50 * 1024 * 1024, // 50MB
+});
+
+// 또는 decode 호출 시 옵션 지정
+const decoded = encoder.decode(encoded, {
+  maxDecodedBytes: 1024 * 1024, // 1MB
+});
+```
+
 ## API
 
 ### `new Ddu64(dduChar?, paddingChar?, options?)`
@@ -97,29 +133,65 @@ const decodedBuffer = encoder.decodeToBuffer(encoded);
 인코더 인스턴스를 생성합니다.
 
 **Parameters:**
-- `dduChar` (string | string[]): charset 문자열 또는 배열
-- `paddingChar` (string): 패딩 문자
-- `options` (DduOptions): 옵션 객체
-  - `dduSetSymbol`: 미리 정의된 charset 사용
-  - `encoding`: Buffer encoding (기본값: 'utf-8')
-  - `usePowerOfTwo`: 2의 제곱수 강제 여부
-  - `useBuildErrorReturn`: 에러 발생 시 throw 여부
 
-### `encode(data: string | Buffer): string`
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `dduChar` | `string \| string[]` | charset 문자열 또는 배열 |
+| `paddingChar` | `string` | 패딩 문자 |
+| `options` | `DduConstructorOptions` | 옵션 객체 |
 
-데이터를 인코딩
+**DduConstructorOptions:**
 
-### `decode(encoded: string): string`
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `dduSetSymbol` | `DduSetSymbol` | `DDU` | 미리 정의된 charset 심볼 |
+| `encoding` | `BufferEncoding` | `'utf-8'` | 문자열 인코딩 |
+| `usePowerOfTwo` | `boolean` | `true` | 2의 제곱수 강제 여부 |
+| `useBuildErrorReturn` | `boolean` | `false` | 에러 발생 시 throw 여부 |
+| `compress` | `boolean` | `false` | 기본 압축 활성화 |
+| `maxDecodedBytes` | `number` | `67108864` | 최대 디코딩 바이트 (64MB) |
+| `maxDecompressedBytes` | `number` | `67108864` | 최대 압축해제 바이트 (64MB) |
 
-인코딩된 문자열을 디코딩
+### `encode(data, options?): string`
 
-### `decodeToBuffer(encoded: string): Buffer`
+데이터를 인코딩합니다.
 
-인코딩된 문자열을 Buffer로 직접 디코딩
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `data` | `string \| Buffer` | 인코딩할 데이터 |
+| `options.compress` | `boolean` | 압축 사용 여부 |
+
+**Returns:** 인코딩된 문자열
+
+### `decode(encoded, options?): string`
+
+인코딩된 문자열을 디코딩합니다.
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `encoded` | `string` | 인코딩된 문자열 |
+| `options.maxDecodedBytes` | `number` | 최대 디코딩 바이트 |
+| `options.maxDecompressedBytes` | `number` | 최대 압축해제 바이트 |
+
+**Returns:** 디코딩된 문자열
 
-### `getCharSetInfo()`
+### `decodeToBuffer(encoded, options?): Buffer`
 
-현재 charset 정보를 반환
+인코딩된 문자열을 Buffer로 직접 디코딩합니다.
+
+**Parameters:** `decode`와 동일
+
+**Returns:** 디코딩된 Buffer
+
+### `getCharSetInfo(): CharSetInfo`
+
+현재 인코더의 charset 정보를 반환합니다.
+
+**Returns:**
 
 ```typescript
 {
@@ -129,5 +201,17 @@ const decodedBuffer = encoder.decodeToBuffer(encoded);
   bitLength: number;
   usePowerOfTwo: boolean;
   encoding: BufferEncoding;
+  defaultCompress: boolean;
+  defaultMaxDecodedBytes: number;
+  defaultMaxDecompressedBytes: number;
 }
-```
+```
+
+## DduSetSymbol
+
+| Symbol | 문자 수 | 비트 길이 | 설명 |
+|--------|---------|-----------|------|
+| `DDU` | 8 | 3 | 한글 + 특수문자 기본 세트 |
+| `ONECHARSET` | 64 | 6 | 영문 + 숫자 + 특수문자 |
+| `TWOCHARSET` | 1024 | 10 | 2글자 조합 세트 |
+| `THREECHARSET` | 32768 | 15 | 3글자 조합 세트 |

package/dist/cjs/base/BaseDdu.d.ts

@@ -1,20 +1,46 @@
-import { DduOptions, BufferToDduBinaryResult } from "../types";
+import { DduOptions } from "../types";
 export declare abstract class BaseDdu {
     protected readonly defaultEncoding: BufferEncoding;
-    protected readonly binaryLookup: string[];
-    protected escapeRegExp(str: string): string;
-    protected splitString(s: string, length: number): Generator<string>;
-    protected getLargestPowerOfTwo(n: number): number;
+    /**
+     * 주어진 숫자보다 작거나 같은 가장 큰 2의 제곱수의 지수를 반환합니다.
+     * @param n - 대상 숫자
+     * @returns 2의 제곱수 지수 (예: n=8 → 3, n=64 → 6)
+     * @example getLargestPowerOfTwoExponent(8) // 3
+     * @example getLargestPowerOfTwoExponent(100) // 6
+     */
     protected getLargestPowerOfTwoExponent(n: number): number;
+    /**
+     * charset 크기에 필요한 비트 길이를 계산합니다.
+     * @param setLength - charset 문자 수
+     * @returns 필요한 비트 수
+     * @example getBitLength(64) // 6
+     * @example getBitLength(100) // 7
+     */
     protected getBitLength(setLength: number): number;
-    protected bufferToDduBinary(input: Buffer, bitLength: number): BufferToDduBinaryResult;
-    protected dduBinaryToBuffer(decodedBin: string, paddingBits: number): Buffer;
+    /**
+     * 입력 데이터를 인코딩합니다.
+     * @param input - 인코딩할 문자열 또는 Buffer
+     * @param options - 인코딩 옵션
+     * @returns 인코딩된 문자열
+     */
     abstract encode(input: Buffer | string, options?: DduOptions): string;
+    /**
+     * 인코딩된 문자열을 Buffer로 디코딩합니다.
+     * @param input - 인코딩된 문자열
+     * @param options - 디코딩 옵션
+     * @returns 디코딩된 Buffer
+     */
     abstract decodeToBuffer(input: string, options?: DduOptions): Buffer;
+    /**
+     * 인코딩된 문자열을 원본 문자열로 디코딩합니다.
+     * @param input - 인코딩된 문자열
+     * @param options - 디코딩 옵션
+     * @returns 디코딩된 문자열
+     */
     abstract decode(input: string, options?: DduOptions): string;
     /**
-     * 테스트 및 디버깅용 추상 메서드
-     * 구현 클래스의 내부 상태 정보를 반환
+     * 현재 인코더의 charset 정보를 반환합니다.
+     * @returns charset 설정 정보 객체
      */
     abstract getCharSetInfo(): {
         charSet: string[];

package/dist/cjs/base/BaseDdu.js

@@ -4,51 +4,26 @@ exports.BaseDdu = void 0;
 class BaseDdu {
     constructor() {
         this.defaultEncoding = "utf-8";
-        this.binaryLookup = Array.from({ length: 256 }, (_, i) => i.toString(2).padStart(8, "0"));
-    }
-    escapeRegExp(str) {
-        return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-    }
-    *splitString(s, length) {
-        for (let i = 0; i < s.length; i += length) {
-            yield s.slice(i, Math.min(i + length, s.length));
-        }
-    }
-    getLargestPowerOfTwo(n) {
-        return 2 ** Math.floor(Math.log2(n));
     }
+    /**
+     * 주어진 숫자보다 작거나 같은 가장 큰 2의 제곱수의 지수를 반환합니다.
+     * @param n - 대상 숫자
+     * @returns 2의 제곱수 지수 (예: n=8 → 3, n=64 → 6)
+     * @example getLargestPowerOfTwoExponent(8) // 3
+     * @example getLargestPowerOfTwoExponent(100) // 6
+     */
     getLargestPowerOfTwoExponent(n) {
         return Math.floor(Math.log2(n));
     }
+    /**
+     * charset 크기에 필요한 비트 길이를 계산합니다.
+     * @param setLength - charset 문자 수
+     * @returns 필요한 비트 수
+     * @example getBitLength(64) // 6
+     * @example getBitLength(100) // 7
+     */
     getBitLength(setLength) {
         return Math.ceil(Math.log2(setLength));
     }
-    bufferToDduBinary(input, bitLength) {
-        // 성능 최적화: reduce 대신 for loop + join 사용
-        if (input.length === 0) {
-            return { dduBinary: [], padding: 0 };
-        }
-        const binaryParts = new Array(input.length);
-        for (let i = 0; i < input.length; i++) {
-            binaryParts[i] = this.binaryLookup[input[i]];
-        }
-        const encodedBin = binaryParts.join("");
-        const dduBinary = Array.from(this.splitString(encodedBin, bitLength));
-        const padding = bitLength - dduBinary[dduBinary.length - 1].length;
-        if (padding > 0) {
-            dduBinary[dduBinary.length - 1] += "0".repeat(padding);
-        }
-        return { dduBinary, padding };
-    }
-    dduBinaryToBuffer(decodedBin, paddingBits) {
-        if (paddingBits > 0) {
-            decodedBin = decodedBin.slice(0, -paddingBits);
-        }
-        const buffer = [];
-        for (let i = 0; i < decodedBin.length; i += 8) {
-            buffer.push(parseInt(decodedBin.slice(i, i + 8), 2));
-        }
-        return Buffer.from(buffer);
-    }
 }
 exports.BaseDdu = BaseDdu;

package/dist/cjs/charSets/index.d.ts

@@ -1,4 +1,18 @@
 import { CharSetConfig, DduSetSymbol } from "../types";
+/**
+ * 심볼에 해당하는 charset 설정을 반환합니다.
+ * @param symbol - charset 심볼
+ * @returns CharSetConfig 또는 undefined
+ */
 export declare function getCharSet(symbol: DduSetSymbol): CharSetConfig | undefined;
+/**
+ * 모든 사용 가능한 charset 심볼 목록을 반환합니다.
+ * @returns DduSetSymbol 배열
+ */
 export declare function getAllSymbols(): DduSetSymbol[];
+/**
+ * 해당 심볼의 charset이 존재하는지 확인합니다.
+ * @param symbol - 확인할 charset 심볼
+ * @returns 존재 여부
+ */
 export declare function hasCharSet(symbol: DduSetSymbol): boolean;