npm package: @jaeyeong/week-utils
Description: Week utilities: month week + ISO week
Latest version: 0.1.1

# @jaeyeong/week-utils

월 주차(Month-based week)와 ISO-8601 주차(ISO week) 유틸리티 함수를 제공하는 TypeScript 라이브러리입니다.

## 설치

```bash
npm i @jaeyeong/week-utils
```

## 기능

### 1. 월 주차 (Month-based week)

해당 월의 몇 주차인지 계산하고, 특정 주차의 날짜 범위를 구할 수 있습니다.

#### `getMonthWeek(dateInput, weekStart?)`

날짜를 받아서 해당 월의 몇 주차인지 반환합니다 (1~5/6).

**파라미터:**
- `dateInput`: `Date` 객체 또는 날짜 문자열
- `weekStart`: 주의 시작일 (`"monday"` | `"sunday"`), 기본값: `"monday"`

**반환값:** `number` (1~5/6)

**예시:**
```ts
import { getMonthWeek } from "@jaeyeong/week-utils";

getMonthWeek("2024-01-22"); // 4 (월요일 기준)
getMonthWeek("2024-01-28", "sunday"); // 4 (일요일 기준)
getMonthWeek(new Date(2024, 0, 15)); // 3
```

#### `getMonthWeekRange(year, month, weekNumber, weekStart?)`

연/월/주차를 받아서 해당 주차의 시작일과 종료일을 반환합니다.

**파라미터:**
- `year`: 연도 (예: 2024)
- `month`: 월 (1~12)
- `weekNumber`: 주차 (1~6)
- `weekStart`: 주의 시작일 (`"monday"` | `"sunday"`), 기본값: `"monday"`

**반환값:** `{ start: Date, end: Date }`

**예시:**
```ts
import { getMonthWeekRange } from "@jaeyeong/week-utils";

// 2024년 1월 4주차의 날짜 범위
const { start, end } = getMonthWeekRange(2024, 1, 4);
console.log(start); // 2024-01-21 (월요일)
console.log(end);   // 2024-01-27 (일요일)

// 일요일 기준으로 계산
const { start: sunStart, end: sunEnd } = getMonthWeekRange(2024, 1, 4, "sunday");
console.log(sunStart); // 2024-01-20 (일요일)
console.log(sunEnd);   // 2024-01-26 (토요일)
```

### 2. ISO 주차 (ISO-8601 week)

ISO 8601 표준에 따른 연간 주차를 계산합니다. ISO 주차는 월요일을 주의 시작으로 하며, 연말/연초에 ISO 주차 연도가 바뀔 수 있습니다.

#### `getISOWeekYear(dateInput)`

ISO week-year를 구합니다. 연말/연초에 ISO 주차 연도가 바뀔 수 있습니다.

**파라미터:**
- `dateInput`: `Date` 객체 또는 날짜 문자열

**반환값:** `number` (ISO week-year)

**예시:**
```ts
import { getISOWeekYear } from "@jaeyeong/week-utils";

getISOWeekYear("2024-01-01"); // 2024
getISOWeekYear("2023-12-31"); // 2023
getISOWeekYear("2024-01-05"); // 2024 (ISO 주차 기준으로는 2024년 1주차)
```

#### `getISOWeek(dateInput)`

ISO week number를 반환합니다 (1~52/53).

**파라미터:**
- `dateInput`: `Date` 객체 또는 날짜 문자열

**반환값:** `number` (1~52/53)

**예시:**
```ts
import { getISOWeek } from "@jaeyeong/week-utils";

getISOWeek("2024-01-28"); // 4
getISOWeek("2024-01-01"); // 1
```

#### `getISOWeekRange(isoYear, isoWeek)`

ISO year/week를 받아서 해당 주의 시작일(월요일)과 종료일(일요일)을 반환합니다.

**파라미터:**
- `isoYear`: ISO week-year
- `isoWeek`: ISO week number (1~53)

**반환값:** `{ start: Date, end: Date }`

**예시:**
```ts
import { getISOWeekRange } from "@jaeyeong/week-utils";

// 2024년 ISO 4주차의 날짜 범위
const { start, end } = getISOWeekRange(2024, 4);
console.log(start); // 2024-01-22 (월요일)
console.log(end);   // 2024-01-28 (일요일)
```

## 전체 예시

```ts
import {
  getMonthWeek,
  getMonthWeekRange,
  getISOWeek,
  getISOWeekYear,
  getISOWeekRange,
  type WeekStart,
} from "@jaeyeong/week-utils";

// 월 주차
const week = getMonthWeek("2024-01-22"); // 4
const { start, end } = getMonthWeekRange(2024, 1, 4);

// ISO 주차
const isoWeek = getISOWeek("2024-01-28"); // 4
const isoYear = getISOWeekYear("2024-01-01"); // 2024
const { start: isoStart, end: isoEnd } = getISOWeekRange(2024, 4);
```

## 타입

```ts
type WeekStart = "monday" | "sunday";
```

## 라이선스

MIT