jell-utils 0.1.0 → 0.2.0

package/.taskmaster/docs/prd.txt

@@ -0,0 +1,584 @@
+---
+title: "jell-utils.js v0.2.0 - 기획서"
+category: Projects
+tags: [npm, typescript, utility-library, open-source, v0.2.0, update]
+created: 2025-12-26
+modified: 2025-12-26
+status: 🟡 Planning
+version: 0.2.0
+related: [[Archive/Completed_Projects/jell-utils.js/📊 개발 완료 보고서]], [[Projects MOC]]
+---
+
+# 📦 jell-utils.js v0.2.0 기획서
+
+> **한국어 특화 TypeScript 유틸리티 라이브러리 - 메이저 업데이트!**
+
+---
+
+## 📊 1. 프로젝트 개요
+
+### 1.1 현재 상태 (v0.1.0)
+
+| 항목 | 값 |
+| ---- | -- |
+| 버전 | v0.1.0 |
+| 배포일 | 2025-10-11 |
+| npm | https://www.npmjs.com/package/jell-utils |
+| GitHub | https://github.com/jellive/jell-utils.js |
+| 테스트 | 50개 (79.67% 커버리지) |
+| 함수 | 30개+ |
+
+### 1.2 v0.2.0 목표
+
+| 항목 | 목표 |
+| ---- | ---- |
+| 새 함수 | **+15개** (45개+ 총) |
+| 테스트 커버리지 | **90%+** (현재 79.67%) |
+| 카테고리 | **+3개** (날짜/숫자/검증) |
+| 한국어 특화 | **강화** (전화번호, 사업자번호 등) |
+
+### 1.3 예상 개발 시간
+
+| 작업 | 시간 |
+| ---- | ---- |
+| 날짜/시간 유틸리티 | 1시간 |
+| 숫자 포맷 유틸리티 | 1시간 |
+| 검증 유틸리티 | 1시간 |
+| 테스트 작성 | 1시간 |
+| 문서화 & 배포 | 30분 |
+| **합계** | **4-5시간** |
+
+---
+
+## ✨ 2. 새로운 기능
+
+### 2.1 📅 날짜/시간 유틸리티 (4개)
+
+#### `formatDate(date, format)`
+
+날짜를 원하는 형식으로 포맷
+
+```typescript
+import { formatDate } from 'jell-utils';
+
+formatDate(new Date(), 'YYYY-MM-DD'); // '2025-12-26'
+formatDate(new Date(), 'YYYY년 MM월 DD일'); // '2025년 12월 26일'
+formatDate(new Date(), 'YYYY/MM/DD HH:mm'); // '2025/12/26 14:30'
+```
+
+**지원 토큰**:
+- `YYYY`: 4자리 연도
+- `MM`: 2자리 월 (01-12)
+- `DD`: 2자리 일 (01-31)
+- `HH`: 2자리 시 (00-23)
+- `mm`: 2자리 분 (00-59)
+- `ss`: 2자리 초 (00-59)
+- `ddd`: 요일 (월, 화, 수, ...)
+- `dddd`: 요일 전체 (월요일, 화요일, ...)
+
+---
+
+#### `timeAgo(date)`
+
+상대적 시간 표시 (한국어)
+
+```typescript
+import { timeAgo } from 'jell-utils';
+
+timeAgo(new Date(Date.now() - 30000)); // '방금 전'
+timeAgo(new Date(Date.now() - 3600000)); // '1시간 전'
+timeAgo(new Date(Date.now() - 86400000)); // '어제'
+timeAgo(new Date(Date.now() - 172800000)); // '2일 전'
+timeAgo(new Date('2025-01-01')); // '11개월 전'
+```
+
+**시간 단위**:
+- 1분 미만: "방금 전"
+- 1시간 미만: "X분 전"
+- 24시간 미만: "X시간 전"
+- 48시간 미만: "어제"
+- 7일 미만: "X일 전"
+- 30일 미만: "X주 전"
+- 12개월 미만: "X개월 전"
+- 그 이상: "X년 전"
+
+---
+
+#### `getDaysInMonth(year, month)`
+
+해당 월의 일수 반환
+
+```typescript
+import { getDaysInMonth } from 'jell-utils';
+
+getDaysInMonth(2025, 2); // 28 (평년)
+getDaysInMonth(2024, 2); // 29 (윤년)
+getDaysInMonth(2025, 12); // 31
+```
+
+---
+
+#### `isLeapYear(year)`
+
+윤년 여부 확인
+
+```typescript
+import { isLeapYear } from 'jell-utils';
+
+isLeapYear(2024); // true
+isLeapYear(2025); // false
+isLeapYear(2000); // true
+isLeapYear(1900); // false
+```
+
+---
+
+### 2.2 💰 숫자 포맷 유틸리티 (5개)
+
+#### `formatNumber(number)`
+
+천 단위 쉼표 포맷
+
+```typescript
+import { formatNumber } from 'jell-utils';
+
+formatNumber(1000); // '1,000'
+formatNumber(1234567); // '1,234,567'
+formatNumber(1234.56); // '1,234.56'
+```
+
+---
+
+#### `formatCurrency(amount, currency?)`
+
+통화 포맷 (기본: 원화)
+
+```typescript
+import { formatCurrency } from 'jell-utils';
+
+formatCurrency(1000); // '1,000원'
+formatCurrency(1234567); // '1,234,567원'
+formatCurrency(1000, 'USD'); // '$1,000'
+formatCurrency(1000, 'EUR'); // '€1,000'
+formatCurrency(1000, 'JPY'); // '¥1,000'
+```
+
+---
+
+#### `formatFileSize(bytes, precision?)`
+
+파일 크기 포맷
+
+```typescript
+import { formatFileSize } from 'jell-utils';
+
+formatFileSize(1024); // '1 KB'
+formatFileSize(1048576); // '1 MB'
+formatFileSize(1073741824); // '1 GB'
+formatFileSize(1536, 2); // '1.50 KB'
+```
+
+---
+
+#### `numberToKorean(number)`
+
+숫자를 한글로 변환
+
+```typescript
+import { numberToKorean } from 'jell-utils';
+
+numberToKorean(123); // '백이십삼'
+numberToKorean(1234); // '천이백삼십사'
+numberToKorean(12345); // '만이천삼백사십오'
+numberToKorean(100000000); // '일억'
+```
+
+---
+
+#### `parseNumber(str)`
+
+문자열에서 숫자 추출
+
+```typescript
+import { parseNumber } from 'jell-utils';
+
+parseNumber('1,234'); // 1234
+parseNumber('1,234.56'); // 1234.56
+parseNumber('$1,000'); // 1000
+parseNumber('1,000원'); // 1000
+```
+
+---
+
+### 2.3 ✅ 검증 유틸리티 (6개)
+
+#### `isEmail(email)`
+
+이메일 주소 검증
+
+```typescript
+import { isEmail } from 'jell-utils';
+
+isEmail('test@example.com'); // true
+isEmail('invalid-email'); // false
+isEmail('test@test'); // false
+```
+
+---
+
+#### `isPhoneNumber(phone)`
+
+한국 전화번호 검증
+
+```typescript
+import { isPhoneNumber } from 'jell-utils';
+
+isPhoneNumber('010-1234-5678'); // true
+isPhoneNumber('01012345678'); // true
+isPhoneNumber('02-123-4567'); // true (지역번호)
+isPhoneNumber('1234-5678'); // false
+```
+
+---
+
+#### `isUrl(url)`
+
+URL 검증
+
+```typescript
+import { isUrl } from 'jell-utils';
+
+isUrl('https://example.com'); // true
+isUrl('http://localhost:3000'); // true
+isUrl('ftp://files.example.com'); // true
+isUrl('not-a-url'); // false
+```
+
+---
+
+#### `isBusinessNumber(brn)`
+
+한국 사업자등록번호 검증 (10자리)
+
+```typescript
+import { isBusinessNumber } from 'jell-utils';
+
+isBusinessNumber('123-45-67890'); // true (유효한 경우)
+isBusinessNumber('1234567890'); // true (하이픈 없이)
+isBusinessNumber('000-00-00000'); // false (무효)
+```
+
+**검증 알고리즘**: 국세청 사업자등록번호 검증 공식 적용
+
+---
+
+#### `formatPhoneNumber(phone)`
+
+전화번호 포맷팅
+
+```typescript
+import { formatPhoneNumber } from 'jell-utils';
+
+formatPhoneNumber('01012345678'); // '010-1234-5678'
+formatPhoneNumber('0212345678'); // '02-1234-5678'
+formatPhoneNumber('03112345678'); // '031-1234-5678'
+```
+
+---
+
+#### `formatBusinessNumber(brn)`
+
+사업자등록번호 포맷팅
+
+```typescript
+import { formatBusinessNumber } from 'jell-utils';
+
+formatBusinessNumber('1234567890'); // '123-45-67890'
+```
+
+---
+
+## 🏗️ 3. 기술 스펙
+
+### 3.1 프로젝트 구조
+
+```
+jell-utils.js/
+├── src/
+│   ├── index.ts              # 메인 엔트리
+│   ├── hangul/               # 한글 유틸리티 (기존)
+│   │   └── index.ts
+│   ├── string/               # 문자열 유틸리티 (기존)
+│   │   └── index.ts
+│   ├── object/               # 객체 유틸리티 (기존)
+│   │   └── index.ts
+│   ├── array/                # 배열 유틸리티 (기존)
+│   │   └── index.ts
+│   ├── async/                # 비동기 유틸리티 (기존)
+│   │   └── index.ts
+│   ├── date/                 # 🆕 날짜/시간 유틸리티
+│   │   ├── index.ts
+│   │   ├── formatDate.ts
+│   │   ├── timeAgo.ts
+│   │   ├── getDaysInMonth.ts
+│   │   └── isLeapYear.ts
+│   ├── number/               # 🆕 숫자 유틸리티
+│   │   ├── index.ts
+│   │   ├── formatNumber.ts
+│   │   ├── formatCurrency.ts
+│   │   ├── formatFileSize.ts
+│   │   ├── numberToKorean.ts
+│   │   └── parseNumber.ts
+│   └── validation/           # 🆕 검증 유틸리티
+│       ├── index.ts
+│       ├── isEmail.ts
+│       ├── isPhoneNumber.ts
+│       ├── isUrl.ts
+│       ├── isBusinessNumber.ts
+│       ├── formatPhoneNumber.ts
+│       └── formatBusinessNumber.ts
+├── __tests__/
+│   ├── date/                 # 🆕
+│   │   ├── formatDate.test.ts
+│   │   ├── timeAgo.test.ts
+│   │   ├── getDaysInMonth.test.ts
+│   │   └── isLeapYear.test.ts
+│   ├── number/               # 🆕
+│   │   ├── formatNumber.test.ts
+│   │   ├── formatCurrency.test.ts
+│   │   ├── formatFileSize.test.ts
+│   │   ├── numberToKorean.test.ts
+│   │   └── parseNumber.test.ts
+│   └── validation/           # 🆕
+│       ├── isEmail.test.ts
+│       ├── isPhoneNumber.test.ts
+│       ├── isUrl.test.ts
+│       ├── isBusinessNumber.test.ts
+│       ├── formatPhoneNumber.test.ts
+│       └── formatBusinessNumber.test.ts
+├── package.json
+├── tsconfig.json
+├── jest.config.js
+└── README.md
+```
+
+### 3.2 타입 정의
+
+```typescript
+// date/types.ts
+export type DateFormatToken = 
+  | 'YYYY' | 'MM' | 'DD' 
+  | 'HH' | 'mm' | 'ss' 
+  | 'ddd' | 'dddd';
+
+export interface TimeAgoOptions {
+  locale?: 'ko' | 'en';
+  now?: Date;
+}
+
+// number/types.ts
+export type CurrencyCode = 'KRW' | 'USD' | 'EUR' | 'JPY' | 'CNY';
+
+export interface FormatCurrencyOptions {
+  currency?: CurrencyCode;
+  showSymbol?: boolean;
+}
+
+// validation/types.ts
+export interface PhoneNumberOptions {
+  country?: 'KR' | 'US';
+  strict?: boolean;
+}
+```
+
+---
+
+## 🧪 4. 테스트 계획
+
+### 4.1 테스트 케이스 (예상 60개+)
+
+| 카테고리 | 함수 수 | 테스트 수 |
+| -------- | ------- | --------- |
+| 날짜/시간 | 4개 | 16개 |
+| 숫자 포맷 | 5개 | 20개 |
+| 검증 | 6개 | 24개 |
+| **합계** | **15개** | **60개+** |
+
+### 4.2 테스트 예시
+
+```typescript
+// __tests__/date/formatDate.test.ts
+describe('formatDate', () => {
+  it('should format date with YYYY-MM-DD', () => {
+    const date = new Date('2025-12-26');
+    expect(formatDate(date, 'YYYY-MM-DD')).toBe('2025-12-26');
+  });
+
+  it('should format date with Korean format', () => {
+    const date = new Date('2025-12-26');
+    expect(formatDate(date, 'YYYY년 MM월 DD일')).toBe('2025년 12월 26일');
+  });
+
+  it('should handle weekday tokens', () => {
+    const date = new Date('2025-12-26'); // 금요일
+    expect(formatDate(date, 'dddd')).toBe('금요일');
+    expect(formatDate(date, 'ddd')).toBe('금');
+  });
+});
+
+// __tests__/validation/isBusinessNumber.test.ts
+describe('isBusinessNumber', () => {
+  it('should validate correct business number', () => {
+    expect(isBusinessNumber('123-45-67890')).toBe(true);
+  });
+
+  it('should validate without hyphens', () => {
+    expect(isBusinessNumber('1234567890')).toBe(true);
+  });
+
+  it('should reject invalid checksum', () => {
+    expect(isBusinessNumber('000-00-00000')).toBe(false);
+  });
+});
+```
+
+### 4.3 커버리지 목표
+
+| 메트릭 | 현재 (v0.1.0) | 목표 (v0.2.0) |
+| ------ | ------------- | ------------- |
+| Statements | 79.67% | **90%+** |
+| Branches | 75.32% | **85%+** |
+| Functions | 85.14% | **95%+** |
+| Lines | 79.67% | **90%+** |
+
+---
+
+## 📅 5. 개발 일정
+
+### 5.1 Phase 1: 구현 (3시간)
+
+| 시간 | 작업 |
+| ---- | ---- |
+| 0:00-1:00 | 날짜/시간 유틸리티 4개 구현 |
+| 1:00-2:00 | 숫자 포맷 유틸리티 5개 구현 |
+| 2:00-3:00 | 검증 유틸리티 6개 구현 |
+
+### 5.2 Phase 2: 테스트 (1시간)
+
+| 시간 | 작업 |
+| ---- | ---- |
+| 3:00-3:30 | 테스트 작성 (60개+) |
+| 3:30-4:00 | 커버리지 확인 및 보완 |
+
+### 5.3 Phase 3: 배포 (30분)
+
+| 시간 | 작업 |
+| ---- | ---- |
+| 4:00-4:15 | README 업데이트 |
+| 4:15-4:30 | npm publish (v0.2.0) |
+
+---
+
+## 📊 6. 성공 기준
+
+### 6.1 필수 (Must Have)
+
+- [ ] 새 함수 15개 구현
+- [ ] 테스트 60개+ 작성
+- [ ] 커버리지 90%+ 달성
+- [ ] npm v0.2.0 배포
+- [ ] README 업데이트
+
+### 6.2 권장 (Should Have)
+
+- [ ] JSDoc 주석 모든 함수에 추가
+- [ ] 타입 정의 완벽하게 제공
+- [ ] 예제 코드 README에 추가
+
+### 6.3 선택 (Nice to Have)
+
+- [ ] 성능 벤치마크
+- [ ] CHANGELOG.md 작성
+- [ ] GitHub Release 생성
+
+---
+
+## 🔗 7. 참고 자료
+
+### 7.1 한국 검증 규칙
+
+**사업자등록번호 검증 공식**:
+```
+가중치: 1, 3, 7, 1, 3, 7, 1, 3, 5
+마지막 자리 = 10 - ((가중치 * 각 자리 합) % 10) % 10
+```
+
+**전화번호 정규식**:
+```typescript
+// 휴대폰
+/^01[016789]-?\d{3,4}-?\d{4}$/
+
+// 지역번호
+/^0[2-6][1-5]?-?\d{3,4}-?\d{4}$/
+```
+
+### 7.2 관련 프로젝트
+
+- **Lodash**: 범용 유틸리티 (참고)
+- **date-fns**: 날짜 유틸리티 (참고)
+- **validator.js**: 검증 유틸리티 (참고)
+
+---
+
+## 📝 8. 체크리스트
+
+### 개발 전
+
+- [ ] GitHub 레포 클론
+- [ ] 의존성 설치 (`npm install`)
+- [ ] 기존 테스트 통과 확인
+
+### 개발 중
+
+- [ ] 각 함수별 테스트 먼저 작성 (TDD)
+- [ ] 타입 정의 완벽하게
+- [ ] JSDoc 주석 추가
+
+### 배포 전
+
+- [ ] 모든 테스트 통과
+- [ ] 커버리지 90%+ 확인
+- [ ] README 업데이트
+- [ ] package.json 버전 업데이트 (0.1.0 → 0.2.0)
+- [ ] `npm publish`
+
+---
+
+## 🎯 9. 예상 결과
+
+### v0.2.0 릴리즈 후
+
+| 항목 | v0.1.0 | v0.2.0 |
+| ---- | ------ | ------ |
+| 함수 개수 | 30개+ | **45개+** |
+| 테스트 개수 | 50개 | **110개+** |
+| 커버리지 | 79.67% | **90%+** |
+| 카테고리 | 5개 | **8개** |
+| 한국어 특화 | 기본 | **강화** |
+
+### 포트폴리오 가치
+
+- ✅ npm 배포 경험
+- ✅ TypeScript 고급 활용
+- ✅ TDD 방법론
+- ✅ 오픈소스 기여
+- ✅ 한국어 특화 유틸리티 (차별화!)
+
+---
+
+_기획서 작성일: 2025-12-26_
+_작성자: PARA+GTD Automation Assistant 🤖_
+_프로젝트 상태: 🟡 Planning_
+
+#jell-utils #npm #typescript #v0.2.0 #update #planning
+

package/.taskmaster/state.json

@@ -0,0 +1,6 @@
+{
+  "currentTag": "master",
+  "lastSwitched": "2025-12-26T01:17:59.904Z",
+  "branchTagMapping": {},
+  "migrationNoticeShown": true
+}