@simplysm/core-common 14.0.4 → 14.0.6

package/docs/types.md

@@ -1,10 +1,8 @@
 # Types
 
-Immutable value types for UUID, date/time, and a self-expiring map.
-
 ## `Uuid`
 
-UUID v4 class. Uses `crypto.getRandomValues` for cryptographically secure generation.
+UUID v4 class. Generates cryptographically secure UUIDs using `crypto.getRandomValues`.
 
 ```typescript
 class Uuid {
@@ -22,32 +20,27 @@ class Uuid {
 
 | 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 |
+| `generate()` | Create a new random UUID v4 instance |
+| `fromBytes(bytes)` | Create UUID from a 16-byte `Uint8Array`. Throws `ArgumentError` if length is not 16. |
 
 ### Instance Methods
 
 | Method | Returns | Description |
 |--------|---------|-------------|
-| `toString()` | `string` | Returns the UUID string representation |
-| `toBytes()` | `Bytes` | Converts to a 16-byte `Uint8Array` |
+| `toString()` | `string` | UUID string in `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` format |
+| `toBytes()` | `Bytes` | 16-byte `Uint8Array` representation |
 
-```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);
-```
+### Constructor
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `uuid` | `string` | UUID string. Must match format `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`. Throws `ArgumentError` if invalid. |
+
+---
 
 ## `LazyGcMap<TKey, TValue>`
 
-A Map with automatic expiration. Entries not accessed within `expireTime` are garbage collected. Supports `using` syntax (Symbol.dispose).
+Auto-expiring Map with LRU-style access tracking. Items are automatically deleted after the configured expire time if not accessed. Must be disposed after use to stop the GC timer.
 
 ```typescript
 class LazyGcMap<TKey, TValue> {
@@ -62,52 +55,46 @@ class LazyGcMap<TKey, TValue> {
   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;
-
+  getOrCreate(key: TKey, factory: () => TValue): TValue;
   values(): IterableIterator<TValue>;
   keys(): IterableIterator<TKey>;
   entries(): IterableIterator<[TKey, TValue]>;
+  dispose(): void;
+  [Symbol.dispose](): void;
 }
 ```
 
 ### 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 |
+| Option | Type | Description |
+|--------|------|-------------|
+| `gcInterval` | `number \| undefined` | GC check interval in ms. Default: `expireTime / 10` (min 1000ms). |
+| `expireTime` | `number` | Time in ms after last access before an item is expired. |
+| `onExpire` | `(key, value) => void \| Promise<void>` | Callback invoked when an item expires. Errors are logged, not thrown. |
 
 ### 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
-```
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `size` | `number` | Number of stored items |
+| `has(key)` | `boolean` | Check if key exists (does not refresh access time) |
+| `get(key)` | `TValue \| undefined` | Get value and refresh access time (LRU) |
+| `set(key, value)` | `void` | Store value and start GC timer if needed |
+| `delete(key)` | `boolean` | Remove item. Stops GC timer if map becomes empty. |
+| `clear()` | `void` | Remove all items (instance remains usable) |
+| `getOrCreate(key, factory)` | `TValue` | Get existing value or create via factory, store, and return. Throws if disposed. |
+| `values()` | `IterableIterator<TValue>` | Iterate over values |
+| `keys()` | `IterableIterator<TKey>` | Iterate over keys |
+| `entries()` | `IterableIterator<[TKey, TValue]>` | Iterate over [key, value] pairs |
+| `dispose()` | `void` | Stop GC timer and clear all data |
+| `[Symbol.dispose]()` | `void` | Supports `using` statement |
+
+---
 
 ## `DateTime`
 
-Immutable date-time class wrapping JavaScript `Date`. Millisecond precision, local timezone.
+Immutable date-time class wrapping JavaScript `Date`. Provides millisecond precision and local timezone operation.
 
 ```typescript
 class DateTime {
@@ -122,14 +109,14 @@ class DateTime {
 
   // Getters
   get year(): number;
-  get month(): number;       // 1-12
+  get month(): number;
   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 dayOfWeek(): number;
   get timezoneOffsetMinutes(): number;
   get isValid(): boolean;
 
@@ -153,32 +140,43 @@ class DateTime {
 
   // Formatting
   toFormatString(formatStr: string): string;
-  toString(): string; // "yyyy-MM-ddTHH:mm:ss.fffzzz"
+  toString(): string;
 }
 ```
 
-### `DateTime.parse` Supported Formats
+### Static Methods
+
+| Method | Description |
+|--------|-------------|
+| `parse(str)` | Parse string to DateTime. Supported formats: `yyyy-MM-dd HH:mm:ss`, `yyyy-MM-dd HH:mm:ss.fff`, `yyyyMMddHHmmss`, `yyyy-MM-dd AM/PM HH:mm:ss`, ISO 8601. Throws `ArgumentError` on failure. |
+
+### Getters
 
-| 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"` |
+| Property | Type | Description |
+|----------|------|-------------|
+| `year` | `number` | Full year |
+| `month` | `number` | Month (1-12) |
+| `day` | `number` | Day of month (1-31) |
+| `hour` | `number` | Hour (0-23) |
+| `minute` | `number` | Minute (0-59) |
+| `second` | `number` | Second (0-59) |
+| `millisecond` | `number` | Millisecond (0-999) |
+| `tick` | `number` | Milliseconds since epoch |
+| `dayOfWeek` | `number` | Day of week (0=Sunday, 6=Saturday) |
+| `timezoneOffsetMinutes` | `number` | Local timezone offset in minutes (e.g., +540 for KST) |
+| `isValid` | `boolean` | Whether the date is valid |
 
-```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"
-```
+### Formatting
+
+`toFormatString(formatStr)` uses C#-style format patterns. See `dt.format` in [utilities.md](./utilities.md) for the full pattern table.
+
+`toString()` returns `"yyyy-MM-ddTHH:mm:ss.fffzzz"`.
+
+---
 
 ## `DateOnly`
 
-Immutable date class (no time component). Local timezone.
+Immutable date-only class (no time component). Local timezone based.
 
 ```typescript
 class DateOnly {
@@ -198,10 +196,10 @@ class DateOnly {
 
   // Getters
   get year(): number;
-  get month(): number;     // 1-12
+  get month(): number;
   get day(): number;
   get tick(): number;
-  get dayOfWeek(): number; // 0(Sun)-6(Sat)
+  get dayOfWeek(): number;
   get isValid(): boolean;
 
   // Immutable setters
@@ -214,7 +212,7 @@ class DateOnly {
   addMonths(months: number): DateOnly;
   addDays(days: number): DateOnly;
 
-  // Week calculations
+  // Week sequence
   getBaseYearMonthSeqForWeekSeq(weekStartDay?: number, minDaysInFirstWeek?: number): { year: number; monthSeq: number };
   getWeekSeqStartDate(weekStartDay?: number, minDaysInFirstWeek?: number): DateOnly;
   getWeekSeqOfYear(weekStartDay?: number, minDaysInFirstWeek?: number): { year: number; weekSeq: number };
@@ -222,37 +220,37 @@ class DateOnly {
 
   // Formatting
   toFormatString(formatStr: string): string;
-  toString(): string; // "yyyy-MM-dd"
+  toString(): string;
 }
 ```
 
-### `DateOnly.parse` Supported Formats
+### Static Methods
 
-| Format | Example |
-|--------|---------|
-| `yyyy-MM-dd` | `"2025-01-15"` (timezone-safe) |
-| `yyyyMMdd` | `"20250115"` (timezone-safe) |
-| ISO 8601 | `"2025-01-15T00:00:00Z"` (converted to local) |
+| Method | Description |
+|--------|-------------|
+| `parse(str)` | Parse string to DateOnly. Supported formats: `yyyy-MM-dd`, `yyyyMMdd`, ISO 8601. Throws `ArgumentError` on failure. |
+| `getDateByYearWeekSeq(arg, weekStartDay?, minDaysInFirstWeek?)` | Get the start date of a given week number within a year or month. |
 
-### Week Calculation Parameters
+### Week Sequence Methods
 
-| 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 |
+All week methods accept optional parameters:
+- `weekStartDay`: 0=Sunday, 1=Monday (default), ..., 6=Saturday
+- `minDaysInFirstWeek`: Minimum days for first week (default: 4, ISO 8601)
 
-```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
-```
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `getBaseYearMonthSeqForWeekSeq(...)` | `{ year, monthSeq }` | Base year and month for this date's week |
+| `getWeekSeqStartDate(...)` | `DateOnly` | Start date of this date's week |
+| `getWeekSeqOfYear(...)` | `{ year, weekSeq }` | Year and week number within that year |
+| `getWeekSeqOfMonth(...)` | `{ year, monthSeq, weekSeq }` | Year, month, and week number within that month |
+
+`toString()` returns `"yyyy-MM-dd"`.
+
+---
 
 ## `Time`
 
-Immutable time class (no date component). Values automatically wrap within 24 hours.
+Immutable time-only class (no date component). Values wrap around 24 hours. Negative values are normalized.
 
 ```typescript
 class Time {
@@ -277,7 +275,7 @@ class Time {
   setSecond(second: number): Time;
   setMillisecond(millisecond: number): Time;
 
-  // Arithmetic (wraps at 24h)
+  // Arithmetic (24-hour wrapping)
   addHours(hours: number): Time;
   addMinutes(minutes: number): Time;
   addSeconds(seconds: number): Time;
@@ -285,23 +283,25 @@ class Time {
 
   // Formatting
   toFormatString(formatStr: string): string;
-  toString(): string; // "HH:mm:ss.fff"
+  toString(): string;
 }
 ```
 
-### `Time.parse` Supported Formats
+### Static Methods
 
-| 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"` |
+| Method | Description |
+|--------|-------------|
+| `parse(str)` | Parse string to Time. Supported formats: `HH:mm:ss`, `HH:mm:ss.fff`, `AM/PM HH:mm:ss`, ISO 8601 (time part extracted). Throws `ArgumentError` on failure. |
 
-```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"
-```
+### Getters
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `hour` | `number` | Hour (0-23) |
+| `minute` | `number` | Minute (0-59) |
+| `second` | `number` | Second (0-59) |
+| `millisecond` | `number` | Millisecond (0-999) |
+| `tick` | `number` | Total milliseconds from midnight (0 to 86399999) |
+| `isValid` | `boolean` | Whether the time is valid |
+
+`toString()` returns `"HH:mm:ss.fff"`.