@simplysm/core-common 13.0.69 → 13.0.71

package/src/utils/xml.ts

@@ -1,5 +1,5 @@
 /**
- * XML 변환 유틸리티
+ * XML conversion utility
  */
 import type { XmlBuilderOptions } from "fast-xml-parser";
 import { XMLBuilder, XMLParser } from "fast-xml-parser";
@@ -7,14 +7,14 @@ import { XMLBuilder, XMLParser } from "fast-xml-parser";
 //#region parse
 
 /**
- * XML 문자열을 객체로 파싱
- * @param str XML 문자열
- * @param options 옵션
- * @param options.stripTagPrefix 태그 prefix 제거 여부 (namespace)
- * @returns 파싱된 객체. 구조:
- *   - 속성: `$` 객체에 그룹화
- *   - 텍스트 노드: `_` 키에 저장
- *   - 자식 요소: 배열로 변환 (루트 요소 제외)
+ * Parse XML string into an object
+ * @param str XML string
+ * @param options Options
+ * @param options.stripTagPrefix Whether to remove tag prefix (namespace)
+ * @returns Parsed object. Structure:
+ *   - Attributes: grouped in `$` object
+ *   - Text nodes: stored in `_` key
+ *   - Child elements: converted to array (except root element)
  * @example
  * xmlParse('<root id="1"><item>hello</item></root>');
  * // { root: { $: { id: "1" }, item: [{ _: "hello" }] } }
@@ -27,6 +27,7 @@ export function xmlParse(str: string, options?: { stripTagPrefix?: boolean }): u
     parseAttributeValue: false,
     parseTagValue: false,
     textNodeName: "_",
+    htmlEntities: true,
     isArray: (_tagName: string, jPath: string, _isLeafNode: boolean, isAttribute: boolean) => {
       return !isAttribute && jPath.split(".").length > 1;
     },
@@ -39,10 +40,10 @@ export function xmlParse(str: string, options?: { stripTagPrefix?: boolean }): u
 //#region stringify
 
 /**
- * 객체를 XML 문자열로 직렬화
- * @param obj 직렬화할 객체
- * @param options fast-xml-parser XmlBuilderOptions (선택)
- * @returns XML 문자열
+ * Serialize object to XML string
+ * @param obj Object to serialize
+ * @param options fast-xml-parser XmlBuilderOptions (optional)
+ * @returns XML string
  * @example
  * xmlStringify({
  *   root: {
@@ -68,10 +69,10 @@ export function xmlStringify(obj: unknown, options?: XmlBuilderOptions): string
 //#region private
 
 /**
- * 태그 이름에서 namespace prefix 제거
- * @note XML 파싱 결과에서 "ns:tag" 형태의 namespace prefix를 제거하여 태그 이름만 남긴다.
- *       이를 통해 namespace를 고려하지 않고 일관된 방식으로 XML 데이터에 접근할 수 있다.
- *       단, 속성(attribute)은 prefix를 유지한다.
+ * Remove namespace prefix from tag name
+ * @note Removes the namespace prefix in the format "ns:tag" from XML parsing results, leaving only the tag name.
+ *       This allows consistent access to XML data without considering namespace.
+ *       However, attributes are kept with their prefix.
  */
 function stripTagPrefix(obj: unknown): unknown {
   if (Array.isArray(obj)) {
@@ -85,11 +86,11 @@ function stripTagPrefix(obj: unknown): unknown {
     for (const key of Object.keys(record)) {
       const value = record[key];
 
-      // Attribute는 prefix를 제거하면 안 된다.
+      // Attributes must not have prefix removed
       if (key === "$") {
         newObj[key] = value;
       } else {
-        // 태그 이름에서만 첫 번째 ":"을 기준으로 prefix 제거
+        // Remove prefix from tag names only, based on first ":"
         const colonIndex = key.indexOf(":");
         const cleanKey = colonIndex !== -1 ? key.slice(colonIndex + 1) : key;
         newObj[cleanKey] = stripTagPrefix(value);

package/src/zip/sd-zip.ts

@@ -1,5 +1,5 @@
 /**
- * ZIP 파일 처리 유틸리티
+ * ZIP file processing utility
  */
 import type { FileEntry } from "@zip.js/zip.js";
 import {
@@ -18,25 +18,25 @@ export interface ZipArchiveProgress {
 }
 
 /**
- * ZIP 아카이브 처리 클래스
+ * ZIP archive processing class
  *
- * ZIP 파일의 읽기, 쓰기, 압축/해제를 처리합니다.
- * 내부 캐시를 사용하여 동일 파일의 중복 압축 해제를 방지합니다.
+ * Handles reading, writing, compression, and decompression of ZIP files.
+ * Uses internal caching to prevent duplicate decompression of the same file.
  *
  * @example
- * // ZIP 파일 읽기
+ * // Read ZIP file
  * await using archive = new ZipArchive(zipBytes);
  * const content = await archive.get("file.txt");
  *
  * @example
- * // ZIP 파일 생성
+ * // Create ZIP file
  * await using archive = new ZipArchive();
  * archive.write("file.txt", textBytes);
  * archive.write("data.json", jsonBytes);
  * const zipBytes = await archive.compress();
  *
  * @example
- * // 전체 압축 해제 (진행률 표시)
+ * // Extract all files (with progress reporting)
  * await using archive = new ZipArchive(zipBytes);
  * const files = await archive.extractAll((progress) => {
  *   console.log(`${progress.fileName}: ${progress.extractedSize}/${progress.totalSize}`);
@@ -48,8 +48,8 @@ export class ZipArchive {
   private _entries?: Awaited<ReturnType<ZipReader<Blob | Bytes>["getEntries"]>>;
 
   /**
-   * ZipArchive 생성
-   * @param data ZIP 데이터 (생략 시 새 아카이브 생성)
+   * Create ZipArchive
+   * @param data ZIP data (omit to create a new archive)
    */
   constructor(data?: Blob | Bytes) {
     if (!data) return;
@@ -70,8 +70,8 @@ export class ZipArchive {
 
   //#region extractAll
   /**
-   * 모든 파일을 압축 해제
-   * @param progressCallback 진행률 콜백
+   * Extract all files
+   * @param progressCallback Progress callback
    */
   async extractAll(
     progressCallback?: (progress: ZipArchiveProgress) => void,
@@ -79,7 +79,7 @@ export class ZipArchive {
     const entries = await this._getEntries();
     if (entries == null) return this._cache;
 
-    // 압축 해제 대상 크기 총합 계산
+    // Calculate total size to extract
     const totalSize = entries
       .filter((e) => !e.directory)
       .reduce((acc, e) => acc + e.uncompressedSize, 0);
@@ -112,7 +112,7 @@ export class ZipArchive {
 
       this._cache.set(entry.filename, entryBytes);
 
-      // 개별 파일이 끝나면 누적 처리
+      // Accumulate when individual file completes
       totalExtracted += entry.uncompressedSize;
 
       progressCallback?.({
@@ -128,8 +128,8 @@ export class ZipArchive {
 
   //#region get
   /**
-   * 특정 파일 압축 해제
-   * @param fileName 파일 이름
+   * Extract specific file
+   * @param fileName File name
    */
   async get(fileName: string): Promise<Bytes | undefined> {
     if (this._cache.has(fileName)) {
@@ -156,8 +156,8 @@ export class ZipArchive {
 
   //#region exists
   /**
-   * 파일 존재 여부 확인
-   * @param fileName 파일 이름
+   * Check if file exists
+   * @param fileName File name
    */
   async exists(fileName: string): Promise<boolean> {
     if (this._cache.has(fileName)) {
@@ -176,9 +176,9 @@ export class ZipArchive {
 
   //#region write
   /**
-   * 파일 쓰기 (캐시에 저장)
-   * @param fileName 파일 이름
-   * @param bytes 파일 내용
+   * Write file (store in cache)
+   * @param fileName File name
+   * @param bytes File content
    */
   write(fileName: string, bytes: Bytes): void {
     this._cache.set(fileName, bytes);
@@ -187,11 +187,11 @@ export class ZipArchive {
 
   //#region compress
   /**
-   * 캐시된 파일들을 ZIP으로 압축
+   * Compress cached files to ZIP
    *
    * @remarks
-   * 내부적으로 `extractAll()`을 호출하여 모든 파일을 메모리에 로드한 후 압축합니다.
-   * 대용량 ZIP 파일의 경우 메모리 사용량에 주의가 필요합니다.
+   * Internally calls `extractAll()` to load all files into memory before compressing.
+   * Be mindful of memory usage when dealing with large ZIP files.
    */
   async compress(): Promise<Bytes> {
     const fileMap = await this.extractAll();
@@ -211,7 +211,7 @@ export class ZipArchive {
 
   //#region close
   /**
-   * 리더 닫기 및 캐시 정리
+   * Close reader and clear cache
    */
   async close(): Promise<void> {
     await this._reader?.close();
@@ -219,7 +219,7 @@ export class ZipArchive {
   }
 
   /**
-   * await using 지원
+   * Support for await using
    */
   async [Symbol.asyncDispose](): Promise<void> {
     await this.close();

package/tests/errors/errors.spec.ts

@@ -0,0 +1,80 @@
+import { describe, it, expect } from "vitest";
+import { SdError, ArgumentError } from "@simplysm/core-common";
+
+describe("Errors", () => {
+  //#region SdError
+
+  describe("SdError", () => {
+    it("Creates with cause", () => {
+      const cause = new Error("original error");
+      const error = new SdError(cause, "wrapped message");
+
+      // Message combined as "wrapped message => original error" format
+      expect(error.message).toContain("wrapped message");
+      expect(error.message).toContain("original error");
+    });
+
+    it("Integrates cause message", () => {
+      const cause = new Error("cause message");
+      const error = new SdError(cause, "main message");
+
+      expect(error.message).toContain("main message");
+    });
+
+    it("Handles multi-level cause chain", () => {
+      const root = new Error("root error");
+      const middle = new SdError(root, "middle error");
+      const top = new SdError(middle, "top error");
+
+      expect(top.message).toContain("top error");
+      expect(top.message).toContain("middle error");
+      expect(top.message).toContain("root error");
+    });
+
+    it("Integrates cause stack to current stack", () => {
+      const cause = new Error("cause error");
+      const error = new SdError(cause, "main error");
+
+      expect(error.stack).toContain("---- cause stack ----");
+      expect(error.stack).toContain(cause.stack);
+    });
+
+    it("Converts non-Error object passed as cause using String()", () => {
+      // number
+      const errorFromNumber = new SdError(42, "number cause");
+      expect(errorFromNumber.message).toContain("42");
+
+      // object
+      const errorFromObject = new SdError({ code: 500, reason: "server error" }, "object cause");
+      expect(errorFromObject.message).toContain("object cause");
+
+      // null/undefined
+      const errorFromNull = new SdError(null, "null cause");
+      expect(errorFromNull.message).toContain("null cause");
+    });
+  });
+
+  //#endregion
+
+  //#region ArgumentError
+
+  describe("ArgumentError", () => {
+    it("Creates with argObj", () => {
+      const error = new ArgumentError("invalid argument", { param: "value", expected: "string" });
+
+      // argObj included in message as YAML format
+      expect(error.message).toContain("invalid argument");
+      expect(error.message).toContain("param");
+      expect(error.message).toContain("value");
+    });
+
+    it("Creates with only argObj without message", () => {
+      const error = new ArgumentError({ key: "value" });
+
+      expect(error.message).toContain("Invalid arguments");
+      expect(error.message).toContain("key");
+    });
+  });
+
+  //#endregion
+});