@simplysm/core-common 13.0.100 → 14.0.4

package/src/utils/xml.ts

@@ -1,5 +1,5 @@
 /**
- * XML conversion utility
+ * XML 변환 유틸리티
  */
 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
 
 /**
- * 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)
+ * XML 문자열을 객체로 파싱
+ * @param str XML 문자열
+ * @param options 옵션
+ * @param options.stripTagPrefix 태그 접두사(네임스페이스) 제거 여부
+ * @returns 파싱된 객체. 구조:
+ *   - 속성: `$` 객체에 그룹화
+ *   - 텍스트 노드: `_` key에 저장
+ *   - 자식 요소: array로 변환 (루트 요소 제외)
  * @example
  * xmlParse('<root id="1"><item>hello</item></root>');
  * // { root: { $: { id: "1" }, item: [{ _: "hello" }] } }
@@ -40,10 +40,10 @@ export function parse(str: string, options?: { stripTagPrefix?: boolean }): unkn
 //#region stringify
 
 /**
- * Serialize object to XML string
- * @param obj Object to serialize
- * @param options fast-xml-parser XmlBuilderOptions (optional)
- * @returns XML string
+ * 객체를 XML 문자열로 직렬화
+ * @param obj 직렬화할 객체
+ * @param options fast-xml-parser XmlBuilderOptions (선택사항)
+ * @returns XML 문자열
  * @example
  * xmlStringify({
  *   root: {
@@ -69,10 +69,10 @@ export function stringify(obj: unknown, options?: XmlBuilderOptions): string {
 //#region private
 
 /**
- * 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.
+ * 태그 이름에서 네임스페이스 접두사 제거
+ * @note XML 파싱 결과에서 "ns:tag" 형식의 네임스페이스 접두사를 제거하여 태그 이름만 남김.
+ *       네임스페이스를 고려하지 않고 XML 데이터에 일관되게 접근 가능.
+ *       단, 속성은 접두사가 유지됨.
  */
 function stripTagPrefix(obj: unknown): unknown {
   if (Array.isArray(obj)) {
@@ -86,11 +86,11 @@ function stripTagPrefix(obj: unknown): unknown {
     for (const key of Object.keys(record)) {
       const value = record[key];
 
-      // Attributes must not have prefix removed
+      // 속성은 접두사를 제거하면 안 됨
       if (key === "$") {
         newObj[key] = value;
       } else {
-        // 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/utils/zip.ts

@@ -1,5 +1,5 @@
 /**
- * ZIP file processing utility
+ * ZIP 파일 처리 유틸리티
  */
 import type { FileEntry } from "@zip.js/zip.js";
 import {
@@ -18,25 +18,25 @@ export interface ZipArchiveProgress {
 }
 
 /**
- * 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.
+ * ZIP 파일의 읽기, 쓰기, 압축, 해제를 처리.
+ * 동일 파일의 중복 해제를 방지하기 위해 내부 캐싱 사용.
  *
  * @example
- * // Read ZIP file
+ * // ZIP 파일 읽기
  * await using archive = new ZipArchive(zipBytes);
  * const content = await archive.get("file.txt");
  *
  * @example
- * // Create ZIP file
+ * // ZIP 파일 생성
  * 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"]>>;
 
   /**
-   * Create ZipArchive
-   * @param data ZIP data (omit to create a new archive)
+   * ZipArchive 생성
+   * @param data ZIP 데이터 (생략하면 새 아카이브 생성)
    */
   constructor(data?: Blob | Bytes) {
     if (!data) return;
@@ -70,8 +70,8 @@ export class ZipArchive {
 
   //#region extractAll
   /**
-   * Extract all files
-   * @param progressCallback Progress callback
+   * 모든 파일 추출
+   * @param progressCallback 진행률 콜백
    */
   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
   /**
-   * Extract specific file
-   * @param fileName File name
+   * 특정 파일 추출
+   * @param fileName 파일 이름
    */
   async get(fileName: string): Promise<Bytes | undefined> {
     if (this._cache.has(fileName)) {
@@ -156,8 +156,8 @@ export class ZipArchive {
 
   //#region exists
   /**
-   * Check if file exists
-   * @param fileName File name
+   * 파일 존재 여부 확인
+   * @param fileName 파일 이름
    */
   async exists(fileName: string): Promise<boolean> {
     if (this._cache.has(fileName)) {
@@ -176,9 +176,9 @@ export class ZipArchive {
 
   //#region write
   /**
-   * Write file (store in cache)
-   * @param fileName File name
-   * @param bytes File content
+   * 파일 쓰기 (캐시에 저장)
+   * @param fileName 파일 이름
+   * @param bytes 파일 내용
    */
   write(fileName: string, bytes: Bytes): void {
     this._cache.set(fileName, bytes);
@@ -187,11 +187,11 @@ export class ZipArchive {
 
   //#region compress
   /**
-   * Compress cached files to ZIP
+   * 캐시된 파일을 ZIP으로 압축
    *
    * @remarks
-   * Internally calls `extractAll()` to load all files into memory before compressing.
-   * Be mindful of memory usage when dealing with large ZIP files.
+   * 내부적으로 `extractAll()`을 호출하여 모든 파일을 메모리에 로드한 후 압축.
+   * 대용량 ZIP 파일 처리 시 메모리 사용량에 주의.
    */
   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 {
   }
 
   /**
-   * Support for await using
+   * await using 지원
    */
   async [Symbol.asyncDispose](): Promise<void> {
     await this.close();

package/docs/extensions.md

@@ -1,387 +0,0 @@
-# Prototype Extensions (side-effect)
-
-Prototype extensions for `Array`, `Map`, and `Set`. These are applied as side effects when importing `@simplysm/core-common`.
-
-**Important:** Importing the package entry point automatically patches these prototypes. If you import only specific sub-modules, you must also import the extension modules or the entry point to get these methods.
-
-Source: `src/extensions/*.ts`
-
----
-
-## Array Extensions
-
-### Readonly methods (return new array or value, do not mutate)
-
-#### `single`
-
-Return single element matching condition. Throws `ArgumentError` if 2+ elements match.
-
-```typescript
-single(predicate?: (item: T, index: number) => boolean): T | undefined;
-```
-
-#### `first`
-
-Return first element.
-
-```typescript
-first(predicate?: (item: T, index: number) => boolean): T | undefined;
-```
-
-#### `last`
-
-Return last element.
-
-```typescript
-last(predicate?: (item: T, index: number) => boolean): T | undefined;
-```
-
-#### `filterAsync`
-
-Async filter (sequential execution).
-
-```typescript
-filterAsync(predicate: (item: T, index: number) => Promise<boolean>): Promise<T[]>;
-```
-
-#### `filterExists`
-
-Remove `null` and `undefined` values.
-
-```typescript
-filterExists(): NonNullable<T>[];
-```
-
-#### `ofType`
-
-Filter only elements of specific type (`PrimitiveTypeStr` or constructor type).
-
-```typescript
-ofType<TKey extends PrimitiveTypeStr>(type: TKey): Extract<T, PrimitiveTypeMap[TKey]>[];
-ofType<TNarrow extends T>(type: Type<TNarrow>): TNarrow[];
-```
-
-#### `mapAsync`
-
-Async mapping (sequential execution).
-
-```typescript
-mapAsync<R>(selector: (item: T, index: number) => Promise<R>): Promise<R[]>;
-```
-
-#### `mapMany`
-
-Flatten nested array, or map then flatten.
-
-```typescript
-mapMany(): T extends readonly (infer U)[] ? U[] : T;
-mapMany<R>(selector: (item: T, index: number) => R[]): R[];
-```
-
-#### `mapManyAsync`
-
-Async mapping and then flatten (sequential execution).
-
-```typescript
-mapManyAsync<R>(selector: (item: T, index: number) => Promise<R[]>): Promise<R[]>;
-```
-
-#### `parallelAsync`
-
-Async parallel processing using `Promise.all`.
-
-```typescript
-parallelAsync<R>(fn: (item: T, index: number) => Promise<R>): Promise<R[]>;
-```
-
-#### `groupBy`
-
-Group by key. O(n) for primitive keys, O(n^2) for object keys (deep comparison).
-
-```typescript
-groupBy<K>(keySelector: (item: T, index: number) => K): { key: K; values: T[] }[];
-groupBy<K, V>(
-  keySelector: (item: T, index: number) => K,
-  valueSelector: (item: T, index: number) => V,
-): { key: K; values: V[] }[];
-```
-
-#### `toMap`
-
-Convert to `Map`. Throws `ArgumentError` on duplicate keys.
-
-```typescript
-toMap<K>(keySelector: (item: T, index: number) => K): Map<K, T>;
-toMap<K, V>(keySelector: (item: T, index: number) => K, valueSelector: (item: T, index: number) => V): Map<K, V>;
-```
-
-#### `toMapAsync`
-
-Async version of `toMap`.
-
-```typescript
-toMapAsync<K>(keySelector: (item: T, index: number) => Promise<K>): Promise<Map<K, T>>;
-toMapAsync<K, V>(
-  keySelector: (item: T, index: number) => Promise<K> | K,
-  valueSelector: (item: T, index: number) => Promise<V> | V,
-): Promise<Map<K, V>>;
-```
-
-#### `toArrayMap`
-
-Convert to `Map<K, T[]>` (groups values by key).
-
-```typescript
-toArrayMap<K>(keySelector: (item: T, index: number) => K): Map<K, T[]>;
-toArrayMap<K, V>(keySelector: (item: T, index: number) => K, valueSelector: (item: T, index: number) => V): Map<K, V[]>;
-```
-
-#### `toSetMap`
-
-Convert to `Map<K, Set<T>>`.
-
-```typescript
-toSetMap<K>(keySelector: (item: T, index: number) => K): Map<K, Set<T>>;
-toSetMap<K, V>(keySelector: (item: T, index: number) => K, valueSelector: (item: T, index: number) => V): Map<K, Set<V>>;
-```
-
-#### `toMapValues`
-
-Group by key, then reduce each group's values.
-
-```typescript
-toMapValues<K, V>(
-  keySelector: (item: T, index: number) => K,
-  valueSelector: (items: T[]) => V,
-): Map<K, V>;
-```
-
-#### `toObject`
-
-Convert to plain object. Throws `ArgumentError` on duplicate keys.
-
-```typescript
-toObject(keySelector: (item: T, index: number) => string): Record<string, T>;
-toObject<V>(keySelector: (item: T, index: number) => string, valueSelector: (item: T, index: number) => V): Record<string, V>;
-```
-
-#### `toTree`
-
-Convert flat array to tree structure. Items with `null`/`undefined` parent key become roots. Uses `toArrayMap` for O(n) complexity.
-
-```typescript
-toTree<K extends keyof T, P extends keyof T>(keyProp: K, parentKey: P): TreeArray<T>[];
-```
-
-#### `distinct`
-
-Remove duplicates. Options: `matchAddress` for reference comparison, `keyFn` for custom key (O(n)). Without `keyFn` on objects: O(n^2).
-
-```typescript
-distinct(options?: boolean | { matchAddress?: boolean; keyFn?: (item: T) => string | number }): T[];
-```
-
-#### `orderBy` / `orderByDesc`
-
-Sort in ascending or descending order. Supports `string`, `number`, `DateTime`, `DateOnly`, `Time`.
-
-```typescript
-orderBy(selector?: (item: T) => string | number | DateTime | DateOnly | Time | undefined): T[];
-orderByDesc(selector?: (item: T) => string | number | DateTime | DateOnly | Time | undefined): T[];
-```
-
-#### `diffs`
-
-Compare two arrays and return INSERT / DELETE / UPDATE results.
-
-```typescript
-diffs<P>(target: P[]): ArrayDiffsResult<T, P>[];
-diffs<P>(target: P[], options: { keys: string[]; excludes?: string[] }): ArrayDiffsResult<T, P>[];
-diffs<P>(target: P[], options: { excludes: string[] }): ArrayDiffsResult<T, P>[];
-```
-
-#### `oneWayDiffs`
-
-One-way diff against original items. Returns `"create"`, `"update"`, or `"same"` for each item.
-
-```typescript
-oneWayDiffs<K extends keyof T>(
-  orgItems: T[] | Map<T[K], T>,
-  keyPropNameOrGetValFn: K | ((item: T) => string | number | undefined),
-  options?: { includeSame?: boolean; excludes?: string[]; includes?: string[] },
-): ArrayOneWayDiffResult<T>[];
-```
-
-#### `merge`
-
-Merge source and target arrays based on diff results.
-
-```typescript
-merge<P>(target: P[]): (T | P | (T & P))[];
-merge<P>(target: P[], options: { keys: string[]; excludes?: string[] }): (T | P | (T & P))[];
-```
-
-#### `sum`
-
-Return sum of elements. Returns `0` for empty arrays.
-
-```typescript
-sum(selector?: (item: T, index: number) => number): number;
-```
-
-#### `min` / `max`
-
-Return minimum or maximum value.
-
-```typescript
-min(): T extends number | string ? T | undefined : never;
-min<P extends number | string>(selector?: (item: T, index: number) => P): P | undefined;
-max(): T extends number | string ? T | undefined : never;
-max<P extends number | string>(selector?: (item: T, index: number) => P): P | undefined;
-```
-
-#### `shuffle`
-
-Return a shuffled copy (Fisher-Yates algorithm).
-
-```typescript
-shuffle(): T[];
-```
-
----
-
-### Mutable methods (modify original array, marked `@mutates`)
-
-#### `distinctThis`
-
-Remove duplicates from original array.
-
-```typescript
-distinctThis(options?: boolean | { matchAddress?: boolean; keyFn?: (item: T) => string | number }): T[];
-```
-
-#### `orderByThis` / `orderByDescThis`
-
-Sort original array in ascending or descending order.
-
-```typescript
-orderByThis(selector?: (item: T) => string | number | DateTime | DateOnly | Time | undefined): T[];
-orderByDescThis(selector?: (item: T) => string | number | DateTime | DateOnly | Time | undefined): T[];
-```
-
-#### `insert`
-
-Insert items at index.
-
-```typescript
-insert(index: number, ...items: T[]): this;
-```
-
-#### `remove`
-
-Remove item or items matching condition.
-
-```typescript
-remove(item: T): this;
-remove(selector: (item: T, index: number) => boolean): this;
-```
-
-#### `toggle`
-
-Toggle item in array (remove if exists, add if not).
-
-```typescript
-toggle(item: T): this;
-```
-
-#### `clear`
-
-Clear all items from array.
-
-```typescript
-clear(): this;
-```
-
----
-
-## Exported Types
-
-```typescript
-export type ArrayDiffsResult<TOriginal, TOther> =
-  | { source: undefined; target: TOther }      // INSERT
-  | { source: TOriginal; target: undefined }    // DELETE
-  | { source: TOriginal; target: TOther };      // UPDATE
-
-export type ArrayOneWayDiffResult<TItem> =
-  | { type: "create"; item: TItem; orgItem: undefined }
-  | { type: "update"; item: TItem; orgItem: TItem }
-  | { type: "same"; item: TItem; orgItem: TItem };
-
-export type TreeArray<TNode> = TNode & { children: TreeArray<TNode>[] };
-
-/** Type that can be sorted/compared */
-export type ComparableType = string | number | boolean | DateTime | DateOnly | Time | undefined;
-```
-
----
-
-## Map Extensions
-
-#### `getOrCreate`
-
-If no value exists for key, set new value and return it. If the second argument is a function, it is called as a factory.
-
-```typescript
-getOrCreate(key: K, newValue: V): V;
-getOrCreate(key: K, newValueFn: () => V): V;
-```
-
-**Caution:** If `V` is a function type, passing the function directly will be recognized as a factory and called. Wrap it in a factory to store the function itself.
-
-#### `update`
-
-Update value for key using function. Called even if key does not exist.
-
-```typescript
-update(key: K, updateFn: (v: V | undefined) => V): void;
-```
-
-**Example:**
-
-```typescript
-const countMap = new Map<string, number>();
-countMap.update("key", (v) => (v ?? 0) + 1);
-
-map.getOrCreate("users", []).push(newUser);
-```
-
----
-
-## Set Extensions
-
-#### `adds`
-
-Add multiple values at once.
-
-```typescript
-adds(...values: T[]): this;
-```
-
-#### `toggle`
-
-Toggle value (remove if exists, add if not). Optional `addOrDel` parameter to force add or remove.
-
-```typescript
-toggle(value: T, addOrDel?: "add" | "del"): this;
-```
-
-**Example:**
-
-```typescript
-const set = new Set<number>([1, 2, 3]);
-set.toggle(2);  // 2 exists, so remove -> {1, 3}
-set.toggle(4);  // 4 doesn't exist, so add -> {1, 3, 4}
-
-const isAdmin = true;
-set.toggle(5, isAdmin ? "add" : "del"); // Force add
-```

package/tests/errors/errors.spec.ts

@@ -1,80 +0,0 @@
-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
-});