@simplysm/core-common 13.0.0-beta.2 → 13.0.0-beta.21

package/src/utils/transferable.ts

@@ -1,269 +0,0 @@
-import { DateTime } from "../types/date-time";
-import { DateOnly } from "../types/date-only";
-import { Time } from "../types/time";
-import { Uuid } from "../types/uuid";
-
-/**
- * Worker 간 전송 가능한 객체 타입
- *
- * 이 코드에서는 ArrayBuffer만 사용됩니다.
- * @see https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Transferable_objects
- */
-type Transferable = ArrayBuffer;
-
-/**
- * Transferable 변환 유틸리티 함수
- *
- * Worker 간 데이터 전송을 위한 직렬화/역직렬화를 수행합니다.
- * structuredClone이 지원하지 않는 커스텀 타입들을 처리합니다.
- *
- * 지원 타입:
- * - Date, DateTime, DateOnly, Time, Uuid, RegExp
- * - Error (cause, code, detail 포함)
- * - Uint8Array (다른 TypedArray는 미지원, 일반 객체로 처리됨)
- * - Array, Map, Set, 일반 객체
- *
- * @note 순환 참조가 있으면 transferableEncode 시 TypeError 발생 (경로 정보 포함)
- * @note 동일 객체가 여러 곳에서 참조되면 캐시된 인코딩 결과를 재사용합니다
- *
- * @example
- * // Worker로 데이터 전송
- * const { result, transferList } = transferableEncode(data);
- * worker.postMessage(result, transferList);
- *
- * // Worker에서 데이터 수신
- * const decoded = transferableDecode(event.data);
- */
-
-//#region encode
-
-/**
- * 심플리즘 타입을 사용한 객체를 일반 객체로 변환
- * Worker에 전송할 수 있는 형태로 직렬화
- *
- * @throws 순환 참조 감지 시 TypeError
- */
-export function transferableEncode(obj: unknown): {
-  result: unknown;
-  transferList: Transferable[];
-} {
-  const transferList: Transferable[] = [];
-  const ancestors = new Set<object>();
-  const cache = new Map<object, unknown>();
-  const result = encodeImpl(obj, transferList, [], ancestors, cache);
-  return { result, transferList };
-}
-
-function encodeImpl(
-  obj: unknown,
-  transferList: Transferable[],
-  path: (string | number)[],
-  ancestors: Set<object>,
-  cache: Map<object, unknown>,
-): unknown {
-  if (obj == null) return obj;
-
-  // 객체 타입 처리: 순환 감지 + 캐시
-  if (typeof obj === "object") {
-    // 순환 참조 감지 (현재 재귀 스택에 있는 객체)
-    if (ancestors.has(obj)) {
-      const currentPath = path.length > 0 ? path.join(".") : "root";
-      throw new TypeError(`순환 참조가 감지되었습니다: ${currentPath}`);
-    }
-
-    // 캐시 히트 → 이전 인코딩 결과 재사용
-    const cached = cache.get(obj);
-    if (cached !== undefined) return cached;
-
-    // 재귀 스택에 추가
-    ancestors.add(obj);
-  }
-
-  let result: unknown;
-
-  try {
-    // 1. Uint8Array
-    if (obj instanceof Uint8Array) {
-      // SharedArrayBuffer는 이미 공유 메모리이므로 transferList에 추가하지 않음
-      // ArrayBuffer만 transferList에 추가
-      const isSharedArrayBuffer = typeof SharedArrayBuffer !== "undefined" && obj.buffer instanceof SharedArrayBuffer;
-      const buffer = obj.buffer as ArrayBuffer;
-      if (!isSharedArrayBuffer && !transferList.includes(buffer)) {
-        transferList.push(buffer);
-      }
-      result = obj;
-    }
-    // 2. 특수 타입 변환 (JSON.stringify 없이 구조체로 변환)
-    else if (obj instanceof Date) {
-      result = { __type__: "Date", data: obj.getTime() };
-    } else if (obj instanceof DateTime) {
-      result = { __type__: "DateTime", data: obj.tick };
-    } else if (obj instanceof DateOnly) {
-      result = { __type__: "DateOnly", data: obj.tick };
-    } else if (obj instanceof Time) {
-      result = { __type__: "Time", data: obj.tick };
-    } else if (obj instanceof Uuid) {
-      result = { __type__: "Uuid", data: obj.toString() };
-    } else if (obj instanceof RegExp) {
-      result = { __type__: "RegExp", data: { source: obj.source, flags: obj.flags } };
-    } else if (obj instanceof Error) {
-      const errObj = obj as Error & {
-        code?: unknown;
-        detail?: unknown;
-      };
-      result = {
-        __type__: "Error",
-        data: {
-          name: errObj.name,
-          message: errObj.message,
-          stack: errObj.stack,
-          ...(errObj.code !== undefined ? { code: errObj.code } : {}),
-          ...(errObj.detail !== undefined
-            ? { detail: encodeImpl(errObj.detail, transferList, [...path, "detail"], ancestors, cache) }
-            : {}),
-          ...(errObj.cause !== undefined
-            ? { cause: encodeImpl(errObj.cause, transferList, [...path, "cause"], ancestors, cache) }
-            : {}),
-        },
-      };
-    }
-    // 3. 배열 재귀 순회
-    else if (Array.isArray(obj)) {
-      result = obj.map((item, idx) => encodeImpl(item, transferList, [...path, idx], ancestors, cache));
-    }
-    // 4. Map 재귀 순회
-    else if (obj instanceof Map) {
-      let idx = 0;
-      result = new Map(
-        Array.from(obj.entries()).map(([k, v]) => {
-          const keyPath = [...path, `Map[${idx}].key`];
-          const valuePath = [...path, `Map[${idx}].value`];
-          idx++;
-          return [
-            encodeImpl(k, transferList, keyPath, ancestors, cache),
-            encodeImpl(v, transferList, valuePath, ancestors, cache),
-          ];
-        }),
-      );
-    }
-    // 5. Set 재귀 순회
-    else if (obj instanceof Set) {
-      let idx = 0;
-      result = new Set(
-        Array.from(obj).map((v) => encodeImpl(v, transferList, [...path, `Set[${idx++}]`], ancestors, cache)),
-      );
-    }
-    // 6. 일반 객체 재귀 순회
-    else if (typeof obj === "object") {
-      const res: Record<string, unknown> = {};
-      const record = obj as Record<string, unknown>;
-      for (const key of Object.keys(record)) {
-        res[key] = encodeImpl(record[key], transferList, [...path, key], ancestors, cache);
-      }
-      result = res;
-    }
-    // 7. 원시 타입
-    else {
-      return obj;
-    }
-
-    // 캐시 저장 (성공 시에만)
-    if (typeof obj === "object") {
-      cache.set(obj, result);
-    }
-
-    return result;
-  } finally {
-    // 재귀 스택에서 제거 (예외 시에도 반드시 실행)
-    if (typeof obj === "object") {
-      ancestors.delete(obj);
-    }
-  }
-}
-
-//#endregion
-
-//#region decode
-
-/**
- * serialize 객체를 심플리즘 타입 사용 객체로 변환
- * Worker로부터 받은 데이터를 역직렬화
- */
-export function transferableDecode(obj: unknown): unknown {
-  if (obj == null) return obj;
-
-  // 1. 특수 타입 복원
-  if (typeof obj === "object" && "__type__" in obj && "data" in obj) {
-    const typed = obj as { __type__: string; data: unknown };
-    const data = typed.data;
-
-    if (typed.__type__ === "Date" && typeof data === "number") return new Date(data);
-    if (typed.__type__ === "DateTime" && typeof data === "number") return new DateTime(data);
-    if (typed.__type__ === "DateOnly" && typeof data === "number") return new DateOnly(data);
-    if (typed.__type__ === "Time" && typeof data === "number") return new Time(data);
-    if (typed.__type__ === "Uuid" && typeof data === "string") return new Uuid(data);
-    if (typed.__type__ === "RegExp" && typeof data === "object" && data !== null) {
-      const regexData = data as { source: string; flags: string };
-      return new RegExp(regexData.source, regexData.flags);
-    }
-    if (typed.__type__ === "Error" && typeof data === "object" && data !== null) {
-      const errorData = data as {
-        name: string;
-        message: string;
-        stack?: string;
-        code?: unknown;
-        cause?: unknown;
-        detail?: unknown;
-      };
-      const err = new Error(errorData.message) as Error & {
-        code?: unknown;
-        detail?: unknown;
-      };
-
-      err.name = errorData.name;
-      err.stack = errorData.stack;
-
-      if (errorData.code !== undefined) err.code = errorData.code;
-      if (errorData.cause !== undefined) (err as Error).cause = transferableDecode(errorData.cause);
-      if (errorData.detail !== undefined) err.detail = transferableDecode(errorData.detail);
-      return err;
-    }
-  }
-
-  // 2. 배열 재귀 (새 배열 생성)
-  if (Array.isArray(obj)) {
-    return obj.map((item) => transferableDecode(item));
-  }
-
-  // 3. Map 재귀
-  if (obj instanceof Map) {
-    const newMap = new Map<unknown, unknown>();
-    for (const [k, v] of obj) {
-      newMap.set(transferableDecode(k), transferableDecode(v));
-    }
-    return newMap;
-  }
-
-  // 4. Set 재귀
-  if (obj instanceof Set) {
-    const newSet = new Set<unknown>();
-    for (const v of obj) {
-      newSet.add(transferableDecode(v));
-    }
-    return newSet;
-  }
-
-  // 5. 객체 재귀 (새 객체 생성)
-  if (typeof obj === "object") {
-    const record = obj as Record<string, unknown>;
-    const result: Record<string, unknown> = {};
-    for (const key of Object.keys(record)) {
-      result[key] = transferableDecode(record[key]);
-    }
-    return result;
-  }
-
-  return obj;
-}
-
-//#endregion

package/src/utils/wait.ts

@@ -1,40 +0,0 @@
-/**
- * 대기 유틸리티 함수
- */
-import { TimeoutError } from "../errors/timeout-error";
-
-/**
- * 조건이 참이 될 때까지 대기
- * @param forwarder 조건 함수
- * @param milliseconds 체크 간격 (기본: 100ms)
- * @param maxCount 최대 시도 횟수 (undefined면 무제한)
- *
- * @note 조건이 첫 번째 호출에서 true면 즉시 반환됩니다.
- * @example
- * // maxCount=3: 최대 3번 조건 확인 후 모두 false면 TimeoutError
- * await waitUntil(() => someCondition, 100, 3);
- * @throws TimeoutError 최대 시도 횟수 초과 시
- */
-export async function waitUntil(
-  forwarder: () => boolean | Promise<boolean>,
-  milliseconds?: number,
-  maxCount?: number,
-): Promise<void> {
-  let count = 0;
-  while (!(await forwarder())) {
-    count++;
-    if (maxCount !== undefined && count >= maxCount) {
-      throw new TimeoutError(count);
-    }
-
-    await waitTime(milliseconds ?? 100);
-  }
-}
-
-/**
- * 지정된 시간만큼 대기
- * @param millisecond 대기 시간 (ms)
- */
-export async function waitTime(millisecond: number): Promise<void> {
-  return new Promise<void>((resolve) => setTimeout(resolve, millisecond));
-}

package/src/utils/xml.ts

@@ -1,105 +0,0 @@
-/**
- * XML 변환 유틸리티
- */
-import type { XmlBuilderOptions } from "fast-xml-parser";
-import { XMLBuilder, XMLParser } from "fast-xml-parser";
-
-//#region parse
-
-/**
- * XML 문자열을 객체로 파싱
- * @param str XML 문자열
- * @param options 옵션
- * @param options.stripTagPrefix 태그 prefix 제거 여부 (namespace)
- * @returns 파싱된 객체. 구조:
- *   - 속성: `$` 객체에 그룹화
- *   - 텍스트 노드: `_` 키에 저장
- *   - 자식 요소: 배열로 변환 (루트 요소 제외)
- * @example
- * xmlParse('<root id="1"><item>hello</item></root>');
- * // { root: { $: { id: "1" }, item: [{ _: "hello" }] } }
- */
-export function xmlParse(str: string, options?: { stripTagPrefix?: boolean }): unknown {
-  const result = new XMLParser({
-    ignoreAttributes: false,
-    attributeNamePrefix: "",
-    attributesGroupName: "$",
-    parseAttributeValue: false,
-    parseTagValue: false,
-    textNodeName: "_",
-    isArray: (_tagName: string, jPath: string, _isLeafNode: boolean, isAttribute: boolean) => {
-      return !isAttribute && jPath.split(".").length > 1;
-    },
-  }).parse(str) as unknown;
-  return options?.stripTagPrefix ? stripTagPrefix(result) : result;
-}
-
-//#endregion
-
-//#region stringify
-
-/**
- * 객체를 XML 문자열로 직렬화
- * @param obj 직렬화할 객체
- * @param options fast-xml-parser XmlBuilderOptions (선택)
- * @returns XML 문자열
- * @example
- * xmlStringify({
- *   root: {
- *     $: { id: "1" },
- *     item: [{ _: "hello" }, { _: "world" }],
- *   },
- * });
- * // '<root id="1"><item>hello</item><item>world</item></root>'
- */
-export function xmlStringify(obj: unknown, options?: XmlBuilderOptions): string {
-  return new XMLBuilder({
-    ignoreAttributes: false,
-    attributeNamePrefix: "",
-    attributesGroupName: "$",
-    suppressBooleanAttributes: false,
-    textNodeName: "_",
-    ...options,
-  }).build(obj);
-}
-
-//#endregion
-
-//#region private
-
-/**
- * 태그 이름에서 namespace prefix 제거
- * @note XML 파싱 결과에서 "ns:tag" 형태의 namespace prefix를 제거하여 태그 이름만 남긴다.
- *       이를 통해 namespace를 고려하지 않고 일관된 방식으로 XML 데이터에 접근할 수 있다.
- *       단, 속성(attribute)은 prefix를 유지한다.
- */
-function stripTagPrefix(obj: unknown): unknown {
-  if (Array.isArray(obj)) {
-    return obj.map((item) => stripTagPrefix(item));
-  }
-
-  if (typeof obj === "object" && obj !== null) {
-    const newObj: Record<string, unknown> = {};
-    const record = obj as Record<string, unknown>;
-
-    for (const key of Object.keys(record)) {
-      const value = record[key];
-
-      // Attribute는 prefix를 제거하면 안 된다.
-      if (key === "$") {
-        newObj[key] = value;
-      } else {
-        // 태그 이름에서만 첫 번째 ":"을 기준으로 prefix 제거
-        const colonIndex = key.indexOf(":");
-        const cleanKey = colonIndex !== -1 ? key.slice(colonIndex + 1) : key;
-        newObj[cleanKey] = stripTagPrefix(value);
-      }
-    }
-
-    return newObj;
-  }
-
-  return obj;
-}
-
-//#endregion

package/src/zip/sd-zip.ts

@@ -1,218 +0,0 @@
-/**
- * ZIP 파일 처리 유틸리티
- */
-import type { FileEntry } from "@zip.js/zip.js";
-import { BlobReader, Uint8ArrayReader, Uint8ArrayWriter, ZipReader, ZipWriter } from "@zip.js/zip.js";
-import type { Bytes } from "../common.types";
-
-export interface ZipArchiveProgress {
-  fileName: string;
-  totalSize: number;
-  extractedSize: number;
-}
-
-/**
- * ZIP 아카이브 처리 클래스
- *
- * ZIP 파일의 읽기, 쓰기, 압축/해제를 처리합니다.
- * 내부 캐시를 사용하여 동일 파일의 중복 압축 해제를 방지합니다.
- *
- * @example
- * // ZIP 파일 읽기
- * await using archive = new ZipArchive(zipBytes);
- * const content = await archive.get("file.txt");
- *
- * @example
- * // ZIP 파일 생성
- * await using archive = new ZipArchive();
- * archive.write("file.txt", textBytes);
- * archive.write("data.json", jsonBytes);
- * const zipBytes = await archive.compress();
- *
- * @example
- * // 전체 압축 해제 (진행률 표시)
- * await using archive = new ZipArchive(zipBytes);
- * const files = await archive.extractAll((progress) => {
- *   console.log(`${progress.fileName}: ${progress.extractedSize}/${progress.totalSize}`);
- * });
- */
-export class ZipArchive {
-  private readonly _reader?: ZipReader<Blob | Bytes>;
-  private readonly _cache = new Map<string, Bytes | undefined>();
-  private _entries?: Awaited<ReturnType<ZipReader<Blob | Bytes>["getEntries"]>>;
-
-  /**
-   * ZipArchive 생성
-   * @param data ZIP 데이터 (생략 시 새 아카이브 생성)
-   */
-  constructor(data?: Blob | Bytes) {
-    if (!data) return;
-
-    if (data instanceof Uint8Array) {
-      this._reader = new ZipReader(new Uint8ArrayReader(data));
-    } else {
-      this._reader = new ZipReader(new BlobReader(data));
-    }
-  }
-
-  private async _getEntries() {
-    if (this._entries == null && this._reader != null) {
-      this._entries = await this._reader.getEntries();
-    }
-    return this._entries;
-  }
-
-  //#region extractAll
-  /**
-   * 모든 파일을 압축 해제
-   * @param progressCallback 진행률 콜백
-   */
-  async extractAll(progressCallback?: (progress: ZipArchiveProgress) => void): Promise<Map<string, Bytes | undefined>> {
-    const entries = await this._getEntries();
-    if (entries == null) return this._cache;
-
-    // 압축 해제 대상 크기 총합 계산
-    const totalSize = entries.filter((e) => !e.directory).reduce((acc, e) => acc + e.uncompressedSize, 0);
-
-    let totalExtracted = 0;
-    for (const entry of entries) {
-      if (entry.directory) continue;
-
-      progressCallback?.({
-        fileName: entry.filename,
-        totalSize: totalSize,
-        extractedSize: totalExtracted,
-      });
-
-      const entryBytes =
-        this._cache.get(entry.filename) ??
-        (await entry.getData(new Uint8ArrayWriter(), {
-          onprogress: (extracted) => {
-            const currentTotal = totalExtracted + extracted;
-
-            progressCallback?.({
-              fileName: entry.filename,
-              totalSize: totalSize,
-              extractedSize: currentTotal,
-            });
-
-            return undefined;
-          },
-        }));
-
-      this._cache.set(entry.filename, entryBytes);
-
-      // 개별 파일이 끝나면 누적 처리
-      totalExtracted += entry.uncompressedSize;
-
-      progressCallback?.({
-        fileName: entry.filename,
-        totalSize: totalSize,
-        extractedSize: totalExtracted,
-      });
-    }
-
-    return this._cache;
-  }
-  //#endregion
-
-  //#region get
-  /**
-   * 특정 파일 압축 해제
-   * @param fileName 파일 이름
-   */
-  async get(fileName: string): Promise<Bytes | undefined> {
-    if (this._cache.has(fileName)) {
-      return this._cache.get(fileName);
-    }
-
-    const entries = await this._getEntries();
-    if (entries == null) {
-      this._cache.set(fileName, undefined);
-      return undefined;
-    }
-
-    const entry = entries.find((item) => item.filename === fileName) as FileEntry | undefined;
-    if (!entry) {
-      this._cache.set(fileName, undefined);
-      return undefined;
-    }
-
-    const bytes = await entry.getData(new Uint8ArrayWriter());
-    this._cache.set(fileName, bytes);
-    return bytes;
-  }
-  //#endregion
-
-  //#region exists
-  /**
-   * 파일 존재 여부 확인
-   * @param fileName 파일 이름
-   */
-  async exists(fileName: string): Promise<boolean> {
-    if (this._cache.has(fileName)) {
-      return this._cache.get(fileName) != null;
-    }
-
-    const entries = await this._getEntries();
-    if (entries == null) {
-      return false;
-    }
-
-    const entry = entries.find((item) => item.filename === fileName) as FileEntry | undefined;
-    return entry !== undefined;
-  }
-  //#endregion
-
-  //#region write
-  /**
-   * 파일 쓰기 (캐시에 저장)
-   * @param fileName 파일 이름
-   * @param bytes 파일 내용
-   */
-  write(fileName: string, bytes: Bytes): void {
-    this._cache.set(fileName, bytes);
-  }
-  //#endregion
-
-  //#region compress
-  /**
-   * 캐시된 파일들을 ZIP으로 압축
-   *
-   * @remarks
-   * 내부적으로 `extractAll()`을 호출하여 모든 파일을 메모리에 로드한 후 압축합니다.
-   * 대용량 ZIP 파일의 경우 메모리 사용량에 주의가 필요합니다.
-   */
-  async compress(): Promise<Bytes> {
-    const fileMap = await this.extractAll();
-
-    const writer = new ZipWriter(new Uint8ArrayWriter());
-
-    for (const key of fileMap.keys()) {
-      const fileBytes = fileMap.get(key);
-      if (!fileBytes) continue;
-
-      await writer.add(key, new Uint8ArrayReader(fileBytes));
-    }
-
-    return writer.close();
-  }
-  //#endregion
-
-  //#region close
-  /**
-   * 리더 닫기 및 캐시 정리
-   */
-  async close(): Promise<void> {
-    await this._reader?.close();
-    this._cache.clear();
-  }
-
-  /**
-   * await using 지원
-   */
-  async [Symbol.asyncDispose](): Promise<void> {
-    await this.close();
-  }
-  //#endregion
-}