@simplysm/core-common 13.0.100 → 14.0.1

package/src/common.types.ts

@@ -6,7 +6,7 @@ import { Uuid } from "./types/uuid";
 //#region Bytes Type
 
 /**
- * Binary type used instead of Buffer
+ * Buffer 대신 사용하는 바이너리 타입
  */
 export type Bytes = Uint8Array;
 
@@ -15,8 +15,8 @@ export type Bytes = Uint8Array;
 //#region Primitive Type
 
 /**
- * Primitive type mapping
- * Shared with orm-common
+ * 원시 타입 매핑
+ * orm-common과 공유
  */
 export type PrimitiveTypeMap = {
   string: string;
@@ -30,12 +30,12 @@ export type PrimitiveTypeMap = {
 };
 
 /**
- * Primitive type string key
+ * 원시 타입 문자열 key
  */
 export type PrimitiveTypeStr = keyof PrimitiveTypeMap;
 
 /**
- * Primitive type union
+ * 원시 타입 union
  */
 export type PrimitiveType = PrimitiveTypeMap[PrimitiveTypeStr] | undefined;
 
@@ -44,11 +44,11 @@ export type PrimitiveType = PrimitiveTypeMap[PrimitiveTypeStr] | undefined;
 //#region Utility Types
 
 /**
- * Deep Partial type
+ * Deep 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.
+ * 객체의 모든 속성을 재귀적으로 optional로 만든다.
+ * 원시 타입(string, number, boolean 등)은 그대로 유지하고,
+ * object/array 타입에만 재귀적으로 Partial을 적용한다.
  *
  * @example
  * ```typescript
@@ -60,7 +60,7 @@ export type PrimitiveType = PrimitiveTypeMap[PrimitiveTypeStr] | undefined;
  *   };
  * }
  *
- * // All properties at every depth become optional
+ * // 모든 깊이의 속성이 optional이 됨
  * const partial: DeepPartial<User> = {
  *   profile: { address: {} }
  * };
@@ -71,10 +71,10 @@ export type DeepPartial<TObject> = Partial<{
 }>;
 
 /**
- * Constructor type
+ * 생성자 타입
  *
- * Used to represent a class constructor as a type.
- * Primarily used in dependency injection, factory patterns, and instanceof checks.
+ * 클래스 생성자를 타입으로 표현할 때 사용한다.
+ * 주로 의존성 주입, 팩토리 패턴, instanceof 체크에 활용된다.
  *
  * @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 instance
+ * const instance = create(MyClass); // MyClass 인스턴스
  */
 export interface Type<TInstance> extends Function {
   new (...args: unknown[]): TInstance;

package/src/env.ts

@@ -6,6 +6,14 @@ declare global {
   }
 }
 
+/**
+ * 환경변수 값을 boolean으로 파싱
+ * "true", "1", "yes", "on" (대소문자 무시) → true, 그 외 → false
+ */
+export function parseBoolEnv(value: unknown): boolean {
+  return ["true", "1", "yes", "on"].includes(String(value ?? "").toLowerCase());
+}
+
 const _metaEnv: Record<string, unknown> = import.meta.env ?? {};
 const _processEnv: Record<string, unknown> = typeof process !== "undefined" ? process.env : {};
 const _raw: Record<string, unknown> = { ..._metaEnv, ..._processEnv };
@@ -16,6 +24,6 @@ export const env: {
   [key: string]: unknown;
 } = {
   ..._raw,
-  DEV: JSON.parse(String(_raw["DEV"] != null && String(_raw["DEV"]) !== "" ? _raw["DEV"] : false)),
+  DEV: parseBoolEnv(_raw["DEV"]),
   VER: _raw["VER"] as string | undefined,
 };

package/src/errors/argument-error.ts

@@ -1,29 +1,29 @@
-// Why we use the yaml library:
-// To represent nested object structures in a readable format.
-// Tree structure is more clearly visible than JSON.stringify.
+// yaml 라이브러리를 사용하는 이유:
+// 중첩된 객체 구조를 읽기 쉬운 형식으로 표현하기 위함.
+// JSON.stringify보다 트리 구조가 더 명확하게 보임.
 import YAML from "yaml";
 import { SdError } from "./sd-error";
 
 /**
- * Argument error
+ * 인자 오류
  *
- * An error thrown when invalid arguments are received.
- * Includes the argument object in YAML format in the message to facilitate debugging.
+ * 유효하지 않은 인자를 전달받았을 때 발생하는 에러.
+ * 디버깅을 용이하게 하기 위해 인자 객체를 YAML 형식으로 메시지에 포함한다.
  *
  * @example
- * // Passing only the argument object
+ * // 인자 객체만 전달
  * throw new ArgumentError({ userId: 123, name: null });
- * // Result message: "Invalid arguments.\n\nuserId: 123\nname: null"
+ * // 결과 메시지: "잘못된 인자입니다.\n\nuserId: 123\nname: null"
  *
  * @example
- * // Passing a custom message and argument object
- * throw new ArgumentError("Invalid user", { userId: 123 });
- * // Result message: "Invalid user\n\nuserId: 123"
+ * // 커스텀 메시지와 인자 객체를 전달
+ * throw new ArgumentError("잘못된 사용자", { userId: 123 });
+ * // 결과 메시지: "잘못된 사용자\n\nuserId: 123"
  */
 export class ArgumentError extends SdError {
-  /** Output argument object in YAML format with default message ("Invalid arguments.") */
+  /** 기본 메시지("잘못된 인자입니다.")와 함께 인자 객체를 YAML 형식으로 출력 */
   constructor(argObj: Record<string, unknown>);
-  /** Output argument object in YAML format with a custom message */
+  /** 커스텀 메시지와 함께 인자 객체를 YAML 형식으로 출력 */
   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 ?? "Invalid arguments.") + "\n\n" + YAML.stringify(argObj));
+      super((message ?? "잘못된 인자입니다.") + "\n\n" + YAML.stringify(argObj));
     } else {
-      super(message ?? "Invalid arguments.");
+      super(message ?? "잘못된 인자입니다.");
     }
     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("Implementation required in subclass");
+ *     throw new NotImplementedError("서브클래스에서 구현 필요");
  *   }
  * }
  *
  * @example
- * // Branch planned for future implementation
+ * // 향후 구현 예정인 분기
  * switch (type) {
  *   case "A": return handleA();
- *   case "B": throw new NotImplementedError(`Handling for type ${type}`);
+ *   case "B": throw new NotImplementedError(`타입 ${type} 처리`);
  * }
  */
 export class NotImplementedError extends SdError {
   /**
-   * @param message Additional description message
+   * @param message 추가 설명 메시지
    */
   constructor(message?: string) {
-    super("Not implemented" + (message != null ? ": " + message : ""));
+    super("미구현" + (message != null ? ": " + message : ""));
     this.name = "NotImplementedError";
   }
 }

package/src/errors/sd-error.ts

@@ -1,27 +1,27 @@
 /**
- * Error class supporting Tree structure composition
- * Utilizes ES2024 cause property
+ * 트리 구조 조합을 지원하는 에러 클래스
+ * ES2024 cause 속성을 활용
  *
  * @example
- * // Wrap a cause error
+ * // 원인 에러를 감싸기
  * try {
  *   await fetch(url);
  * } catch (err) {
- *   throw new SdError(err, "API call failed", "User load failed");
+ *   throw new SdError(err, "API 호출 실패", "사용자 로드 실패");
  * }
- * // Result message: "User load failed => API call failed => original error message"
+ * // 결과 메시지: "사용자 로드 실패 => API 호출 실패 => 원본 에러 메시지"
  *
  * @example
- * // Create with message only
- * throw new SdError("invalid state", "processing not possible");
- * // Result message: "processing not possible => invalid state"
+ * // 메시지만으로 생성
+ * throw new SdError("잘못된 상태", "처리 불가");
+ * // 결과 메시지: "처리 불가 => 잘못된 상태"
  */
 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";
 
-    // captureStackTrace available only on V8 engine (Node.js, Chrome)
+    // captureStackTrace는 V8 엔진(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 {
       );
     }
 
-    // Add cause chain stack to current stack
+    // 원인 체인 stack을 현재 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
+ * 타임아웃 오류
  *
- * 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().
+ * 대기 시간이 초과되었을 때 발생하는 에러.
+ * Wait.until() 같은 비동기 대기 함수에서 최대 시도 횟수를 초과하면 자동으로 발생한다.
  *
  * @example
- * // Automatically thrown from Wait.until
+ * // Wait.until에서 자동 발생
  * try {
- *   await Wait.until(() => isReady, 100, 50); // 100ms interval, max 50 attempts
+ *   await Wait.until(() => isReady, 100, 50); // 100ms 간격, 최대 50회 시도
  * } catch (err) {
  *   if (err instanceof TimeoutError) {
- *     console.log("Timeout exceeded");
+ *     console.log("타임아웃 초과");
  *   }
  * }
  *
  * @example
- * // Thrown directly
+ * // 직접 발생
  * if (elapsed > maxTime) {
- *   throw new TimeoutError(undefined, "Waiting for API response exceeded");
+ *   throw new TimeoutError(undefined, "API 응답 대기 초과");
  * }
  */
 export class TimeoutError extends SdError {
   /**
-   * @param count Number of attempts
-   * @param message Additional message
+   * @param count 시도 횟수
+   * @param message 추가 메시지
    */
   constructor(count?: number, message?: string) {
     super(
-      "Waiting time exceeded" +
-        (count != null ? `(${count} attempts)` : "") +
+      "대기 시간 초과" +
+        (count != null ? `(${count}회 시도)` : "") +
         (message != null ? `: ${message}` : ""),
     );
     this.name = "TimeoutError";

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

@@ -1,5 +1,5 @@
 /**
- * Array extension helper functions
+ * Array 확장 헬퍼 함수
  */
 
 import { DateTime } from "../types/date-time";
@@ -10,7 +10,7 @@ import { equal } from "../utils/obj";
 import type { ComparableType } from "./arr-ext.types";
 
 /**
- * Convert DateTime, DateOnly, Time to comparable primitive values
+ * DateTime, DateOnly, Time을 비교 가능한 원시 값으로 변환
  */
 export function toComparable(value: ComparableType): string | number | boolean | undefined {
   if (value instanceof DateOnly || value instanceof DateTime || value instanceof Time) {
@@ -20,13 +20,13 @@ export function toComparable(value: ComparableType): string | number | boolean |
 }
 
 /**
- * Comparison function for sorting
+ * 정렬용 비교 함수
  *
- * @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
+ * @param pp 비교 대상 1
+ * @param pn 비교 대상 2
+ * @param desc true: 내림차순, false: 오름차순
+ * @returns 음수: pp가 앞, 0: 같음, 양수: pn이 앞
+ * @note null/undefined 값은 오름차순에서 앞, 내림차순에서 뒤로 정렬됨
  */
 export function compareForOrder(pp: ComparableType, pn: ComparableType, desc: boolean): number {
   const cpp = toComparable(pp);
@@ -46,19 +46,19 @@ 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 comes last in ascending, first in descending
+    // true > false: 오름차순에서 true가 뒤, 내림차순에서 true가 앞
     return cpn ? (desc ? 1 : -1) : desc ? -1 : 1;
   }
 
-  throw new ArgumentError("Cannot use orderBy with this type.", {
+  throw new ArgumentError("이 타입으로는 orderBy를 사용할 수 없습니다.", {
     type1: typeof cpp,
     type2: typeof cpn,
   });
 }
 
 /**
- * Returns a Set of indices to KEEP (i.e., first occurrence of each unique item).
- * Handles all deduplication strategies: matchAddress, keyFn, and default type-based.
+ * 유지할 index의 Set을 반환 (즉, 각 고유 항목의 첫 번째 등장 위치).
+ * matchAddress, keyFn, 기본 타입 기반 등 모든 중복 제거 전략을 처리한다.
  */
 export function getDistinctIndices<TItem>(
   items: readonly TItem[],
@@ -67,7 +67,7 @@ export function getDistinctIndices<TItem>(
   const opts = typeof options === "boolean" ? { matchAddress: options } : (options ?? {});
   const result = new Set<number>();
 
-  // matchAddress: Set-based O(n)
+  // matchAddress: Set 기반 O(n)
   if (opts.matchAddress === true) {
     const seen = new Set<TItem>();
     for (let i = 0; i < items.length; i++) {
@@ -79,7 +79,7 @@ export function getDistinctIndices<TItem>(
     return result;
   }
 
-  // keyFn provided: custom key-based O(n)
+  // keyFn 제공됨: 커스텀 key 기반 O(n)
   if (opts.keyFn) {
     const seen = new Set<string | number>();
     for (let i = 0; i < items.length; i++) {
@@ -92,7 +92,7 @@ export function getDistinctIndices<TItem>(
     return result;
   }
 
-  // Default: type-based processing with edge cases
+  // 기본: 엣지 케이스를 포함한 타입 기반 처리
   const seen = new Map<string, TItem>();
   const seenRefs = new Set<symbol | ((...args: unknown[]) => unknown)>();
 
@@ -125,7 +125,7 @@ export function getDistinctIndices<TItem>(
       continue;
     }
 
-    // Objects: deep comparison (O(n²) — only add if no duplicate found in already-kept items)
+    // 객체: 깊은 비교 (O(n²) — 이미 유지된 항목에서 중복이 없을 때만 추가)
     let hasDuplicate = false;
     for (const keptIdx of result) {
       if (equal(items[keptIdx], item)) {