@simplysm/core-common 13.0.100 → 14.0.4

package/README.md

@@ -1,8 +1,6 @@
 # @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.
+Platform-neutral utility library for the Simplysm framework. Provides type-safe primitives, collection extensions, error hierarchy, async utilities, and serialization helpers that work in both browser and Node.js environments.
 
 ## Installation
 
@@ -10,26 +8,41 @@ Provides error classes, immutable date/time types, prototype extensions, event h
 npm install @simplysm/core-common
 ```
 
-## Side-Effect Imports
+## API Overview
 
-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`:
+### Environment
 
-- `extensions/arr-ext` -- Array prototype extensions
-- `extensions/map-ext` -- Map prototype extensions
-- `extensions/set-ext` -- Set prototype extensions
+| API | Type | Description |
+|-----|------|-------------|
+| `env` | `object` | Unified environment variables from `import.meta.env` and `process.env` |
+| `parseBoolEnv` | `function` | Parse a value to boolean (`"true"`, `"1"`, `"yes"`, `"on"` -> `true`) |
 
-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.
+-> See [docs/env.md](./docs/env.md) for details.
 
-## API Overview
+### Array / Set / Map Extensions
+
+| API | Type | Description |
+|-----|------|-------------|
+| `Array.prototype.*` | extension | 30+ methods: `single`, `first`, `last`, `groupBy`, `toMap`, `distinct`, `orderBy`, `diffs`, `sum`, `min`, `max`, etc. |
+| `Set.prototype.adds` | extension | Add multiple values at once |
+| `Set.prototype.toggle` | extension | Toggle a value (add if absent, remove if present) |
+| `Map.prototype.getOrCreate` | extension | Get value or create with default/factory |
+| `Map.prototype.update` | extension | Update a value using a function |
+| `ArrayDiffsResult` | type | Result type for `diffs()` |
+| `ArrayOneWayDiffResult` | type | Result type for `oneWayDiffs()` |
+| `TreeArray` | type | Tree node type for `toTree()` |
+| `ComparableType` | type | Union of types usable in ordering |
+
+-> See [docs/array-extensions.md](./docs/array-extensions.md) for details.
 
 ### Errors
 
 | API | Type | Description |
 |-----|------|-------------|
-| `SdError` | class | Error with tree-structured cause chaining |
+| `SdError` | class | Tree-structured error with cause chaining |
 | `ArgumentError` | class | Invalid argument error with YAML-formatted details |
 | `NotImplementedError` | class | Unimplemented feature error |
-| `TimeoutError` | class | Waiting time exceeded error |
+| `TimeoutError` | class | Timeout exceeded error |
 
 -> See [docs/errors.md](./docs/errors.md) for details.
 
@@ -38,17 +51,10 @@ If you import only specific modules (e.g., `@simplysm/core-common/dist/types/dat
 | 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 |
+| `LazyGcMap` | class | Auto-expiring Map with LRU-style GC |
+| `DateTime` | class | Immutable date-time wrapper with millisecond precision |
+| `DateOnly` | class | Immutable date-only wrapper (no time component) |
+| `Time` | class | Immutable time-only wrapper (no date component, 24h cyclic) |
 
 -> See [docs/types.md](./docs/types.md) for details.
 
@@ -56,105 +62,93 @@ If you import only specific modules (e.g., `@simplysm/core-common/dist/types/dat
 
 | 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 |
+| `DebounceQueue` | class | Async debounce queue -- only executes the last enqueued function |
+| `SerialQueue` | class | Async serial queue -- executes functions one at a time in order |
+| `EventEmitter` | class | Type-safe event emitter built on EventTarget |
 
 -> See [docs/features.md](./docs/features.md) for details.
 
-### Prototype Extensions (side-effect)
+### Utils (Namespace Exports)
 
 | API | Type | Description |
 |-----|------|-------------|
-| `Array` extensions | prototype | 34 methods -- query, transform, diff, sort, mutate |
-| `Map` extensions | prototype | `getOrCreate`, `update` |
-| `Set` extensions | prototype | `adds`, `toggle` |
+| `obj` | namespace | Deep clone, deep equal, deep merge, 3-way merge, omit, pick, chain access, type-safe keys/entries |
+| `str` | namespace | Korean suffix, full-width conversion, case transforms, `isNullOrEmpty`, `insert` |
+| `num` | namespace | parseInt, parseFloat, parseRoundedInt, isNullOrEmpty, format |
+| `bytes` | namespace | Uint8Array concat, hex, base64 conversions |
+| `path` | namespace | POSIX-style path join, basename, extname (browser-safe) |
+| `json` | namespace | JSON stringify/parse with custom type support (DateTime, Uuid, Map, Set, etc.) |
+| `xml` | namespace | XML parse/stringify via fast-xml-parser |
+| `wait` | namespace | `until` (poll condition) and `time` (delay) |
+| `transfer` | namespace | Worker-transferable encode/decode for custom types |
+| `err` | namespace | Extract error message from unknown |
+| `dt` | namespace | Date/time format strings (C#-style patterns) |
+| `primitive` | namespace | Runtime primitive type string detection |
+| `js`, `ts`, `html`, `tsql`, `mysql`, `pgsql` | template tag | IDE syntax highlighting template tags with indent normalization |
+| `ZipArchive` | class | ZIP read/write/compress/extract |
 
--> See [docs/extensions.md](./docs/extensions.md) for details.
+-> See [docs/utils.md](./docs/utils.md) for details.
 
-### Utilities
+### Type 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 |
+| `Bytes` | type alias | `Uint8Array` (replaces `Buffer`) |
+| `PrimitiveTypeMap` | type | Maps type-string keys to their TypeScript types |
+| `PrimitiveTypeStr` | type | `"string" \| "number" \| "boolean" \| "DateTime" \| "DateOnly" \| "Time" \| "Uuid" \| "Bytes"` |
+| `PrimitiveType` | type | Union of all primitive type values |
+| `DeepPartial<T>` | type | Recursively makes all properties optional |
+| `Type<T>` | interface | Constructor type (`new (...args) => T`) |
 
--> See [docs/utils.md](./docs/utils.md) for details.
+-> See [docs/type-utilities.md](./docs/type-utilities.md) for details.
 
-## Quick Usage Examples
+## Usage Examples
 
-### DateTime (immutable date/time)
+### Deep cloning and comparing objects
 
 ```typescript
-import { DateTime, DateOnly } from "@simplysm/core-common";
+import { obj } 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 original = { a: 1, b: { c: [2, 3] } };
+const cloned = obj.clone(original);
+obj.equal(original, cloned); // true
 
-const today = new DateOnly();
-const weekInfo = today.getWeekSeqOfYear(); // { year, weekSeq }
+const merged = obj.merge(original, { b: { d: 4 } });
+// { a: 1, b: { c: [2, 3], d: 4 } }
 ```
 
-### Object utilities
+### Using Array extensions
 
 ```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
-```
+import "@simplysm/core-common";
 
-### Array extensions
+const users = [
+  { id: 1, role: "admin", name: "Alice" },
+  { id: 2, role: "user", name: "Bob" },
+  { id: 3, role: "user", name: "Carol" },
+];
 
-```typescript
-import "@simplysm/core-common";
+const grouped = users.groupBy((u) => u.role);
+// [{ key: "admin", values: [Alice] }, { key: "user", values: [Bob, Carol] }]
 
-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 userMap = users.toMap((u) => u.id);
+// Map { 1 => Alice, 2 => Bob, 3 => Carol }
 
-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" }
+const sorted = users.orderBy((u) => u.name);
 ```
 
-### EventEmitter
+### JSON serialization with custom types
 
 ```typescript
-import { EventEmitter } from "@simplysm/core-common";
+import { json, DateTime, Uuid } from "@simplysm/core-common";
 
-interface MyEvents { data: string; done: void }
+const data = {
+  id: Uuid.generate(),
+  createdAt: new DateTime(2025, 6, 15, 10, 30, 0),
+  tags: new Set(["a", "b"]),
+};
 
-class MyService extends EventEmitter<MyEvents> {}
-
-const svc = new MyService();
-svc.on("data", (msg) => console.log(msg));
-svc.emit("data", "hello");
-svc.emit("done");
+const serialized = json.stringify(data);
+const restored = json.parse(serialized);
+// restored.id is Uuid, restored.createdAt is DateTime, restored.tags is Set
 ```
-
-## License
-
-Apache-2.0

package/dist/common.types.d.ts

@@ -3,12 +3,12 @@ import { DateOnly } from "./types/date-only";
 import { Time } from "./types/time";
 import { Uuid } from "./types/uuid";
 /**
- * Binary type used instead of Buffer
+ * Buffer 대신 사용하는 바이너리 타입
  */
 export type Bytes = Uint8Array;
 /**
- * Primitive type mapping
- * Shared with orm-common
+ * 원시 타입 매핑
+ * orm-common과 공유
  */
 export type PrimitiveTypeMap = {
     string: string;
@@ -21,19 +21,19 @@ export type PrimitiveTypeMap = {
     Bytes: Bytes;
 };
 /**
- * Primitive type string key
+ * 원시 타입 문자열 key
  */
 export type PrimitiveTypeStr = keyof PrimitiveTypeMap;
 /**
- * Primitive type union
+ * 원시 타입 union
  */
 export type PrimitiveType = PrimitiveTypeMap[PrimitiveTypeStr] | undefined;
 /**
- * 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
@@ -45,7 +45,7 @@ export type PrimitiveType = PrimitiveTypeMap[PrimitiveTypeStr] | undefined;
  *   };
  * }
  *
- * // All properties at every depth become optional
+ * // 모든 깊이의 속성이 optional이 됨
  * const partial: DeepPartial<User> = {
  *   profile: { address: {} }
  * };
@@ -55,10 +55,10 @@ export type DeepPartial<TObject> = Partial<{
     [K in keyof TObject]: TObject[K] extends PrimitiveType ? TObject[K] : DeepPartial<TObject[K]>;
 }>;
 /**
- * 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 {
@@ -66,7 +66,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/dist/common.types.js

@@ -2,4 +2,5 @@ import { DateTime } from "./types/date-time.js";
 import { DateOnly } from "./types/date-only.js";
 import { Time } from "./types/time.js";
 import { Uuid } from "./types/uuid.js";
-//# sourceMappingURL=common.types.js.map
+//#endregion
+//# sourceMappingURL=common.types.js.map

package/dist/common.types.js.map

@@ -1,6 +1 @@
-{
-  "version": 3,
-  "sources": ["../src/common.types.ts"],
-  "mappings": "AAAA,SAAS,gBAAgB;AACzB,SAAS,gBAAgB;AACzB,SAAS,YAAY;AACrB,SAAS,YAAY;",
-  "names": []
-}
+{"version":3,"file":"common.types.js","sourceRoot":"","sources":["../src/common.types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC7C,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC7C,OAAO,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AACpC,OAAO,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAuFpC,YAAY"}

package/dist/env.d.ts

@@ -1,8 +1,15 @@
 declare global {
+    interface ImportMetaEnv extends Record<string, unknown> {
+    }
     interface ImportMeta {
-        env?: Record<string, unknown>;
+        readonly env: ImportMetaEnv;
     }
 }
+/**
+ * 환경변수 값을 boolean으로 파싱
+ * "true", "1", "yes", "on" (대소문자 무시) → true, 그 외 → false
+ */
+export declare function parseBoolEnv(value: unknown): boolean;
 export declare const env: {
     DEV: boolean;
     VER?: string;

package/dist/env.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAEA,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,UAAU;QAClB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAC/B;CACF;AAMD,eAAO,MAAM,GAAG,EAAE;IAChB,GAAG,EAAE,OAAO,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CAKxB,CAAC"}
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAEA,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,aAAc,SAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;KAAG;IAC1D,UAAU,UAAU;QAClB,QAAQ,CAAC,GAAG,EAAE,aAAa,CAAC;KAC7B;CACF;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEpD;AAMD,eAAO,MAAM,GAAG,EAAE;IAChB,GAAG,EAAE,OAAO,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CAKxB,CAAC"}

package/dist/env.js

@@ -1,12 +1,16 @@
-const _metaEnv = import.meta.env ?? {};
+/**
+ * 환경변수 값을 boolean으로 파싱
+ * "true", "1", "yes", "on" (대소문자 무시) → true, 그 외 → false
+ */
+export function parseBoolEnv(value) {
+    return ["true", "1", "yes", "on"].includes(String(value ?? "").toLowerCase());
+}
+const _metaEnv = { ...import.meta.env };
 const _processEnv = typeof process !== "undefined" ? process.env : {};
 const _raw = { ..._metaEnv, ..._processEnv };
-const env = {
-  ..._raw,
-  DEV: JSON.parse(String(_raw["DEV"] != null && String(_raw["DEV"]) !== "" ? _raw["DEV"] : false)),
-  VER: _raw["VER"]
+export const env = {
+    ..._raw,
+    DEV: parseBoolEnv(_raw["DEV"]),
+    VER: _raw["VER"],
 };
-export {
-  env
-};
-//# sourceMappingURL=env.js.map
+//# sourceMappingURL=env.js.map

package/dist/env.js.map

@@ -1,6 +1 @@
-{
-  "version": 3,
-  "sources": ["../src/env.ts"],
-  "mappings": "AAQA,MAAM,WAAoC,YAAY,OAAO,CAAC;AAC9D,MAAM,cAAuC,OAAO,YAAY,cAAc,QAAQ,MAAM,CAAC;AAC7F,MAAM,OAAgC,EAAE,GAAG,UAAU,GAAG,YAAY;AAE7D,MAAM,MAIT;AAAA,EACF,GAAG;AAAA,EACH,KAAK,KAAK,MAAM,OAAO,KAAK,KAAK,KAAK,QAAQ,OAAO,KAAK,KAAK,CAAC,MAAM,KAAK,KAAK,KAAK,IAAI,KAAK,CAAC;AAAA,EAC/F,KAAK,KAAK,KAAK;AACjB;",
-  "names": []
-}
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AASA;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,OAAO,CAAC,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;AAChF,CAAC;AAED,MAAM,QAAQ,GAA4B,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;AACjE,MAAM,WAAW,GAA4B,OAAO,OAAO,KAAK,WAAW,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;AAC/F,MAAM,IAAI,GAA4B,EAAE,GAAG,QAAQ,EAAE,GAAG,WAAW,EAAE,CAAC;AAEtE,MAAM,CAAC,MAAM,GAAG,GAIZ;IACF,GAAG,IAAI;IACP,GAAG,EAAE,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC9B,GAAG,EAAE,IAAI,CAAC,KAAK,CAAuB;CACvC,CAAC"}

package/dist/errors/argument-error.d.ts

@@ -1,24 +1,24 @@
 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 declare 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>);
 }

package/dist/errors/argument-error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"argument-error.d.ts","sourceRoot":"","sources":["../../src/errors/argument-error.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAErC;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,aAAc,SAAQ,OAAO;IACxC,wFAAwF;gBAC5E,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC3C,kEAAkE;gBACtD,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;gBAChD,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAYnF"}
+{"version":3,"file":"argument-error.d.ts","sourceRoot":"","sources":["../../src/errors/argument-error.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAErC;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,aAAc,SAAQ,OAAO;IACxC,mDAAmD;gBACvC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC3C,sCAAsC;gBAC1B,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;gBAChD,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAYnF"}

package/dist/errors/argument-error.js

@@ -1,18 +1,35 @@
+// yaml 라이브러리를 사용하는 이유:
+// 중첩된 객체 구조를 읽기 쉬운 형식으로 표현하기 위함.
+// JSON.stringify보다 트리 구조가 더 명확하게 보임.
 import YAML from "yaml";
 import { SdError } from "./sd-error.js";
-class ArgumentError extends SdError {
-  constructor(arg1, arg2) {
-    const message = typeof arg1 === "string" ? arg1 : void 0;
-    const argObj = typeof arg1 === "string" ? arg2 : arg1;
-    if (argObj != null) {
-      super((message ?? "Invalid arguments.") + "\n\n" + YAML.stringify(argObj));
-    } else {
-      super(message ?? "Invalid arguments.");
+/**
+ * 인자 오류
+ *
+ * 유효하지 않은 인자를 전달받았을 때 발생하는 에러.
+ * 디버깅을 용이하게 하기 위해 인자 객체를 YAML 형식으로 메시지에 포함한다.
+ *
+ * @example
+ * // 인자 객체만 전달
+ * throw new ArgumentError({ userId: 123, name: null });
+ * // 결과 메시지: "잘못된 인자입니다.\n\nuserId: 123\nname: null"
+ *
+ * @example
+ * // 커스텀 메시지와 인자 객체를 전달
+ * throw new ArgumentError("잘못된 사용자", { userId: 123 });
+ * // 결과 메시지: "잘못된 사용자\n\nuserId: 123"
+ */
+export class ArgumentError extends SdError {
+    constructor(arg1, arg2) {
+        const message = typeof arg1 === "string" ? arg1 : undefined;
+        const argObj = typeof arg1 === "string" ? arg2 : arg1;
+        if (argObj != null) {
+            super((message ?? "잘못된 인자입니다.") + "\n\n" + YAML.stringify(argObj));
+        }
+        else {
+            super(message ?? "잘못된 인자입니다.");
+        }
+        this.name = "ArgumentError";
     }
-    this.name = "ArgumentError";
-  }
 }
-export {
-  ArgumentError
-};
-//# sourceMappingURL=argument-error.js.map
+//# sourceMappingURL=argument-error.js.map

package/dist/errors/argument-error.js.map

@@ -1,6 +1 @@
-{
-  "version": 3,
-  "sources": ["../../src/errors/argument-error.ts"],
-  "mappings": "AAGA,OAAO,UAAU;AACjB,SAAS,eAAe;AAkBjB,MAAM,sBAAsB,QAAQ;AAAA,EAMzC,YAAY,MAAwC,MAAgC;AAClF,UAAM,UAAU,OAAO,SAAS,WAAW,OAAO;AAClD,UAAM,SAAS,OAAO,SAAS,WAAW,OAAO;AAEjD,QAAI,UAAU,MAAM;AAClB,aAAO,WAAW,wBAAwB,SAAS,KAAK,UAAU,MAAM,CAAC;AAAA,IAC3E,OAAO;AACL,YAAM,WAAW,oBAAoB;AAAA,IACvC;AACA,SAAK,OAAO;AAAA,EACd;AACF;",
-  "names": []
-}
+{"version":3,"file":"argument-error.js","sourceRoot":"","sources":["../../src/errors/argument-error.ts"],"names":[],"mappings":"AAAA,uBAAuB;AACvB,iCAAiC;AACjC,qCAAqC;AACrC,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAErC;;;;;;;;;;;;;;;GAeG;AACH,MAAM,OAAO,aAAc,SAAQ,OAAO;IAMxC,YAAY,IAAsC,EAAE,IAA8B;QAChF,MAAM,OAAO,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;QAC5D,MAAM,MAAM,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;QAEtD,IAAI,MAAM,IAAI,IAAI,EAAE,CAAC;YACnB,KAAK,CAAC,CAAC,OAAO,IAAI,YAAY,CAAC,GAAG,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC;QACrE,CAAC;aAAM,CAAC;YACN,KAAK,CAAC,OAAO,IAAI,YAAY,CAAC,CAAC;QACjC,CAAC;QACD,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAC9B,CAAC;CACF"}

package/dist/errors/not-implemented-error.d.ts

@@ -1,28 +1,28 @@
 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 declare class NotImplementedError extends SdError {
     /**
-     * @param message Additional description message
+     * @param message 추가 설명 메시지
      */
     constructor(message?: string);
 }

package/dist/errors/not-implemented-error.js

@@ -1,14 +1,32 @@
 import { SdError } from "./sd-error.js";
-class NotImplementedError extends SdError {
-  /**
-   * @param message Additional description message
-   */
-  constructor(message) {
-    super("Not implemented" + (message != null ? ": " + message : ""));
-    this.name = "NotImplementedError";
-  }
+/**
+ * 미구현 오류
+ *
+ * 아직 구현되지 않은 기능이 호출되었을 때 발생하는 에러.
+ * 추상 메서드 스텁, 향후 구현 예정인 분기 등에 사용된다.
+ *
+ * @example
+ * // 추상 메서드 구현 전
+ * class BaseService {
+ *   process(): void {
+ *     throw new NotImplementedError("서브클래스에서 구현 필요");
+ *   }
+ * }
+ *
+ * @example
+ * // 향후 구현 예정인 분기
+ * switch (type) {
+ *   case "A": return handleA();
+ *   case "B": throw new NotImplementedError(`타입 ${type} 처리`);
+ * }
+ */
+export class NotImplementedError extends SdError {
+    /**
+     * @param message 추가 설명 메시지
+     */
+    constructor(message) {
+        super("미구현" + (message != null ? ": " + message : ""));
+        this.name = "NotImplementedError";
+    }
 }
-export {
-  NotImplementedError
-};
-//# sourceMappingURL=not-implemented-error.js.map
+//# sourceMappingURL=not-implemented-error.js.map

package/dist/errors/not-implemented-error.js.map

@@ -1,6 +1 @@
-{
-  "version": 3,
-  "sources": ["../../src/errors/not-implemented-error.ts"],
-  "mappings": "AAAA,SAAS,eAAe;AAuBjB,MAAM,4BAA4B,QAAQ;AAAA;AAAA;AAAA;AAAA,EAI/C,YAAY,SAAkB;AAC5B,UAAM,qBAAqB,WAAW,OAAO,OAAO,UAAU,GAAG;AACjE,SAAK,OAAO;AAAA,EACd;AACF;",
-  "names": []
-}
+{"version":3,"file":"not-implemented-error.js","sourceRoot":"","sources":["../../src/errors/not-implemented-error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAErC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,OAAO,mBAAoB,SAAQ,OAAO;IAC9C;;OAEG;IACH,YAAY,OAAgB;QAC1B,KAAK,CAAC,KAAK,GAAG,CAAC,OAAO,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,GAAG,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACvD,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACpC,CAAC;CACF"}

package/dist/errors/sd-error.d.ts

@@ -1,26 +1,26 @@
 /**
- * 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 declare class SdError extends Error {
     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[]);
 }