@simplysm/core-common 13.0.96 → 13.0.98

package/README.md

@@ -1,113 +1,160 @@
 # @simplysm/core-common
 
-Simplysm 프레임워크의 기반 유틸리티 패키지. 플랫폼 중립적인 타입, 유틸리티 함수, 에러 클래스, 확장 메서드를 제공한다.
+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
 
-- `@zip.js/zip.js` -- ZIP 파일 처리
-- `consola` -- 로깅
-- `fast-xml-parser` -- XML 파싱/직렬화
-- `yaml` -- YAML 직렬화 (ArgumentError 메시지용)
+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
 
-| 카테고리 | 설명 |
-|---------|------|
-| [타입](docs/types.md) | DateTime, DateOnly, Time, Uuid, LazyGcMap 등 불변 타입 |
-| [유틸리티](docs/utilities.md) | obj, str, num, bytes, json, xml, zip 등 네임스페이스 유틸리티 |
-| [기능](docs/features.md) | EventEmitter, DebounceQueue, SerialQueue, 에러 클래스, 확장 메서드, env |
+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
 
-```typescript
-import { DateTime, DateOnly, Time } from "@simplysm/core-common";
+| 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 |
 
-const now = new DateTime();
-const tomorrow = now.addDays(1);
-const formatted = now.toFormatString("yyyy-MM-dd HH:mm:ss");
+-> See [docs/errors.md](./docs/errors.md) for details.
 
-const today = new DateOnly();
-const weekInfo = today.getWeekSeqOfYear(); // { year, weekSeq }
+### Types
 
-const time = Time.parse("14:30:00");
-const later = time.addHours(2); // 24시간 래핑
-```
+| 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.
 
-```typescript
-import { obj, str, json, bytes } from "@simplysm/core-common";
+### Features
 
-// 객체 딥 클론/비교/병합
-const cloned = obj.clone(source);
-const isEqual = obj.equal(a, b);
-const merged = obj.merge(source, target);
+| 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 |
 
-// 문자열 변환
-str.toPascalCase("hello-world"); // "HelloWorld"
-str.toKebabCase("HelloWorld");   // "hello-world"
+-> See [docs/features.md](./docs/features.md) for details.
 
-// JSON (커스텀 타입 지원)
-const serialized = json.stringify({ date: new DateTime() });
-const parsed = json.parse<{ date: DateTime }>(serialized);
+### Prototype Extensions (side-effect)
 
-// 바이너리
-const hex = bytes.toHex(data);
-const b64 = bytes.toBase64(data);
-```
+| 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 { EventEmitter } from "@simplysm/core-common";
+import { DateTime, DateOnly } from "@simplysm/core-common";
 
-const emitter = new EventEmitter<{ change: string; error: Error }>();
-emitter.on("change", (data) => { /* ... */ });
-emitter.emit("change", "updated");
+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 "@simplysm/core-common"; // side-effect import
-
-const items = [1, 2, 3, 4, 5];
-items.first();                    // 1
-items.last();                     // 5
-items.distinct();                 // 중복 제거
-items.orderBy((x) => x);         // 정렬
-items.groupBy((x) => x % 2);     // 그룹화
-items.sum();                      // 15
+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
 ```
 
-### ZIP 처리
+### Array extensions
 
 ```typescript
-import { ZipArchive } from "@simplysm/core-common";
+import "@simplysm/core-common";
 
-await using zip = new ZipArchive(data);
-const content = await zip.get("file.txt");
-zip.write("new-file.txt", bytes);
-const compressed = await zip.compress();
+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 { SdError, ArgumentError, TimeoutError } from "@simplysm/core-common";
+import { EventEmitter } from "@simplysm/core-common";
 
-// 에러 체인 (=> 구분자로 조인)
-throw new SdError(originalError, "추가 컨텍스트");
-// 메시지: "추가 컨텍스트 => 원본 에러 메시지"
+interface MyEvents { data: string; done: void }
 
-// 인자 에러 (YAML 형식)
-throw new ArgumentError({ userId: -1, name: "" });
+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/dist/env.d.ts

@@ -1,3 +1,8 @@
+declare global {
+    interface ImportMeta {
+        env?: Record<string, unknown>;
+    }
+}
 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,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,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"}

package/dist/env.js

@@ -1,7 +1,10 @@
+const _metaEnv = import.meta.env ?? {};
+const _processEnv = typeof process !== "undefined" ? process.env : {};
+const _raw = { ..._metaEnv, ..._processEnv };
 const env = {
-  ...process.env,
-  DEV: JSON.parse(process.env.DEV != null && process.env.DEV !== "" ? process.env.DEV : "false"),
-  VER: process.env.VER
+  ..._raw,
+  DEV: JSON.parse(String(_raw["DEV"] != null && String(_raw["DEV"]) !== "" ? _raw["DEV"] : false)),
+  VER: _raw["VER"]
 };
 export {
   env

package/dist/env.js.map

@@ -1,6 +1,6 @@
 {
   "version": 3,
   "sources": ["../src/env.ts"],
-  "mappings": "AAEO,MAAM,MAIT;AAAA,EACF,GAAG,QAAQ;AAAA,EACX,KAAK,KAAK,MAAM,QAAQ,IAAI,OAAO,QAAQ,QAAQ,IAAI,QAAQ,KAAK,QAAQ,IAAI,MAAM,OAAO;AAAA,EAC7F,KAAK,QAAQ,IAAI;AACnB;",
+  "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": []
 }

package/docs/errors.md

@@ -0,0 +1,119 @@
+# 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)"
+  }
+}
+```