@simplysm/core-common 13.0.100 → 14.0.4

package/docs/types.md

@@ -1,179 +1,56 @@
 # Types
 
-Data types and common type definitions.
-
-Source: `src/types/*.ts`, `src/common.types.ts`, `src/env.ts`
-
----
+Immutable value types for UUID, date/time, and a self-expiring map.
 
 ## `Uuid`
 
-UUID v4 class. Generates cryptographically secure UUIDs based on `crypto.getRandomValues` (Chrome 79+, Node.js compatible).
+UUID v4 class. Uses `crypto.getRandomValues` for cryptographically secure generation.
 
 ```typescript
-export class Uuid {
-  /** Create new UUID v4 instance */
+class Uuid {
   static generate(): Uuid;
-
-  /**
-   * Create UUID from 16-byte Uint8Array
-   * @throws {ArgumentError} If byte size is not 16
-   */
   static fromBytes(bytes: Bytes): Uuid;
 
-  /**
-   * @param uuid UUID string (format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)
-   * @throws {ArgumentError} If format is invalid
-   */
   constructor(uuid: string);
 
-  /** Convert UUID to string */
   toString(): string;
-
-  /** Convert UUID to 16-byte Uint8Array */
   toBytes(): Bytes;
 }
 ```
 
----
+### Static Methods
 
-## `DateTime`
+| 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 |
 
-Immutable date+time class wrapping JavaScript `Date`. Supports millisecond precision and operates based on local timezone.
+### Constructor
 
-```typescript
-export class DateTime {
-  readonly date: Date;
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `uuid` | `string` | UUID string in format `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`. Throws `ArgumentError` if invalid |
 
-  /** Create with current time */
-  constructor();
-  /** Create with year, month, day, hour, minute, second, millisecond */
-  constructor(year: number, month: number, day: number, hour?: number, minute?: number, second?: number, millisecond?: number);
-  /** Create from tick (millisecond) */
-  constructor(tick: number);
-  /** Create from Date object */
-  constructor(date: Date);
-
-  /**
-   * Parse a string to create DateTime instance
-   * Supported formats: 'yyyy-MM-dd HH:mm:ss', 'yyyy-MM-dd HH:mm:ss.fff', 'yyyyMMddHHmmss',
-   *   'yyyy-MM-dd AM/PM HH:mm:ss', Korean AM/PM (오전/오후), ISO 8601
-   * @throws ArgumentError If unsupported format
-   */
-  static parse(str: string): DateTime;
-}
-```
+### Instance Methods
 
-**Getters** (read-only): `year`, `month`, `day`, `hour`, `minute`, `second`, `millisecond`, `tick`, `dayOfWeek` (0=Sunday), `timezoneOffsetMinutes`, `isValid`
-
-**Immutable setters** (return new instance): `setYear(year)`, `setMonth(month)`, `setDay(day)`, `setHour(hour)`, `setMinute(minute)`, `setSecond(second)`, `setMillisecond(millisecond)`
-
-**Arithmetic** (return new instance): `addYears(n)`, `addMonths(n)`, `addDays(n)`, `addHours(n)`, `addMinutes(n)`, `addSeconds(n)`, `addMilliseconds(n)`
-
-**Formatting**: `toFormatString(formatStr)`, `toString()` (default: `"yyyy-MM-ddTHH:mm:ss.fffzzz"`)
-
----
-
-## `DateOnly`
-
-Immutable date class (without time: `yyyy-MM-dd`). Operates based on local timezone.
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `toString()` | `string` | Returns the UUID string representation |
+| `toBytes()` | `Bytes` | Converts to a 16-byte `Uint8Array` |
 
 ```typescript
-export class DateOnly {
-  readonly date: Date;
-
-  /** Current date */
-  constructor();
-  /** Initialize with year, month, day */
-  constructor(year: number, month: number, day: number);
-  /** Create from tick (millisecond) */
-  constructor(tick: number);
-  /** Create from Date type */
-  constructor(date: Date);
-
-  /**
-   * Parse a string into DateOnly
-   * Supported formats: 'yyyy-MM-dd', 'yyyyMMdd', ISO 8601
-   */
-  static parse(str: string): DateOnly;
-
-  /**
-   * Get the start date of a week based on week information
-   */
-  static getDateByYearWeekSeq(
-    arg: { year: number; month?: number; weekSeq: number },
-    weekStartDay?: number,
-    minDaysInFirstWeek?: number,
-  ): DateOnly;
-}
-```
-
-**Getters** (read-only): `year`, `month`, `day`, `tick`, `dayOfWeek`, `isValid`
-
-**Immutable setters**: `setYear(year)`, `setMonth(month)`, `setDay(day)`
-
-**Arithmetic**: `addYears(n)`, `addMonths(n)`, `addDays(n)`
-
-**Week calculation methods**:
-
-```typescript
-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 };
-```
-
-Defaults: `weekStartDay = 1` (Monday), `minDaysInFirstWeek = 4` (ISO 8601 standard).
-
-**Formatting**: `toFormatString(formatStr)`, `toString()` (default: `"yyyy-MM-dd"`)
-
----
-
-## `Time`
-
-Immutable time class (without date: `HH:mm:ss.fff`). Values exceeding 24 hours or negative values are automatically normalized (24-hour wraparound).
-
-```typescript
-export class Time {
-  /** Create with current time */
-  constructor();
-  /** Create with hour, minute, second, millisecond */
-  constructor(hour: number, minute: number, second?: number, millisecond?: number);
-  /** Create from tick (millisecond) */
-  constructor(tick: number);
-  /** Create by extracting time part only from Date object */
-  constructor(date: Date);
-
-  /**
-   * Parse a string to create Time instance
-   * Supported formats: 'HH:mm:ss', 'HH:mm:ss.fff', 'AM/PM HH:mm:ss', ISO 8601 (extract time part)
-   * @throws ArgumentError If unsupported format
-   */
-  static parse(str: string): Time;
-}
+const id = Uuid.generate();
+const fromStr = new Uuid("550e8400-e29b-41d4-a716-446655440000");
+const bytes = id.toBytes();       // Uint8Array(16)
+const restored = Uuid.fromBytes(bytes);
 ```
 
-**Getters**: `hour`, `minute`, `second`, `millisecond`, `tick`, `isValid`
-
-**Immutable setters**: `setHour(hour)`, `setMinute(minute)`, `setSecond(second)`, `setMillisecond(millisecond)`
-
-**Arithmetic** (24-hour wraparound): `addHours(n)`, `addMinutes(n)`, `addSeconds(n)`, `addMilliseconds(n)`
-
-**Formatting**: `toFormatString(formatStr)`, `toString()` (default: `"HH:mm:ss.fff"`)
-
----
-
-## `LazyGcMap`
+## `LazyGcMap<TKey, TValue>`
 
-Map with automatic expiration feature. Updates access time in LRU manner; auto-deletes if not accessed for specified time. Supports the `using` statement (`Symbol.dispose`).
+A Map with automatic expiration. Entries not accessed within `expireTime` are garbage collected. Supports `using` syntax (Symbol.dispose).
 
 ```typescript
-export class LazyGcMap<TKey, TValue> {
-  /**
-   * @param options.gcInterval GC interval in ms. Default: 1/10 of expireTime (minimum 1000ms)
-   * @param options.expireTime Expiration time in ms since last access
-   * @param options.onExpire Callback called on expiration (can be async)
-   */
+class LazyGcMap<TKey, TValue> {
   constructor(options: {
     gcInterval?: number;
     expireTime: number;
@@ -185,103 +62,246 @@ export class LazyGcMap<TKey, TValue> {
   get(key: TKey): TValue | undefined;
   set(key: TKey, value: TValue): void;
   delete(key: TKey): boolean;
-  clear(): void;
   getOrCreate(key: TKey, factory: () => TValue): TValue;
+  clear(): void;
+  dispose(): void;
+  [Symbol.dispose](): void;
+
   values(): IterableIterator<TValue>;
   keys(): IterableIterator<TKey>;
   entries(): IterableIterator<[TKey, TValue]>;
-  dispose(): void;
-  [Symbol.dispose](): void;
 }
 ```
 
-**Example:**
+### Constructor Options
 
-```typescript
-using map = new LazyGcMap({ gcInterval: 10000, expireTime: 60000 });
-map.set("session", data);
-const val = map.getOrCreate("key", () => computeExpensive());
-```
+| 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
 
-## `Bytes`
+| 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 |
 
-Binary type alias used instead of `Buffer`.
+**Important:** Always call `dispose()` or use `using` to prevent memory leaks from the GC timer.
 
 ```typescript
-export type Bytes = Uint8Array;
-```
+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
+```
 
-## `PrimitiveTypeMap`
+## `DateTime`
 
-Primitive type mapping shared with orm-common.
+Immutable date-time class wrapping JavaScript `Date`. Millisecond precision, local timezone.
 
 ```typescript
-export type PrimitiveTypeMap = {
-  string: string;
-  number: number;
-  boolean: boolean;
-  DateTime: DateTime;
-  DateOnly: DateOnly;
-  Time: Time;
-  Uuid: Uuid;
-  Bytes: Bytes;
-};
+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
 
-## `PrimitiveTypeStr`
+| 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
-export type PrimitiveTypeStr = keyof PrimitiveTypeMap;
+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`
 
-## `PrimitiveType`
+Immutable date class (no time component). Local timezone.
 
 ```typescript
-export type PrimitiveType = PrimitiveTypeMap[PrimitiveTypeStr] | undefined;
+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) |
 
-## `DeepPartial<T>`
+### Week Calculation Parameters
 
-Recursively makes all properties of an object optional. Primitive types are kept as-is.
+| 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
-export type DeepPartial<TObject> = Partial<{
-  [K in keyof TObject]: TObject[K] extends PrimitiveType ? TObject[K] : DeepPartial<TObject[K]>;
-}>;
+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
 ```
 
----
-
-## `Type<T>`
+## `Time`
 
-Constructor type used for dependency injection, factory patterns, and `instanceof` checks.
+Immutable time class (no date component). Values automatically wrap within 24 hours.
 
 ```typescript
-export interface Type<TInstance> extends Function {
-  new (...args: unknown[]): TInstance;
+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"
 }
 ```
 
----
-
-## `env`
+### `Time.parse` Supported Formats
 
-Unified environment variable accessor. Merges `import.meta.env` and `process.env`. `DEV` is parsed as boolean, `VER` as optional string.
+| 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
-export const env: {
-  DEV: boolean;
-  VER?: string;
-  [key: string]: unknown;
-};
+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"
 ```