goodchuck-utils 1.2.0 → 1.3.0

package/dist/string/validation.js

@@ -0,0 +1,115 @@
+/**
+ * String Validation Utilities
+ */
+/**
+ * 빈 문자열 또는 공백만 있는지 확인
+ * @example isEmpty('') // true
+ * @example isEmpty('  ') // true
+ * @example isEmpty('hello') // false
+ */
+export function isEmpty(str) {
+    return !str || str.trim().length === 0;
+}
+/**
+ * 문자열이 특정 문자로 시작하는지 확인
+ * @example startsWith('hello', 'he') // true
+ */
+export function startsWith(str, searchString) {
+    return str.startsWith(searchString);
+}
+/**
+ * 문자열이 특정 문자로 끝나는지 확인
+ * @example endsWith('hello', 'lo') // true
+ */
+export function endsWith(str, searchString) {
+    return str.endsWith(searchString);
+}
+/**
+ * 문자열에 특정 문자열이 포함되어 있는지 확인
+ * @example contains('hello world', 'world') // true
+ */
+export function contains(str, searchString) {
+    return str.includes(searchString);
+}
+/**
+ * 알파벳만 포함하는지 확인
+ * @example isAlpha('hello') // true
+ * @example isAlpha('hello123') // false
+ */
+export function isAlpha(str) {
+    return /^[a-zA-Z]+$/.test(str);
+}
+/**
+ * 숫자만 포함하는지 확인
+ * @example isNumeric('123') // true
+ * @example isNumeric('123.45') // false
+ */
+export function isNumeric(str) {
+    return /^[0-9]+$/.test(str);
+}
+/**
+ * 알파벳과 숫자만 포함하는지 확인
+ * @example isAlphanumeric('hello123') // true
+ * @example isAlphanumeric('hello_123') // false
+ */
+export function isAlphanumeric(str) {
+    return /^[a-zA-Z0-9]+$/.test(str);
+}
+/**
+ * 소문자만 포함하는지 확인
+ * @example isLowerCase('hello') // true
+ * @example isLowerCase('Hello') // false
+ */
+export function isLowerCase(str) {
+    return str === str.toLowerCase() && str !== str.toUpperCase();
+}
+/**
+ * 대문자만 포함하는지 확인
+ * @example isUpperCase('HELLO') // true
+ * @example isUpperCase('Hello') // false
+ */
+export function isUpperCase(str) {
+    return str === str.toUpperCase() && str !== str.toLowerCase();
+}
+/**
+ * JSON 형식인지 확인
+ * @example isJSON('{"name":"John"}') // true
+ * @example isJSON('not json') // false
+ */
+export function isJSON(str) {
+    try {
+        JSON.parse(str);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 16진수 색상 코드인지 확인
+ * @example isHexColor('#fff') // true
+ * @example isHexColor('#ffffff') // true
+ * @example isHexColor('fff') // false
+ */
+export function isHexColor(str) {
+    return /^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$/.test(str);
+}
+/**
+ * UUID 형식인지 확인
+ * @example isUUID('123e4567-e89b-12d3-a456-426614174000') // true
+ */
+export function isUUID(str) {
+    return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(str);
+}
+/**
+ * Base64 인코딩된 문자열인지 확인
+ * @example isBase64('SGVsbG8gV29ybGQ=') // true
+ */
+export function isBase64(str) {
+    try {
+        return btoa(atob(str)) === str;
+    }
+    catch {
+        return false;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "goodchuck-utils",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "type": "module",
   "main": "dist/index.js",
   "scripts": {
@@ -18,6 +18,11 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "require": "./src/index.js"
+    },
+    "./hooks": {
+      "types": "./dist/hooks/index.d.ts",
+      "import": "./dist/hooks/index.js",
+      "require": "./src/hooks/index.js"
     }
   },
   "keywords": [],
@@ -33,7 +38,16 @@
     "src/**/*.ts"
   ],
   "devDependencies": {
+    "@types/react": "^19.2.8",
     "@vitest/ui": "^4.0.16",
     "vitest": "^4.0.16"
+  },
+  "peerDependencies": {
+    "react": ">=16.8.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
   }
 }

package/src/form/__tests__/formatter.test.ts

@@ -0,0 +1,97 @@
+import { describe, it, expect } from 'vitest';
+import {
+  formatPhoneNumber,
+  formatBusinessNumber,
+  formatCreditCard,
+  extractNumbers,
+  formatCurrency,
+  maskResidentNumber,
+  maskCreditCard,
+} from '../formatter';
+
+describe('Form Formatters', () => {
+  describe('formatPhoneNumber', () => {
+    it('should format phone numbers correctly', () => {
+      expect(formatPhoneNumber('01012345678')).toBe('010-1234-5678');
+      expect(formatPhoneNumber('0212345678')).toBe('021-2345-678');
+      expect(formatPhoneNumber('010')).toBe('010');
+      expect(formatPhoneNumber('0101234')).toBe('010-1234');
+    });
+
+    it('should handle already formatted numbers', () => {
+      expect(formatPhoneNumber('010-1234-5678')).toBe('010-1234-5678');
+    });
+
+    it('should limit to 11 digits', () => {
+      expect(formatPhoneNumber('010123456789999')).toBe('010-1234-5678');
+    });
+  });
+
+  describe('formatBusinessNumber', () => {
+    it('should format business numbers correctly', () => {
+      expect(formatBusinessNumber('1234567890')).toBe('123-45-67890');
+      expect(formatBusinessNumber('123')).toBe('123');
+      expect(formatBusinessNumber('12345')).toBe('123-45');
+    });
+
+    it('should limit to 10 digits', () => {
+      expect(formatBusinessNumber('12345678901234')).toBe('123-45-67890');
+    });
+  });
+
+  describe('formatCreditCard', () => {
+    it('should format credit card numbers', () => {
+      expect(formatCreditCard('1234567890123456')).toBe('1234-5678-9012-3456');
+      expect(formatCreditCard('1234')).toBe('1234');
+    });
+  });
+
+  describe('extractNumbers', () => {
+    it('should extract only numbers', () => {
+      expect(extractNumbers('abc123def456')).toBe('123456');
+      expect(extractNumbers('010-1234-5678')).toBe('01012345678');
+      expect(extractNumbers('no numbers')).toBe('');
+    });
+  });
+
+  describe('formatCurrency', () => {
+    it('should format numbers with commas', () => {
+      expect(formatCurrency(1234567)).toBe('1,234,567원');
+      expect(formatCurrency(1000)).toBe('1,000원');
+      expect(formatCurrency(0)).toBe('0원');
+    });
+
+    it('should handle string input', () => {
+      expect(formatCurrency('1234567')).toBe('1,234,567원');
+    });
+
+    it('should allow custom currency', () => {
+      expect(formatCurrency(1000, '달러')).toBe('1,000달러');
+    });
+
+    it('should handle invalid input', () => {
+      expect(formatCurrency('invalid')).toBe('0원');
+    });
+  });
+
+  describe('maskResidentNumber', () => {
+    it('should mask resident registration number', () => {
+      expect(maskResidentNumber('1234561234567')).toBe('123456-*******');
+      expect(maskResidentNumber('123456-1234567')).toBe('123456-*******');
+    });
+
+    it('should handle partial input', () => {
+      expect(maskResidentNumber('12345')).toBe('12345');
+    });
+  });
+
+  describe('maskCreditCard', () => {
+    it('should mask credit card number', () => {
+      expect(maskCreditCard('1234567890123456')).toBe('1234-****-****-3456');
+    });
+
+    it('should handle partial input', () => {
+      expect(maskCreditCard('1234567')).toBe('1234567');
+    });
+  });
+});

package/src/form/__tests__/helpers.test.ts

@@ -0,0 +1,53 @@
+import { describe, it, expect } from 'vitest';
+import {
+  hasFormErrors,
+  getChangedFields,
+  removeEmptyValues,
+} from '../helpers';
+
+describe('Form State Helpers', () => {
+  describe('hasFormErrors', () => {
+    it('should detect errors', () => {
+      expect(hasFormErrors({ email: 'error' })).toBe(true);
+      expect(hasFormErrors({})).toBe(false);
+    });
+  });
+
+  describe('getChangedFields', () => {
+    it('should return only changed fields', () => {
+      const original = { name: 'John', email: 'john@example.com', age: 30 };
+      const current = { name: 'Jane', email: 'john@example.com', age: 31 };
+      const changed = getChangedFields(original, current);
+
+      expect(changed).toEqual({ name: 'Jane', age: 31 });
+    });
+
+    it('should return empty object when nothing changed', () => {
+      const original = { name: 'John' };
+      const current = { name: 'John' };
+      expect(getChangedFields(original, current)).toEqual({});
+    });
+  });
+
+  describe('removeEmptyValues', () => {
+    it('should remove null, undefined, and empty strings', () => {
+      const input = {
+        name: 'John',
+        email: '',
+        age: null,
+        phone: undefined,
+        address: 'Seoul',
+      };
+
+      expect(removeEmptyValues(input)).toEqual({
+        name: 'John',
+        address: 'Seoul',
+      });
+    });
+
+    it('should keep zero values', () => {
+      const input = { count: 0, active: false };
+      expect(removeEmptyValues(input)).toEqual({ count: 0, active: false });
+    });
+  });
+});

package/src/form/__tests__/validation.test.ts

@@ -0,0 +1,84 @@
+import { describe, it, expect } from 'vitest';
+import {
+  isEmail,
+  isPhoneNumber,
+  isUrl,
+  isStrongPassword,
+  isBusinessNumber,
+} from '../validation';
+
+describe('Form Validation', () => {
+  describe('isEmail', () => {
+    it('should validate correct email formats', () => {
+      expect(isEmail('test@example.com')).toBe(true);
+      expect(isEmail('user.name@domain.co.kr')).toBe(true);
+      expect(isEmail('test+tag@example.com')).toBe(true);
+    });
+
+    it('should reject invalid email formats', () => {
+      expect(isEmail('invalid')).toBe(false);
+      expect(isEmail('test@')).toBe(false);
+      expect(isEmail('@example.com')).toBe(false);
+      expect(isEmail('test @example.com')).toBe(false);
+    });
+  });
+
+  describe('isPhoneNumber', () => {
+    it('should validate Korean phone numbers', () => {
+      expect(isPhoneNumber('010-1234-5678')).toBe(true);
+      expect(isPhoneNumber('01012345678')).toBe(true);
+      expect(isPhoneNumber('02-1234-5678')).toBe(true);
+      expect(isPhoneNumber('031-123-4567')).toBe(true);
+    });
+
+    it('should reject invalid phone numbers', () => {
+      expect(isPhoneNumber('123-456-7890')).toBe(false);
+      expect(isPhoneNumber('010-12-3456')).toBe(false);
+    });
+  });
+
+  describe('isUrl', () => {
+    it('should validate URLs', () => {
+      expect(isUrl('https://example.com')).toBe(true);
+      expect(isUrl('http://test.co.kr')).toBe(true);
+      expect(isUrl('https://example.com/path?query=1')).toBe(true);
+    });
+
+    it('should reject invalid URLs', () => {
+      expect(isUrl('not-a-url')).toBe(false);
+      expect(isUrl('example.com')).toBe(false);
+    });
+  });
+
+  describe('isStrongPassword', () => {
+    it('should validate strong passwords', () => {
+      expect(isStrongPassword('Password123!')).toBe(true);
+      expect(isStrongPassword('Str0ng#Pass')).toBe(true);
+    });
+
+    it('should reject weak passwords', () => {
+      expect(isStrongPassword('short')).toBe(false);
+      expect(isStrongPassword('NoNumbers!')).toBe(false);
+      expect(isStrongPassword('nouppercas3!')).toBe(false);
+      expect(isStrongPassword('NOLOWERCASE1!')).toBe(false);
+      expect(isStrongPassword('NoSpecialChar1')).toBe(false);
+    });
+
+    it('should respect custom options', () => {
+      expect(isStrongPassword('simple', { minLength: 6, requireUppercase: false, requireNumbers: false, requireSpecialChars: false })).toBe(true);
+      expect(isStrongPassword('PASSWORD', { requireLowercase: false, requireNumbers: false, requireSpecialChars: false })).toBe(true);
+    });
+  });
+
+  describe('isBusinessNumber', () => {
+    it('should validate 10-digit business numbers', () => {
+      expect(isBusinessNumber('1234567890')).toBe(true);
+      expect(isBusinessNumber('123-45-67890')).toBe(true);
+    });
+
+    it('should reject invalid business numbers', () => {
+      expect(isBusinessNumber('123456789')).toBe(false);
+      expect(isBusinessNumber('12345678901')).toBe(false);
+    });
+  });
+});

package/src/form/formatter.ts

@@ -0,0 +1,85 @@
+/**
+ * Form Formatter Utilities
+ */
+
+/**
+ * 전화번호 포맷팅 (010-1234-5678)
+ */
+export function formatPhoneNumber(value: string): string {
+  const cleaned = value.replace(/[^0-9]/g, '');
+
+  if (cleaned.length <= 3) return cleaned;
+  if (cleaned.length <= 7) {
+    return `${cleaned.slice(0, 3)}-${cleaned.slice(3)}`;
+  }
+  if (cleaned.length <= 11) {
+    return `${cleaned.slice(0, 3)}-${cleaned.slice(3, 7)}-${cleaned.slice(7)}`;
+  }
+
+  return `${cleaned.slice(0, 3)}-${cleaned.slice(3, 7)}-${cleaned.slice(7, 11)}`;
+}
+
+/**
+ * 사업자등록번호 포맷팅 (123-45-67890)
+ */
+export function formatBusinessNumber(value: string): string {
+  const cleaned = value.replace(/[^0-9]/g, '');
+
+  if (cleaned.length <= 3) return cleaned;
+  if (cleaned.length <= 5) {
+    return `${cleaned.slice(0, 3)}-${cleaned.slice(3)}`;
+  }
+  if (cleaned.length <= 10) {
+    return `${cleaned.slice(0, 3)}-${cleaned.slice(3, 5)}-${cleaned.slice(5)}`;
+  }
+
+  return `${cleaned.slice(0, 3)}-${cleaned.slice(3, 5)}-${cleaned.slice(5, 10)}`;
+}
+
+/**
+ * 신용카드 번호 포맷팅 (1234-5678-9012-3456)
+ */
+export function formatCreditCard(value: string): string {
+  const cleaned = value.replace(/[^0-9]/g, '');
+  const groups = cleaned.match(/.{1,4}/g);
+  return groups ? groups.join('-') : cleaned;
+}
+
+/**
+ * 숫자만 추출
+ */
+export function extractNumbers(value: string): string {
+  return value.replace(/[^0-9]/g, '');
+}
+
+/**
+ * 통화 포맷팅 (천 단위 콤마)
+ * @param value - 숫자 값
+ * @param currency - 통화 기호 (기본값: '원')
+ */
+export function formatCurrency(value: number | string, currency: string = '원'): string {
+  const num = typeof value === 'string' ? parseFloat(value) : value;
+  if (isNaN(num)) return '0' + currency;
+
+  return num.toLocaleString('ko-KR') + currency;
+}
+
+/**
+ * 주민등록번호 앞자리만 표시 (123456-*******)
+ */
+export function maskResidentNumber(value: string): string {
+  const cleaned = value.replace(/[^0-9]/g, '');
+  if (cleaned.length < 6) return cleaned;
+
+  return `${cleaned.slice(0, 6)}-${'*'.repeat(7)}`;
+}
+
+/**
+ * 카드번호 마스킹 (1234-****-****-5678)
+ */
+export function maskCreditCard(value: string): string {
+  const cleaned = value.replace(/[^0-9]/g, '');
+  if (cleaned.length < 12) return value;
+
+  return `${cleaned.slice(0, 4)}-****-****-${cleaned.slice(-4)}`;
+}

package/src/form/helpers.ts

@@ -0,0 +1,44 @@
+/**
+ * Form State Helpers
+ */
+
+/**
+ * 폼 에러가 있는지 확인
+ */
+export function hasFormErrors(errors: Record<string, any>): boolean {
+  return Object.keys(errors).length > 0;
+}
+
+/**
+ * 변경된 필드만 추출
+ */
+export function getChangedFields<T extends Record<string, any>>(
+  original: T,
+  current: T
+): Partial<T> {
+  const changed: Partial<T> = {};
+
+  for (const key in current) {
+    if (current[key] !== original[key]) {
+      changed[key] = current[key];
+    }
+  }
+
+  return changed;
+}
+
+/**
+ * 빈 값 제거 (null, undefined, 빈 문자열)
+ */
+export function removeEmptyValues<T extends Record<string, any>>(obj: T): Partial<T> {
+  const result: Partial<T> = {};
+
+  for (const key in obj) {
+    const value = obj[key];
+    if (value !== null && value !== undefined && value !== '') {
+      result[key] = value;
+    }
+  }
+
+  return result;
+}

package/src/form/index.ts

@@ -0,0 +1,14 @@
+/**
+ * Form Utilities
+ *
+ * This module provides utilities for form validation, formatting, and state management.
+ */
+
+// Validation utilities
+export * from './validation';
+
+// Formatter utilities
+export * from './formatter';
+
+// Helper utilities
+export * from './helpers';

package/src/form/validation.ts

@@ -0,0 +1,72 @@
+/**
+ * Form Validation Utilities
+ */
+
+/**
+ * 이메일 형식 검증
+ */
+export function isEmail(value: string): boolean {
+  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+  return emailRegex.test(value);
+}
+
+/**
+ * 한국 전화번호 형식 검증
+ * 010-1234-5678, 01012345678, 02-1234-5678 등 허용
+ */
+export function isPhoneNumber(value: string): boolean {
+  const phoneRegex = /^(01[016789]|02|0[3-9]{1}[0-9]{1})-?[0-9]{3,4}-?[0-9]{4}$/;
+  return phoneRegex.test(value.replace(/\s/g, ''));
+}
+
+/**
+ * URL 형식 검증
+ */
+export function isUrl(value: string): boolean {
+  try {
+    new URL(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 비밀번호 강도 검증
+ * @param value - 검증할 비밀번호
+ * @param options - 검증 옵션
+ */
+export function isStrongPassword(
+  value: string,
+  options: {
+    minLength?: number;
+    requireUppercase?: boolean;
+    requireLowercase?: boolean;
+    requireNumbers?: boolean;
+    requireSpecialChars?: boolean;
+  } = {}
+): boolean {
+  const {
+    minLength = 8,
+    requireUppercase = true,
+    requireLowercase = true,
+    requireNumbers = true,
+    requireSpecialChars = true,
+  } = options;
+
+  if (value.length < minLength) return false;
+  if (requireUppercase && !/[A-Z]/.test(value)) return false;
+  if (requireLowercase && !/[a-z]/.test(value)) return false;
+  if (requireNumbers && !/[0-9]/.test(value)) return false;
+  if (requireSpecialChars && !/[!@#$%^&*(),.?":{}|<>]/.test(value)) return false;
+
+  return true;
+}
+
+/**
+ * 한국 사업자등록번호 형식 검증 (10자리)
+ */
+export function isBusinessNumber(value: string): boolean {
+  const cleaned = value.replace(/[^0-9]/g, '');
+  return cleaned.length === 10;
+}

package/src/hooks/index.ts

@@ -0,0 +1,14 @@
+/**
+ * React Hooks
+ *
+ * This module provides React hooks for common use cases.
+ * Note: Requires React as a peer dependency.
+ */
+
+// Storage hooks
+export * from './useLocalStorage';
+export * from './useSessionStorage';
+
+// UI/UX hooks
+export * from './useMediaQuery';
+export * from './useClickOutside';