@ddunigma/node 3.0.0 → 3.0.2

package/README.md

@@ -8,6 +8,13 @@ V2 추가사항
 
 - 이제 한글 종성 결합 시스템을 활용하여 8개 기본 문자 × 8개 종성으로 64가지 조합을 만들어, 6비트를 한 글자로 표현합니다.
 
+### Credits
+
+- Original Python Implementation by:
+  - [@i3ls](https://github.com/i3l3)
+  - [@gunu3371](https://github.com/gunu3371)
+- Original Repository: [ddunigma](https://github.com/i3l3/ddunigma)
+
 ## Requirements
 
 - **Node.js >= 18.0.0**
@@ -36,305 +43,317 @@ dduV1.decode(".우땨땨이?땨뜌.이.뜌이?이!.우우땨이?우뜌.우땨뜌
 
 ---
 
-## 기본 사용법
-
-### 인코딩/디코딩
+## Binary Data
 
 ```typescript
-import { Ddu64 } from "@ddunigma/node";
-
-const encoder = new Ddu64();
+const ddu = new Ddu64();
+const input = new Uint8Array([0, 1, 127, 128, 255]);
 
-const encoded = encoder.encode("Hello World!");
-const decoded = encoder.decode(encoded);
+const encoded = ddu.encode(input);
+const bytes = ddu.decodeToUint8Array(encoded);
+const buffer = ddu.decodeToBuffer(encoded); // Node.js Buffer
 ```
 
-### 커스텀 charset
+## Presets
 
 ```typescript
-// 문자열 또는 배열로 charset 지정
-const encoder = new Ddu64("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/", "=");
+import { Ddu64, DduSetSymbol } from "@ddunigma/node";
 
-// 종성 결합 커스텀 charset (dduChar × codaChar 동적 생성)
-const encoder2 = new Ddu64(["가", "나", "다", "라"], "뭐", {
-  codaChar: ["", "ㄱ", "ㄲ", "ㄷ"], // 4×4 = 16개 조합
-});
+// 기본값 - 한글 종성 결합 64문자
+new Ddu64();
+
+// 구버전 호환 8문자
+new Ddu64(undefined, undefined, { dduSetSymbol: DduSetSymbol.DDU_V1 });
+
+// 영문+숫자 64문자
+new Ddu64(undefined, undefined, { dduSetSymbol: DduSetSymbol.ONECHARSET });
 ```
 
-### 프리셋
+| Symbol       | 문자 수 | 설명                               |
+| ------------ | ------: | ---------------------------------- |
+| `DDU`        |      64 | 한글 기본 문자 8개 × 종성 8개 조합 |
+| `DDU_V1`     |       8 | 기존 8문자 쌍 방식 (하위 호환)     |
+| `ONECHARSET` |      64 | 영문, 숫자, 일부 특수문자          |
 
-| Symbol       | 문자 수 | 비트 | 설명                                 |
-| ------------ | ------- | ---- | ------------------------------------ |
-| `DDU`        | 64      | 6    | 한글 종성 결합 (8 기본문자 × 8 종성) |
-| `DDU_V1`     | 8       | 3    | 구버전 호환 (뜌땨이우야!?.)          |
-| `ONECHARSET` | 64      | 6    | 영문 + 숫자 + 특수문자               |
+## Custom Charset
 
 ```typescript
-import { Ddu64, DduSetSymbol } from "@ddunigma/node";
-
-const encoder = new Ddu64(undefined, undefined, {
-  dduSetSymbol: DduSetSymbol.ONECHARSET,
+// 문자열로 직접 지정
+const base64Like = new Ddu64(
+  "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/",
+  "=",
+);
+
+// 한글 종성 조합으로 커스텀 charset 생성
+const hangulCoda = new Ddu64(["가", "나", "다", "라"], "뭐", {
+  codaChar: ["", "ㄱ", "ㄲ", "ㄷ"],
 });
+// → 가, 각, 갂, 갇, 나, 낙, 낚, 낟, 다, 닥, 닦, 닫, 라, 락, 랔, 랗 (16문자)
 ```
 
----
+## CharsetBuilder
 
-## 고급 기능
+```typescript
+import { CharsetBuilder, Ddu64 } from "@ddunigma/node";
 
-### 압축
+// Base64에서 혼동 문자 제거 후 2의 제곱수로 맞추기
+const { charset, padding } = CharsetBuilder.base64()
+  .excludeConfusing()
+  .limitToPowerOfTwo()
+  .buildWithPadding();
 
-deflate(기본) 또는 brotli 압축을 지원합니다. 디코딩 시 자동으로 압축 여부를 감지합니다.
+const ddu = new Ddu64(charset, padding);
 
-```typescript
-const encoder = new Ddu64();
+// 유니코드 범위에서 생성
+const chars = CharsetBuilder.fromUnicodeRange(0x4e00, 0x4e3f)
+  .shuffle(12345)
+  .limitToPowerOfTwo()
+  .build();
+```
 
-// 호출 시 옵션으로 지정
-const encoded = encoder.encode(longText, { compress: true });
-const decoded = encoder.decode(encoded);
+## Compression
 
-// 생성자에서 기본 활성화
-const compressEncoder = new Ddu64(undefined, undefined, {
-  compress: true,
-  compressionAlgorithm: "brotli",
-  compressionLevel: 6,
+```typescript
+const ddu = new Ddu64(undefined, undefined, {
+  compress: true, // 압축 활성화
+  compressionAlgorithm: "deflate", // "deflate" | "brotli"
+  compressionLevel: 6, // deflate: 0-9, brotli: 0-11
 });
+
+const encoded = ddu.encode("A".repeat(1000)); // 압축되어 짧아짐
+const decoded = ddu.decode(encoded);
 ```
 
-### 암호화
+압축은 원본보다 작아질 때만 적용됩니다. 압축 결과가 더 크면 비압축으로 저장됩니다.
 
-AES-256-GCM 암호화를 내장합니다. 동일한 키로 생성된 인코더만 복호화할 수 있습니다.
+## Encryption
 
 ```typescript
-const encoder = new Ddu64(undefined, undefined, {
+// SHA-256 키 파생 (기본)
+const ddu = new Ddu64(undefined, undefined, {
   encryptionKey: "my-secret-key",
 });
 
-const encoded = encoder.encode("비밀 메시지");
-const decoded = encoder.decode(encoded);
+const encoded = ddu.encode("secret message");
+const decoded = ddu.decode(encoded); // 같은 키로만 복호화 가능
+
+// PBKDF2 키 파생
+const dduPbkdf2 = new Ddu64(undefined, undefined, {
+  encryptionKey: "user password",
+  keyDerivation: {
+    algorithm: "pbkdf2",
+    salt: "app-specific-salt",
+    iterations: 210_000,
+    hash: "SHA-256",
+  },
+});
 ```
 
-### 체크섬
-
-CRC32 체크섬으로 데이터 무결성을 검증합니다.
+## Checksum
 
 ```typescript
-const encoder = new Ddu64();
+const ddu = new Ddu64(undefined, undefined, { checksum: true });
 
-const encoded = encoder.encode(data, { checksum: true });
-const decoded = encoder.decode(encoded, { checksum: true });
-// 데이터 변조 시 에러 발생
+const encoded = ddu.encode("data"); // CRC32 체크섬 포함
+const decoded = ddu.decode(encoded); // 무결성 검증 후 반환
 ```
 
-### URL-Safe
-
-`+`, `/`, `=` 를 URL 안전 문자(`-`, `_`, `.`)로 변환합니다.
+## URL-Safe
 
 ```typescript
-const encoder = new Ddu64("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/", "=", {
+const ddu = new Ddu64("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/", "=", {
   urlSafe: true,
 });
-```
 
-> charset/padding에 `-`, `_`, `.` 가 포함되면 urlSafe를 활성화할 수 없습니다.
+// +→- /→_ =→. 로 자동 변환
+const encoded = ddu.encode("URL safe text");
+```
 
-### 청크 분할
+## Chunking
 
 ```typescript
-const encoder = new Ddu64();
-
-const encoded = encoder.encode(data, {
+const ddu = new Ddu64(undefined, undefined, {
   chunkSize: 76,
   chunkSeparator: "\n",
 });
-// 디코딩 시 구분자 자동 제거
-```
-
-### 비동기 처리
-
-대용량 데이터에서 이벤트 루프 블로킹을 방지합니다.
 
-```typescript
-const encoded = await encoder.encodeAsync(largeBuffer);
-const decoded = await encoder.decodeAsync(encoded);
-const buffer = await encoder.decodeToBufferAsync(encoded);
+const encoded = ddu.encode("long data ".repeat(100));
+// 76자마다 줄바꿈 삽입
 ```
 
-### 진행률 콜백
+## Obfuscation (한글 난독화)
 
 ```typescript
-encoder.encode(data, {
-  onProgress: ({ percent, stage }) => {
-    console.log(`${percent}% (${stage})`);
-  },
+const ddu = new Ddu64(undefined, undefined, {
+  encryptionKey: "secret",
+  obfuscate: true, // 암호화 필수
 });
+
+const encoded = ddu.encode("hello");
+// 출력이 한글 음절 블록(U+AC00–U+D7A3)으로 변환됨
 ```
 
-### 통계
+## Async (브라우저 호환)
 
 ```typescript
-const stats = encoder.getStats(data, { compress: true });
-// { originalSize, encodedSize, compressedSize, compressionRatio, expansionRatio, charsetSize, bitLength }
+// 브라우저에서는 async 메서드 사용
+import { Ddu64 } from "@ddunigma/node/browser";
+
+const ddu = new Ddu64();
+const encoded = await ddu.encodeAsync("browser text");
+const decoded = await ddu.decodeAsync(encoded);
 ```
 
-### Zip Bomb 방어
+Node.js에서도 async 메서드를 사용할 수 있습니다. 브라우저 진입점(`@ddunigma/node/browser`)은 Node.js 내장 모듈을 임포트하지 않습니다.
+
+## Web Streams
 
 ```typescript
-const encoder = new Ddu64(undefined, undefined, {
-  maxDecodedBytes: 10 * 1024 * 1024, // 10MB
-  maxDecompressedBytes: 50 * 1024 * 1024, // 50MB
+import { Ddu64, createReadableEncodeStream, createReadableDecodeStream } from "@ddunigma/node";
+
+const ddu = new Ddu64(undefined, undefined, {
+  compress: true,
+  encryptionKey: "stream-key",
 });
-```
 
----
+const encodedStream = readableByteStream.pipeThrough(
+  createReadableEncodeStream(ddu, { compress: true }),
+);
 
-## CharsetBuilder
+const decodedStream = encodedStream.pipeThrough(createReadableDecodeStream(ddu));
+```
 
-커스텀 charset을 빌더 패턴으로 생성합니다.
+## WASM Acceleration
 
 ```typescript
-import { CharsetBuilder } from "@ddunigma/node";
-
-// 유니코드 범위
-CharsetBuilder.fromUnicodeRange(0x4e00, 0x4e3f).build();
+import { Ddu64, preloadWasm } from "@ddunigma/node";
 
-// Base64에서 혼동 문자 제외
-CharsetBuilder.base64().excludeConfusing().build();
+await preloadWasm(); // 선택적 사전 로드
 
-// 2의 제곱수로 제한 + 시드 셔플
-CharsetBuilder.fromString("ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789")
-  .limitToPowerOfTwo()
-  .shuffle(12345)
-  .build();
+const ddu = new Ddu64(undefined, undefined, {
+  wasmThreshold: 4096, // 이 크기 이상일 때 WASM 사용
+});
 
-// 패딩 문자 자동 선택
-const { charset, padding } = CharsetBuilder.base64().buildWithPadding();
+const encoded = ddu.encode(new Uint8Array(1024 * 1024));
 ```
 
----
-
-## DduPipeline
+WASM을 사용할 수 없으면 JavaScript로 자동 폴백됩니다.
 
-압축 → 암호화 → 인코딩을 체이닝하고, `reverse()`로 역순 복원합니다.
+## Progress Callback
 
 ```typescript
-import { DduPipeline, Ddu64 } from "@ddunigma/node";
-
-const pipeline = new DduPipeline().compress(6, "brotli").encrypt("secret-key").encode(new Ddu64());
+const ddu = new Ddu64(undefined, undefined, { compress: true });
 
-const encoded = pipeline.processToString("Hello");
-const decoded = pipeline.reverse().processToString(encoded);
+ddu.encode("data", {
+  onProgress: ({ percent, stage }) => {
+    console.log(`${stage}: ${percent}%`);
+    // stage: start → compress → encrypt → encode → done
+  },
+});
 ```
 
----
-
-## 스트림
-
-대용량 파일을 메모리 효율적으로 처리합니다. 스트림 헤더로 압축/암호화를 자동 감지합니다.
+## Stats
 
 ```typescript
-import { Ddu64, createEncodeStream, createDecodeStream } from "@ddunigma/node";
-import fs from "fs";
+const ddu = new Ddu64(undefined, undefined, { compress: true });
+const stats = ddu.getStats("A".repeat(1000));
 
-const encoder = new Ddu64(undefined, undefined, {
-  compress: true,
-  encryptionKey: "stream-key",
-});
+// { originalSize, encodedSize, compressedSize, compressionRatio, expansionRatio, charsetSize, bitLength }
+```
 
-fs.createReadStream("input.bin")
-  .pipe(createEncodeStream(encoder))
-  .pipe(fs.createWriteStream("output.ddu"));
+## Size Limits
 
-fs.createReadStream("output.ddu")
-  .pipe(createDecodeStream(encoder))
-  .pipe(fs.createWriteStream("restored.bin"));
+```typescript
+const ddu = new Ddu64(undefined, undefined, {
+  maxDecodedBytes: 10 * 1024 * 1024, // 디코딩 최대 크기 (기본 64MB)
+  maxDecompressedBytes: 50 * 1024 * 1024, // 압축해제 최대 크기 (기본 64MB)
+});
 ```
 
 ---
 
-## API Reference
-
-### `new Ddu64(dduChar?, paddingChar?, options?)`
-
-| Parameter     | Type                    | Description              |
-| ------------- | ----------------------- | ------------------------ |
-| `dduChar`     | `string \| string[]`    | charset 문자열 또는 배열 |
-| `paddingChar` | `string`                | 패딩 문자                |
-| `options`     | `DduConstructorOptions` | 옵션 객체                |
-
-**생성자 옵션:**
-
-| Option                 | Type                    | Default     | Description                   |
-| ---------------------- | ----------------------- | ----------- | ----------------------------- |
-| `dduSetSymbol`         | `DduSetSymbol`          | `DDU`       | 프리셋 심볼                   |
-| `codaChar`             | `string[]`              | —           | 종성 배열 (동적 charset 생성) |
-| `encoding`             | `BufferEncoding`        | `'utf-8'`   | 문자열 인코딩                 |
-| `compress`             | `boolean`               | `false`     | 기본 압축 활성화              |
-| `compressionAlgorithm` | `"deflate" \| "brotli"` | `'deflate'` | 압축 알고리즘                 |
-| `compressionLevel`     | `number`                | `6`         | 압축 레벨                     |
-| `urlSafe`              | `boolean`               | `false`     | URL-Safe 모드                 |
-| `encryptionKey`        | `string`                | —           | AES-256-GCM 암호화 키         |
-| `checksum`             | `boolean`               | `false`     | CRC32 체크섬                  |
-| `chunkSize`            | `number`                | —           | 청크 분할 크기                |
-| `chunkSeparator`       | `string`                | `'\n'`      | 청크 구분자                   |
-| `maxDecodedBytes`      | `number`                | `67108864`  | 최대 디코딩 바이트 (64MB)     |
-| `maxDecompressedBytes` | `number`                | `67108864`  | 최대 압축해제 바이트 (64MB)   |
-| `throwOnError`         | `boolean`               | `false`     | 초기화 오류 시 throw          |
-| `useRepeatPadding`     | `boolean`               | `false`     | 패딩 문자 반복 방식           |
-| `usePowerOfTwo`        | `boolean`               | `true`      | 2의 제곱수 charset 강제       |
-
-**메서드:**
-
-| Method                                   | Return            | Description          |
-| ---------------------------------------- | ----------------- | -------------------- |
-| `encode(data, options?)`                 | `string`          | 인코딩               |
-| `decode(encoded, options?)`              | `string`          | 디코딩               |
-| `decodeToBuffer(encoded, options?)`      | `Buffer`          | Buffer로 디코딩      |
-| `encodeAsync(data, options?)`            | `Promise<string>` | 비동기 인코딩        |
-| `decodeAsync(encoded, options?)`         | `Promise<string>` | 비동기 디코딩        |
-| `decodeToBufferAsync(encoded, options?)` | `Promise<Buffer>` | 비동기 Buffer 디코딩 |
-| `getStats(data, options?)`               | `DduEncodeStats`  | 인코딩 통계          |
-| `getCharSetInfo()`                       | `CharSetInfo`     | charset 정보         |
-
-**encode/decode 옵션 (DduOptions):**
-
-| Option                 | Type                    | Description          |
-| ---------------------- | ----------------------- | -------------------- |
-| `compress`             | `boolean`               | 압축 사용            |
-| `compressionAlgorithm` | `"deflate" \| "brotli"` | 압축 알고리즘        |
-| `compressionLevel`     | `number`                | 압축 레벨            |
-| `checksum`             | `boolean`               | 체크섬 추가/검증     |
-| `chunkSize`            | `number`                | 청크 분할 크기       |
-| `chunkSeparator`       | `string`                | 청크 구분자          |
-| `maxDecodedBytes`      | `number`                | 최대 디코딩 바이트   |
-| `maxDecompressedBytes` | `number`                | 최대 압축해제 바이트 |
-| `onProgress`           | `function`              | 진행률 콜백          |
+## API
 
----
+```typescript
+class Ddu64 {
+  encode(data: string | Uint8Array, options?: DduOptions): string;
+  decode(encoded: string, options?: DduOptions): string;
+  decodeToUint8Array(encoded: string, options?: DduOptions): Uint8Array;
+  decodeToBuffer(encoded: string, options?: DduOptions): Buffer;
+
+  encodeAsync(data: string | Uint8Array, options?: DduOptions): Promise<string>;
+  decodeAsync(encoded: string, options?: DduOptions): Promise<string>;
+  decodeToUint8ArrayAsync(encoded: string, options?: DduOptions): Promise<Uint8Array>;
+  decodeToBufferAsync(encoded: string, options?: DduOptions): Promise<Buffer>;
+
+  getStats(data: string | Uint8Array, options?: DduOptions): DduEncodeStats;
+  getCharSetInfo(): CharSetInfo;
+
+  static setWorkerPoolSize(n: number): void;
+}
+```
 
-## Testing
+## Constructor Options
 
-```bash
-pnpm test            # 전체 테스트
-pnpm test:watch      # 워치 모드
-pnpm test:coverage   # 커버리지
+```typescript
+new Ddu64(dduChar?, paddingChar?, options?);
 ```
 
-## Build & Verify
+| Option                 | Type                    | Default     | 설명                  |
+| ---------------------- | ----------------------- | ----------- | --------------------- |
+| `dduSetSymbol`         | `DduSetSymbol`          | `DDU`       | 프리셋 선택           |
+| `dduChar`              | `string \| string[]`    | -           | 커스텀 charset        |
+| `paddingChar`          | `string`                | -           | 패딩 문자             |
+| `codaChar`             | `string[]`              | -           | 종성 조합 문자        |
+| `compress`             | `boolean`               | `false`     | 압축 활성화           |
+| `compressionAlgorithm` | `"deflate" \| "brotli"` | `"deflate"` | 압축 알고리즘         |
+| `compressionLevel`     | `number`                | `6`         | 압축 레벨             |
+| `encryptionKey`        | `string`                | -           | AES-256-GCM 암호화 키 |
+| `keyDerivation`        | `KeyDerivationOptions`  | `sha256`    | 키 파생 방식          |
+| `checksum`             | `boolean`               | `false`     | CRC32 체크섬          |
+| `urlSafe`              | `boolean`               | `false`     | URL-Safe 변환         |
+| `obfuscate`            | `boolean`               | `false`     | 한글 난독화           |
+| `chunkSize`            | `number`                | -           | 청크 분할 크기        |
+| `chunkSeparator`       | `string`                | `"\n"`      | 청크 구분자           |
+| `maxDecodedBytes`      | `number`                | `67108864`  | 디코딩 크기 제한      |
+| `maxDecompressedBytes` | `number`                | `67108864`  | 압축해제 크기 제한    |
+| `wasmThreshold`        | `number`                | `4096`      | WASM 사용 임계값      |
+| `throwOnError`         | `boolean`               | `false`     | 초기화 에러 시 throw  |
+
+## Per-Call Options
+
+`encode`, `decode`, `encodeAsync`, `decodeAsync` 등에서 호출별로 오버라이드 가능:
+
+| Option                 | Type                    | 설명               |
+| ---------------------- | ----------------------- | ------------------ |
+| `compress`             | `boolean`               | 압축 사용 여부     |
+| `compressionAlgorithm` | `"deflate" \| "brotli"` | 압축 알고리즘      |
+| `compressionLevel`     | `number`                | 압축 레벨          |
+| `encrypt`              | `boolean`               | 암호화 사용 여부   |
+| `checksum`             | `boolean`               | 체크섬 사용 여부   |
+| `obfuscate`            | `boolean`               | 난독화 사용 여부   |
+| `chunkSize`            | `number`                | 청크 크기          |
+| `maxDecodedBytes`      | `number`                | 디코딩 크기 제한   |
+| `maxDecompressedBytes` | `number`                | 압축해제 크기 제한 |
+| `onProgress`           | `(info) => void`        | 진행률 콜백        |
+
+## Entry Points
+
+| Import Path              | 용도                                  |
+| ------------------------ | ------------------------------------- |
+| `@ddunigma/node`         | Node.js 전체 기능 (동기+비동기)       |
+| `@ddunigma/node/browser` | 브라우저 최적화 (Node.js 모듈 미포함) |
+| `@ddunigma/node/core`    | 최소 코어 (인코딩/디코딩만)           |
+
+## Build & Test
 
 ```bash
+pnpm test
 pnpm build
 pnpm lint
 pnpm bench
-pnpm pack:check
 ```
 
----
-
-## Credits
-
-- Original: [@i3ls](https://github.com/i3l3), [@gunu3371](https://github.com/gunu3371)
-- Repository: [ddunigma](https://github.com/i3l3/ddunigma)
-
 ## License
 
 BSD-2-Clause