@simplysm/core-common 13.0.0-beta.2 → 13.0.0-beta.21

package/src/types/date-time.ts

@@ -1,294 +0,0 @@
-import { ArgumentError } from "../errors/argument-error";
-import { convert12To24, formatDate, normalizeMonth } from "../utils/date-format";
-
-/**
- * 날짜시간 클래스 (불변)
- *
- * JavaScript Date 객체를 래핑하여 불변성과 편리한 API를 제공한다.
- * 밀리초 단위까지 지원하며, 로컬 타임존을 기준으로 동작한다.
- *
- * @example
- * const now = new DateTime();
- * const specific = new DateTime(2025, 1, 15, 10, 30, 0);
- * const parsed = DateTime.parse("2025-01-15 10:30:00");
- */
-export class DateTime {
-  readonly date: Date;
-
-  /** 현재 시간으로 생성 */
-  constructor();
-  /** 연월일시분초밀리초로 생성 */
-  constructor(
-    year: number,
-    month: number,
-    day: number,
-    hour?: number,
-    minute?: number,
-    second?: number,
-    millisecond?: number,
-  );
-  /** tick (밀리초)으로 생성 */
-  constructor(tick: number);
-  /** Date 객체로 생성 */
-  constructor(date: Date);
-  constructor(
-    arg1?: number | Date,
-    arg2?: number,
-    arg3?: number,
-    arg4?: number,
-    arg5?: number,
-    arg6?: number,
-    arg7?: number,
-  ) {
-    if (arg1 === undefined) {
-      this.date = new Date();
-    } else if (arg2 !== undefined && arg3 !== undefined) {
-      this.date = new Date(arg1 as number, arg2 - 1, arg3, arg4 ?? 0, arg5 ?? 0, arg6 ?? 0, arg7 ?? 0);
-    } else if (arg1 instanceof Date) {
-      this.date = new Date(arg1.getTime());
-    } else {
-      this.date = new Date(arg1);
-    }
-  }
-
-  /**
-   * 문자열을 파싱하여 DateTime 인스턴스를 생성
-   *
-   * @param str 날짜시간 문자열
-   * @returns 파싱된 DateTime 인스턴스
-   * @throws ArgumentError 지원하지 않는 형식인 경우
-   *
-   * @example
-   * DateTime.parse("2025-01-15 10:30:00")     // yyyy-MM-dd HH:mm:ss
-   * DateTime.parse("2025-01-15 10:30:00.123") // yyyy-MM-dd HH:mm:ss.fff
-   * DateTime.parse("20250115103000")          // yyyyMMddHHmmss
-   * DateTime.parse("2025-01-15 오전 10:30:00") // yyyy-MM-dd 오전/오후 HH:mm:ss
-   * DateTime.parse("2025-01-15T10:30:00Z")    // ISO 8601
-   */
-  static parse(str: string): DateTime {
-    const parsedTick = Date.parse(str);
-    if (!Number.isNaN(parsedTick)) {
-      return new DateTime(parsedTick);
-    }
-
-    const match1 =
-      /^([0-9]{4})-([0-9]{2})-([0-9]{2}) (오전|오후) ([0-9]{1,2}):([0-9]{2}):([0-9]{2})(\.([0-9]{1,3}))?$/.exec(str);
-    if (match1 != null) {
-      const rawHour = Number(match1[5]);
-      const isPM = match1[4] === "오후";
-      const hour = convert12To24(rawHour, isPM);
-      return new DateTime(
-        Number(match1[1]),
-        Number(match1[2]),
-        Number(match1[3]),
-        hour,
-        Number(match1[6]),
-        Number(match1[7]),
-        match1[9] ? Number(match1[9].padEnd(3, "0")) : undefined,
-      );
-    }
-
-    const match2 = /^[0-9]{14}$/.exec(str);
-    if (match2 != null) {
-      return new DateTime(
-        Number(str.substring(0, 4)),
-        Number(str.substring(4, 6)),
-        Number(str.substring(6, 8)),
-        Number(str.substring(8, 10)),
-        Number(str.substring(10, 12)),
-        Number(str.substring(12, 14)),
-      );
-    }
-
-    const match3 = /^([0-9]{4})-([0-9]{2})-([0-9]{2}) ([0-9]{2}):([0-9]{2}):([0-9]{2})(\.([0-9]{1,3}))?$/.exec(str);
-    if (match3 != null) {
-      return new DateTime(
-        Number(match3[1]),
-        Number(match3[2]),
-        Number(match3[3]),
-        Number(match3[4]),
-        Number(match3[5]),
-        Number(match3[6]),
-        match3[8] ? Number(match3[8].padEnd(3, "0")) : undefined,
-      );
-    }
-
-    throw new ArgumentError(
-      `날짜시간 형식을 파싱할 수 없습니다. 지원 형식: 'yyyy-MM-dd HH:mm:ss', 'yyyyMMddHHmmss', 'yyyy-MM-dd 오전/오후 HH:mm:ss', ISO 8601`,
-      { input: str },
-    );
-  }
-
-  //#region Getters (읽기 전용)
-
-  get year(): number {
-    return this.date.getFullYear();
-  }
-
-  get month(): number {
-    return this.date.getMonth() + 1;
-  }
-
-  get day(): number {
-    return this.date.getDate();
-  }
-
-  get hour(): number {
-    return this.date.getHours();
-  }
-
-  get minute(): number {
-    return this.date.getMinutes();
-  }
-
-  get second(): number {
-    return this.date.getSeconds();
-  }
-
-  get millisecond(): number {
-    return this.date.getMilliseconds();
-  }
-
-  get tick(): number {
-    return this.date.getTime();
-  }
-
-  /** 요일 (일~토: 0~6) */
-  get dayOfWeek(): number {
-    return this.date.getDay();
-  }
-
-  get timezoneOffsetMinutes(): number {
-    return -this.date.getTimezoneOffset();
-  }
-
-  /** 날짜시간 세팅이 제대로 되었는지 여부 */
-  get isValid(): boolean {
-    return this.date instanceof Date && !Number.isNaN(this.date.getTime());
-  }
-
-  //#endregion
-
-  //#region 불변 변환 메서드 (새 인스턴스 반환)
-
-  /** 지정된 연도로 새 인스턴스 반환 */
-  setYear(year: number): DateTime {
-    return new DateTime(year, this.month, this.day, this.hour, this.minute, this.second, this.millisecond);
-  }
-
-  /**
-   * 지정된 월로 새 DateTime 인스턴스를 반환
-   * @param month 설정할 월 (1-12, 범위 외 값은 연도 조정)
-   * @note 대상 월의 일수보다 현재 일자가 크면 해당 월의 마지막 날로 조정됨
-   *       (예: 1월 31일에서 setMonth(2) → 2월 28일 또는 29일)
-   */
-  setMonth(month: number): DateTime {
-    const normalized = normalizeMonth(this.year, month, this.day);
-    return new DateTime(
-      normalized.year,
-      normalized.month,
-      normalized.day,
-      this.hour,
-      this.minute,
-      this.second,
-      this.millisecond,
-    );
-  }
-
-  /**
-   * 지정된 일자로 새 DateTime 인스턴스를 반환
-   * @param day 설정할 일자
-   * @note 해당 월의 유효 범위를 벗어나는 일자는 JavaScript Date 기본 동작에 따라
-   *       자동으로 다음/이전 달로 조정됨 (예: 1월에 day=32 → 2월 1일)
-   */
-  setDay(day: number): DateTime {
-    return new DateTime(this.year, this.month, day, this.hour, this.minute, this.second, this.millisecond);
-  }
-
-  /** 지정된 시로 새 인스턴스 반환 */
-  setHour(hour: number): DateTime {
-    return new DateTime(this.year, this.month, this.day, hour, this.minute, this.second, this.millisecond);
-  }
-
-  /** 지정된 분으로 새 인스턴스 반환 */
-  setMinute(minute: number): DateTime {
-    return new DateTime(this.year, this.month, this.day, this.hour, minute, this.second, this.millisecond);
-  }
-
-  /** 지정된 초로 새 인스턴스 반환 */
-  setSecond(second: number): DateTime {
-    return new DateTime(this.year, this.month, this.day, this.hour, this.minute, second, this.millisecond);
-  }
-
-  /** 지정된 밀리초로 새 인스턴스 반환 */
-  setMillisecond(millisecond: number): DateTime {
-    return new DateTime(this.year, this.month, this.day, this.hour, this.minute, this.second, millisecond);
-  }
-
-  //#endregion
-
-  //#region 산술 메서드 (새 인스턴스 반환)
-
-  /** 지정된 연수를 더한 새 인스턴스 반환 */
-  addYears(years: number): DateTime {
-    return this.setYear(this.year + years);
-  }
-
-  /** 지정된 월수를 더한 새 인스턴스 반환 */
-  addMonths(months: number): DateTime {
-    return this.setMonth(this.month + months);
-  }
-
-  /** 지정된 일수를 더한 새 인스턴스 반환 */
-  addDays(days: number): DateTime {
-    return new DateTime(this.tick + days * 24 * 60 * 60 * 1000);
-  }
-
-  /** 지정된 시간을 더한 새 인스턴스 반환 */
-  addHours(hours: number): DateTime {
-    return new DateTime(this.tick + hours * 60 * 60 * 1000);
-  }
-
-  /** 지정된 분을 더한 새 인스턴스 반환 */
-  addMinutes(minutes: number): DateTime {
-    return new DateTime(this.tick + minutes * 60 * 1000);
-  }
-
-  /** 지정된 초를 더한 새 인스턴스 반환 */
-  addSeconds(seconds: number): DateTime {
-    return new DateTime(this.tick + seconds * 1000);
-  }
-
-  /** 지정된 밀리초를 더한 새 인스턴스 반환 */
-  addMilliseconds(milliseconds: number): DateTime {
-    return new DateTime(this.tick + milliseconds);
-  }
-
-  //#endregion
-
-  //#region 포맷팅
-
-  /**
-   * 지정된 포맷으로 문자열 변환
-   * @param format 포맷 문자열
-   * @see dtFormat 지원 포맷 문자열 참조
-   */
-  toFormatString(formatStr: string): string {
-    return formatDate(formatStr, {
-      year: this.year,
-      month: this.month,
-      day: this.day,
-      hour: this.hour,
-      minute: this.minute,
-      second: this.second,
-      millisecond: this.millisecond,
-      timezoneOffsetMinutes: this.timezoneOffsetMinutes,
-    });
-  }
-
-  toString(): string {
-    return this.toFormatString("yyyy-MM-ddTHH:mm:ss.fffzzz");
-  }
-
-  //#endregion
-}

package/src/types/lazy-gc-map.ts

@@ -1,244 +0,0 @@
-import { createConsola } from "consola";
-
-/**
- * 자동 만료 기능이 있는 Map
- * LRU 방식으로 접근 시간 갱신, 일정 시간 미접근 시 자동 삭제
- *
- * @note 인스턴스 사용 후 반드시 dispose()를 호출하거나 using 문을 사용해야 함.
- *       그렇지 않으면 GC 타이머가 계속 동작하여 메모리 누수 발생.
- *
- * @example
- * // using 문 사용 (권장)
- * using map = new LazyGcMap({ gcInterval: 10000, expireTime: 60000 });
- *
- * // 또는 명시적 dispose() 호출
- * const map = new LazyGcMap({ gcInterval: 10000, expireTime: 60000 });
- * try {
- *   // ... 사용
- * } finally {
- *   map.dispose();
- * }
- */
-export class LazyGcMap<K, V> {
-  private static readonly _logger = createConsola().withTag("LazyGcMap");
-
-  /**
-   * dispose() 미호출 감지용 registry
-   * @note FinalizationRegistry는 Chrome 84+, Node 14.6+ 지원
-   *       미지원 환경에서는 경고 없이 동작하지만, dispose() 미호출 시 메모리 누수 가능
-   */
-  private static readonly _registry =
-    typeof FinalizationRegistry !== "undefined"
-      ? new FinalizationRegistry<string>((id) => {
-          LazyGcMap._logger.warn(`LazyGcMap(${id})이 dispose() 없이 가비지 수집됨. 메모리 누수 가능성 있음.`);
-        })
-      : undefined;
-
-  // 실제 데이터와 마지막 접근 시간을 함께 저장
-  private readonly _map = new Map<K, { value: V; lastAccess: number }>();
-
-  // GC 타이머
-  private _gcTimer?: ReturnType<typeof setInterval>;
-  // GC 실행 중 플래그 (중복 실행 방지)
-  private _isGcRunning = false;
-  // destroy 호출 여부
-  private _isDestroyed = false;
-  // 인스턴스 식별자 (경고 메시지용)
-  private readonly _instanceId = Math.random().toString(36).slice(2);
-
-  /**
-   * @param _options 설정 옵션
-   * @param _options.gcInterval GC 주기 (밀리초). 기본값: expireTime의 1/10 (최소 1000ms)
-   * @param _options.expireTime 만료 시간 (밀리초). 마지막 접근 후 이 시간이 지나면 삭제됨. 예: 60000 (60초)
-   * @param _options.onExpire 만료 시 호출되는 콜백. 비동기 함수도 가능하며, 에러 발생 시 로깅 후 계속 진행됨
-   */
-  constructor(
-    private readonly _options: {
-      gcInterval?: number;
-      expireTime: number;
-      onExpire?: (key: K, value: V) => void | Promise<void>;
-    },
-  ) {
-    LazyGcMap._registry?.register(this, this._instanceId);
-  }
-
-  /** 저장된 항목 수 */
-  get size(): number {
-    return this._map.size;
-  }
-
-  /** 키 존재 여부 확인 (접근 시간 갱신 안함) */
-  has(key: K): boolean {
-    if (this._isDestroyed) return false;
-    return this._map.has(key);
-  }
-
-  /** 값 조회 (접근 시간 갱신됨) */
-  get(key: K): V | undefined {
-    if (this._isDestroyed) return undefined;
-    const item = this._map.get(key);
-    if (item == null) return undefined;
-
-    // 접근 시 시간 갱신 (LRU)
-    item.lastAccess = Date.now();
-    return item.value;
-  }
-
-  /** 값 저장 (접근 시간 설정 및 GC 타이머 시작) */
-  set(key: K, value: V): void {
-    if (this._isDestroyed) return;
-    this._map.set(key, { value, lastAccess: Date.now() });
-    // 데이터가 들어왔으므로 GC 타이머 가동
-    this._startGc();
-  }
-
-  /** 항목 삭제 (비었으면 GC 타이머 중지) */
-  delete(key: K): boolean {
-    if (this._isDestroyed) return false;
-    const result = this._map.delete(key);
-    // 비었으면 타이머 중지
-    if (this._map.size === 0) {
-      this._stopGc();
-    }
-    return result;
-  }
-
-  /** 인스턴스 정리 (GC 타이머 중지 및 데이터 삭제) */
-  dispose(): void {
-    if (this._isDestroyed) return;
-    this._isDestroyed = true;
-    LazyGcMap._registry?.unregister(this);
-
-    this._map.clear();
-    this._stopGc();
-  }
-
-  /** using 문 지원 */
-  [Symbol.dispose](): void {
-    this.dispose();
-  }
-
-  /**
-   * 모든 항목 삭제 (인스턴스는 계속 사용 가능)
-   */
-  clear(): void {
-    if (this._isDestroyed) return;
-    this._map.clear();
-    this._stopGc();
-  }
-
-  /**
-   * 키에 해당하는 값을 반환하고, 없으면 factory로 생성 후 저장하여 반환
-   * @param key 조회할 키
-   * @param factory 키가 없을 때 값을 생성하는 함수
-   * @returns 기존 값 또는 새로 생성된 값
-   */
-  getOrCreate(key: K, factory: () => V): V {
-    if (this._isDestroyed) {
-      throw new Error("LazyGcMap이 이미 dispose되었습니다.");
-    }
-    const item = this._map.get(key);
-    if (item == null) {
-      const value = factory();
-      this.set(key, value);
-      return value;
-    }
-
-    item.lastAccess = Date.now();
-    return item.value;
-  }
-
-  /** 값들만 순회 (Iterator) */
-  *values(): IterableIterator<V> {
-    if (this._isDestroyed) return;
-    for (const item of this._map.values()) {
-      yield item.value;
-    }
-  }
-
-  /** 키들만 순회 (Iterator) */
-  *keys(): IterableIterator<K> {
-    if (this._isDestroyed) return;
-    yield* this._map.keys();
-  }
-
-  /** 엔트리 순회 (Iterator) */
-  *entries(): IterableIterator<[K, V]> {
-    if (this._isDestroyed) return;
-    for (const [key, item] of this._map.entries()) {
-      yield [key, item.value];
-    }
-  }
-
-  //#region GC 로직
-
-  private _startGc(): void {
-    if (this._isDestroyed) return;
-    if (this._gcTimer != null) return;
-
-    const interval = this._options.gcInterval ?? Math.max(this._options.expireTime / 10, 1000);
-    this._gcTimer = setInterval(() => {
-      void this._runGc();
-    }, interval);
-  }
-
-  private async _runGc(): Promise<void> {
-    // 이미 실행 중이면 스킵 (onExpire 콜백이 오래 걸리는 경우 중복 실행 방지)
-    if (this._isGcRunning) return;
-    this._isGcRunning = true;
-
-    try {
-      const now = Date.now();
-
-      // 1. 만료된 항목 수집 (삭제 전)
-      const expiredEntries: { key: K; item: { value: V; lastAccess: number } }[] = [];
-      for (const [key, item] of this._map) {
-        if (now - item.lastAccess > this._options.expireTime) {
-          expiredEntries.push({ key, item });
-        }
-      }
-
-      // 2. 각 항목에 대해 콜백 실행 후 삭제
-      for (const { key, item } of expiredEntries) {
-        // 콜백 실행 전 현재 상태 확인 (이미 다른 값으로 교체되었거나 삭제되었으면 스킵)
-        const currentItem = this._map.get(key);
-        if (currentItem !== item) {
-          continue;
-        }
-
-        // 만료 콜백 실행
-        if (this._options.onExpire != null) {
-          try {
-            await this._options.onExpire(key, item.value);
-          } catch (err) {
-            LazyGcMap._logger.error("onExpire 콜백 에러", err);
-          }
-        }
-
-        // 콜백 후 재등록 여부 확인
-        // 시나리오: onExpire 콜백에서 동일 키로 새 값을 set()한 경우,
-        // 새로 등록된 항목을 삭제하면 안 됨. item 참조가 같으면 재등록되지 않은 것이므로 삭제 진행.
-        const afterItem = this._map.get(key);
-        if (afterItem === item) {
-          this._map.delete(key);
-        }
-      }
-
-      // GC 후 비었으면 끄기
-      if (this._map.size === 0) {
-        this._stopGc();
-      }
-    } finally {
-      this._isGcRunning = false;
-    }
-  }
-
-  private _stopGc(): void {
-    if (this._gcTimer != null) {
-      clearInterval(this._gcTimer);
-      this._gcTimer = undefined;
-    }
-  }
-
-  //#endregion
-}