@simplysm/core-common 13.0.69 → 13.0.71

package/dist/zip/sd-zip.d.ts

@@ -5,25 +5,25 @@ export interface ZipArchiveProgress {
     extractedSize: number;
 }
 /**
- * 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}`);
@@ -34,46 +34,46 @@ export declare class ZipArchive {
     private readonly _cache;
     private _entries?;
     /**
-     * ZipArchive 생성
-     * @param data ZIP 데이터 (생략 시 새 아카이브 생성)
+     * Create ZipArchive
+     * @param data ZIP data (omit to create a new archive)
      */
     constructor(data?: Blob | Bytes);
     private _getEntries;
     /**
-     * 모든 파일을 압축 해제
-     * @param progressCallback 진행률 콜백
+     * Extract all files
+     * @param progressCallback Progress callback
      */
     extractAll(progressCallback?: (progress: ZipArchiveProgress) => void): Promise<Map<string, Bytes | undefined>>;
     /**
-     * 특정 파일 압축 해제
-     * @param fileName 파일 이름
+     * Extract specific file
+     * @param fileName File name
      */
     get(fileName: string): Promise<Bytes | undefined>;
     /**
-     * 파일 존재 여부 확인
-     * @param fileName 파일 이름
+     * Check if file exists
+     * @param fileName File name
      */
     exists(fileName: string): Promise<boolean>;
     /**
-     * 파일 쓰기 (캐시에 저장)
-     * @param fileName 파일 이름
-     * @param bytes 파일 내용
+     * Write file (store in cache)
+     * @param fileName File name
+     * @param bytes File content
      */
     write(fileName: string, bytes: Bytes): void;
     /**
-     * 캐시된 파일들을 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.
      */
     compress(): Promise<Bytes>;
     /**
-     * 리더 닫기 및 캐시 정리
+     * Close reader and clear cache
      */
     close(): Promise<void>;
     /**
-     * await using 지원
+     * Support for await using
      */
     [Symbol.asyncDispose](): Promise<void>;
 }

package/dist/zip/sd-zip.js

@@ -10,8 +10,8 @@ class ZipArchive {
   _cache = /* @__PURE__ */ new Map();
   _entries;
   /**
-   * ZipArchive 생성
-   * @param data ZIP 데이터 (생략 시 새 아카이브 생성)
+   * Create ZipArchive
+   * @param data ZIP data (omit to create a new archive)
    */
   constructor(data) {
     if (!data) return;
@@ -29,8 +29,8 @@ class ZipArchive {
   }
   //#region extractAll
   /**
-   * 모든 파일을 압축 해제
-   * @param progressCallback 진행률 콜백
+   * Extract all files
+   * @param progressCallback Progress callback
    */
   async extractAll(progressCallback) {
     const entries = await this._getEntries();
@@ -68,8 +68,8 @@ class ZipArchive {
   //#endregion
   //#region get
   /**
-   * 특정 파일 압축 해제
-   * @param fileName 파일 이름
+   * Extract specific file
+   * @param fileName File name
    */
   async get(fileName) {
     if (this._cache.has(fileName)) {
@@ -92,8 +92,8 @@ class ZipArchive {
   //#endregion
   //#region exists
   /**
-   * 파일 존재 여부 확인
-   * @param fileName 파일 이름
+   * Check if file exists
+   * @param fileName File name
    */
   async exists(fileName) {
     if (this._cache.has(fileName)) {
@@ -109,9 +109,9 @@ class ZipArchive {
   //#endregion
   //#region write
   /**
-   * 파일 쓰기 (캐시에 저장)
-   * @param fileName 파일 이름
-   * @param bytes 파일 내용
+   * Write file (store in cache)
+   * @param fileName File name
+   * @param bytes File content
    */
   write(fileName, bytes) {
     this._cache.set(fileName, bytes);
@@ -119,11 +119,11 @@ class ZipArchive {
   //#endregion
   //#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() {
     const fileMap = await this.extractAll();
@@ -138,7 +138,7 @@ class ZipArchive {
   //#endregion
   //#region close
   /**
-   * 리더 닫기 및 캐시 정리
+   * Close reader and clear cache
    */
   async close() {
     var _a;
@@ -146,7 +146,7 @@ class ZipArchive {
     this._cache.clear();
   }
   /**
-   * await using 지원
+   * Support for await using
    */
   async [Symbol.asyncDispose]() {
     await this.close();

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@simplysm/core-common",
-  "version": "13.0.69",
-  "description": "심플리즘 패키지 - 코어 모듈 (common)",
-  "author": "김석래",
+  "version": "13.0.71",
+  "description": "Simplysm package - Core module (common)",
+  "author": "simplysm",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -15,7 +15,7 @@
   "files": [
     "dist",
     "src",
-    "docs"
+    "tests"
   ],
   "sideEffects": [
     "./src/extensions/arr-ext.ts",

package/src/common.types.ts

@@ -3,20 +3,20 @@ import { DateOnly } from "./types/date-only";
 import { Time } from "./types/time";
 import { Uuid } from "./types/uuid";
 
-//#region Bytes 타입
+//#region Bytes Type
 
 /**
- * Buffer 대신 사용하는 바이너리 타입
+ * Binary type used instead of Buffer
  */
 export type Bytes = Uint8Array;
 
 //#endregion
 
-//#region Primitive 타입
+//#region Primitive Type
 
 /**
- * Primitive 타입 매핑
- * orm-common과 공유
+ * Primitive type mapping
+ * Shared with orm-common
  */
 export type PrimitiveTypeMap = {
   string: string;
@@ -30,25 +30,25 @@ export type PrimitiveTypeMap = {
 };
 
 /**
- * Primitive 타입 문자열 키
+ * Primitive type string key
  */
 export type PrimitiveTypeStr = keyof PrimitiveTypeMap;
 
 /**
- * Primitive 타입 유니온
+ * Primitive type union
  */
 export type PrimitiveType = PrimitiveTypeMap[PrimitiveTypeStr] | undefined;
 
 //#endregion
 
-//#region 유틸리티 타입
+//#region Utility Types
 
 /**
- * 깊은 Partial 타입
+ * Deep Partial type
  *
- * 객체의 모든 속성을 재귀적으로 선택적(optional)으로 만듭니다.
- * Primitive 타입(string, number, boolean 등)은 그대로 유지하고,
- * 객체/배열 타입만 재귀적으로 Partial을 적용합니다.
+ * Recursively makes all properties of an object optional.
+ * Primitive types (string, number, boolean, etc.) are kept as-is,
+ * only object/array types have Partial applied recursively.
  *
  * @example
  * ```typescript
@@ -60,7 +60,7 @@ export type PrimitiveType = PrimitiveTypeMap[PrimitiveTypeStr] | undefined;
  *   };
  * }
  *
- * // 모든 깊이의 속성이 선택적이 됨
+ * // All properties at every depth become optional
  * const partial: DeepPartial<User> = {
  *   profile: { address: {} }
  * };
@@ -71,10 +71,10 @@ export type DeepPartial<TObject> = Partial<{
 }>;
 
 /**
- * 생성자 타입
+ * Constructor type
  *
- * 클래스 생성자를 타입으로 표현할 때 사용합니다.
- * 주로 의존성 주입, 팩토리 패턴, instanceof 체크 등에서 활용됩니다.
+ * Used to represent a class constructor as a type.
+ * Primarily used in dependency injection, factory patterns, and instanceof checks.
  *
  * @example
  * function create<T>(ctor: Type<T>): T {
@@ -82,7 +82,7 @@ export type DeepPartial<TObject> = Partial<{
  * }
  *
  * class MyClass { name = "test"; }
- * const instance = create(MyClass); // MyClass 인스턴스
+ * const instance = create(MyClass); // MyClass instance
  */
 export interface Type<TInstance> extends Function {
   new (...args: unknown[]): TInstance;

package/src/errors/argument-error.ts

@@ -1,29 +1,29 @@
-// yaml 라이브러리를 사용하는 이유:
-// 중첩된 객체 구조를 가독성 좋게 표현하기 위함.
-// JSON.stringify보다 트리 구조가 더 명확하게 보임.
+// Why we use the yaml library:
+// To represent nested object structures in a readable format.
+// Tree structure is more clearly visible than JSON.stringify.
 import YAML from "yaml";
 import { SdError } from "./sd-error";
 
 /**
- * 인수 오류
+ * Argument error
  *
- * 잘못된 인수를 받았을 때 발생시키는 에러이다.
- * 인수 객체를 YAML 형식으로 메시지에 포함하여 디버깅을 용이하게 한다.
+ * An error thrown when invalid arguments are received.
+ * Includes the argument object in YAML format in the message to facilitate debugging.
  *
  * @example
- * // 인수 객체만 전달
+ * // Passing only the argument object
  * throw new ArgumentError({ userId: 123, name: null });
- * // 결과 메시지: "인수가 잘못되었습니다.\n\nuserId: 123\nname: null"
+ * // Result message: "Invalid arguments.\n\nuserId: 123\nname: null"
  *
  * @example
- * // 커스텀 메시지와 인수 객체 전달
- * throw new ArgumentError("유효하지 않은 사용자", { userId: 123 });
- * // 결과 메시지: "유효하지 않은 사용자\n\nuserId: 123"
+ * // Passing a custom message and argument object
+ * throw new ArgumentError("Invalid user", { userId: 123 });
+ * // Result message: "Invalid user\n\nuserId: 123"
  */
 export class ArgumentError extends SdError {
-  /** 기본 메시지("인수가 잘못되었습니다.")와 함께 인수 객체를 YAML 형식으로 출력 */
+  /** Output argument object in YAML format with default message ("Invalid arguments.") */
   constructor(argObj: Record<string, unknown>);
-  /** 커스텀 메시지와 함께 인수 객체를 YAML 형식으로 출력 */
+  /** Output argument object in YAML format with a custom message */
   constructor(message: string, argObj: Record<string, unknown>);
   constructor(arg1: Record<string, unknown> | string, arg2?: Record<string, unknown>);
   constructor(arg1: Record<string, unknown> | string, arg2?: Record<string, unknown>) {
@@ -31,9 +31,9 @@ export class ArgumentError extends SdError {
     const argObj = typeof arg1 === "string" ? arg2 : arg1;
 
     if (argObj != null) {
-      super((message ?? "인수가 잘못되었습니다.") + "\n\n" + YAML.stringify(argObj));
+      super((message ?? "Invalid arguments.") + "\n\n" + YAML.stringify(argObj));
     } else {
-      super(message ?? "인수가 잘못되었습니다.");
+      super(message ?? "Invalid arguments.");
     }
     this.name = "ArgumentError";
   }

package/src/errors/not-implemented-error.ts

@@ -1,32 +1,32 @@
 import { SdError } from "./sd-error";
 
 /**
- * 미구현 오류
+ * Not implemented error
  *
- * 아직 구현되지 않은 기능을 호출했을 때 발생시키는 에러이다.
- * 추상 메서드 스텁, 향후 구현 예정인 분기 등에 사용한다.
+ * An error thrown when a feature that has not yet been implemented is called.
+ * Used for abstract method stubs, branches planned for future implementation, etc.
  *
  * @example
- * // 추상 메서드 구현 전
+ * // Before abstract method implementation
  * class BaseService {
  *   process(): void {
- *     throw new NotImplementedError("서브클래스에서 구현 필요");
+ *     throw new NotImplementedError("Implementation required in subclass");
  *   }
  * }
  *
  * @example
- * // 향후 구현 예정 분기
+ * // Branch planned for future implementation
  * switch (type) {
  *   case "A": return handleA();
- *   case "B": throw new NotImplementedError(`타입 ${type} 처리`);
+ *   case "B": throw new NotImplementedError(`Handling for type ${type}`);
  * }
  */
 export class NotImplementedError extends SdError {
   /**
-   * @param message 추가 설명 메시지
+   * @param message Additional description message
    */
   constructor(message?: string) {
-    super("구현되어 있지 않습니다" + (message != null ? ": " + message : ""));
+    super("Not implemented" + (message != null ? ": " + message : ""));
     this.name = "NotImplementedError";
   }
 }

package/src/errors/sd-error.ts

@@ -1,27 +1,27 @@
 /**
- * 오류의 Tree 구조 구성이 가능한 오류 클래스
- * ES2024 cause 속성 활용
+ * Error class supporting Tree structure composition
+ * Utilizes ES2024 cause property
  *
  * @example
- * // 원인 에러를 감싸서 생성
+ * // Wrap a cause error
  * try {
  *   await fetch(url);
  * } catch (err) {
- *   throw new SdError(err, "API 호출 실패", "사용자 로드 실패");
+ *   throw new SdError(err, "API call failed", "User load failed");
  * }
- * // 결과 메시지: "사용자 로드 실패 => API 호출 실패 => 원본 에러 메시지"
+ * // Result message: "User load failed => API call failed => original error message"
  *
  * @example
- * // 메시지만으로 생성
- * throw new SdError("잘못된 상태", "처리 불가");
- * // 결과 메시지: "처리 불가 => 잘못된 상태"
+ * // Create with message only
+ * throw new SdError("invalid state", "processing not possible");
+ * // Result message: "processing not possible => invalid state"
  */
 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[]);
   constructor(arg1?: unknown, ...messages: string[]);
   constructor(arg1?: unknown, ...messages: string[]) {
@@ -46,7 +46,7 @@ export class SdError extends Error {
     Object.setPrototypeOf(this, new.target.prototype);
     this.name = "SdError";
 
-    // V8 엔진(Node.js, Chrome)에서만 사용 가능한 captureStackTrace
+    // captureStackTrace available only on V8 engine (Node.js, Chrome)
     if ("captureStackTrace" in Error) {
       (Error.captureStackTrace as (targetObject: object, constructorOpt?: Function) => void)(
         this,
@@ -54,7 +54,7 @@ export class SdError extends Error {
       );
     }
 
-    // cause 체인의 stack을 현재 stack에 추가
+    // Add cause chain stack to current stack
     if (cause?.stack != null) {
       this.stack += `\n---- cause stack ----\n${cause.stack}`;
     }

package/src/errors/timeout-error.ts

@@ -1,36 +1,36 @@
 import { SdError } from "./sd-error";
 
 /**
- * 타임아웃 오류
+ * Timeout error
  *
- * 대기 시간이 초과되었을 때 발생하는 에러이다.
- * Wait.until() 등의 비동기 대기 함수에서 최대 시도 횟수를 초과하면 자동으로 발생한다.
+ * An error that occurs when the waiting time is exceeded.
+ * Automatically thrown when the maximum number of attempts is exceeded in async waiting functions like Wait.until().
  *
  * @example
- * // Wait.until에서 자동 발생
+ * // Automatically thrown from Wait.until
  * try {
- *   await Wait.until(() => isReady, 100, 50); // 100ms 간격, 최대 50회
+ *   await Wait.until(() => isReady, 100, 50); // 100ms interval, max 50 attempts
  * } catch (err) {
  *   if (err instanceof TimeoutError) {
- *     console.log("시간 초과");
+ *     console.log("Timeout exceeded");
  *   }
  * }
  *
  * @example
- * // 직접 발생
+ * // Thrown directly
  * if (elapsed > maxTime) {
- *   throw new TimeoutError(undefined, "API 응답 대기 초과");
+ *   throw new TimeoutError(undefined, "Waiting for API response exceeded");
  * }
  */
 export class TimeoutError extends SdError {
   /**
-   * @param count 시도 횟수
-   * @param message 추가 메시지
+   * @param count Number of attempts
+   * @param message Additional message
    */
   constructor(count?: number, message?: string) {
     super(
-      "대기 시간이 초과되었습니다" +
-        (count != null ? `(${count}회)` : "") +
+      "Waiting time exceeded" +
+        (count != null ? `(${count} attempts)` : "") +
         (message != null ? `: ${message}` : ""),
     );
     this.name = "TimeoutError";

package/src/extensions/arr-ext.helpers.ts

@@ -1,5 +1,5 @@
 /**
- * Array 확장 헬퍼 함수
+ * Array extension helper functions
  */
 
 import { DateTime } from "../types/date-time";
@@ -9,7 +9,7 @@ import { ArgumentError } from "../errors/argument-error";
 import type { ComparableType } from "./arr-ext.types";
 
 /**
- * DateTime, DateOnly, Time을 비교 가능한 primitive 값으로 변환
+ * Convert DateTime, DateOnly, Time to comparable primitive values
  */
 export function toComparable(value: ComparableType): string | number | boolean | undefined {
   if (value instanceof DateOnly || value instanceof DateTime || value instanceof Time) {
@@ -19,13 +19,13 @@ export function toComparable(value: ComparableType): string | number | boolean |
 }
 
 /**
- * 정렬을 위한 비교 함수
+ * Comparison function for sorting
  *
- * @param pp 비교 대상 1
- * @param pn 비교 대상 2
- * @param desc true: 내림차순, false: 오름차순
- * @returns 음수: pp가 앞, 0: 같음, 양수: pn이 앞
- * @note null/undefined 값은 오름차순 시 앞으로, 내림차순 시 뒤로 정렬됨
+ * @param pp comparison target 1
+ * @param pn comparison target 2
+ * @param desc true: descending, false: ascending
+ * @returns negative: pp comes first, 0: equal, positive: pn comes first
+ * @note null/undefined values are sorted first in ascending, last in descending
  */
 export function compareForOrder(pp: ComparableType, pn: ComparableType, desc: boolean): number {
   const cpp = toComparable(pp);
@@ -45,11 +45,11 @@ export function compareForOrder(pp: ComparableType, pn: ComparableType, desc: bo
     return cpp < cpn ? -1 : cpp > cpn ? 1 : 0;
   }
   if (typeof cpn === "boolean" && typeof cpp === "boolean") {
-    // true > false: 오름차순 시 true가 뒤, 내림차순 시 true가 앞
+    // true > false: true comes last in ascending, first in descending
     return cpn ? (desc ? 1 : -1) : desc ? -1 : 1;
   }
 
-  throw new ArgumentError("orderBy를 사용할 수 없는 타입입니다.", {
+  throw new ArgumentError("Cannot use orderBy with this type.", {
     type1: typeof cpp,
     type2: typeof cpn,
   });