@ddunigma/node 2.0.2 → 2.1.1

package/LICENCE

@@ -1,4 +1,4 @@
-Copyright 2025 i3l3
+Copyright 2025 junhypar
 
 Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
 

package/README.md

@@ -6,6 +6,8 @@
 
 Node.js implementation of [ddunigma](https://github.com/i3l3/ddunigma) (Python original)
 
+커스텀 charset을 사용하는 Base64 스타일 인코더/디코더 라이브러리입니다.
+
 ### Credits
 
 - Original Python Implementation by:
@@ -25,7 +27,7 @@ npm install @ddunigma/node
 
 ## Usage
 
-### 간단한 문자열 인코딩/디코딩
+### 기본 인코딩/디코딩
 
 ```typescript
 import { Ddu64 } from "@ddunigma/node";
@@ -69,64 +71,224 @@ const encoder4 = new Ddu64(undefined, undefined, {
 const text = "안녕하세요";
 const encoded = encoder1.encode(text);
 const decoded = encoder1.decode(encoded);
-const decodedBuffer = encoder1.decodeToBuffer(encoded);
 ```
 
-### 커스텀 Charset 사용
+### 압축 인코딩
 
 ```typescript
 import { Ddu64 } from "@ddunigma/node";
 
-const koreanChars = [
-  "뜌", "뜍", "뜎", "뜏", "뜐", "뜑", "뜒", "뜓",
-  "뜔", "뜕", "뜖", "뜗", "뜘", "뜙", "뜚", "뜛",
-  "뜜", "뜝", "뜞", "뜟", "뜠", "뜡", "뜢", "뜣",
-  "뜨", "뜩", "뜪", "뜫",
-  // ... 256개 문자
-];
+// 생성자에서 기본 압축 활성화
+const encoder = new Ddu64(undefined, undefined, {
+  compress: true,
+});
 
-const encoder = new Ddu64(koreanChars, "뭐");
+// 또는 encode 호출 시 압축 옵션 지정
+const text = "반복되는 긴 텍스트...".repeat(100);
+const encoded = encoder.encode(text, { compress: true });
+const decoded = encoder.decode(encoded); // 자동으로 압축 해제
+```
 
-const text = "안녕하세요12";
-const encoded = encoder.encode(text);
-const decoded = encoder.decode(encoded);
-const decodedBuffer = encoder.decodeToBuffer(encoded);
+### URL-Safe 인코딩
+
+```typescript
+import { Ddu64 } from "@ddunigma/node";
+
+const encoder = new Ddu64(undefined, undefined, {
+  dduSetSymbol: DduSetSymbol.ONECHARSET,
+  urlSafe: true, // +, /, = 를 URL 안전 문자로 변환
+});
+
+const encoded = encoder.encode("Hello World!");
+// URL에서 안전하게 사용 가능한 문자열 반환
 ```
 
-### 압축 인코딩 사용
+### 체크섬 (무결성 검증)
 
 ```typescript
 import { Ddu64 } from "@ddunigma/node";
 
-// 생성자에서 기본 압축 활성화
 const encoder = new Ddu64(undefined, undefined, {
-  compress: true,
+  checksum: true, // CRC32 체크섬 활성화
 });
 
-// 또는 encode 호출 시 압축 옵션 지정
-const text = "반복되는 긴 텍스트...".repeat(100);
-const encoded = encoder.encode(text, { compress: true });
-const decoded = encoder.decode(encoded); // 자동으로 압축 해제
+const encoded = encoder.encode("Important data", { checksum: true });
+const decoded = encoder.decode(encoded); // 자동으로 체크섬 검증
+// 체크섬 불일치 시 에러 발생
+```
+
+### 암호화
+
+```typescript
+import { Ddu64 } from "@ddunigma/node";
+
+const encoder = new Ddu64(undefined, undefined, {
+  encryptionKey: "my-secret-key-123", // AES-256-GCM 암호화
+});
+
+const encoded = encoder.encode("Secret message!");
+const decoded = encoder.decode(encoded); // 자동으로 복호화
+```
+
+### 청크 분할
+
+```typescript
+import { Ddu64 } from "@ddunigma/node";
+
+const encoder = new Ddu64();
+
+const encoded = encoder.encode(longData, {
+  chunkSize: 76, // 76자마다 분할
+  chunkSeparator: "\n", // 줄바꿈으로 구분
+});
+// 결과: "ABCDxyz...\nEFGHijk...\n..."
+
+const decoded = encoder.decode(encoded); // 자동으로 줄바꿈 제거
+```
+
+### 비동기 인코딩/디코딩
+
+```typescript
+import { Ddu64 } from "@ddunigma/node";
+
+const encoder = new Ddu64();
+
+// 비동기 인코딩 (이벤트 루프 블로킹 방지)
+const encoded = await encoder.encodeAsync(largeData);
+const decoded = await encoder.decodeAsync(encoded);
+const buffer = await encoder.decodeToBufferAsync(encoded);
+```
+
+### 진행률 콜백
+
+```typescript
+import { Ddu64 } from "@ddunigma/node";
+
+const encoder = new Ddu64();
+
+encoder.encode(largeData, {
+  onProgress: (info) => {
+    console.log(`진행률: ${info.percent}%`);
+    console.log(`처리됨: ${info.processedBytes}/${info.totalBytes}`);
+  },
+});
+```
+
+### 통계/분석
+
+```typescript
+import { Ddu64 } from "@ddunigma/node";
+
+const encoder = new Ddu64();
+
+const stats = encoder.getStats("Test data", { compress: true });
+console.log(stats);
+// {
+//   originalSize: 9,
+//   encodedSize: 12,
+//   compressedSize: 17,
+//   compressionRatio: 1.89,
+//   expansionRatio: 1.33,
+//   charsetSize: 64,
+//   bitLength: 6
+// }
 ```
 
-### Zip Bomb 방어 설정
+### 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
-});
+// 제한 초과 시 에러 발생
+```
+
+---
+
+## CharsetBuilder
+
+커스텀 charset을 쉽게 생성할 수 있는 빌더 유틸리티입니다.
+
+```typescript
+import { CharsetBuilder } from "@ddunigma/node";
+
+// 유니코드 범위에서 생성
+const chars1 = CharsetBuilder.fromUnicodeRange(0x4e00, 0x4e3f).build();
+
+// Base64 문자셋
+const chars2 = CharsetBuilder.base64().build();
+
+// 혼동 문자 제외 (0, O, 1, l, I 등)
+const chars3 = CharsetBuilder.base64().excludeConfusing().build();
+
+// 2의 제곱수로 제한
+const chars4 = CharsetBuilder.fromString("ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789")
+  .limitToPowerOfTwo()
+  .build(); // 32자
+
+// URL 안전 문자만
+const chars5 = CharsetBuilder.base64().excludeUrlUnsafe().build();
+
+// 시드 기반 셔플
+const chars6 = CharsetBuilder.base64().shuffle(12345).build();
+
+// 패딩 문자와 함께 빌드
+const { charset, padding } = CharsetBuilder.base64().buildWithPadding();
+```
+
+---
+
+## DduPipeline
+
+다단계 인코딩/암호화/압축을 조합할 수 있는 파이프라인 빌더입니다.
+
+```typescript
+import { DduPipeline, Ddu64 } from "@ddunigma/node";
+
+const encoder = new Ddu64();
+
+// 압축 → 암호화 → 인코딩 파이프라인
+const pipeline = new DduPipeline()
+  .compress()
+  .encrypt("my-secret-key")
+  .encode(encoder);
+
+const encoded = pipeline.processToString("Hello World!");
+
+// 역순 파이프라인으로 복원
+const decoded = pipeline.reverse().processToString(encoded);
 ```
 
-## API
+---
+
+## 스트림 지원
+
+대용량 파일 처리를 위한 스트림 인코딩/디코딩을 지원합니다.
+
+```typescript
+import { Ddu64, createEncodeStream, createDecodeStream } from "@ddunigma/node";
+import fs from "fs";
+
+const encoder = new Ddu64();
+
+// 인코딩 스트림
+fs.createReadStream("input.bin")
+  .pipe(createEncodeStream(encoder))
+  .pipe(fs.createWriteStream("output.txt"));
+
+// 디코딩 스트림
+fs.createReadStream("output.txt")
+  .pipe(createDecodeStream(encoder))
+  .pipe(fs.createWriteStream("restored.bin"));
+```
+
+---
+
+## API Reference
 
 ### `new Ddu64(dduChar?, paddingChar?, options?)`
 
@@ -134,84 +296,96 @@ const decoded = encoder.decode(encoded, {
 
 **Parameters:**
 
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `dduChar` | `string \| string[]` | charset 문자열 또는 배열 |
-| `paddingChar` | `string` | 패딩 문자 |
-| `options` | `DduConstructorOptions` | 옵션 객체 |
+| Parameter     | Type                    | Description              |
+| ------------- | ----------------------- | ------------------------ |
+| `dduChar`     | `string \| string[]`    | charset 문자열 또는 배열 |
+| `paddingChar` | `string`                | 패딩 문자                |
+| `options`     | `DduConstructorOptions` | 옵션 객체                |
 
 **DduConstructorOptions:**
 
-| 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) |
+| 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) |
+| `urlSafe`              | `boolean`        | `false`     | URL-Safe 모드               |
+| `encryptionKey`        | `string`         | `undefined` | AES-256-GCM 암호화 키       |
+| `checksum`             | `boolean`        | `false`     | CRC32 체크섬 활성화         |
+| `chunkSize`            | `number`         | `undefined` | 청크 분할 크기              |
+| `chunkSeparator`       | `string`         | `'\n'`      | 청크 구분자                 |
 
 ### `encode(data, options?): string`
 
 데이터를 인코딩합니다.
 
-**Parameters:**
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `data` | `string \| Buffer` | 인코딩할 데이터 |
-| `options.compress` | `boolean` | 압축 사용 여부 |
+**DduOptions:**
 
-**Returns:** 인코딩된 문자열
+| Option           | Type       | Description      |
+| ---------------- | ---------- | ---------------- |
+| `compress`       | `boolean`  | 압축 사용 여부   |
+| `checksum`       | `boolean`  | 체크섬 추가 여부 |
+| `chunkSize`      | `number`   | 청크 분할 크기   |
+| `chunkSeparator` | `string`   | 청크 구분자      |
+| `onProgress`     | `function` | 진행률 콜백      |
 
 ### `decode(encoded, options?): string`
 
 인코딩된 문자열을 디코딩합니다.
 
-**Parameters:**
+### `decodeToBuffer(encoded, options?): Buffer`
 
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `encoded` | `string` | 인코딩된 문자열 |
-| `options.maxDecodedBytes` | `number` | 최대 디코딩 바이트 |
-| `options.maxDecompressedBytes` | `number` | 최대 압축해제 바이트 |
+인코딩된 문자열을 Buffer로 직접 디코딩합니다.
 
-**Returns:** 디코딩된 문자열
+### `encodeAsync(data, options?): Promise<string>`
 
-### `decodeToBuffer(encoded, options?): Buffer`
+비동기로 데이터를 인코딩합니다.
 
-인코딩된 문자열을 Buffer로 직접 디코딩합니다.
+### `decodeAsync(encoded, options?): Promise<string>`
 
-**Parameters:** `decode`와 동일
+비동기로 데이터를 디코딩합니다.
 
-**Returns:** 디코딩된 Buffer
+### `decodeToBufferAsync(encoded, options?): Promise<Buffer>`
 
-### `getCharSetInfo(): CharSetInfo`
+비동기로 Buffer로 디코딩합니다.
 
-현재 인코더의 charset 정보를 반환합니다.
+### `getStats(data, options?): DduEncodeStats`
 
-**Returns:**
+인코딩 통계 정보를 반환합니다.
 
 ```typescript
 {
-  charSet: string[];
-  paddingChar: string;
-  charLength: number;
-  bitLength: number;
-  usePowerOfTwo: boolean;
-  encoding: BufferEncoding;
-  defaultCompress: boolean;
-  defaultMaxDecodedBytes: number;
-  defaultMaxDecompressedBytes: number;
+  originalSize: number;      // 원본 데이터 크기
+  encodedSize: number;       // 인코딩된 문자열 길이
+  compressedSize?: number;   // 압축된 크기
+  compressionRatio?: number; // 압축률 (0-1)
+  expansionRatio: number;    // 인코딩 확장 비율
+  charsetSize: number;       // charset 크기
+  bitLength: number;         // 비트 길이
 }
 ```
 
+### `getCharSetInfo(): CharSetInfo`
+
+현재 인코더의 charset 정보를 반환합니다.
+
+---
+
 ## DduSetSymbol
 
-| Symbol | 문자 수 | 비트 길이 | 설명 |
-|--------|---------|-----------|------|
-| `DDU` | 8 | 3 | 한글 + 특수문자 기본 세트 |
-| `ONECHARSET` | 64 | 6 | 영문 + 숫자 + 특수문자 |
-| `TWOCHARSET` | 1024 | 10 | 2글자 조합 세트 |
-| `THREECHARSET` | 32768 | 15 | 3글자 조합 세트 |
+| Symbol         | 문자 수 | 비트 길이 | 설명                      |
+| -------------- | ------- | --------- | ------------------------- |
+| `DDU`          | 8       | 3         | 한글 + 특수문자 기본 세트 |
+| `ONECHARSET`   | 64      | 6         | 영문 + 숫자 + 특수문자    |
+| `TWOCHARSET`   | 1024    | 10        | 2글자 조합 세트           |
+| `THREECHARSET` | 32768   | 15        | 3글자 조합 세트           |
+
+---
+
+## License
+
+BSD-2-Clause

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

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