@zwoninstitute/il-gaemi
Version:
Temporal 기반 Typescript 날짜/시간 유틸리티 패키지
796 lines (788 loc) • 31.6 kB
TypeScript
import { Temporal } from '@js-temporal/polyfill';
export { Temporal } from '@js-temporal/polyfill';
/**
* Supported date/time format types for the format function.
*
* @example
* ```typescript
* // Different format types produce different outputs
* const date = Temporal.PlainDate.from('2024-01-15');
*
* format(date, 'date'); // "2024-01-15"
* format(date, 'datetime'); // "2024-01-15 00:00:00"
* format(date, 'iso'); // "2024-01-15"
* format(date, 'custom', 'YYYY/MM/DD'); // "2024/01/15"
* ```
*/
type DateFormatType = "date" | "time" | "datetime" | "iso" | "custom";
/**
* Day of the week type using ISO weekday numbering.
*
* Uses the ISO 8601 standard where:
* - 1 = Monday
* - 2 = Tuesday
* - 3 = Wednesday
* - 4 = Thursday
* - 5 = Friday
* - 6 = Saturday
* - 7 = Sunday
*
* @example
* ```typescript
* const weekday: WeekDay = getWeekDay('2024-01-15'); // 1 (Monday)
*
* // Check if it's a weekend
* const isWeekend = (day: WeekDay) => day === 6 || day === 7;
* console.log(isWeekend(weekday)); // false
*
* // Custom weekend definition (e.g., Friday-Saturday)
* const customWeekend: WeekDay[] = [5, 6];
* ```
*/
type WeekDay = 1 | 2 | 3 | 4 | 5 | 6 | 7;
/**
* Holiday information interface for business day calculations.
*
* Represents a holiday that can affect business day calculations.
* Supports both one-time holidays and recurring annual holidays.
*
* @example
* ```typescript
* // One-time holiday
* const newYear2024: Holiday = {
* date: '2024-01-01',
* name: 'New Year\'s Day 2024',
* recurring: false
* };
*
* // Recurring annual holiday
* const christmas: Holiday = {
* date: '2024-12-25',
* name: 'Christmas Day',
* recurring: true // Will apply to December 25th every year
* };
*
* // Holiday list for business day calculations
* const holidays: Holiday[] = [
* { date: '2024-01-01', name: 'New Year\'s Day', recurring: true },
* { date: '2024-07-04', name: 'Independence Day', recurring: true },
* { date: '2024-12-25', name: 'Christmas Day', recurring: true },
* { date: '2024-11-28', name: 'Special Event', recurring: false }
* ];
*
* const isWorkday = isWorkday('2024-12-25', holidays); // false
* ```
*/
interface Holiday {
/** The holiday date in YYYY-MM-DD format */
date: string;
/** The name or description of the holiday */
name: string;
/**
* Whether this holiday recurs annually.
* When true, the holiday will be recognized every year on the same month and day.
* When false or undefined, the holiday applies only to the specific year in the date.
*/
recurring?: boolean;
}
/**
* Type aliases for Temporal API objects for convenience and consistency.
*
* These aliases provide shorter, more convenient names for commonly used
* Temporal types throughout the library.
*
* @example
* ```typescript
* // Instead of writing Temporal.ZonedDateTime
* const zoned: ZonedDateTime = getNow();
*
* // Instead of writing Temporal.PlainDate
* const date: PlainDate = Temporal.PlainDate.from('2024-01-15');
*
* // Function parameter types
* function processDateTime(dt: PlainDateTime): string {
* return format(dt, 'datetime');
* }
*
* // Timezone handling
* const timezone: TimeZone = 'America/New_York';
* const converted = convertToZonedDateTime(date, timezone);
* ```
*/
/** Represents a date and time with timezone information */
type ZonedDateTime = Temporal.ZonedDateTime;
/** Represents a date without time or timezone information */
type PlainDate = Temporal.PlainDate;
/** Represents a time without date or timezone information */
type PlainTime = Temporal.PlainTime;
/** Represents a date and time without timezone information */
type PlainDateTime = Temporal.PlainDateTime;
/**
* Represents a timezone identifier string.
*
* Can be:
* - IANA timezone names (e.g., 'America/New_York', 'Asia/Seoul', 'Europe/London')
* - UTC offset strings (e.g., '+09:00', '-05:00')
* - 'UTC' for Coordinated Universal Time
*/
type TimeZone = string;
/**
* Determines whether a given date is a business day (workday).
*
* A business day is defined as a day that is:
* - Not a weekend day (configurable, defaults to Saturday and Sunday)
* - Not a holiday from the provided holiday list
*
* @param date - The date to check. Can be a Temporal.PlainDate object or an ISO date string (YYYY-MM-DD)
* @param holidayList - An array of holiday objects. Each holiday can be either a one-time holiday or a recurring annual holiday
* @param dayOffWeekdays - An array of weekday numbers representing non-working days. Uses ISO weekday numbering (1=Monday, 7=Sunday). Defaults to [6, 7] (Saturday, Sunday)
* @returns `true` if the date is a business day, `false` otherwise
*
* @example
* ```typescript
* // Check if a specific date is a workday
* const isWorkday1 = isWorkday('2024-01-15'); // true (Monday)
* const isWorkday2 = isWorkday('2024-01-13'); // false (Saturday)
*
* // With custom holidays
* const holidays = [
* { date: '2024-01-01', recurring: false }, // New Year's Day
* { date: '2024-12-25', recurring: true } // Christmas (recurring)
* ];
* const isWorkday3 = isWorkday('2024-01-01', holidays); // false
*
* // With custom weekend days (e.g., Friday-Saturday weekend)
* const isWorkday4 = isWorkday('2024-01-12', [], [5, 6]); // false (Friday in this case)
* ```
*/
declare function isWorkday(date: PlainDate | string, holidayList?: Holiday[], dayOffWeekdays?: WeekDay[]): boolean;
/**
* Returns the day of the week for a given date using ISO weekday numbering.
*
* @param date - The date to get the weekday for. Can be a Temporal.PlainDate object or an ISO date string (YYYY-MM-DD)
* @returns The weekday number (1=Monday, 2=Tuesday, ..., 7=Sunday)
*
* @example
* ```typescript
* const weekday1 = getWeekDay('2024-01-15'); // 1 (Monday)
* const weekday2 = getWeekDay('2024-01-14'); // 7 (Sunday)
*
* // Using with Temporal.PlainDate
* const date = Temporal.PlainDate.from('2024-01-16');
* const weekday3 = getWeekDay(date); // 2 (Tuesday)
* ```
*/
declare function getWeekDay(date: PlainDate | string): WeekDay;
/**
* Calculates which week number a given date belongs to within its month.
*
* The week calculation follows these rules:
* - Weeks start on Monday (ISO week date system)
* - If the Monday of the week containing the given date falls in a different month,
* the week number is calculated based on that Monday's month
* - Week numbering starts from 1
*
* @param date - The date to calculate the week number for. Can be a Temporal.PlainDate object or an ISO date string (YYYY-MM-DD)
* @returns An object containing the year, month, and week number that the date belongs to
*
* @example
* ```typescript
* // For a date in the middle of a month
* const week1 = getWeekNum('2024-01-15'); // { year: 2024, month: 1, weekNum: 3 }
*
* // For a date where the Monday falls in the previous month
* const week2 = getWeekNum('2024-02-01'); // Might return { year: 2024, month: 1, weekNum: 5 }
*
* // Using with Temporal.PlainDate
* const date = Temporal.PlainDate.from('2024-01-31');
* const week3 = getWeekNum(date); // { year: 2024, month: 1, weekNum: 5 }
* ```
*/
declare function getWeekNum(date: PlainDate | string): {
month: number;
year: number;
weekNum: number;
};
/**
* Finds the next business day after a given date.
*
* This function will increment the date by one day repeatedly until it finds
* a day that qualifies as a business day according to the `isWorkday` function.
*
* @param date - The starting date. Can be a Temporal.PlainDate object or an ISO date string (YYYY-MM-DD)
* @param holidayList - An array of holiday objects to consider when determining business days
* @returns The next business day as a Temporal.PlainDate object
*
* @example
* ```typescript
* // Find next workday after Friday
* const nextWorkday1 = getNextWorkday('2024-01-12'); // 2024-01-15 (Monday)
*
* // Find next workday considering holidays
* const holidays = [{ date: '2024-01-15', recurring: false }];
* const nextWorkday2 = getNextWorkday('2024-01-12', holidays); // 2024-01-16 (Tuesday)
*
* // Using with Temporal.PlainDate
* const date = Temporal.PlainDate.from('2024-01-31');
* const nextWorkday3 = getNextWorkday(date); // 2024-02-01 or next available workday
* ```
*/
declare function getNextWorkday(date: PlainDate | string, holidayList?: Holiday[], dayOffWeekdays?: WeekDay[]): PlainDate;
/**
* Finds the previous business day before a given date.
*
* This function will decrement the date by one day repeatedly until it finds
* a day that qualifies as a business day according to the `isWorkday` function.
*
* @param date - The starting date. Can be a Temporal.PlainDate object or an ISO date string (YYYY-MM-DD)
* @param holidayList - An array of holiday objects to consider when determining business days
* @returns The previous business day as a Temporal.PlainDate object
*
* @example
* ```typescript
* // Find previous workday before Monday
* const prevWorkday1 = getPreviousWorkday('2024-01-15'); // 2024-01-12 (Friday)
*
* // Find previous workday considering holidays
* const holidays = [{ date: '2024-01-12', recurring: false }];
* const prevWorkday2 = getPreviousWorkday('2024-01-15', holidays); // 2024-01-11 (Thursday)
*
* // Using with Temporal.PlainDate
* const date = Temporal.PlainDate.from('2024-02-01');
* const prevWorkday3 = getPreviousWorkday(date); // 2024-01-31 or previous available workday
* ```
*/
declare function getPreviousWorkday(date: PlainDate | string, holidayList?: Holiday[], dayOffWeekdays?: WeekDay[]): PlainDate;
/**
* Default timezone for the library (Korea Standard Time).
*
* This constant is used as the default timezone throughout the library
* when no specific timezone is provided.
*/
declare const DEFAULT_TIMEZONE = "Asia/Seoul";
/**
* Returns the current date and time in Asia/Seoul timezone.
*
* This is a convenience function that provides the current moment
* in Korean Standard Time (KST).
*
* @returns The current ZonedDateTime in Asia/Seoul timezone
*
* @example
* ```typescript
* const now = getNow();
* console.log(now.toString()); // "2024-01-15T14:30:00+09:00[Asia/Seoul]"
*
* // Access individual components
* console.log(now.year); // 2024
* console.log(now.month); // 1
* console.log(now.day); // 15
* console.log(now.hour); // 14
* ```
*/
declare function getNow(): ZonedDateTime;
/**
* Creates a date in the default timezone (Asia/Seoul).
*
* @param year - The year
* @param month - The month (1-12)
* @param day - The day (1-31)
* @returns A ZonedDateTime object in the default timezone
*
* @example
* ```typescript
* const date = getDate(2024, 1, 15);
* console.log(date.toString()); // "2024-01-15T00:00:00+09:00[Asia/Seoul]"
* ```
*/
declare function getDate(year: number, month: number, day: number): ZonedDateTime;
/**
* Creates a date and time in the default timezone (Asia/Seoul).
*
* @param year - The year
* @param month - The month (1-12)
* @param day - The day (1-31)
* @param hour - The hour (0-23)
* @param minute - The minute (0-59)
* @param second - The second (0-59, optional)
* @param millisecond - The millisecond (0-999, optional)
* @param microsecond - The microsecond (0-999, optional)
* @param nanosecond - The nanosecond (0-999, optional)
* @returns A ZonedDateTime object in the default timezone
*
* @example
* ```typescript
* const dateTime = getDateTime(2024, 1, 15, 14, 30, 45, 123, 456, 789);
* console.log(dateTime.toString()); // "2024-01-15T14:30:45.123456789+09:00[Asia/Seoul]"
* ```
*/
declare function getDateTime(year: number, month: number, day: number, hour: number, minute: number, second?: number, millisecond?: number, microsecond?: number, nanosecond?: number): ZonedDateTime;
/**
* Creates a date and time in UTC timezone.
*
* @param year - The year
* @param month - The month (1-12)
* @param day - The day (1-31)
* @param hour - The hour (0-23)
* @param minute - The minute (0-59)
* @param second - The second (0-59, optional)
* @param millisecond - The millisecond (0-999, optional)
* @param microsecond - The microsecond (0-999, optional)
* @param nanosecond - The nanosecond (0-999, optional)
* @returns A ZonedDateTime object in UTC timezone
*
* @example
* ```typescript
* const utcDateTime = getDateTimeUTC(2024, 1, 15, 14, 30, 45);
* console.log(utcDateTime.toString()); // "2024-01-15T14:30:45+00:00[UTC]"
* ```
*/
declare function getDateTimeUTC(year: number, month: number, day: number, hour: number, minute: number, second?: number, millisecond?: number, microsecond?: number, nanosecond?: number): ZonedDateTime;
/**
* Creates a date in UTC timezone.
*
* @param year - The year
* @param month - The month (1-12)
* @param day - The day (1-31)
* @returns A ZonedDateTime object in UTC timezone
*
* @example
* ```typescript
* const utcDate = getDateUTC(2024, 1, 15);
* console.log(utcDate.toString()); // "2024-01-15T00:00:00+00:00[UTC]"
* ```
*/
declare function getDateUTC(year: number, month: number, day: number): ZonedDateTime;
/**
* Creates a PlainTime object with time information.
*
* @param hour - The hour (0-23)
* @param minute - The minute (0-59)
* @param second - The second (0-59, optional)
* @param millisecond - The millisecond (0-999, optional)
* @param microsecond - The microsecond (0-999, optional)
* @param nanosecond - The nanosecond (0-999, optional)
* @returns A PlainTime object
*
* @example
* ```typescript
* const time = getTime(14, 30, 45, 123, 456, 789);
* console.log(time.toString()); // "14:30:45.123456789"
* ```
*/
declare function getTime(hour: number, minute: number, second?: number, millisecond?: number, microsecond?: number, nanosecond?: number): Temporal.PlainTime;
/**
* Returns the current date and time in UTC timezone.
*
* This function provides the current moment in Coordinated Universal Time (UTC),
* which is useful for storing timestamps in a timezone-neutral format.
*
* @returns The current ZonedDateTime in UTC timezone
*
* @example
* ```typescript
* const nowUTC = getNowUTC();
* console.log(nowUTC.toString()); // "2024-01-15T05:30:00+00:00[UTC]"
*
* // Compare with local time
* const nowLocal = getNow();
* console.log(nowLocal.toString()); // "2024-01-15T14:30:00+09:00[Asia/Seoul]"
*
* // Both represent the same instant
* console.log(nowUTC.epochMilliseconds === nowLocal.epochMilliseconds); // true
* ```
*/
declare function getNowUTC(): ZonedDateTime;
/**
* Converts a date/time to a ZonedDateTime in the specified timezone.
*
* This function handles various input types and converts them to a ZonedDateTime
* with the specified timezone. It's particularly useful for timezone conversions
* and ensuring consistent timezone handling throughout an application.
*
* @param date - The date/time to convert. Can be a ZonedDateTime, PlainDateTime, or an ISO string
* @param timeZone - The target timezone. Defaults to Asia/Seoul
* @returns A ZonedDateTime in the specified timezone
*
* @example
* ```typescript
* // From string (date only) - assumes start of day in target timezone
* const zoned1 = convertToZonedDateTime('2024-01-15');
* console.log(zoned1.toString()); // "2024-01-15T00:00:00+09:00[Asia/Seoul]"
*
* // From ISO datetime string - converts to target timezone
* const zoned2 = convertToZonedDateTime('2024-01-15T12:00:00Z', 'America/New_York');
* console.log(zoned2.toString()); // "2024-01-15T07:00:00-05:00[America/New_York]"
*
* // From PlainDateTime - interprets in target timezone
* const plainDT = Temporal.PlainDateTime.from('2024-01-15T12:00:00');
* const zoned3 = convertToZonedDateTime(plainDT, 'Europe/London');
* console.log(zoned3.toString()); // "2024-01-15T12:00:00+00:00[Europe/London]"
*
* // From existing ZonedDateTime - converts to new timezone
* const existing = Temporal.Now.zonedDateTimeISO('UTC');
* const converted = convertToZonedDateTime(existing, 'Asia/Tokyo');
* // Same instant, different timezone representation
* ```
*/
declare function convertToZonedDateTime(date: ZonedDateTime | Temporal.PlainDateTime | string, timeZone?: string): ZonedDateTime;
/**
* Converts a ZonedDateTime to UTC timezone.
*
* This function takes a ZonedDateTime in any timezone and returns
* the equivalent moment in UTC. The instant in time remains the same,
* only the timezone representation changes.
*
* @param zonedDateTime - The ZonedDateTime to convert to UTC
* @returns The same instant represented in UTC timezone
*
* @example
* ```typescript
* // Convert Korean time to UTC
* const kst = Temporal.ZonedDateTime.from('2024-01-15T14:30:00+09:00[Asia/Seoul]');
* const utc = toUTC(kst);
* console.log(utc.toString()); // "2024-01-15T05:30:00+00:00[UTC]"
*
* // The epoch milliseconds are identical (same instant)
* console.log(kst.epochMilliseconds === utc.epochMilliseconds); // true
*
* // Different timezone representations
* console.log(kst.timeZone.id); // "Asia/Seoul"
* console.log(utc.timeZone.id); // "UTC"
* ```
*/
declare function toUTC(zonedDateTime: ZonedDateTime): ZonedDateTime;
/**
* Converts a UTC ZonedDateTime to a specified timezone.
*
* This function takes a ZonedDateTime in UTC and converts it to
* the specified timezone. This is the inverse operation of `toUTC`.
*
* @param utcDateTime - The UTC ZonedDateTime to convert
* @param timeZone - The target timezone. Defaults to Asia/Seoul
* @returns The same instant represented in the target timezone
*
* @example
* ```typescript
* // Start with UTC time
* const utc = Temporal.ZonedDateTime.from('2024-01-15T05:30:00+00:00[UTC]');
*
* // Convert to different timezones
* const kst = fromUTC(utc); // Default to Asia/Seoul
* console.log(kst.toString()); // "2024-01-15T14:30:00+09:00[Asia/Seoul]"
*
* const est = fromUTC(utc, 'America/New_York');
* console.log(est.toString()); // "2024-01-15T00:30:00-05:00[America/New_York]"
*
* const jst = fromUTC(utc, 'Asia/Tokyo');
* console.log(jst.toString()); // "2024-01-15T14:30:00+09:00[Asia/Tokyo]"
*
* // All represent the same instant
* console.log(utc.epochMilliseconds === kst.epochMilliseconds); // true
* ```
*/
declare function fromUTC(utcDateTime: ZonedDateTime, timeZone?: string): ZonedDateTime;
/**
* Calculates the time difference between two timezones in hours.
*
* This function determines how many hours ahead or behind the target timezone
* is compared to the source timezone. Positive values indicate the target
* is ahead, negative values indicate it's behind.
*
* @param fromTimeZone - The source timezone to compare from
* @param toTimeZone - The target timezone to compare to
* @param referenceDate - The reference date for calculation. Defaults to current time in Asia/Seoul. This is important for timezones with daylight saving time
* @returns The time difference in hours (positive if target is ahead, negative if behind)
*
* @example
* ```typescript
* // Calculate offset from UTC to different timezones
* const utcToKst = getTimeZoneOffset('UTC', 'Asia/Seoul');
* console.log(utcToKst); // 9 (KST is UTC+9)
*
* const utcToEst = getTimeZoneOffset('UTC', 'America/New_York');
* console.log(utcToEst); // -5 (EST is UTC-5) or -4 (EDT is UTC-4) depending on date
*
* // Calculate offset between non-UTC timezones
* const kstToJst = getTimeZoneOffset('Asia/Seoul', 'Asia/Tokyo');
* console.log(kstToJst); // 0 (both are UTC+9)
*
* const kstToEst = getTimeZoneOffset('Asia/Seoul', 'America/New_York');
* console.log(kstToEst); // -14 (or -13 during EDT)
*
* // With specific reference date (useful for historical calculations)
* const summerDate = Temporal.ZonedDateTime.from('2024-07-15T12:00:00+09:00[Asia/Seoul]');
* const summerOffset = getTimeZoneOffset('UTC', 'America/New_York', summerDate);
* console.log(summerOffset); // -4 (EDT in summer)
*
* const winterDate = Temporal.ZonedDateTime.from('2024-01-15T12:00:00+09:00[Asia/Seoul]');
* const winterOffset = getTimeZoneOffset('UTC', 'America/New_York', winterDate);
* console.log(winterOffset); // -5 (EST in winter)
* ```
*/
declare function getTimeZoneOffset(fromTimeZone: string, toTimeZone: string, referenceDate?: ZonedDateTime): number;
/**
* Formats a Temporal date/time object into a string representation.
*
* This function provides flexible formatting options for various Temporal types,
* supporting predefined formats (date, time, datetime, iso) as well as custom formatting.
*
* @param date - The date/time to format. Can be a ZonedDateTime, PlainDate, PlainDateTime, or an ISO string
* @param type - The format type to use. Defaults to "datetime"
* @param formatString - Custom format string (required when type is "custom"). Supports tokens like YYYY, MM, DD, HH, mm, ss
* @returns The formatted date/time string
*
* @throws {Error} When PlainDate is used with "time" format type
* @throws {Error} When formatString is not provided for "custom" type
* @throws {Error} When an unsupported format type is provided
*
* @example
* ```typescript
* // Basic formatting
* const date = Temporal.PlainDate.from('2024-01-15');
* const formatted1 = format(date, 'date'); // "2024-01-15"
* const formatted2 = format(date, 'datetime'); // "2024-01-15 00:00:00"
*
* // With ZonedDateTime
* const zonedDate = Temporal.Now.zonedDateTimeISO('Asia/Seoul');
* const formatted3 = format(zonedDate, 'iso'); // ISO 8601 format
*
* // Custom formatting
* const formatted4 = format(date, 'custom', 'YYYY/MM/DD'); // "2024/01/15"
* const formatted5 = format(zonedDate, 'custom', 'YYYY-MM-DD HH:mm'); // "2024-01-15 14:30"
*
* // From string input
* const formatted6 = format('2024-01-15', 'date'); // "2024-01-15"
* ```
*/
declare function format(date: ZonedDateTime | PlainDate | PlainDateTime | string, type?: DateFormatType, formatString?: string): string;
/**
* Formats a date in Korean style (e.g., "2024년 1월 15일").
*
* This is a convenience function that uses the custom format with Korean suffixes.
*
* @param date - The date to format. Can be a ZonedDateTime, PlainDate, PlainDateTime, or an ISO string
* @returns A Korean-formatted date string
*
* @example
* ```typescript
* const date = Temporal.PlainDate.from('2024-01-15');
* const korean = formatKorean(date); // "2024년 1월 15일"
*
* const datetime = Temporal.ZonedDateTime.from('2024-01-15T14:30:00+09:00[Asia/Seoul]');
* const korean2 = formatKorean(datetime); // "2024년 1월 15일"
*
* // From string
* const korean3 = formatKorean('2024-12-25'); // "2024년 12월 25일"
* ```
*/
declare function formatKorean(date: ZonedDateTime | PlainDate | PlainDateTime | string): string;
/**
* Formats a date as a relative time expression (e.g., "3 days ago", "2 hours later").
*
* This function calculates the time difference between the given date and a base date,
* then returns a human-readable relative time string in Korean.
*
* @param date - The target date to compare. Can be a ZonedDateTime, PlainDate, PlainDateTime, or an ISO string
* @param baseDate - The reference date for comparison. Defaults to current time in Asia/Seoul timezone
* @returns A Korean relative time string
*
* @example
* ```typescript
* const now = Temporal.Now.zonedDateTimeISO('Asia/Seoul');
* const yesterday = now.subtract({ days: 1 });
* const tomorrow = now.add({ days: 1 });
* const twoHoursLater = now.add({ hours: 2 });
* const fiveMinutesAgo = now.subtract({ minutes: 5 });
*
* formatRelative(yesterday); // "1일 전"
* formatRelative(tomorrow); // "1일 후"
* formatRelative(twoHoursLater); // "2시간 후"
* formatRelative(fiveMinutesAgo); // "5분 전"
*
* // With custom base date
* const baseDate = Temporal.ZonedDateTime.from('2024-01-15T12:00:00+09:00[Asia/Seoul]');
* const targetDate = '2024-01-16T12:00:00+09:00[Asia/Seoul]';
* formatRelative(targetDate, baseDate); // "1일 후"
*
* // Very recent times
* const justNow = now.subtract({ seconds: 30 });
* formatRelative(justNow); // "방금 전"
* ```
*/
declare function formatRelative(date: ZonedDateTime | PlainDate | PlainDateTime | string, baseDate?: ZonedDateTime): string;
/**
* 📚 **DATABASE STORAGE RECOMMENDATIONS**
*
* When storing Temporal data in databases, consider these patterns:
*
* **BEST PRACTICE: Two-field approach for ZonedDateTime**
* ```sql
* CREATE TABLE events (
* id SERIAL PRIMARY KEY,
* event_time_utc TIMESTAMP NOT NULL, -- Always UTC
* event_timezone VARCHAR(50) NOT NULL -- e.g., 'Asia/Seoul'
* );
* ```
*
* **GOOD: Single field with Instant/ZonedDateTime**
* ```typescript
* // Store Instant or ZonedDateTime.epochMilliseconds
* const instant = Temporal.Now.instant();
* const date = temporalToDate(instant); // No data loss
* ```
*
* **CAUTION: Single field with Plain types**
* ```typescript
* // Requires timezone assumption - document this clearly!
* const plainDate = Temporal.PlainDate.from('2024-01-15');
* const date = temporalToDate(plainDate); // Assumes Asia/Seoul
* ```
*
* **AVOID: Storing timezone-less data without clear rules**
* - Always document which timezone Plain types assume
* - Consider using explicit functions like plainDateToDate() instead
*/
/**
* Converts a Temporal object to a JavaScript Date object for database storage.
*
* This function handles the conversion from various Temporal types to Date objects
* that can be stored in database columns. It ensures proper timezone handling
* and maintains the exact moment in time.
*
* ⚠️ **IMPORTANT TIMEZONE CONSIDERATIONS:**
* - `Temporal.Instant` and `Temporal.ZonedDateTime`: No data loss (recommended)
* - `Temporal.PlainDateTime` and `Temporal.PlainDate`: **Timezone assumption required**
* - These are interpreted in the DEFAULT_TIMEZONE (Asia/Seoul)
* - This is an arbitrary decision that may not match your intent
* - Consider using ZonedDateTime instead for explicit timezone handling
*
* @param temporal - The Temporal object to convert
* @returns A JavaScript Date object representing the same moment in time
*
* @example
* ```typescript
* // ✅ Recommended: No data loss
* const instant = Temporal.Now.instant();
* const zonedDateTime = getNow();
* const dateFromInstant = temporalToDate(instant);
* const dateFromZoned = temporalToDate(zonedDateTime);
*
* // ⚠️ Timezone assumption: Interpreted as Asia/Seoul
* const plainDate = Temporal.PlainDate.from('2024-01-15');
* const dateFromPlain = temporalToDate(plainDate);
* // This assumes 2024-01-15 00:00:00 in Asia/Seoul timezone!
*
* const plainDateTime = Temporal.PlainDateTime.from('2024-01-15T14:30:00');
* const dateFromPlainDT = temporalToDate(plainDateTime);
* // This assumes the time is in Asia/Seoul timezone!
* ```
*/
declare function temporalToDate(temporal: Temporal.Instant | ZonedDateTime | PlainDate | PlainDateTime | null | undefined): Date | null;
/**
* Converts a JavaScript Date object to a ZonedDateTime in the specified timezone.
*
* This function converts Date objects from the database back into ZonedDateTime
* objects with proper timezone information. The default timezone is Asia/Seoul
* but can be customized.
*
* @param date - The Date object to convert
* @param timeZone - The target timezone (defaults to Asia/Seoul)
* @returns A ZonedDateTime object in the specified timezone
*
* @example
* ```typescript
* const date = new Date('2024-01-15T05:30:00.000Z');
* const zoned = dateToZonedDateTime(date);
* console.log(zoned.timeZoneId); // "Asia/Seoul"
* console.log(zoned.hour); // 14 (5:30 UTC = 14:30 KST)
*
* // Convert to different timezone
* const nyTime = dateToZonedDateTime(date, 'America/New_York');
* console.log(nyTime.hour); // 0 (5:30 UTC = 00:30 EST)
* ```
*/
declare function dateToZonedDateTime(date: Date | null | undefined, timeZone?: string): ZonedDateTime | null;
/**
* Converts a JavaScript Date object to a PlainDate.
*
* This function extracts the date components from a Date object and creates
* a PlainDate. The conversion uses the default timezone to determine the
* local date representation.
*
* @param date - The Date object to convert
* @param timeZone - The timezone to use for date calculation (defaults to Asia/Seoul)
* @returns A PlainDate object representing the date in the specified timezone
*
* @example
* ```typescript
* const date = new Date('2024-01-15T05:30:00.000Z');
* const plainDate = dateToPlainDate(date);
* console.log(plainDate.toString()); // "2024-01-15" (in Asia/Seoul timezone)
*
* // Same instant, different timezone
* const utcPlainDate = dateToPlainDate(date, 'UTC');
* console.log(utcPlainDate.toString()); // "2024-01-15" (in UTC)
* ```
*/
declare function dateToPlainDate(date: Date | null | undefined, timeZone?: string): PlainDate | null;
/**
* Converts a JavaScript Date object to a PlainDateTime.
*
* This function extracts the date and time components from a Date object
* and creates a PlainDateTime. The conversion uses the specified timezone
* to determine the local representation.
*
* @param date - The Date object to convert
* @param timeZone - The timezone to use for calculation (defaults to Asia/Seoul)
* @returns A PlainDateTime object representing the date and time in the specified timezone
*
* @example
* ```typescript
* const date = new Date('2024-01-15T05:30:00.000Z');
* const plainDateTime = dateToPlainDateTime(date);
* console.log(plainDateTime.toString()); // "2024-01-15T14:30:00" (in Asia/Seoul)
*
* // Same instant, different timezone
* const utcPlainDateTime = dateToPlainDateTime(date, 'UTC');
* console.log(utcPlainDateTime.toString()); // "2024-01-15T05:30:00" (in UTC)
* ```
*/
declare function dateToPlainDateTime(date: Date | null | undefined, timeZone?: string): PlainDateTime | null;
/**
* Base error class for all zwon-date-function errors
*/
declare class DateError extends Error {
constructor(message: string);
}
/**
* Error thrown when an invalid date format is encountered
*/
declare class InvalidDateFormatError extends DateError {
constructor(dateString: string, supportedFormats?: string[]);
}
/**
* Error thrown when an invalid date value is encountered
*/
declare class InvalidDateError extends DateError {
constructor(dateString: string);
}
/**
* Error thrown when an unsupported format type is used
*/
declare class UnsupportedFormatTypeError extends DateError {
constructor(formatType: string, supportedTypes?: string[]);
}
/**
* Error thrown when a required parameter is missing
*/
declare class MissingParameterError extends DateError {
constructor(parameterName: string);
}
/**
* Error thrown when an incompatible operation is attempted
*/
declare class IncompatibleOperationError extends DateError {
constructor(operation: string, reason: string);
}
export { DEFAULT_TIMEZONE, DateError, type DateFormatType, type Holiday, IncompatibleOperationError, InvalidDateError, InvalidDateFormatError, MissingParameterError, type PlainDate, type PlainDateTime, type PlainTime, type TimeZone, UnsupportedFormatTypeError, type WeekDay, type ZonedDateTime, convertToZonedDateTime, dateToPlainDate, dateToPlainDateTime, dateToZonedDateTime, format, formatKorean, formatRelative, fromUTC, getDate, getDateTime, getDateTimeUTC, getDateUTC, getNextWorkday, getNow, getNowUTC, getPreviousWorkday, getTime, getTimeZoneOffset, getWeekDay, getWeekNum, isWorkday, temporalToDate, toUTC };