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

package/src/utils/date-format.ts

@@ -1,239 +0,0 @@
-/**
- * 월 설정 시 연도/월/일 정규화 결과
- */
-export interface DtNormalizedMonth {
-  year: number;
-  month: number;
-  day: number;
-}
-
-/**
- * 월 설정 시 연도/월/일을 정규화
- * - 월이 1-12 범위를 벗어나면 연도를 조정
- * - 대상 월의 일수보다 현재 일자가 크면 해당 월의 마지막 날로 조정
- *
- * @param year 기준 연도
- * @param month 설정할 월 (1-12 범위 외의 값도 허용)
- * @param day 기준 일자
- * @returns 정규화된 연도, 월, 일
- *
- * @example
- * normalizeMonth(2025, 13, 15) // { year: 2026, month: 1, day: 15 }
- * normalizeMonth(2025, 2, 31)  // { year: 2025, month: 2, day: 28 }
- */
-export function normalizeMonth(year: number, month: number, day: number): DtNormalizedMonth {
-  // 월 오버플로우/언더플로우 정규화
-  // month가 1-12 범위를 벗어나면 연도를 조정
-  const normalizedYear = year + Math.floor((month - 1) / 12);
-  // JavaScript % 연산자는 음수에서 음수를 반환하므로 (% 12 + 12) % 12 패턴으로 0-11 범위를 보장 후 1-12로 변환
-  const normalizedMonth = ((((month - 1) % 12) + 12) % 12) + 1;
-
-  // 대상 월의 마지막 날 구하기
-  const lastDay = new Date(normalizedYear, normalizedMonth, 0).getDate();
-  const normalizedDay = Math.min(day, lastDay);
-
-  return { year: normalizedYear, month: normalizedMonth, day: normalizedDay };
-}
-
-/**
- * 12시간제를 24시간제로 변환
- * - 오전 12시 = 0시, 오후 12시 = 12시
- * - 오전 1-11시 = 1-11시, 오후 1-11시 = 13-23시
- *
- * @param rawHour 12시간제 시 (1-12)
- * @param isPM 오후 여부
- * @returns 24시간제 시 (0-23)
- */
-export function convert12To24(rawHour: number, isPM: boolean): number {
-  if (rawHour === 12) {
-    return isPM ? 12 : 0;
-  }
-  return isPM ? rawHour + 12 : rawHour;
-}
-
-//#region 정규식 캐싱 (모듈 로드 시 1회만 생성)
-
-/**
- * 포맷 패턴 정규식
- *
- * 순서 중요:
- * dtFormat() 함수에서 긴 패턴(yyyy, MM, dd 등)을 먼저 처리해야
- * 짧은 패턴(y, M, d 등)이 부분 매칭되는 것을 방지합니다.
- * 예: "yyyy"를 먼저 처리하지 않으면 "yy"가 두 번 매칭될 수 있음
- */
-const patterns = {
-  yyyy: /yyyy/g,
-  yy: /yy/g,
-  MM: /MM/g,
-  M: /M/g,
-  ddd: /ddd/g,
-  dd: /dd/g,
-  d: /d/g,
-  tt: /tt/g,
-  hh: /hh/g,
-  h: /h/g,
-  HH: /HH/g,
-  H: /H/g,
-  mm: /mm/g,
-  m: /m/g,
-  ss: /ss/g,
-  s: /s/g,
-  fff: /fff/g,
-  ff: /ff/g,
-  f: /f/g,
-  zzz: /zzz/g,
-  zz: /zz/g,
-  z: /z/g,
-};
-
-const weekStrings = ["일", "월", "화", "수", "목", "금", "토"];
-
-//#endregion
-
-/**
- * 포맷 문자열에 따라 날짜/시간을 문자열로 변환한다
- *
- * @param formatString 포맷 문자열
- * @param args 날짜/시간 구성 요소
- *
- * @remarks
- * C#과 동일한 포맷 문자열을 지원한다:
- *
- * | 포맷 | 설명 | 예시 |
- * |------|------|------|
- * | yyyy | 4자리 연도 | 2024 |
- * | yy | 2자리 연도 | 24 |
- * | MM | 0으로 패딩된 월 | 01~12 |
- * | M | 월 | 1~12 |
- * | ddd | 요일 (한글) | 일, 월, 화, 수, 목, 금, 토 |
- * | dd | 0으로 패딩된 일 | 01~31 |
- * | d | 일 | 1~31 |
- * | tt | 오전/오후 | 오전, 오후 |
- * | hh | 0으로 패딩된 12시간 | 01~12 |
- * | h | 12시간 | 1~12 |
- * | HH | 0으로 패딩된 24시간 | 00~23 |
- * | H | 24시간 | 0~23 |
- * | mm | 0으로 패딩된 분 | 00~59 |
- * | m | 분 | 0~59 |
- * | ss | 0으로 패딩된 초 | 00~59 |
- * | s | 초 | 0~59 |
- * | fff | 밀리초 (3자리) | 000~999 |
- * | ff | 밀리초 (2자리) | 00~99 |
- * | f | 밀리초 (1자리) | 0~9 |
- * | zzz | 타임존 오프셋 (±HH:mm) | +09:00 |
- * | zz | 타임존 오프셋 (±HH) | +09 |
- * | z | 타임존 오프셋 (±H) | +9 |
- *
- * @example
- * ```typescript
- * formatDate("yyyy-MM-dd", { year: 2024, month: 3, day: 15 });
- * // "2024-03-15"
- *
- * formatDate("yyyy년 M월 d일 (ddd)", { year: 2024, month: 3, day: 15 });
- * // "2024년 3월 15일 (금)"
- *
- * formatDate("tt h:mm:ss", { hour: 14, minute: 30, second: 45 });
- * // "오후 2:30:45"
- * ```
- */
-export function formatDate(
-  formatString: string,
-  args: {
-    year?: number;
-    month?: number;
-    day?: number;
-    hour?: number;
-    minute?: number;
-    second?: number;
-    millisecond?: number;
-    timezoneOffsetMinutes?: number;
-  },
-): string {
-  const { year, month, day, hour, minute, second, millisecond, timezoneOffsetMinutes } = args;
-
-  const absOffsetMinutes = timezoneOffsetMinutes !== undefined ? Math.abs(timezoneOffsetMinutes) : undefined;
-  const offsetHour = absOffsetMinutes !== undefined ? Math.floor(absOffsetMinutes / 60) : undefined;
-  const offsetMinute = absOffsetMinutes !== undefined ? absOffsetMinutes % 60 : undefined;
-  const offsetSign = timezoneOffsetMinutes !== undefined ? (timezoneOffsetMinutes >= 0 ? "+" : "-") : undefined;
-
-  const week =
-    year !== undefined && month !== undefined && day !== undefined
-      ? new Date(year, month - 1, day).getDay()
-      : undefined;
-
-  let result = formatString;
-
-  // 연도
-  if (year !== undefined) {
-    const yearStr = year.toString();
-    result = result.replace(patterns.yyyy, yearStr);
-    result = result.replace(patterns.yy, yearStr.substring(2, 4));
-  }
-
-  // 월
-  if (month !== undefined) {
-    const monthStr = month.toString();
-    result = result.replace(patterns.MM, monthStr.padStart(2, "0"));
-    result = result.replace(patterns.M, monthStr);
-  }
-
-  // 요일
-  if (week !== undefined) {
-    result = result.replace(patterns.ddd, weekStrings[week]);
-  }
-
-  // 일
-  if (day !== undefined) {
-    const dayStr = day.toString();
-    result = result.replace(patterns.dd, dayStr.padStart(2, "0"));
-    result = result.replace(patterns.d, dayStr);
-  }
-
-  // 시간
-  if (hour !== undefined) {
-    result = result.replace(patterns.tt, hour < 12 ? "오전" : "오후");
-
-    const hour12 = hour % 12 || 12;
-    const hour12Str = hour12.toString();
-    result = result.replace(patterns.hh, hour12Str.padStart(2, "0"));
-    result = result.replace(patterns.h, hour12Str);
-
-    const hourStr = hour.toString();
-    result = result.replace(patterns.HH, hourStr.padStart(2, "0"));
-    result = result.replace(patterns.H, hourStr);
-  }
-
-  // 분
-  if (minute !== undefined) {
-    const minuteStr = minute.toString();
-    result = result.replace(patterns.mm, minuteStr.padStart(2, "0"));
-    result = result.replace(patterns.m, minuteStr);
-  }
-
-  // 초
-  if (second !== undefined) {
-    const secondStr = second.toString();
-    result = result.replace(patterns.ss, secondStr.padStart(2, "0"));
-    result = result.replace(patterns.s, secondStr);
-  }
-
-  // 밀리초
-  if (millisecond !== undefined) {
-    const msStr = millisecond.toString().padStart(3, "0");
-    result = result.replace(patterns.fff, msStr);
-    result = result.replace(patterns.ff, msStr.substring(0, 2));
-    result = result.replace(patterns.f, msStr.substring(0, 1));
-  }
-
-  // 타임존
-  if (offsetSign !== undefined && offsetHour !== undefined && offsetMinute !== undefined) {
-    result = result.replace(
-      patterns.zzz,
-      `${offsetSign}${offsetHour.toString().padStart(2, "0")}:${offsetMinute.toString().padStart(2, "0")}`,
-    );
-    result = result.replace(patterns.zz, `${offsetSign}${offsetHour.toString().padStart(2, "0")}`);
-    result = result.replace(patterns.z, `${offsetSign}${offsetHour}`);
-  }
-
-  return result;
-}

package/src/utils/json.ts

@@ -1,230 +0,0 @@
-/**
- * JSON 변환 유틸리티
- * 커스텀 타입(DateTime, DateOnly, Time, Uuid 등)을 지원하는 JSON 직렬화/역직렬화
- */
-import { DateTime } from "../types/date-time";
-import { DateOnly } from "../types/date-only";
-import { Time } from "../types/time";
-import { Uuid } from "../types/uuid";
-import { objNullToUndefined } from "./obj";
-import { SdError } from "../errors/sd-error";
-import { bytesToHex, bytesFromHex } from "./bytes";
-import { env } from "../env";
-
-interface TypedObject {
-  __type__: string;
-  data: unknown;
-}
-
-//#region stringify
-
-/**
- * 객체를 JSON 문자열로 직렬화
- * DateTime, DateOnly, Time, Uuid, Set, Map, Error, Uint8Array 등 커스텀 타입 지원
- *
- * @param obj 직렬화할 객체
- * @param options 직렬화 옵션
- * @param options.space JSON 들여쓰기 (숫자: 공백 수, 문자열: 들여쓰기 문자열)
- * @param options.replacer 커스텀 replacer 함수. 기본 타입 변환 전에 호출됨
- * @param options.redactBytes true 시 Uint8Array 내용을 "__hidden__"으로 대체 (로깅용). 이 옵션으로 직렬화한 결과는 jsonParse()로 원본 Uint8Array를 복원할 수 없음
- *
- * @remarks
- * - 순환 참조가 있는 객체는 TypeError를 던짐
- * - 객체의 toJSON 메서드가 있으면 호출하여 결과를 사용함 (Date, DateTime 등 커스텀 타입 제외)
- * - 전역 프로토타입을 수정하지 않아 Worker 환경에서도 안전함
- */
-export function jsonStringify(
-  obj: unknown,
-  options?: {
-    space?: string | number;
-    replacer?: (key: string | undefined, value: unknown) => unknown;
-    redactBytes?: boolean;
-  },
-): string {
-  // 순환 참조 감지를 위한 WeakSet
-  const seen = new WeakSet<object>();
-
-  /**
-   * 재귀적으로 객체를 순회하며 특수 타입을 __type__ 형식으로 변환
-   *
-   * JSON.stringify의 replacer는 toJSON 호출 후의 값을 받으므로,
-   * Date 등의 타입을 올바르게 처리하려면 미리 변환해야 함.
-   * 이 방식은 전역 프로토타입을 수정하지 않아 Worker 환경에서도 안전함.
-   *
-   * @param key 현재 값의 키 (루트는 undefined)
-   * @param value 변환할 값
-   */
-  const convertSpecialTypes = (key: string | undefined, value: unknown): unknown => {
-    // 커스텀 replacer 적용
-    const currValue = options?.replacer !== undefined ? options.replacer(key, value) : value;
-
-    if (currValue instanceof Date) {
-      return { __type__: "Date", data: currValue.toISOString() };
-    }
-    if (currValue instanceof DateTime) {
-      return { __type__: "DateTime", data: currValue.toString() };
-    }
-    if (currValue instanceof DateOnly) {
-      return { __type__: "DateOnly", data: currValue.toString() };
-    }
-    if (currValue instanceof Time) {
-      return { __type__: "Time", data: currValue.toString() };
-    }
-    if (currValue instanceof Uuid) {
-      return { __type__: "Uuid", data: currValue.toString() };
-    }
-    if (currValue instanceof Set) {
-      return {
-        __type__: "Set",
-        data: Array.from(currValue).map((item, i) => convertSpecialTypes(String(i), item)),
-      };
-    }
-    if (currValue instanceof Map) {
-      return {
-        __type__: "Map",
-        data: Array.from(currValue.entries()).map(([k, v], i) => [
-          convertSpecialTypes(String(i), k),
-          convertSpecialTypes(String(i), v),
-        ]),
-      };
-    }
-    if (currValue instanceof Error) {
-      return {
-        __type__: "Error",
-        data: {
-          name: currValue.name,
-          message: currValue.message,
-          stack: currValue.stack,
-          ...("code" in currValue ? { code: currValue.code } : {}),
-          ...("detail" in currValue ? { detail: currValue.detail } : {}),
-          ...("cause" in currValue ? { cause: convertSpecialTypes("cause", currValue.cause) } : {}),
-        },
-      };
-    }
-    if (currValue instanceof Uint8Array) {
-      if (options?.redactBytes === true) {
-        return { __type__: "Uint8Array", data: "__hidden__" };
-      }
-      return { __type__: "Uint8Array", data: bytesToHex(currValue) };
-    }
-
-    // 배열 처리
-    if (Array.isArray(currValue)) {
-      // 순환 참조 감지
-      if (seen.has(currValue)) {
-        throw new TypeError("Converting circular structure to JSON");
-      }
-      seen.add(currValue);
-      const result = currValue.map((item, i) => convertSpecialTypes(String(i), item));
-      seen.delete(currValue);
-      return result;
-    }
-
-    // 일반 객체 처리
-    if (currValue !== null && typeof currValue === "object") {
-      // 순환 참조 감지
-      if (seen.has(currValue)) {
-        throw new TypeError("Converting circular structure to JSON");
-      }
-      seen.add(currValue);
-
-      // toJSON 메서드가 있으면 호출 (Date, DateTime 등 커스텀 타입은 이미 위에서 처리됨)
-      if ("toJSON" in currValue && typeof (currValue as { toJSON: unknown }).toJSON === "function") {
-        const toJsonResult = (currValue as { toJSON: (key?: string) => unknown }).toJSON(key);
-        seen.delete(currValue);
-        return convertSpecialTypes(key, toJsonResult);
-      }
-
-      const result: Record<string, unknown> = {};
-      for (const [k, v] of Object.entries(currValue)) {
-        const converted = convertSpecialTypes(k, v);
-        // undefined는 JSON에서 제외됨
-        if (converted !== undefined) {
-          result[k] = converted;
-        }
-      }
-      seen.delete(currValue);
-      return result;
-    }
-
-    return currValue;
-  };
-
-  // 전체 객체를 미리 변환 후 JSON.stringify 호출
-  // 이 방식은 Date.prototype.toJSON을 수정하지 않아 동시성 환경에서 안전함
-  const converted = convertSpecialTypes(undefined, obj);
-  return JSON.stringify(converted, null, options?.space);
-}
-
-//#endregion
-
-//#region parse
-
-/**
- * JSON 문자열을 객체로 역직렬화
- * DateTime, DateOnly, Time, Uuid, Set, Map, Error, Uint8Array 등 커스텀 타입 복원
- *
- * @remarks
- * `__type__`과 `data` 키를 가진 객체는 타입 복원에 사용된다.
- * 사용자 데이터에 `{ __type__: "Date" | "DateTime" | "DateOnly" | "Time" | "Uuid" | "Set" | "Map" | "Error" | "Uint8Array", data: ... }`
- * 형태가 있으면 의도치 않게 타입 변환될 수 있으므로 주의한다.
- *
- * @security 개발 모드(`__DEV__`)에서만 에러 메시지에 JSON 문자열 전체가 포함된다.
- * 프로덕션 모드에서는 JSON 길이만 포함된다.
- */
-export function jsonParse<T = unknown>(json: string): T {
-  try {
-    return objNullToUndefined(
-      JSON.parse(json, (_key, value: unknown) => {
-        if (value != null && typeof value === "object") {
-          // __type__ 기반 타입 복원
-          if ("__type__" in value && "data" in value) {
-            const typed = value as TypedObject;
-            if (typed.__type__ === "Date" && typeof typed.data === "string") {
-              return new Date(Date.parse(typed.data));
-            }
-            if (typed.__type__ === "DateTime" && typeof typed.data === "string") {
-              return DateTime.parse(typed.data);
-            }
-            if (typed.__type__ === "DateOnly" && typeof typed.data === "string") {
-              return DateOnly.parse(typed.data);
-            }
-            if (typed.__type__ === "Time" && typeof typed.data === "string") {
-              return Time.parse(typed.data);
-            }
-            if (typed.__type__ === "Uuid" && typeof typed.data === "string") {
-              return new Uuid(typed.data);
-            }
-            if (typed.__type__ === "Set" && Array.isArray(typed.data)) {
-              return new Set(typed.data);
-            }
-            if (typed.__type__ === "Map" && Array.isArray(typed.data)) {
-              return new Map(typed.data as [unknown, unknown][]);
-            }
-            if (typed.__type__ === "Error" && typeof typed.data === "object") {
-              const errorData = typed.data as Record<string, unknown>;
-              const error = new Error(errorData["message"] as string);
-              Object.assign(error, errorData);
-              return error;
-            }
-            if (typed.__type__ === "Uint8Array" && typeof typed.data === "string") {
-              if (typed.data === "__hidden__") {
-                throw new SdError("redactBytes 옵션으로 직렬화된 Uint8Array는 parse로 복원할 수 없습니다");
-              }
-              return bytesFromHex(typed.data);
-            }
-          }
-        }
-
-        return value;
-      }),
-    ) as T;
-  } catch (err) {
-    if (env.DEV) {
-      throw new SdError(err, "JSON 파싱 에러: \n" + json);
-    }
-    throw new SdError(err, `JSON 파싱 에러 (length: ${json.length})`);
-  }
-}
-
-//#endregion

package/src/utils/num.ts

@@ -1,97 +0,0 @@
-/**
- * 숫자 유틸리티 함수
- */
-
-//#region numParseInt / numParseFloat / numParseRoundedInt
-
-/**
- * 문자열을 정수로 파싱
- * 숫자가 아닌 문자(0-9, -, . 제외)는 제거 후 파싱
- *
- * @note 소수점이 포함된 문자열은 정수 부분만 반환됩니다 (예: '12.34' → 12).
- *       반올림이 필요하면 {@link numParseRoundedInt}를 사용하세요.
- * @note 문자열 중간의 `-`도 유지되므로 의도치 않은 음수가 될 수 있습니다.
- *       예: `"가-123나"` → `-123`
- */
-export function numParseInt(text: unknown): number | undefined {
-  if (typeof text === "number") return Math.trunc(text);
-  if (typeof text !== "string") return undefined;
-  const txt = text.replace(/[^0-9.\-]/g, "").trim();
-  if (txt === "") return undefined;
-  const result = Number.parseInt(txt, 10);
-  if (Number.isNaN(result)) return undefined;
-  return result;
-}
-
-/**
- * 문자열을 실수로 파싱 후 반올림하여 정수 반환
- */
-export function numParseRoundedInt(text: unknown): number | undefined {
-  const float = numParseFloat(text);
-  return float !== undefined ? Math.round(float) : undefined;
-}
-
-/**
- * 문자열을 실수로 파싱
- * 숫자가 아닌 문자는 제거 후 파싱
- */
-export function numParseFloat(text: unknown): number | undefined {
-  if (typeof text === "number") return text;
-  if (typeof text !== "string") return undefined;
-  const txt = text.replace(/[^0-9.\-]/g, "").trim();
-  if (txt === "") return undefined;
-  const result = Number.parseFloat(txt);
-  if (Number.isNaN(result)) return undefined;
-  return result;
-}
-
-//#endregion
-
-//#region numIsNullOrEmpty
-
-/**
- * undefined, null, 0 체크 (타입 가드)
- *
- * 타입 가드로 동작하여, true 반환 시 `val`이 `0 | undefined`임을 보장합니다.
- * false 반환 시 `val`이 0이 아닌 유효한 숫자임이 보장됩니다.
- *
- * @param val 체크할 값
- * @returns undefined, null, 0이면 true
- * @example
- * const count: number | undefined = getValue();
- * if (numIsNullOrEmpty(count)) {
- *   // count: 0 | undefined
- *   console.log("비어있음");
- * } else {
- *   // count: number (0이 아닌 값)
- *   console.log(`개수: ${count}`);
- * }
- */
-export function numIsNullOrEmpty(val: number | undefined): val is 0 | undefined {
-  return val == null || val === 0;
-}
-
-//#endregion
-
-//#region numFormat
-
-/**
- * 숫자를 천단위 구분자가 포함된 문자열로 포맷팅
- * @param val 포맷팅할 숫자
- * @param digit 소수점 자릿수 옵션
- * @param digit.max 최대 소수점 자릿수
- * @param digit.min 최소 소수점 자릿수 (부족하면 0으로 채움)
- * @example
- * numFormat(1234.567, { max: 2 }) // "1,234.57"
- * numFormat(1234, { min: 2 }) // "1,234.00"
- */
-export function numFormat(val: number, digit?: { max?: number; min?: number }): string;
-export function numFormat(val: number | undefined, digit?: { max?: number; min?: number }): string | undefined;
-export function numFormat(val: number | undefined, digit?: { max?: number; min?: number }): string | undefined {
-  return val?.toLocaleString(undefined, {
-    maximumFractionDigits: digit?.max,
-    minimumFractionDigits: digit?.min,
-  });
-}
-
-//#endregion