@withwiz/toolkit 0.1.0

package/dist/utils/ip-utils.js

@@ -0,0 +1,91 @@
+import "../chunk-ORMEWXMH.js";
+
+// src/utils/ip-utils.ts
+function isPrivateIP(ip) {
+  if (!ip) return false;
+  const privateRanges = [
+    /^10\./,
+    // 10.0.0.0/8
+    /^172\.(1[6-9]|2[0-9]|3[01])\./,
+    // 172.16.0.0/12
+    /^192\.168\./,
+    // 192.168.0.0/16
+    /^127\./,
+    // 127.0.0.0/8 (localhost)
+    /^169\.254\./,
+    // 169.254.0.0/16 (link-local)
+    /^0\./,
+    // 0.0.0.0/8
+    /^224\./,
+    // 224.0.0.0/4 (multicast)
+    /^240\./
+    // 240.0.0.0/4 (reserved)
+  ];
+  const ipv6PrivateRanges = [
+    /^::1$/,
+    // localhost
+    /^fe80:/,
+    // link-local
+    /^fc00:/,
+    // unique local
+    /^fd00:/
+    // unique local
+  ];
+  if (ip.includes(".")) {
+    return privateRanges.some((range) => range.test(ip));
+  }
+  if (ip.includes(":")) {
+    return ipv6PrivateRanges.some((range) => range.test(ip));
+  }
+  return false;
+}
+function isIPv6(ip) {
+  return ip.includes(":");
+}
+function normalizeIP(ip) {
+  if (!ip) return "";
+  if (isIPv6(ip)) {
+    return ip.toLowerCase();
+  }
+  return ip;
+}
+function extractClientIp(headers) {
+  const cf = headers.get("cf-connecting-ip");
+  if (cf && isValidIP(cf.trim())) return cf.trim();
+  const trueClientIp = headers.get("true-client-ip");
+  if (trueClientIp && isValidIP(trueClientIp.trim())) return trueClientIp.trim();
+  const xri = headers.get("x-real-ip");
+  if (xri && isValidIP(xri.trim())) return xri.trim();
+  const xff = headers.get("x-forwarded-for");
+  if (xff) {
+    const ips = xff.split(",").map((ip) => ip.trim()).filter(Boolean);
+    if (ips.length > 0 && isValidIP(ips[0])) {
+      return ips[0];
+    }
+  }
+  const xc = headers.get("x-client-ip");
+  if (xc && isValidIP(xc.trim())) return xc.trim();
+  return null;
+}
+function isValidIP(ip) {
+  if (!ip || typeof ip !== "string") return false;
+  if (ip.includes(".")) {
+    const parts = ip.split(".");
+    if (parts.length !== 4) return false;
+    return parts.every((part) => {
+      const num = parseInt(part, 10);
+      return !isNaN(num) && num >= 0 && num <= 255;
+    });
+  }
+  if (ip.includes(":")) {
+    return /^([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}$/.test(ip) || /^::1$/.test(ip) || /^::/.test(ip) || /^2001:4860:4860::8888$/.test(ip);
+  }
+  return false;
+}
+export {
+  extractClientIp,
+  isIPv6,
+  isPrivateIP,
+  isValidIP,
+  normalizeIP
+};

package/dist/utils/optimistic-lock.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Optimistic Locking Utility
+ *
+ * 다중 인스턴스 환경에서 동시 업데이트 충돌을 감지하기 위한 낙관적 락 유틸리티.
+ * Prisma의 updateMany + where version 조건을 활용.
+ */
+/**
+ * 낙관적 락이 적용된 업데이트 실행
+ *
+ * @param updateFn - Prisma updateMany를 실행하는 함수. count를 반환해야 함.
+ * @param entityName - 엔티티 이름 (에러 메시지용)
+ * @throws AppError 40901 (Conflict) - 버전 충돌 시
+ *
+ * @example
+ * ```typescript
+ * await withOptimisticLock(
+ *   () => prisma.link.updateMany({
+ *     where: { id: linkId, version: currentVersion },
+ *     data: { title: newTitle, version: { increment: 1 } },
+ *   }),
+ *   'Link'
+ * );
+ * ```
+ */
+export declare function withOptimisticLock(updateFn: () => Promise<{
+    count: number;
+}>, entityName?: string): Promise<void>;

package/dist/utils/optimistic-lock.js

@@ -0,0 +1,16 @@
+import {
+  AppError
+} from "../chunk-MLGO3HLS.js";
+import "../chunk-Y3OTJH2S.js";
+import "../chunk-ORMEWXMH.js";
+
+// src/utils/optimistic-lock.ts
+async function withOptimisticLock(updateFn, entityName = "Record") {
+  const result = await updateFn();
+  if (result.count === 0) {
+    throw new AppError(40904, `${entityName} was modified by another request. Please retry.`);
+  }
+}
+export {
+  withOptimisticLock
+};

package/dist/utils/sanitizer.d.ts

@@ -0,0 +1,72 @@
+/**
+ * sanitizer.ts
+ *
+ * XSS 방지를 위한 입력값 정제(Sanitization) 유틸리티
+ * - HTML 태그 제거
+ * - 악성 스크립트 방지
+ * - 안전한 문자열 처리
+ */
+/**
+ * XSS 방지를 위한 HTML 태그 제거
+ * - 모든 HTML 태그 제거
+ * - 이스케이프된 HTML 엔티티 처리
+ * - 공백 정리
+ *
+ * @param input - 정제할 문자열
+ * @returns 정제된 문자열
+ *
+ * @example
+ * sanitizeHtml('<script>alert("xss")</script>Hello') // 'Hello'
+ * sanitizeHtml('Hello <b>World</b>') // 'Hello World'
+ */
+export declare function sanitizeHtml(input: string): string;
+/**
+ * JavaScript 이벤트 핸들러 제거
+ * - onclick, onerror 등 이벤트 핸들러 제거
+ *
+ * @param input - 정제할 문자열
+ * @returns 정제된 문자열
+ */
+export declare function removeEventHandlers(input: string): string;
+/**
+ * URL에서 JavaScript 프로토콜 제거
+ * - javascript:, data: 등 위험한 프로토콜 제거
+ *
+ * @param url - 검증할 URL
+ * @returns 안전한 URL 또는 빈 문자열
+ */
+export declare function sanitizeUrl(url: string): string;
+/**
+ * 모든 sanitization을 통합 적용
+ * - HTML 태그 제거
+ * - 이벤트 핸들러 제거
+ * - 공백 정규화
+ *
+ * @param input - 정제할 문자열
+ * @returns 정제된 문자열
+ */
+export declare function sanitizeInput(input: string): string;
+/**
+ * 배열의 모든 문자열 요소에 sanitization 적용
+ *
+ * @param arr - 정제할 문자열 배열
+ * @returns 정제된 문자열 배열
+ */
+export declare function sanitizeArray(arr: string[]): string[];
+/**
+ * 객체의 문자열 필드에 sanitization 적용
+ *
+ * @param obj - 정제할 객체
+ * @param fields - 정제할 필드 이름 배열
+ * @returns 정제된 객체
+ */
+export declare function sanitizeObjectFields<T extends Record<string, unknown>>(obj: T, fields: (keyof T)[]): T;
+declare const _default: {
+    sanitizeHtml: typeof sanitizeHtml;
+    sanitizeUrl: typeof sanitizeUrl;
+    sanitizeInput: typeof sanitizeInput;
+    sanitizeArray: typeof sanitizeArray;
+    sanitizeObjectFields: typeof sanitizeObjectFields;
+    removeEventHandlers: typeof removeEventHandlers;
+};
+export default _default;

package/dist/utils/sanitizer.js

@@ -0,0 +1,19 @@
+import {
+  removeEventHandlers,
+  sanitizeArray,
+  sanitizeHtml,
+  sanitizeInput,
+  sanitizeObjectFields,
+  sanitizeUrl,
+  sanitizer_default
+} from "../chunk-SR65BF6X.js";
+import "../chunk-ORMEWXMH.js";
+export {
+  sanitizer_default as default,
+  removeEventHandlers,
+  sanitizeArray,
+  sanitizeHtml,
+  sanitizeInput,
+  sanitizeObjectFields,
+  sanitizeUrl
+};

package/dist/utils/shared-utils.d.ts

@@ -0,0 +1,25 @@
+/**
+ * shared-utils (범용 유틸리티)
+ *
+ * 이 파일은 프로젝트 독립적인 범용 유틸리티만 포함합니다.
+ * URL shortener 비즈니스 로직은 <your-project>/utils/ 에 위치합니다.
+ *
+ * @see <your-project>/utils/alias-validation.ts - Alias 검증 관련 함수
+ */
+import type { IGeoLocationData, IGeoIPResponse } from '@withwiz/types/database';
+export type { IGeoLocationData, IGeoIPResponse };
+export * from './url-normalizer';
+export * from './format-number';
+export * from './short-code-generator';
+/**
+ * 에러 메시지 생성 (템플릿 변수 치환)
+ *
+ * @param code - 에러 코드
+ * @param message - 에러 메시지 템플릿
+ * @param replacements - 치환할 변수들
+ * @returns 에러 객체
+ */
+export declare function createValidationError(code: string, message: string, replacements?: Record<string, string>): {
+    code: string;
+    message: string;
+};

package/dist/utils/shared-utils.js

@@ -0,0 +1,43 @@
+import {
+  generateShortCode,
+  generateUniqueShortCode
+} from "../chunk-5ATB5D6S.js";
+import {
+  SUPPORTED_SCHEMES,
+  extractScheme,
+  getUrlType,
+  hasValidScheme,
+  isAppScheme,
+  isWebUrl,
+  normalizeUrl,
+  validateUrl
+} from "../chunk-VWODEQ5C.js";
+import {
+  formatChartNumber,
+  formatNumber
+} from "../chunk-TDZJ6SAI.js";
+import "../chunk-ORMEWXMH.js";
+
+// src/utils/shared-utils.ts
+function createValidationError(code, message, replacements = {}) {
+  let finalMessage = message;
+  Object.entries(replacements).forEach(([key, value]) => {
+    finalMessage = finalMessage.replace(`{${key}}`, value);
+  });
+  return { code, message: finalMessage };
+}
+export {
+  SUPPORTED_SCHEMES,
+  createValidationError,
+  extractScheme,
+  formatChartNumber,
+  formatNumber,
+  generateShortCode,
+  generateUniqueShortCode,
+  getUrlType,
+  hasValidScheme,
+  isAppScheme,
+  isWebUrl,
+  normalizeUrl,
+  validateUrl
+};

package/dist/utils/short-code-generator.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 단축 코드 생성 전용 유틸리티
+ * 순수 함수로 구현하여 외부 의존성 없음
+ */
+/**
+ * 기본 단축 코드 생성 함수
+ * @param length - 생성할 코드 길이 (기본값: 8)
+ * @returns 생성된 단축 코드
+ */
+export declare function generateShortCode(length?: number): string;
+/**
+ * 단축 코드 생성 옵션 인터페이스
+ */
+export interface IShortCodeOptions {
+    length?: number;
+    maxAttempts?: number;
+    checkDuplicate?: (code: string) => Promise<boolean> | boolean;
+}
+/**
+ * 중복 검사와 함께 고유한 단축 코드 생성
+ * @param options - 생성 옵션
+ * @returns 고유한 단축 코드
+ */
+export declare function generateUniqueShortCode(options?: IShortCodeOptions): Promise<string>;

package/dist/utils/short-code-generator.js

@@ -0,0 +1,9 @@
+import {
+  generateShortCode,
+  generateUniqueShortCode
+} from "../chunk-5ATB5D6S.js";
+import "../chunk-ORMEWXMH.js";
+export {
+  generateShortCode,
+  generateUniqueShortCode
+};

package/dist/utils/timezone.d.ts

@@ -0,0 +1,56 @@
+/**
+ * 글로벌 서비스를 위한 타임존 유틸리티
+ * 데이터베이스: UTC 저장
+ * 프론트엔드: 사용자 로컬 타임존 표시
+ */
+/**
+ * 현재 시간을 UTC로 반환 (데이터베이스 저장용)
+ */
+export declare function getCurrentUTC(): Date;
+/**
+ * UTC 시간을 사용자 로컬 타임존으로 변환
+ */
+export declare function utcToLocal(utcDate: Date | string, timezone?: string): Date;
+/**
+ * 사용자 로컬 시간을 UTC로 변환 (데이터베이스 저장용)
+ */
+export declare function localToUTC(localDate: Date | string): Date;
+/**
+ * 시간을 사용자 친화적인 형식으로 포맷팅 (로컬 타임존 기준)
+ */
+export declare function formatUserFriendlyDate(date: Date | string, options?: Intl.DateTimeFormatOptions): string;
+/**
+ * 간단한 날짜 포맷 (YYYY-MM-DD)
+ */
+export declare function formatSimpleDate(date: Date | string): string;
+/**
+ * 간단한 시간 포맷 (HH:MM:SS)
+ */
+export declare function formatSimpleTime(date: Date | string): string;
+/**
+ * 전체 날짜 시간 포맷 (YYYY-MM-DD HH:MM:SS)
+ */
+export declare function formatFullDateTime(date: Date | string): string;
+/**
+ * 테이블용 날짜 시간 포맷 (2줄 표시)
+ */
+export declare function formatTableDateTime(date: Date | string): {
+    date: string;
+    time: string;
+};
+/**
+ * Relative time display (e.g., "3h ago", "3d ago")
+ */
+export declare function getRelativeTime(date: Date | string): string;
+/**
+ * 타임존 정보 가져오기
+ */
+export declare function getUserTimezone(): string;
+/**
+ * 타임존 오프셋 가져오기 (분 단위)
+ */
+export declare function getTimezoneOffset(): number;
+/**
+ * UTC 시간을 ISO 문자열로 변환 (API 응답용)
+ */
+export declare function toUTCISOString(date: Date | string): string;

package/dist/utils/timezone.js

@@ -0,0 +1,29 @@
+import {
+  formatFullDateTime,
+  formatSimpleDate,
+  formatSimpleTime,
+  formatTableDateTime,
+  formatUserFriendlyDate,
+  getCurrentUTC,
+  getRelativeTime,
+  getTimezoneOffset,
+  getUserTimezone,
+  localToUTC,
+  toUTCISOString,
+  utcToLocal
+} from "../chunk-TRBKJ7JT.js";
+import "../chunk-ORMEWXMH.js";
+export {
+  formatFullDateTime,
+  formatSimpleDate,
+  formatSimpleTime,
+  formatTableDateTime,
+  formatUserFriendlyDate,
+  getCurrentUTC,
+  getRelativeTime,
+  getTimezoneOffset,
+  getUserTimezone,
+  localToUTC,
+  toUTCISOString,
+  utcToLocal
+};

package/dist/utils/type-guards.d.ts

@@ -0,0 +1,164 @@
+/**
+ * 범용 타입 가드 함수들
+ *
+ * 프로젝트 독립적인 런타임 타입 검증 유틸리티
+ * TypeScript의 타입 좁히기를 활용합니다.
+ */
+/**
+ * null이 아닌 값인지 확인
+ */
+export declare function isNotNull<T>(value: T | null): value is T;
+/**
+ * undefined가 아닌 값인지 확인
+ */
+export declare function isDefined<T>(value: T | undefined): value is T;
+/**
+ * null과 undefined가 아닌 값인지 확인
+ */
+export declare function isPresent<T>(value: T | null | undefined): value is T;
+/**
+ * 문자열인지 확인
+ */
+export declare function isString(value: unknown): value is string;
+/**
+ * 숫자인지 확인
+ */
+export declare function isNumber(value: unknown): value is number;
+/**
+ * boolean인지 확인
+ */
+export declare function isBoolean(value: unknown): value is boolean;
+/**
+ * 객체인지 확인 (null 제외)
+ */
+export declare function isObject(value: unknown): value is Record<string, unknown>;
+/**
+ * 배열인지 확인
+ */
+export declare function isArray<T = unknown>(value: unknown): value is T[];
+/**
+ * 함수인지 확인
+ */
+export declare function isFunction(value: unknown): value is Function;
+/**
+ * 유효한 이메일 형식인지 확인
+ */
+export declare function isValidEmail(value: unknown): value is string;
+/**
+ * 유효한 URL 형식인지 확인
+ */
+export declare function isValidUrl(value: unknown): value is string;
+/**
+ * 유효한 IPv4 주소인지 확인
+ */
+export declare function isIPv4(value: unknown): value is string;
+/**
+ * 유효한 IPv6 주소인지 확인
+ */
+export declare function isIPv6(value: unknown): value is string;
+/**
+ * 유효한 IP 주소인지 확인 (IPv4 또는 IPv6)
+ */
+export declare function isIPAddress(value: unknown): value is string;
+/**
+ * 유효한 Date 객체인지 확인
+ */
+export declare function isValidDate(value: unknown): value is Date;
+/**
+ * ISO 8601 날짜 문자열인지 확인
+ */
+export declare function isISODateString(value: unknown): value is string;
+/**
+ * 날짜 문자열로 파싱 가능한지 확인
+ */
+export declare function isDateParseable(value: unknown): value is string | number | Date;
+/**
+ * 정렬 순서 타입
+ */
+export type SortOrder = 'asc' | 'desc';
+/**
+ * 정렬 순서 타입 가드
+ */
+export declare function isSortOrder(value: unknown): value is SortOrder;
+/**
+ * API 성공 응답 타입
+ */
+export interface ApiSuccessResponse<T = unknown> {
+    success: true;
+    data: T;
+}
+/**
+ * API 에러 응답 타입
+ */
+export interface ApiErrorResponse {
+    success: false;
+    error: {
+        code: string;
+        message: string;
+    };
+}
+/**
+ * API 응답 유니온 타입
+ */
+export type ApiResponseType<T = unknown> = ApiSuccessResponse<T> | ApiErrorResponse;
+/**
+ * API 성공 응답인지 확인
+ */
+export declare function isApiSuccessResponse<T>(response: ApiResponseType<T>): response is ApiSuccessResponse<T>;
+/**
+ * API 에러 응답인지 확인
+ */
+export declare function isApiErrorResponse<T>(response: ApiResponseType<T>): response is ApiErrorResponse;
+/**
+ * 유효한 JSON 문자열인지 확인
+ */
+export declare function isValidJSON(value: unknown): value is string;
+/**
+ * JSON 직렬화 가능한지 확인
+ */
+export declare function isJSONSerializable(value: unknown): boolean;
+/**
+ * 빈 문자열인지 확인
+ */
+export declare function isEmptyString(value: unknown): value is '';
+/**
+ * 빈 배열인지 확인
+ */
+export declare function isEmptyArray(value: unknown): value is [];
+/**
+ * 빈 객체인지 확인
+ */
+export declare function isEmptyObject(value: unknown): boolean;
+/**
+ * 빈 값인지 확인 (null, undefined, '', [], {})
+ */
+export declare function isEmpty(value: unknown): boolean;
+declare const _default: {
+    isNotNull: typeof isNotNull;
+    isDefined: typeof isDefined;
+    isPresent: typeof isPresent;
+    isString: typeof isString;
+    isNumber: typeof isNumber;
+    isBoolean: typeof isBoolean;
+    isObject: typeof isObject;
+    isArray: typeof isArray;
+    isFunction: typeof isFunction;
+    isValidEmail: typeof isValidEmail;
+    isValidUrl: typeof isValidUrl;
+    isIPv4: typeof isIPv4;
+    isIPv6: typeof isIPv6;
+    isIPAddress: typeof isIPAddress;
+    isValidDate: typeof isValidDate;
+    isISODateString: typeof isISODateString;
+    isDateParseable: typeof isDateParseable;
+    isSortOrder: typeof isSortOrder;
+    isApiSuccessResponse: typeof isApiSuccessResponse;
+    isApiErrorResponse: typeof isApiErrorResponse;
+    isValidJSON: typeof isValidJSON;
+    isJSONSerializable: typeof isJSONSerializable;
+    isEmptyString: typeof isEmptyString;
+    isEmptyArray: typeof isEmptyArray;
+    isEmptyObject: typeof isEmptyObject;
+    isEmpty: typeof isEmpty;
+};
+export default _default;

package/dist/utils/type-guards.js

@@ -0,0 +1,59 @@
+import {
+  isApiErrorResponse,
+  isApiSuccessResponse,
+  isArray,
+  isBoolean,
+  isDateParseable,
+  isDefined,
+  isEmpty,
+  isEmptyArray,
+  isEmptyObject,
+  isEmptyString,
+  isFunction,
+  isIPAddress,
+  isIPv4,
+  isIPv6,
+  isISODateString,
+  isJSONSerializable,
+  isNotNull,
+  isNumber,
+  isObject,
+  isPresent,
+  isSortOrder,
+  isString,
+  isValidDate,
+  isValidEmail,
+  isValidJSON,
+  isValidUrl,
+  type_guards_default
+} from "../chunk-EUQATJLI.js";
+import "../chunk-ORMEWXMH.js";
+export {
+  type_guards_default as default,
+  isApiErrorResponse,
+  isApiSuccessResponse,
+  isArray,
+  isBoolean,
+  isDateParseable,
+  isDefined,
+  isEmpty,
+  isEmptyArray,
+  isEmptyObject,
+  isEmptyString,
+  isFunction,
+  isIPAddress,
+  isIPv4,
+  isIPv6,
+  isISODateString,
+  isJSONSerializable,
+  isNotNull,
+  isNumber,
+  isObject,
+  isPresent,
+  isSortOrder,
+  isString,
+  isValidDate,
+  isValidEmail,
+  isValidJSON,
+  isValidUrl
+};

package/dist/utils/url-normalizer.d.ts

@@ -0,0 +1,53 @@
+/**
+ * URL 정규화 및 검증 유틸리티
+ * 다양한 스키마(http, https, mailto, tel, 앱 스키마 등) 지원
+ */
+/**
+ * 지원되는 URL 스키마 목록
+ */
+export declare const SUPPORTED_SCHEMES: string[];
+/**
+ * URL이 유효한 스키마를 가지고 있는지 확인
+ */
+export declare function hasValidScheme(url: string): boolean;
+/**
+ * URL에서 스키마 추출
+ */
+export declare function extractScheme(url: string): string | null;
+/**
+ * URL 정규화
+ * - 스키마가 없으면 https:// 추가
+ * - 이미 유효한 스키마가 있으면 그대로 반환
+ * - 공백 제거 및 기본적인 정리
+ */
+export declare function normalizeUrl(url: string): string;
+/**
+ * URL 검증 결과의 메시지 키 (i18n용)
+ */
+export type UrlValidationMessageKey = 'validUrl' | 'urlRequired' | 'unsupportedProtocol' | 'invalidDomain' | 'invalidDomainFormat' | 'invalidEmail' | 'invalidPhone' | 'urlTooLong' | 'invalidUrlFormat';
+/**
+ * URL 검증 (다양한 스키마 지원)
+ * @param url 검증할 URL
+ * @param options.skipNormalization true이면 URL을 정규화하지 않고 검증 (기본: false)
+ */
+export declare function validateUrl(url: string, options?: {
+    skipNormalization?: boolean;
+}): {
+    isValid: boolean;
+    message: string;
+    messageKey: UrlValidationMessageKey;
+    messageParams?: Record<string, string>;
+    normalizedUrl?: string;
+};
+/**
+ * URL이 웹 URL인지 확인 (http 또는 https)
+ */
+export declare function isWebUrl(url: string): boolean;
+/**
+ * URL이 앱 스키마인지 확인
+ */
+export declare function isAppScheme(url: string): boolean;
+/**
+ * URL 타입 반환 (웹, 이메일, 전화, 앱 등)
+ */
+export declare function getUrlType(url: string): 'web' | 'email' | 'tel' | 'app' | 'other';