@simplysm/core-common 14.0.1 → 14.0.4

package/docs/errors.md

@@ -0,0 +1,104 @@
+# Errors
+
+A hierarchy of error classes built on `SdError`, which supports tree-structured cause chaining via the ES2024 `cause` property.
+
+## `SdError`
+
+Base error class with cause-chain support. Messages are joined in reverse order with ` => `.
+
+```typescript
+class SdError extends Error {
+  cause?: Error;
+
+  constructor(cause: Error, ...messages: string[]);
+  constructor(...messages: string[]);
+}
+```
+
+| Constructor Overload | Description |
+|---------------------|-------------|
+| `new SdError(cause, ...messages)` | Wraps an existing error. Message becomes `"messages[n] => ... => messages[0] => cause.message"` |
+| `new SdError(...messages)` | Creates without cause. Message becomes `"messages[n] => ... => messages[0]"` |
+
+When a cause error is provided, its stack trace is appended under a `---- cause stack ----` separator.
+
+```typescript
+try {
+  await fetch(url);
+} catch (err) {
+  throw new SdError(err, "API call failed", "User load failed");
+  // message: "User load failed => API call failed => <original message>"
+}
+
+throw new SdError("Invalid state", "Cannot process");
+// message: "Cannot process => Invalid state"
+```
+
+## `ArgumentError`
+
+Error for invalid arguments. Extends `SdError`. Formats the argument object as YAML in the message for easy debugging.
+
+```typescript
+class ArgumentError extends SdError {
+  constructor(argObj: Record<string, unknown>);
+  constructor(message: string, argObj: Record<string, unknown>);
+}
+```
+
+| Constructor Overload | Description |
+|---------------------|-------------|
+| `new ArgumentError(argObj)` | Default message + YAML-formatted args |
+| `new ArgumentError(message, argObj)` | Custom message + YAML-formatted args |
+
+```typescript
+throw new ArgumentError({ userId: 123, name: null });
+// message: "잘못된 인자입니다.\n\nuserId: 123\nname: null"
+
+throw new ArgumentError("Invalid user", { userId: 123 });
+// message: "Invalid user\n\nuserId: 123"
+```
+
+## `NotImplementedError`
+
+Error for unimplemented features. Extends `SdError`.
+
+```typescript
+class NotImplementedError extends SdError {
+  constructor(message?: string);
+}
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `message` | `string \| undefined` | Optional description of what is not implemented |
+
+```typescript
+throw new NotImplementedError();
+// message: "미구현"
+
+throw new NotImplementedError("Subclass must override");
+// message: "미구현: Subclass must override"
+```
+
+## `TimeoutError`
+
+Error for timeout conditions. Extends `SdError`.
+
+```typescript
+class TimeoutError extends SdError {
+  constructor(count?: number, message?: string);
+}
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `count` | `number \| undefined` | Number of attempts made |
+| `message` | `string \| undefined` | Additional description |
+
+```typescript
+throw new TimeoutError(50);
+// message: "대기 시간 초과(50회 시도)"
+
+throw new TimeoutError(undefined, "API response wait exceeded");
+// message: "대기 시간 초과: API response wait exceeded"
+```

package/docs/features.md

@@ -0,0 +1,128 @@
+# Features
+
+Async queue and event emitter utilities. All support `using` syntax via `Symbol.dispose`.
+
+## `DebounceQueue`
+
+Async debounce queue. When called multiple times in rapid succession, only the last enqueued function executes after the delay. Extends `EventEmitter<{ error: SdError }>`.
+
+```typescript
+class DebounceQueue extends EventEmitter<{ error: SdError }> {
+  constructor(delay?: number);
+
+  run(fn: () => void | Promise<void>): void;
+  dispose(): void;
+  [Symbol.dispose](): void;
+}
+```
+
+### Constructor
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `delay` | `number \| undefined` | `undefined` (next event loop) | Debounce delay in milliseconds |
+
+### Methods
+
+| Method | Description |
+|--------|-------------|
+| `run(fn)` | Enqueue a function. Replaces any previously pending function. After the delay, executes the last enqueued function |
+| `dispose()` | Cancels pending timer and clears state |
+
+### Behavior
+
+- If a new `run()` call arrives while a previous function is executing, the new function runs immediately after the current one completes (no debounce delay).
+- Errors are emitted as `"error"` events if listeners exist; otherwise logged via consola.
+
+```typescript
+const queue = new DebounceQueue(300);
+queue.on("error", (err) => console.error(err));
+
+queue.run(() => console.log("1")); // cancelled
+queue.run(() => console.log("2")); // cancelled
+queue.run(() => console.log("3")); // executes after 300ms
+```
+
+## `SerialQueue`
+
+Async serial queue. Functions are executed one at a time in the order they are enqueued. Errors in one function do not prevent subsequent functions from running. Extends `EventEmitter<{ error: SdError }>`.
+
+```typescript
+class SerialQueue extends EventEmitter<{ error: SdError }> {
+  constructor(gap?: number);
+
+  run(fn: () => void | Promise<void>): void;
+  dispose(): void;
+  [Symbol.dispose](): void;
+}
+```
+
+### Constructor
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `gap` | `number` | `0` | Delay between each task execution (ms) |
+
+### Methods
+
+| Method | Description |
+|--------|-------------|
+| `run(fn)` | Add a function to the queue. Starts processing if not already running |
+| `dispose()` | Clears the pending queue. The currently running task still completes |
+
+```typescript
+const queue = new SerialQueue();
+queue.on("error", (err) => console.error(err));
+
+queue.run(async () => { await fetch("/api/1"); }); // runs first
+queue.run(async () => { await fetch("/api/2"); }); // runs after 1 completes
+queue.run(async () => { await fetch("/api/3"); }); // runs after 2 completes
+```
+
+## `EventEmitter<TEvents>`
+
+Type-safe event emitter built on the `EventTarget` API. Works in both browser and Node.js.
+
+```typescript
+class EventEmitter<TEvents extends { [K in keyof TEvents]: unknown } = Record<string, unknown>> {
+  on<K extends keyof TEvents & string>(type: K, listener: (data: TEvents[K]) => void): void;
+  off<K extends keyof TEvents & string>(type: K, listener: (data: TEvents[K]) => void): void;
+  emit<K extends keyof TEvents & string>(
+    type: K,
+    ...args: TEvents[K] extends void ? [] : [data: TEvents[K]]
+  ): void;
+  listenerCount<K extends keyof TEvents & string>(type: K): number;
+  dispose(): void;
+  [Symbol.dispose](): void;
+}
+```
+
+### Methods
+
+| Method | Description |
+|--------|-------------|
+| `on(type, listener)` | Register a listener. Duplicate registration for the same event+listener is ignored |
+| `off(type, listener)` | Remove a listener |
+| `emit(type, data?)` | Dispatch an event. For `void` event types, data argument is omitted |
+| `listenerCount(type)` | Returns the number of registered listeners for an event type |
+| `dispose()` | Removes all listeners from all event types |
+
+### Type Parameter
+
+`TEvents` is a map where keys are event names and values are event data types. Use `void` for events with no data.
+
+```typescript
+interface MyEvents {
+  data: string;
+  error: Error;
+  done: void;
+}
+
+class MyService extends EventEmitter<MyEvents> {}
+
+const svc = new MyService();
+svc.on("data", (data) => {});   // data: string
+svc.on("done", () => {});       // no argument
+svc.emit("data", "hello");
+svc.emit("done");               // no argument needed
+```

package/docs/type-utilities.md

@@ -0,0 +1,91 @@
+# Type Utilities
+
+TypeScript type aliases and interfaces exported from `common.types.ts`.
+
+## `Bytes`
+
+Type alias for `Uint8Array`. Used throughout the framework instead of `Buffer`.
+
+```typescript
+type Bytes = Uint8Array;
+```
+
+## `PrimitiveTypeMap`
+
+Maps primitive type string keys to their corresponding TypeScript types. Shared with `orm-common`.
+
+```typescript
+type PrimitiveTypeMap = {
+  string: string;
+  number: number;
+  boolean: boolean;
+  DateTime: DateTime;
+  DateOnly: DateOnly;
+  Time: Time;
+  Uuid: Uuid;
+  Bytes: Bytes;
+};
+```
+
+## `PrimitiveTypeStr`
+
+Union of all keys in `PrimitiveTypeMap`.
+
+```typescript
+type PrimitiveTypeStr = keyof PrimitiveTypeMap;
+// "string" | "number" | "boolean" | "DateTime" | "DateOnly" | "Time" | "Uuid" | "Bytes"
+```
+
+## `PrimitiveType`
+
+Union of all primitive type values (including `undefined`).
+
+```typescript
+type PrimitiveType = PrimitiveTypeMap[PrimitiveTypeStr] | undefined;
+// string | number | boolean | DateTime | DateOnly | Time | Uuid | Uint8Array | undefined
+```
+
+## `DeepPartial<TObject>`
+
+Recursively makes all properties optional. Primitive types (`PrimitiveType`) are preserved as-is; only object/array types are recursively made partial.
+
+```typescript
+type DeepPartial<TObject> = Partial<{
+  [K in keyof TObject]: TObject[K] extends PrimitiveType
+    ? TObject[K]
+    : DeepPartial<TObject[K]>;
+}>;
+```
+
+```typescript
+interface User {
+  name: string;
+  profile: {
+    age: number;
+    address: { city: string };
+  };
+}
+
+const partial: DeepPartial<User> = {
+  profile: { address: {} },
+};
+```
+
+## `Type<TInstance>`
+
+Constructor type interface. Represents a class constructor that creates instances of `TInstance`. Used for dependency injection, factory patterns, and `instanceof` checks.
+
+```typescript
+interface Type<TInstance> extends Function {
+  new (...args: unknown[]): TInstance;
+}
+```
+
+```typescript
+function create<T>(ctor: Type<T>): T {
+  return new ctor();
+}
+
+class MyClass { name = "test"; }
+const instance = create(MyClass); // MyClass instance
+```

package/docs/types.md

@@ -0,0 +1,307 @@
+# Types
+
+Immutable value types for UUID, date/time, and a self-expiring map.
+
+## `Uuid`
+
+UUID v4 class. Uses `crypto.getRandomValues` for cryptographically secure generation.
+
+```typescript
+class Uuid {
+  static generate(): Uuid;
+  static fromBytes(bytes: Bytes): Uuid;
+
+  constructor(uuid: string);
+
+  toString(): string;
+  toBytes(): Bytes;
+}
+```
+
+### Static Methods
+
+| Method | Description |
+|--------|-------------|
+| `generate()` | Creates a new random UUID v4 instance |
+| `fromBytes(bytes)` | Creates a UUID from a 16-byte `Uint8Array`. Throws `ArgumentError` if length is not 16 |
+
+### Constructor
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `uuid` | `string` | UUID string in format `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`. Throws `ArgumentError` if invalid |
+
+### Instance Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `toString()` | `string` | Returns the UUID string representation |
+| `toBytes()` | `Bytes` | Converts to a 16-byte `Uint8Array` |
+
+```typescript
+const id = Uuid.generate();
+const fromStr = new Uuid("550e8400-e29b-41d4-a716-446655440000");
+const bytes = id.toBytes();       // Uint8Array(16)
+const restored = Uuid.fromBytes(bytes);
+```
+
+## `LazyGcMap<TKey, TValue>`
+
+A Map with automatic expiration. Entries not accessed within `expireTime` are garbage collected. Supports `using` syntax (Symbol.dispose).
+
+```typescript
+class LazyGcMap<TKey, TValue> {
+  constructor(options: {
+    gcInterval?: number;
+    expireTime: number;
+    onExpire?: (key: TKey, value: TValue) => void | Promise<void>;
+  });
+
+  get size(): number;
+  has(key: TKey): boolean;
+  get(key: TKey): TValue | undefined;
+  set(key: TKey, value: TValue): void;
+  delete(key: TKey): boolean;
+  getOrCreate(key: TKey, factory: () => TValue): TValue;
+  clear(): void;
+  dispose(): void;
+  [Symbol.dispose](): void;
+
+  values(): IterableIterator<TValue>;
+  keys(): IterableIterator<TKey>;
+  entries(): IterableIterator<[TKey, TValue]>;
+}
+```
+
+### Constructor Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `gcInterval` | `number` | `expireTime / 10` (min 1000ms) | Interval between GC runs (ms) |
+| `expireTime` | `number` | required | Time since last access before entry is removed (ms) |
+| `onExpire` | `(key, value) => void \| Promise<void>` | `undefined` | Callback when an entry expires |
+
+### Methods
+
+| Method | Description |
+|--------|-------------|
+| `has(key)` | Check if key exists (does NOT refresh access time) |
+| `get(key)` | Get value and refresh access time (LRU) |
+| `set(key, value)` | Set value and start GC timer if needed |
+| `delete(key)` | Delete entry; stops GC if map becomes empty |
+| `getOrCreate(key, factory)` | Get or create value. Throws if disposed |
+| `clear()` | Remove all entries (instance remains usable) |
+| `dispose()` | Stop GC timer and clear all data. Instance becomes unusable |
+
+**Important:** Always call `dispose()` or use `using` to prevent memory leaks from the GC timer.
+
+```typescript
+using map = new LazyGcMap<string, Connection>({
+  expireTime: 60_000,
+  onExpire: async (_key, conn) => { await conn.close(); },
+});
+
+map.set("conn1", createConnection());
+const conn = map.get("conn1"); // refreshes access time
+```
+
+## `DateTime`
+
+Immutable date-time class wrapping JavaScript `Date`. Millisecond precision, local timezone.
+
+```typescript
+class DateTime {
+  readonly date: Date;
+
+  constructor();
+  constructor(year: number, month: number, day: number, hour?: number, minute?: number, second?: number, millisecond?: number);
+  constructor(tick: number);
+  constructor(date: Date);
+
+  static parse(str: string): DateTime;
+
+  // Getters
+  get year(): number;
+  get month(): number;       // 1-12
+  get day(): number;
+  get hour(): number;
+  get minute(): number;
+  get second(): number;
+  get millisecond(): number;
+  get tick(): number;
+  get dayOfWeek(): number;   // 0(Sun)-6(Sat)
+  get timezoneOffsetMinutes(): number;
+  get isValid(): boolean;
+
+  // Immutable setters (return new instance)
+  setYear(year: number): DateTime;
+  setMonth(month: number): DateTime;
+  setDay(day: number): DateTime;
+  setHour(hour: number): DateTime;
+  setMinute(minute: number): DateTime;
+  setSecond(second: number): DateTime;
+  setMillisecond(millisecond: number): DateTime;
+
+  // Arithmetic (return new instance)
+  addYears(years: number): DateTime;
+  addMonths(months: number): DateTime;
+  addDays(days: number): DateTime;
+  addHours(hours: number): DateTime;
+  addMinutes(minutes: number): DateTime;
+  addSeconds(seconds: number): DateTime;
+  addMilliseconds(milliseconds: number): DateTime;
+
+  // Formatting
+  toFormatString(formatStr: string): string;
+  toString(): string; // "yyyy-MM-ddTHH:mm:ss.fffzzz"
+}
+```
+
+### `DateTime.parse` Supported Formats
+
+| Format | Example |
+|--------|---------|
+| `yyyy-MM-dd HH:mm:ss` | `"2025-01-15 10:30:00"` |
+| `yyyy-MM-dd HH:mm:ss.fff` | `"2025-01-15 10:30:00.123"` |
+| `yyyyMMddHHmmss` | `"20250115103000"` |
+| `yyyy-MM-dd AM/PM HH:mm:ss` | `"2025-01-15 AM 10:30:00"` |
+| ISO 8601 | `"2025-01-15T10:30:00Z"` |
+| Korean AM/PM | `"2025-01-15 오전 10:30:00"` |
+
+```typescript
+const now = new DateTime();
+const d = new DateTime(2025, 1, 15, 10, 30, 0);
+const parsed = DateTime.parse("2025-01-15 10:30:00");
+const next = d.addDays(7).setHour(14);
+d.toFormatString("yyyy-MM-dd HH:mm"); // "2025-01-15 10:30"
+```
+
+## `DateOnly`
+
+Immutable date class (no time component). Local timezone.
+
+```typescript
+class DateOnly {
+  readonly date: Date;
+
+  constructor();
+  constructor(year: number, month: number, day: number);
+  constructor(tick: number);
+  constructor(date: Date);
+
+  static parse(str: string): DateOnly;
+  static getDateByYearWeekSeq(
+    arg: { year: number; month?: number; weekSeq: number },
+    weekStartDay?: number,
+    minDaysInFirstWeek?: number,
+  ): DateOnly;
+
+  // Getters
+  get year(): number;
+  get month(): number;     // 1-12
+  get day(): number;
+  get tick(): number;
+  get dayOfWeek(): number; // 0(Sun)-6(Sat)
+  get isValid(): boolean;
+
+  // Immutable setters
+  setYear(year: number): DateOnly;
+  setMonth(month: number): DateOnly;
+  setDay(day: number): DateOnly;
+
+  // Arithmetic
+  addYears(years: number): DateOnly;
+  addMonths(months: number): DateOnly;
+  addDays(days: number): DateOnly;
+
+  // Week calculations
+  getBaseYearMonthSeqForWeekSeq(weekStartDay?: number, minDaysInFirstWeek?: number): { year: number; monthSeq: number };
+  getWeekSeqStartDate(weekStartDay?: number, minDaysInFirstWeek?: number): DateOnly;
+  getWeekSeqOfYear(weekStartDay?: number, minDaysInFirstWeek?: number): { year: number; weekSeq: number };
+  getWeekSeqOfMonth(weekStartDay?: number, minDaysInFirstWeek?: number): { year: number; monthSeq: number; weekSeq: number };
+
+  // Formatting
+  toFormatString(formatStr: string): string;
+  toString(): string; // "yyyy-MM-dd"
+}
+```
+
+### `DateOnly.parse` Supported Formats
+
+| Format | Example |
+|--------|---------|
+| `yyyy-MM-dd` | `"2025-01-15"` (timezone-safe) |
+| `yyyyMMdd` | `"20250115"` (timezone-safe) |
+| ISO 8601 | `"2025-01-15T00:00:00Z"` (converted to local) |
+
+### Week Calculation Parameters
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `weekStartDay` | `1` (Monday) | Week start day: 0=Sun, 1=Mon, ..., 6=Sat |
+| `minDaysInFirstWeek` | `4` (ISO 8601) | Minimum days in the first week |
+
+```typescript
+const today = new DateOnly();
+const d = new DateOnly(2025, 1, 15);
+const parsed = DateOnly.parse("2025-01-15");
+d.getWeekSeqOfYear();       // { year: 2025, weekSeq: 3 }
+d.getWeekSeqOfMonth();      // { year: 2025, monthSeq: 1, weekSeq: 3 }
+DateOnly.getDateByYearWeekSeq({ year: 2025, weekSeq: 2 }); // 2025-01-06
+```
+
+## `Time`
+
+Immutable time class (no date component). Values automatically wrap within 24 hours.
+
+```typescript
+class Time {
+  constructor();
+  constructor(hour: number, minute: number, second?: number, millisecond?: number);
+  constructor(tick: number);
+  constructor(date: Date);
+
+  static parse(str: string): Time;
+
+  // Getters
+  get hour(): number;
+  get minute(): number;
+  get second(): number;
+  get millisecond(): number;
+  get tick(): number;
+  get isValid(): boolean;
+
+  // Immutable setters
+  setHour(hour: number): Time;
+  setMinute(minute: number): Time;
+  setSecond(second: number): Time;
+  setMillisecond(millisecond: number): Time;
+
+  // Arithmetic (wraps at 24h)
+  addHours(hours: number): Time;
+  addMinutes(minutes: number): Time;
+  addSeconds(seconds: number): Time;
+  addMilliseconds(milliseconds: number): Time;
+
+  // Formatting
+  toFormatString(formatStr: string): string;
+  toString(): string; // "HH:mm:ss.fff"
+}
+```
+
+### `Time.parse` Supported Formats
+
+| Format | Example |
+|--------|---------|
+| `HH:mm:ss` | `"10:30:00"` |
+| `HH:mm:ss.fff` | `"10:30:00.123"` |
+| `AM/PM HH:mm:ss` | `"AM 10:30:00"` |
+| ISO 8601 (time part) | `"2025-01-15T10:30:00Z"` |
+
+```typescript
+const now = new Time();
+const t = new Time(14, 30, 0);
+const parsed = Time.parse("10:30:00");
+t.addHours(12); // wraps: 02:30:00
+t.toFormatString("tt h:mm:ss"); // "PM 2:30:00"
+```