@simplysm/core-common 13.0.99 → 14.0.1

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/README.md

@@ -1,160 +0,0 @@
-# @simplysm/core-common
-
-Core module (common) -- platform-neutral core utilities for the Simplysm framework.
-
-Provides error classes, immutable date/time types, prototype extensions, event handling, and utility namespaces that work in both browser and Node.js environments.
-
-## Installation
-
-```bash
-npm install @simplysm/core-common
-```
-
-## Side-Effect Imports
-
-Importing the package entry point (`@simplysm/core-common`) automatically patches `Array`, `Map`, and `Set` prototypes with extension methods. These are declared as side effects in `package.json`:
-
-- `extensions/arr-ext` -- Array prototype extensions
-- `extensions/map-ext` -- Map prototype extensions
-- `extensions/set-ext` -- Set prototype extensions
-
-If you import only specific modules (e.g., `@simplysm/core-common/dist/types/date-time`), the prototype extensions are **not** applied unless you also import the entry point or the extension modules directly.
-
-## API Overview
-
-### Errors
-
-| API | Type | Description |
-|-----|------|-------------|
-| `SdError` | class | Error with tree-structured cause chaining |
-| `ArgumentError` | class | Invalid argument error with YAML-formatted details |
-| `NotImplementedError` | class | Unimplemented feature error |
-| `TimeoutError` | class | Waiting time exceeded error |
-
--> See [docs/errors.md](./docs/errors.md) for details.
-
-### Types
-
-| API | Type | Description |
-|-----|------|-------------|
-| `Uuid` | class | UUID v4 generation and parsing |
-| `DateTime` | class | Immutable date+time (millisecond precision) |
-| `DateOnly` | class | Immutable date without time |
-| `Time` | class | Immutable time without date (24h wraparound) |
-| `LazyGcMap` | class | Map with LRU-based automatic expiration |
-| `Bytes` | type alias | `Uint8Array` (replaces `Buffer`) |
-| `PrimitiveTypeMap` | type | Mapping of type name strings to types |
-| `PrimitiveTypeStr` | type | `keyof PrimitiveTypeMap` |
-| `PrimitiveType` | type | Union of all primitive types |
-| `DeepPartial<T>` | type | Recursively makes all properties optional |
-| `Type<T>` | interface | Constructor type for DI and factory patterns |
-| `env` | const | Unified `DEV` / `VER` environment accessor |
-
--> See [docs/types.md](./docs/types.md) for details.
-
-### Features
-
-| API | Type | Description |
-|-----|------|-------------|
-| `EventEmitter` | class | Type-safe event emitter (EventTarget wrapper) |
-| `DebounceQueue` | class | Async debounce -- only the last call executes |
-| `SerialQueue` | class | Async serial execution queue |
-
--> See [docs/features.md](./docs/features.md) for details.
-
-### Prototype Extensions (side-effect)
-
-| API | Type | Description |
-|-----|------|-------------|
-| `Array` extensions | prototype | 34 methods -- query, transform, diff, sort, mutate |
-| `Map` extensions | prototype | `getOrCreate`, `update` |
-| `Set` extensions | prototype | `adds`, `toggle` |
-
--> See [docs/extensions.md](./docs/extensions.md) for details.
-
-### Utilities
-
-| API | Type | Description |
-|-----|------|-------------|
-| `obj` | namespace | clone, equal, merge, merge3, omit, pick, chain access |
-| `str` | namespace | Korean particles, case conversion, full-width replacement |
-| `num` | namespace | parseInt, parseFloat, format with separators |
-| `bytes` | namespace | concat, hex, base64 conversion |
-| `path` | namespace | POSIX-only join, basename, extname |
-| `json` | namespace | Custom-type-aware JSON stringify/parse |
-| `xml` | namespace | XML parse/stringify via fast-xml-parser |
-| `wait` | namespace | `until` (polling) and `time` (delay) |
-| `transfer` | namespace | Worker-safe encode/decode for custom types |
-| `err` | namespace | Extract message from unknown error |
-| `dt` | namespace | Date format, month normalization, 12h/24h conversion |
-| `primitive` | namespace | Infer `PrimitiveTypeStr` from a value |
-| `js`, `ts`, `html`, `tsql`, `mysql`, `pgsql` | function | Template tag functions for syntax highlighting |
-| `ZipArchive` | class | ZIP read/write/compress with caching |
-
--> See [docs/utils.md](./docs/utils.md) for details.
-
-## Quick Usage Examples
-
-### DateTime (immutable date/time)
-
-```typescript
-import { DateTime, DateOnly } from "@simplysm/core-common";
-
-const now = new DateTime();
-const tomorrow = now.addDays(1);
-const formatted = now.toFormatString("yyyy-MM-dd HH:mm:ss");
-const parsed = DateTime.parse("2025-01-15 10:30:00");
-
-const today = new DateOnly();
-const weekInfo = today.getWeekSeqOfYear(); // { year, weekSeq }
-```
-
-### Object utilities
-
-```typescript
-import { obj, json } from "@simplysm/core-common";
-
-const cloned = obj.clone(deepObject);
-const isEqual = obj.equal(a, b, { ignoreArrayIndex: true });
-const merged = obj.merge(base, override);
-const value = obj.getChainValue(data, "a.b[0].c");
-
-// Custom-type-aware JSON
-const str = json.stringify({ date: new DateTime(), id: Uuid.generate() });
-const restored = json.parse(str); // DateTime and Uuid instances restored
-```
-
-### Array extensions
-
-```typescript
-import "@simplysm/core-common";
-
-const items = [3, 1, 4, 1, 5];
-items.distinct();          // [3, 1, 4, 5]
-items.orderBy();           // [1, 1, 3, 4, 5]
-items.sum();               // 14
-items.groupBy((x) => x % 2 === 0 ? "even" : "odd");
-
-const users = [{ id: 1, name: "A" }, { id: 2, name: "B" }];
-users.toMap((u) => u.id);  // Map { 1 => {...}, 2 => {...} }
-users.single((u) => u.id === 1); // { id: 1, name: "A" }
-```
-
-### EventEmitter
-
-```typescript
-import { EventEmitter } from "@simplysm/core-common";
-
-interface MyEvents { data: string; done: void }
-
-class MyService extends EventEmitter<MyEvents> {}
-
-const svc = new MyService();
-svc.on("data", (msg) => console.log(msg));
-svc.emit("data", "hello");
-svc.emit("done");
-```
-
-## License
-
-Apache-2.0

package/docs/errors.md

@@ -1,119 +0,0 @@
-# Errors
-
-Error classes for the Simplysm framework. All classes extend `SdError`, which itself extends `Error`.
-
-Source: `src/errors/*.ts`
-
----
-
-## `SdError`
-
-Error class supporting tree-structured cause chaining. Utilizes ES2024 `cause` property. Messages are joined in reverse order with ` => ` separator, and cause stack traces are appended.
-
-```typescript
-export class SdError extends Error {
-  override cause?: Error;
-
-  /** Create by wrapping a cause error. Messages are joined in reverse order (upper message => lower message => cause message) */
-  constructor(cause: Error, ...messages: string[]);
-  /** Create with messages only. Messages are joined in reverse order (upper message => lower message) */
-  constructor(...messages: string[]);
-}
-```
-
-**Example:**
-
-```typescript
-try {
-  await fetch(url);
-} catch (err) {
-  throw new SdError(err, "API call failed", "User load failed");
-}
-// Result message: "User load failed => API call failed => original error message"
-
-throw new SdError("invalid state", "processing not possible");
-// Result message: "processing not possible => invalid state"
-```
-
----
-
-## `ArgumentError`
-
-An error thrown when invalid arguments are received. Includes the argument object in YAML format in the message to facilitate debugging. Extends `SdError`.
-
-```typescript
-export class ArgumentError extends SdError {
-  /** Output argument object in YAML format with default message ("Invalid arguments.") */
-  constructor(argObj: Record<string, unknown>);
-  /** Output argument object in YAML format with a custom message */
-  constructor(message: string, argObj: Record<string, unknown>);
-}
-```
-
-**Example:**
-
-```typescript
-throw new ArgumentError({ userId: 123, name: null });
-// Result message: "Invalid arguments.\n\nuserId: 123\nname: null"
-
-throw new ArgumentError("Invalid user", { userId: 123 });
-// Result message: "Invalid user\n\nuserId: 123"
-```
-
----
-
-## `NotImplementedError`
-
-An error thrown when a feature that has not yet been implemented is called. Extends `SdError`.
-
-```typescript
-export class NotImplementedError extends SdError {
-  /**
-   * @param message Additional description message
-   */
-  constructor(message?: string);
-}
-```
-
-**Example:**
-
-```typescript
-class BaseService {
-  process(): void {
-    throw new NotImplementedError("Implementation required in subclass");
-  }
-}
-
-switch (type) {
-  case "A": return handleA();
-  case "B": throw new NotImplementedError(`Handling for type ${type}`);
-}
-```
-
----
-
-## `TimeoutError`
-
-An error that occurs when the waiting time is exceeded. Automatically thrown when the maximum number of attempts is exceeded in `wait.until()`. Extends `SdError`.
-
-```typescript
-export class TimeoutError extends SdError {
-  /**
-   * @param count Number of attempts
-   * @param message Additional message
-   */
-  constructor(count?: number, message?: string);
-}
-```
-
-**Example:**
-
-```typescript
-try {
-  await wait.until(() => isReady, 100, 50);
-} catch (err) {
-  if (err instanceof TimeoutError) {
-    // "Waiting time exceeded(50 attempts)"
-  }
-}
-```