@ddunigma/node 3.0.1 → 3.0.2

package/dist/core-BccIjoLZ.d.cts

@@ -0,0 +1,663 @@
+/**
+ * ddunigma 아이소모픽 라이브러리의 핵심 타입 정의.
+ * 모든 타입 정의의 정규 소스입니다.
+ *
+ * @module core/types
+ */
+declare enum DduSetSymbol {
+    DDU = "ddu",
+    DDU_V1 = "ddu_v1",
+    ONECHARSET = "oneCharSet"
+}
+interface CharSetConfig {
+    /** charset 식별 심볼 */
+    symbol: DduSetSymbol;
+    /** 인코딩에 사용할 문자 배열 (codaChar가 있으면 기본 문자 배열) */
+    charSet: string[];
+    /** 종성 문자 배열 (charSet × codaChar 조합으로 최종 charset 생성) */
+    codaChar?: string[];
+    /** 최대 필요 문자 수 */
+    maxRequiredLength: number;
+    /** 비트 길이 (log2) */
+    bitLength: number;
+    /** 패딩 문자 */
+    paddingChar: string;
+    /** 패딩 문자 반복 방식 사용 여부 */
+    useRepeatPadding?: boolean;
+}
+interface CharSetInfo {
+    /** 인코딩에 사용할 문자 배열 */
+    charSet: string[];
+    /** 패딩 문자 */
+    paddingChar: string;
+    /** 비트 길이 */
+    bitLength: number;
+    /** 2의 제곱수 charset 여부 */
+    usePowerOfTwo: boolean;
+    /** 문자열 인코딩 방식 */
+    encoding: BufferEncoding;
+    /** 기본 압축 사용 여부 */
+    defaultCompress: boolean;
+    /** 기본 최대 디코딩 바이트 수 */
+    defaultMaxDecodedBytes: number;
+    /** 기본 최대 압축해제 바이트 수 */
+    defaultMaxDecompressedBytes: number;
+    /** URL-Safe 모드 여부 */
+    urlSafe: boolean;
+    /** 암호화 키 보유 여부 */
+    hasEncryptionKey: boolean;
+    /** 기본 체크섬 사용 여부 */
+    defaultChecksum: boolean;
+    /** 기본 청크 크기 */
+    defaultChunkSize: number | undefined;
+    /** 기본 청크 구분자 */
+    defaultChunkSeparator: string;
+    /** 기본 압축 레벨 */
+    defaultCompressionLevel: number;
+    /** 기본 압축 알고리즘 */
+    defaultCompressionAlgorithm: "deflate" | "brotli";
+}
+/** 진행률 콜백 정보 */
+interface DduProgressInfo {
+    /** 현재 처리된 바이트 수 (근사값) */
+    processedBytes: number;
+    /** 전체 바이트 수 */
+    totalBytes: number;
+    /** 진행률 (0-100, 단계별 근사값) */
+    percent: number;
+    /** 현재 처리 단계 */
+    stage?: "start" | "encrypt" | "compress" | "encode" | "decode" | "decompress" | "checksum" | "decrypt" | "done";
+}
+/** 인코딩 통계 정보 */
+interface DduEncodeStats {
+    /** 원본 데이터 크기 (바이트) */
+    originalSize: number;
+    /** 인코딩된 문자열 길이 */
+    encodedSize: number;
+    /** 압축된 크기 (압축 사용시) */
+    compressedSize?: number;
+    /** 압축률 (0-1, 낮을수록 효율적) */
+    compressionRatio?: number;
+    /** 인코딩 확장 비율 */
+    expansionRatio: number;
+    /** 사용된 charset 크기 */
+    charsetSize: number;
+    /** 비트 길이 */
+    bitLength: number;
+}
+type KeyDerivationAlgorithm = "sha256" | "pbkdf2";
+interface KeyDerivationOptions {
+    /** Key derivation algorithm. `sha256` preserves legacy compatibility. */
+    algorithm?: KeyDerivationAlgorithm;
+    /** Salt for PBKDF2. Provide a stable value to decode across instances. */
+    salt?: string | Uint8Array;
+    /** PBKDF2 iteration count. Values below 10000 are clamped unless throwOnError is enabled. */
+    iterations?: number;
+    /** Hash function used by PBKDF2. */
+    hash?: "SHA-256" | "SHA-384" | "SHA-512";
+}
+interface DduOptions {
+    /** 압축 사용 여부 (zlib deflate 또는 brotli) */
+    compress?: boolean;
+    /** decode stream에서 footer 기반 자동 감지 사용 여부 (기본값: true) */
+    streamAutoDetect?: boolean;
+    /** 내부 암/복호화 사용 여부 (기본값: true, 스트림 파이프라인 내부 제어용) */
+    encrypt?: boolean;
+    /** 압축 알고리즘 (기본값: "deflate") */
+    compressionAlgorithm?: "deflate" | "brotli";
+    /** 압축 레벨 (deflate 기본값: 6, brotli도 기본값 6을 사용하며 전달값은 0~11 범위로 보정) */
+    compressionLevel?: number;
+    /** 최대 디코딩 바이트 수 (Zip Bomb 방어) */
+    maxDecodedBytes?: number;
+    /** 최대 압축해제 바이트 수 (Zip Bomb 방어) */
+    maxDecompressedBytes?: number;
+    /** 체크섬 추가 여부 (CRC32) */
+    checksum?: boolean;
+    /** 청크 분할 크기 */
+    chunkSize?: number;
+    /** 청크 구분자 (기본값: '\n') */
+    chunkSeparator?: string;
+    /** 중간 스트림 청크처럼 푸터를 생략해야 할 때 사용 */
+    omitFooter?: boolean;
+    /** 진행률 콜백 */
+    onProgress?: (info: DduProgressInfo) => void;
+    /** 한글 난독화 활성화 (encryptionKey 필요) */
+    obfuscate?: boolean;
+}
+interface DduConstructorOptions extends DduOptions {
+    /** 미리 정의된 charset 심볼 */
+    dduSetSymbol?: DduSetSymbol;
+    /** 커스텀 charset 문자 배열 또는 문자열 */
+    dduChar?: string[] | string;
+    /** 종성 문자 배열 (dduChar × codaChar 조합으로 최종 charset 동적 생성) */
+    codaChar?: string[];
+    /** 패딩 문자 */
+    paddingChar?: string;
+    /** 필요 문자 수 */
+    requiredLength?: number;
+    /** 비트 길이 */
+    bitLength?: number;
+    /** 2의 제곱수 강제 여부 */
+    usePowerOfTwo?: boolean;
+    /**
+     * true이면 초기화 오류 시 throw합니다. false이면 fallback charset으로 대체합니다.
+     * @default false
+     * @deprecated throwOnError를 사용하세요. 이 옵션은 하위 호환성을 위해 유지됩니다.
+     */
+    useBuildErrorReturn?: boolean;
+    /**
+     * true이면 초기화 오류 시 throw합니다. false이면 fallback charset으로 대체합니다.
+     * useBuildErrorReturn과 동일한 동작이며, 둘 다 지정 시 throwOnError가 우선합니다.
+     * @default false
+     */
+    throwOnError?: boolean;
+    /** Buffer 인코딩 방식 */
+    encoding?: BufferEncoding;
+    /** URL-Safe 모드 (특수문자를 URL 안전 문자로 변환) */
+    urlSafe?: boolean;
+    /** 암호화 키 (AES-256-GCM) */
+    encryptionKey?: string;
+    /** 암호화 키 파생 옵션 */
+    keyDerivation?: KeyDerivationOptions;
+    /** 패딩 문자 반복 방식 사용 여부 */
+    useRepeatPadding?: boolean;
+    /** 명시적 플랫폼 어댑터 (자동 감지 대신 사용) */
+    adapter?: PlatformAdapter;
+    /** 한글 난독화 활성화 (encryptionKey 필요) */
+    obfuscate?: boolean;
+    /** WASM 임계값 (바이트 단위, 기본값: 4096, 범위: 1024-1048576) */
+    wasmThreshold?: number;
+}
+/**
+ * 암호화 및 압축 연산을 제공하는 플랫폼 어댑터 인터페이스.
+ * 각 런타임(Node.js, 브라우저, 엣지)이 이 인터페이스를 구현합니다.
+ *
+ * 동기 메서드(`?`로 표시)는 Node.js에서만 사용 가능합니다.
+ * 브라우저/엣지 어댑터는 동기 메서드 호출 시 throw합니다.
+ */
+interface PlatformAdapter {
+    /** UTF-8 키 문자열에서 256비트 키를 파생 */
+    deriveKey(key: string, options?: KeyDerivationOptions): Promise<Uint8Array>;
+    /** 동기적으로 256비트 키를 파생 (Node.js 전용) */
+    deriveKeySync?(key: string, options?: KeyDerivationOptions): Uint8Array;
+    /** AES-256-GCM으로 데이터를 암호화. IV(12) + authTag(16) + 암호문을 반환 */
+    encrypt(data: Uint8Array, keyHash: Uint8Array): Promise<Uint8Array>;
+    /** 동기적으로 데이터를 암호화 (Node.js 전용) */
+    encryptSync?(data: Uint8Array, keyHash: Uint8Array): Uint8Array;
+    /** AES-256-GCM 페이로드를 복호화. IV(12) + authTag(16) + 암호문 형식을 기대 */
+    decrypt(data: Uint8Array, keyHash: Uint8Array): Promise<Uint8Array>;
+    /** 동기적으로 데이터를 복호화 (Node.js 전용) */
+    decryptSync?(data: Uint8Array, keyHash: Uint8Array): Uint8Array;
+    /** 암호학적으로 안전한 랜덤 바이트를 생성 */
+    randomBytes(length: number): Uint8Array;
+    /** deflate 알고리즘으로 데이터를 압축 */
+    deflate(data: Uint8Array, level?: number): Promise<Uint8Array>;
+    /** 동기적으로 deflate 압축 (Node.js 전용) */
+    deflateSync?(data: Uint8Array, level?: number): Uint8Array;
+    /** deflate 데이터를 압축 해제 */
+    inflate(data: Uint8Array, maxBytes?: number): Promise<Uint8Array>;
+    /** 동기적으로 deflate 데이터를 압축 해제 (Node.js 전용) */
+    inflateSync?(data: Uint8Array, maxBytes?: number): Uint8Array;
+    /** brotli 알고리즘으로 데이터를 압축 (Node.js 전용) */
+    brotliCompress?(data: Uint8Array, level?: number): Promise<Uint8Array>;
+    /** 동기적으로 brotli 압축 (Node.js 전용) */
+    brotliCompressSync?(data: Uint8Array, level?: number): Uint8Array;
+    /** brotli 데이터를 압축 해제 (Node.js 전용) */
+    brotliDecompress?(data: Uint8Array, maxBytes?: number): Promise<Uint8Array>;
+    /** 동기적으로 brotli 데이터를 압축 해제 (Node.js 전용) */
+    brotliDecompressSync?(data: Uint8Array, maxBytes?: number): Uint8Array;
+    /** 이 어댑터가 동기 암호화 연산을 지원하는지 여부 */
+    readonly supportsSyncCrypto: boolean;
+    /** 이 어댑터가 동기 압축 연산을 지원하는지 여부 */
+    readonly supportsSyncCompression: boolean;
+    /** 이 어댑터가 brotli 압축을 지원하는지 여부 */
+    readonly supportsBrotli: boolean;
+    /** 감지된 런타임 환경 */
+    readonly runtime: "node" | "browser" | "edge" | "deno" | "bun" | "unknown";
+}
+/**
+ * WASM 가속 비트 패킹 코덱 인터페이스.
+ * 순수 JavaScript 구현과 바이트 단위로 동일한 인코딩/디코딩 연산을 제공합니다.
+ */
+interface WasmCodec {
+    /** 바이트를 charset 인덱스로 인코딩 */
+    encode(input: Uint8Array, bitLength: number): {
+        indices: Uint16Array;
+        paddingBits: number;
+    };
+    /** charset 인덱스를 바이트로 디코딩 */
+    decode(indices: Uint16Array, bitLength: number, paddingBits: number): Uint8Array;
+    /** WASM 모듈이 초기화되어 사용 가능한지 확인 */
+    readonly ready: boolean;
+}
+/**
+ * 인코딩/디코딩 연산을 위해 워커 스레드에 전달되는 설정.
+ */
+interface EncoderConfig {
+    charSet: string[];
+    paddingChar: string;
+    bitLength: number;
+    usePowerOfTwo: boolean;
+    compress?: boolean;
+    compressionAlgorithm?: "deflate" | "brotli";
+    compressionLevel?: number;
+    encrypt?: boolean;
+    encryptionKeyHash?: Uint8Array;
+    checksum?: boolean;
+    urlSafe?: boolean;
+    chunkSize?: number;
+    chunkSeparator?: string;
+    useRepeatPadding?: boolean;
+}
+/**
+ * 대용량 페이로드의 인코딩/디코딩 연산을 오프로드하는 워커 스레드 풀 인터페이스.
+ */
+interface WorkerPool {
+    /** 워커 스레드를 사용하여 인코딩 */
+    encode(input: Uint8Array, config: EncoderConfig): Promise<string>;
+    /** 워커 스레드를 사용하여 디코딩 */
+    decode(input: string, config: EncoderConfig): Promise<Uint8Array>;
+    /** 풀의 워커 스레드 수를 설정 (1-64) */
+    setPoolSize(n: number): void;
+    /** 모든 워커 스레드를 종료하고 리소스를 정리 */
+    terminate(): Promise<void>;
+}
+/**
+ * 한글 음절 난독화 레이어 인터페이스.
+ * 암호화된 출력을 자연스러운 한국어 음절 블록으로 변환합니다.
+ */
+interface ObfuscationLayer {
+    /**
+     * 암호화된 charset 인코딩 문자열을 자연스러운 한글 음절로 변환합니다.
+     * 모든 출력 문자는 U+AC00–U+D7A3 범위에 있습니다.
+     * 출력 길이 <= 입력 길이의 1.5배.
+     */
+    obfuscate(input: string): string;
+    /**
+     * 난독화를 역변환하여 원본 charset 인코딩 문자열을 복원합니다.
+     */
+    deobfuscate(input: string): string;
+}
+/**
+ * 크로스 플랫폼 인코딩 호환성 및 와이어 포맷 적합성을 검증하기 위한
+ * 표준화된 테스트 벡터 형식.
+ */
+interface TestVector {
+    /** 이 테스트 벡터의 고유 식별자 */
+    id: string;
+    /** 이 벡터가 테스트하는 내용에 대한 설명 */
+    description: string;
+    /** 입력 데이터 명세 */
+    input: {
+        /** 16진수 인코딩된 입력 바이트 */
+        raw: string;
+        /** 원시 데이터의 인코딩 */
+        encoding: "utf-8" | "binary";
+    };
+    /** 이 벡터의 charset 설정 */
+    charset: {
+        /** 프리셋 심볼 (내장 charset 사용 시) */
+        preset?: DduSetSymbol;
+        /** 커스텀 charset 문자 (프리셋 미사용 시) */
+        dduChar?: string[];
+        /** 조합 charset용 종성 문자 */
+        codaChar?: string[];
+        /** 패딩 문자 */
+        paddingChar: string;
+    };
+    /** 인코딩 옵션 */
+    options: {
+        compress?: boolean;
+        compressionAlgorithm?: "deflate" | "brotli";
+        encrypt?: boolean;
+        encryptionKey?: string;
+        checksum?: boolean;
+        urlSafe?: boolean;
+        chunkSize?: number;
+        useRepeatPadding?: boolean;
+    };
+    /** 기대 출력 */
+    expected: {
+        /** 기대되는 인코딩 문자열 */
+        encoded: string;
+        /** 바이너리 비교를 위한 16진수 표현 */
+        encodedHex?: string;
+    };
+    /** 테스트 벡터 분류 태그 */
+    tags: string[];
+}
+
+/**
+ * 플랫폼 독립 Ddu64 인코더/디코더 코어.
+ * PlatformAdapter 인터페이스를 통해 암호화 및 압축 연산을 수행하는 전체 인코딩/디코딩 파이프라인을 제공합니다.
+ *
+ * @module core/Ddu64Core
+ */
+
+/**
+ * 플랫폼 독립 Ddu64 인코더/디코더.
+ *
+ * 모든 암호화 및 압축 연산에 PlatformAdapter를 사용합니다.
+ */
+declare class Ddu64Core {
+    /** 인코딩에 사용되는 문자 */
+    protected readonly dduChar: string[];
+    /** 패딩 문자 */
+    protected readonly paddingChar: string;
+    /** 비트 길이 (2의 제곱수 charset의 경우 charset 크기의 log2) */
+    protected readonly bitLength: number;
+    /** charset 크기가 2의 제곱수인지 여부 */
+    protected readonly usePowerOfTwo: boolean;
+    /** 인코딩에 사용되는 유효 비트 길이 */
+    private readonly effectiveBitLength;
+    /** 문자 → 인덱스 역방향 룩업 맵 */
+    protected readonly dduBinaryLookup: Map<string, number>;
+    /** 미리 정의된 charset 사용 여부 */
+    private readonly isPredefinedCharSet;
+    /** 기본 압축 활성화 */
+    protected readonly defaultCompress: boolean;
+    /** 기본 최대 디코딩 바이트 수 */
+    private readonly defaultMaxDecodedBytes;
+    /** 기본 최대 압축해제 바이트 수 */
+    private readonly defaultMaxDecompressedBytes;
+    /** URL-Safe 모드 */
+    private readonly urlSafe;
+    /** 암호화 키 (원시 문자열, 해시 파생용) */
+    private readonly encryptionKey;
+    /** 암호화 키 파생 옵션 */
+    private readonly keyDerivation;
+    /** 캐시된 암호화 키 해시 */
+    private encryptionKeyHash;
+    /** 기본 체크섬 활성화 */
+    private readonly defaultChecksum;
+    /** 기본 청크 크기 */
+    private readonly defaultChunkSize;
+    /** 기본 청크 구분자 */
+    private readonly defaultChunkSeparator;
+    /** 기본 압축 레벨 */
+    private readonly defaultCompressionLevel;
+    /** 기본 압축 알고리즘 */
+    private readonly defaultCompressionAlgorithm;
+    /** 반복 패딩 모드 사용 여부 */
+    private readonly useRepeatPadding;
+    /** BitPack 설정 */
+    private readonly bitPackConfig;
+    /** WASM 사용 임계값 */
+    private readonly wasmThreshold;
+    /** 네이티브 Base64 fast path 사용 여부 */
+    private readonly canUseNativeBase64;
+    /** 현재 charset 문자 → 네이티브 Base64 문자 매핑 */
+    private readonly nativeDecodeMap;
+    /** 플랫폼 어댑터 (동기용 지연 로드 또는 명시적 제공) */
+    private adapter;
+    /** 기본 난독화 활성화 */
+    private readonly defaultObfuscate;
+    /** 지연 초기화되는 난독화 레이어 */
+    private _obfuscationLayer;
+    constructor(dduChar?: string[] | string, paddingChar?: string, dduOptions?: DduConstructorOptions);
+    /**
+     * 입력 데이터를 charset 인코딩 문자열로 인코딩합니다.
+     *
+     * @param input - 인코딩할 String 또는 Uint8Array
+     * @param options - 인코딩 옵션
+     * @returns 인코딩된 문자열
+     * @throws 동기 암호화/압축이 필요하지만 어댑터가 지원하지 않는 경우
+     */
+    encode(input: Uint8Array | string, options?: DduOptions): string;
+    /**
+     * 인코딩된 문자열을 UTF-8 문자열로 디코딩합니다.
+     *
+     * @param input - 디코딩할 인코딩된 문자열
+     * @param options - 디코딩 옵션
+     * @returns 디코딩된 문자열
+     */
+    decode(input: string, options?: DduOptions): string;
+    /**
+     * 인코딩된 문자열을 Uint8Array로 디코딩합니다.
+     *
+     * @param input - 디코딩할 인코딩된 문자열
+     * @param options - 디코딩 옵션
+     * @returns 디코딩된 바이트
+     */
+    decodeToUint8Array(input: string, options?: DduOptions): Uint8Array;
+    /**
+     * 비동기 인코딩 - 브라우저를 포함한 모든 런타임에서 동작합니다.
+     */
+    encodeAsync(input: Uint8Array | string, options?: DduOptions): Promise<string>;
+    /**
+     * 비동기 디코딩 - 브라우저를 포함한 모든 런타임에서 동작합니다.
+     */
+    decodeAsync(input: string, options?: DduOptions): Promise<string>;
+    /**
+     * 비동기 Uint8Array 디코딩 - 브라우저를 포함한 모든 런타임에서 동작합니다.
+     */
+    decodeToUint8ArrayAsync(input: string, options?: DduOptions): Promise<Uint8Array>;
+    /**
+     * charset 정보를 가져옵니다.
+     */
+    getCharSetInfo(): CharSetInfo;
+    /**
+     * 인코딩 통계를 가져옵니다.
+     */
+    getStats(input: Uint8Array | string, options?: DduOptions): DduEncodeStats;
+    /**
+     * 대용량 인코딩/디코딩 연산을 오프로드하기 위한 전역 워커 풀 크기를 설정합니다.
+     *
+     * @param n - 워커 수 (정수, 1–64)
+     * @throws n이 정수가 아니거나 [1, 64] 범위를 벗어난 경우 에러
+     */
+    static setWorkerPoolSize(n: number): void;
+    /**
+     * 통계를 위한 메타데이터 포함 내부 인코딩.
+     */
+    private encodeInternal;
+    /**
+     * 인코딩 후처리: 난독화, 체크섬, URL-safe, 청킹을 적용합니다.
+     */
+    private applyPostEncoding;
+    /**
+     * BitPack + 푸터를 사용하여 바이트를 charset 문자열로 인코딩합니다.
+     */
+    private encodeBytes;
+    /**
+     * charset 문자열을 인덱스로 변환한 후 BitPack으로 바이트를 얻습니다.
+     */
+    private decodeChars;
+    private encodeBytesWithNativeBase64;
+    private decodeCharsWithNativeBase64;
+    private bytesToBase64;
+    private base64ToBytes;
+    private shouldUseWasm;
+    private reportProgress;
+    private requireSyncAdapter;
+    private encryptSync;
+    private decryptSync;
+    private compressSync;
+    private decompressSync;
+    private getAdapterAsync;
+    private getKeyHashAsync;
+    /**
+     * 난독화 레이어를 가져오거나 생성합니다 (지연 초기화).
+     * 알파벳에는 charset 문자, 패딩 문자, 모든 푸터 마커 문자가 포함됩니다.
+     */
+    private getObfuscationLayer;
+    /**
+     * 주어진 호출에 난독화를 적용해야 하는지 결정합니다.
+     * 호출별 옵션이 생성자 기본값을 오버라이드합니다.
+     * 암호화 키 없이 난독화가 활성화되면 throw합니다.
+     */
+    private shouldObfuscate;
+    private normalizeLimit;
+    private estimateDecodedBytes;
+    private assertEncodedInputAligned;
+}
+
+/**
+ * 커스텀 Charset을 쉽게 생성하기 위한 빌더 클래스.
+ *
+ * @module core/CharsetBuilder
+ *
+ * @example
+ * const chars = CharsetBuilder
+ *   .fromUnicodeRange(0x4E00, 0x4E3F)
+ *   .excludeConfusing()
+ *   .shuffle()
+ *   .build();
+ */
+declare class CharsetBuilder {
+    private chars;
+    private constructor();
+    /**
+     * 빈 빌더를 생성합니다.
+     */
+    static create(): CharsetBuilder;
+    /**
+     * 유니코드 범위에서 문자들을 추가합니다.
+     *
+     * @param start - 시작 유니코드 코드포인트
+     * @param end - 끝 유니코드 코드포인트 (포함)
+     */
+    static fromUnicodeRange(start: number, end: number): CharsetBuilder;
+    /**
+     * 문자열에서 문자들을 추가합니다.
+     *
+     * @param chars - 문자열 또는 문자 배열
+     */
+    static fromString(chars: string | string[]): CharsetBuilder;
+    /**
+     * Base64 표준 문자셋으로 시작합니다.
+     */
+    static base64(): CharsetBuilder;
+    /**
+     * Base32 표준 문자셋으로 시작합니다.
+     */
+    static base32(): CharsetBuilder;
+    /**
+     * 영문 대문자만 포함합니다.
+     */
+    static uppercase(): CharsetBuilder;
+    /**
+     * 영문 소문자만 포함합니다.
+     */
+    static lowercase(): CharsetBuilder;
+    /**
+     * 숫자만 포함합니다.
+     */
+    static digits(): CharsetBuilder;
+    /**
+     * 한글 자모를 포함합니다.
+     */
+    static hangulJamo(): CharsetBuilder;
+    /**
+     * 유니코드 범위에서 문자들을 추가합니다.
+     */
+    addUnicodeRange(start: number, end: number): CharsetBuilder;
+    /**
+     * 문자열에서 문자들을 추가합니다.
+     */
+    addString(chars: string | string[]): CharsetBuilder;
+    /**
+     * 특정 문자들을 추가합니다.
+     */
+    add(...chars: string[]): CharsetBuilder;
+    /**
+     * 혼동하기 쉬운 문자들을 제거합니다.
+     * (0, O, o, 1, l, I, i 등)
+     */
+    excludeConfusing(): CharsetBuilder;
+    /**
+     * 특정 문자들을 제거합니다.
+     */
+    exclude(...chars: string[]): CharsetBuilder;
+    /**
+     * URL에서 안전하지 않은 문자들을 제거합니다.
+     */
+    excludeUrlUnsafe(): CharsetBuilder;
+    /**
+     * 중복 문자를 제거합니다.
+     */
+    unique(): CharsetBuilder;
+    /**
+     * 문자셋을 무작위로 섞습니다.
+     */
+    shuffle(seed?: number): CharsetBuilder;
+    /**
+     * 시드 기반 난수 생성기 (xorshift32)
+     */
+    private seededRandom;
+    /**
+     * 특정 길이로 자릅니다.
+     */
+    limit(length: number): CharsetBuilder;
+    /**
+     * 2의 제곱수 길이로 자릅니다.
+     */
+    limitToPowerOfTwo(): CharsetBuilder;
+    /**
+     * 문자셋을 정렬합니다.
+     */
+    sort(): CharsetBuilder;
+    /**
+     * 역순으로 정렬합니다.
+     */
+    reverse(): CharsetBuilder;
+    /**
+     * 현재 문자 수를 반환합니다.
+     */
+    get length(): number;
+    /**
+     * 문자셋을 문자열로 빌드합니다.
+     */
+    buildString(): string;
+    /**
+     * 문자셋을 배열로 빌드합니다.
+     */
+    build(): string[];
+    /**
+     * 문자셋과 패딩 문자를 함께 빌드합니다.
+     *
+     * @param paddingChar - 패딩 문자 (기본값: charset에서 제외된 첫 번째 문자)
+     */
+    buildWithPadding(paddingChar?: string): {
+        charset: string[];
+        padding: string;
+    };
+}
+
+/**
+ * ddunigma 비트 패킹 가속을 위한 WASM 로더 및 통합.
+ *
+ * 순수 JavaScript 구현과 바이트 단위로 동일한 선택적 WASM 가속
+ * 인코딩/디코딩을 제공합니다. WASM을 사용할 수 없거나 실패하면
+ * 조용히 JS로 폴백합니다.
+ *
+ * @module wasm/WasmCodec
+ */
+
+/**
+ * WASM 모듈을 사전 로드하고 초기화합니다.
+ *
+ * 첫 번째 인코딩/디코딩 연산 전에 WASM이 준비되도록 애플리케이션 초기에
+ * 호출하세요. WASM이 초기화되면 resolve되고, 10초 내에 초기화에 실패하면
+ * reject됩니다.
+ *
+ * @throws WASM 초기화가 실패하거나 타임아웃(10초)된 경우 에러
+ */
+declare function preloadWasm(): Promise<void>;
+/**
+ * WASM 코덱이 준비되었으면 반환하거나, 온디맨드 초기화를 시도합니다.
+ *
+ * `preloadWasm()`이 호출되지 않았으면 5초 타임아웃으로 초기화를 시도합니다.
+ * WASM을 사용할 수 없으면 null을 반환합니다.
+ *
+ * 이 함수는 throw하지 않음 — 실패 시 null을 반환합니다.
+ */
+declare function getWasmCodec(): WasmCodec | null;
+/**
+ * WASM 코덱이 이미 초기화된 경우에만 반환합니다.
+ * 온디맨드 초기화를 트리거하지 않습니다.
+ * WASM이 준비되지 않았으면 null을 반환합니다.
+ */
+declare function getWasmCodecSync(): WasmCodec | null;
+
+export { type CharSetConfig as C, Ddu64Core as D, type EncoderConfig as E, type KeyDerivationOptions as K, type ObfuscationLayer as O, type PlatformAdapter as P, type TestVector as T, type WasmCodec as W, type DduConstructorOptions as a, type DduOptions as b, type CharSetInfo as c, CharsetBuilder as d, type DduEncodeStats as e, type DduProgressInfo as f, DduSetSymbol as g, type KeyDerivationAlgorithm as h, type WorkerPool as i, getWasmCodec as j, getWasmCodecSync as k, preloadWasm as p };