speexjs-core 0.7.0

package/dist/date/index.d.ts

@@ -0,0 +1,588 @@
+/**
+ * Error thrown when a date value is invalid.
+ */
+declare class InvalidDateError extends Error {
+    constructor(input: unknown);
+}
+interface DateDiff {
+    years: number;
+    months: number;
+    days: number;
+    hours: number;
+    minutes: number;
+    seconds: number;
+}
+/**
+ * Formats a Date to a string using the given format pattern.
+ *
+ * Supported tokens:
+ * - `YYYY` — 4-digit year
+ * - `YY` — 2-digit year
+ * - `MMMM` — full month name
+ * - `MMM` — abbreviated month name
+ * - `MM` — 2-digit month (01–12)
+ * - `DD` — 2-digit day (01–31)
+ * - `HH` — 2-digit hours (00–23)
+ * - `mm` — 2-digit minutes
+ * - `ss` — 2-digit seconds
+ * - `SSS` — milliseconds
+ *
+ * @param date - The date to format.
+ * @param format - The format string (default `'YYYY-MM-DD'`).
+ * @returns The formatted date string.
+ */
+declare function formatDate(date: Date, format?: string): string;
+/**
+ * Parses a date from a string, number (timestamp in ms), or Date object.
+ *
+ * Supported string formats:
+ * - ISO (`YYYY-MM-DD`, `YYYY-MM-DDTHH:mm:ss`)
+ * - `DD/MM/YYYY` or `DD-MM-YYYY`
+ * - `DD MMM YYYY` or `DD MMMM YYYY`
+ * - Unix timestamp (milliseconds)
+ *
+ * @param input - The value to parse.
+ * @returns A valid Date object.
+ * @throws {InvalidDateError} If the input cannot be parsed.
+ */
+declare function parseDate(input: string | number | Date): Date;
+/**
+ * Computes the difference between two dates.
+ *
+ * @param date1 - Start date.
+ * @param date2 - End date.
+ * @returns An object with years, months, days, hours, minutes, seconds.
+ * @throws {InvalidDateError} If either date is invalid.
+ */
+declare function dateDiff(date1: Date, date2: Date): DateDiff;
+/**
+ * Adds days to a date.
+ *
+ * @param date - The original date.
+ * @param days - Number of days to add (negative to subtract).
+ * @returns A new Date.
+ * @throws {InvalidDateError} If the input date is invalid.
+ */
+declare function addDays(date: Date, days: number): Date;
+/**
+ * Adds months to a date. Handles month-end overflow (e.g., Jan 31 + 1 month
+ * becomes Feb 28).
+ *
+ * @param date - The original date.
+ * @param months - Number of months to add (negative to subtract).
+ * @returns A new Date.
+ * @throws {InvalidDateError} If the input date is invalid.
+ */
+declare function addMonths(date: Date, months: number): Date;
+/**
+ * Adds years to a date. Handles leap-year overflow (e.g., Feb 29 + 1 year
+ * becomes Feb 28).
+ *
+ * @param date - The original date.
+ * @param years - Number of years to add (negative to subtract).
+ * @returns A new Date.
+ * @throws {InvalidDateError} If the input date is invalid.
+ */
+declare function addYears(date: Date, years: number): Date;
+/**
+ * Returns the start of the day (00:00:00.000) for the given date.
+ *
+ * @param date - The date.
+ * @returns A new Date set to midnight.
+ * @throws {InvalidDateError} If the input date is invalid.
+ */
+declare function startOfDay(date: Date): Date;
+/**
+ * Returns the end of the day (23:59:59.999) for the given date.
+ *
+ * @param date - The date.
+ * @returns A new Date set to the last millisecond of the day.
+ * @throws {InvalidDateError} If the input date is invalid.
+ */
+declare function endOfDay(date: Date): Date;
+/**
+ * Returns the first moment of the month for the given date.
+ *
+ * @param date - The date.
+ * @returns A new Date set to the start of the month.
+ * @throws {InvalidDateError} If the input date is invalid.
+ */
+declare function startOfMonth(date: Date): Date;
+/**
+ * Returns the last moment of the month for the given date.
+ *
+ * @param date - The date.
+ * @returns A new Date set to the end of the month.
+ * @throws {InvalidDateError} If the input date is invalid.
+ */
+declare function endOfMonth(date: Date): Date;
+/**
+ * Returns the first moment of the year for the given date.
+ *
+ * @param date - The date.
+ * @returns A new Date set to Jan 1 00:00:00.000.
+ * @throws {InvalidDateError} If the input date is invalid.
+ */
+declare function startOfYear(date: Date): Date;
+/**
+ * Returns the last moment of the year for the given date.
+ *
+ * @param date - The date.
+ * @returns A new Date set to Dec 31 23:59:59.999.
+ * @throws {InvalidDateError} If the input date is invalid.
+ */
+declare function endOfYear(date: Date): Date;
+/**
+ * Checks if the date falls on a weekend (Saturday or Sunday).
+ *
+ * @param date - The date to check.
+ * @returns Whether the date is a weekend.
+ * @throws {InvalidDateError} If the input date is invalid.
+ */
+declare function isWeekend(date: Date): boolean;
+/**
+ * Checks if a year is a leap year.
+ *
+ * @param year - The year to check.
+ * @returns Whether the year is a leap year.
+ */
+declare function isLeapYear(year: number): boolean;
+/**
+ * Checks if `date1` is before `date2`.
+ *
+ * @param date1 - First date.
+ * @param date2 - Second date.
+ * @returns Whether `date1` is before `date2`.
+ * @throws {InvalidDateError} If either date is invalid.
+ */
+declare function isBefore(date1: Date, date2: Date): boolean;
+/**
+ * Checks if `date1` is after `date2`.
+ *
+ * @param date1 - First date.
+ * @param date2 - Second date.
+ * @returns Whether `date1` is after `date2`.
+ * @throws {InvalidDateError} If either date is invalid.
+ */
+declare function isAfter(date1: Date, date2: Date): boolean;
+/**
+ * Checks if a date is within the inclusive range [start, end].
+ *
+ * @param date - The date to check.
+ * @param start - Start of the range.
+ * @param end - End of the range.
+ * @returns Whether the date is between start and end.
+ * @throws {InvalidDateError} If any date is invalid.
+ */
+declare function isBetween(date: Date, start: Date, end: Date): boolean;
+/**
+ * Checks if a date is a business day (Monday to Friday).
+ *
+ * @param date - The date to check.
+ * @returns Whether the date is a business day.
+ */
+declare function isBusinessDay(date: Date): boolean;
+/**
+ * Adds business days (skipping weekends) to a date.
+ *
+ * @param date - The starting date.
+ * @param days - Number of business days to add (negative to subtract).
+ * @returns A new Date.
+ * @throws {InvalidDateError} If the input date is invalid.
+ */
+declare function addBusinessDays(date: Date, days: number): Date;
+/**
+ * Calculates age in years from a birth date.
+ *
+ * @param birthDate - The date of birth.
+ * @returns The age in years.
+ * @throws {InvalidDateError} If the birth date is invalid.
+ */
+declare function calculateAge(birthDate: Date): number;
+/**
+ * Returns a human-readable relative time string (e.g. "5 menit yang lalu").
+ *
+ * @param date - The past date.
+ * @param options - Options with locale ('id' by default, 'en' supported).
+ * @returns A relative time string.
+ */
+declare function timeAgo(date: Date, options?: {
+    locale?: string;
+}): string;
+/**
+ * Shows the time remaining until a future date.
+ *
+ * @param target - The target future date.
+ * @param options - Options with locale ('id' by default, 'en' supported).
+ * @returns A relative time string.
+ */
+declare function timeRemaining(target: Date, options?: {
+    locale?: string;
+}): string;
+/**
+ * Represents a duration split into calendar and time components.
+ */
+interface Duration {
+    years: number;
+    months: number;
+    days: number;
+    hours: number;
+    minutes: number;
+    seconds: number;
+}
+/**
+ * Formats a Duration object into a human-readable string.
+ *
+ * @example
+ * formatDuration({ hours: 2, minutes: 30, seconds: 15 }) // "2 jam 30 menit 15 detik"
+ * formatDuration({ hours: 2, minutes: 30 }, { locale: 'en' }) // "2 hours 30 minutes"
+ *
+ * @param duration - The duration to format.
+ * @param options - Options with locale ('id' by default, 'en' supported).
+ * @returns A formatted duration string.
+ */
+declare function formatDuration(duration: Duration, options?: {
+    locale?: string;
+}): string;
+/** UTC+7 — Western Indonesia Time (WIB). */
+declare const TIMEZONE_WIB = 7;
+/** UTC+8 — Central Indonesia Time (WITA). */
+declare const TIMEZONE_WITA = 8;
+/** UTC+9 — Eastern Indonesia Time (WIT). */
+declare const TIMEZONE_WIT = 9;
+/**
+ * Converts a date to a specific timezone offset by returning a new Date whose
+ * local-time getters (getHours, getMinutes etc.) reflect the target timezone.
+ *
+ * @param date - The source date.
+ * @param offsetHours - The timezone offset in hours (e.g. 7 for WIB).
+ * @returns A new Date adjusted to the target timezone.
+ * @throws {InvalidDateError} If the input date is invalid.
+ */
+declare function toTimezone(date: Date, offsetHours: number): Date;
+/**
+ * Formats a date in a specific timezone using `formatDate` tokens.
+ *
+ * @param date - The source date.
+ * @param format - The format string (see `formatDate` for supported tokens).
+ * @param offsetHours - The timezone offset in hours.
+ * @returns The formatted date string.
+ */
+declare function formatInTimezone(date: Date, format: string, offsetHours: number): string;
+/**
+ * Checks if a date is today.
+ *
+ * @param date - The date to check.
+ * @returns Whether the date is today.
+ * @throws {InvalidDateError} If the input date is invalid.
+ *
+ * @example
+ * isToday(new Date()) // true
+ */
+declare function isToday(date: Date): boolean;
+/**
+ * Checks if a date is yesterday.
+ *
+ * @param date - The date to check.
+ * @returns Whether the date is yesterday.
+ * @throws {InvalidDateError} If the input date is invalid.
+ *
+ * @example
+ * isYesterday(new Date(Date.now() - 86400000)) // true
+ */
+declare function isYesterday(date: Date): boolean;
+/**
+ * Checks if a date is tomorrow.
+ *
+ * @param date - The date to check.
+ * @returns Whether the date is tomorrow.
+ * @throws {InvalidDateError} If the input date is invalid.
+ *
+ * @example
+ * isTomorrow(new Date(Date.now() + 86400000)) // true
+ */
+declare function isTomorrow(date: Date): boolean;
+/**
+ * Checks if a date is in the past (before now).
+ *
+ * @param date - The date to check.
+ * @returns Whether the date is in the past.
+ * @throws {InvalidDateError} If the input date is invalid.
+ *
+ * @example
+ * isPast(new Date('2020-01-01')) // true
+ */
+declare function isPast(date: Date): boolean;
+/**
+ * Checks if a date is in the future (after now).
+ *
+ * @param date - The date to check.
+ * @returns Whether the date is in the future.
+ * @throws {InvalidDateError} If the input date is invalid.
+ *
+ * @example
+ * isFuture(new Date('2099-01-01')) // true
+ */
+declare function isFuture(date: Date): boolean;
+/**
+ * Checks if two dates fall on the same calendar day.
+ *
+ * @param date1 - First date.
+ * @param date2 - Second date.
+ * @returns Whether the dates are the same day.
+ * @throws {InvalidDateError} If either date is invalid.
+ *
+ * @example
+ * isSameDay(new Date('2024-01-01'), new Date('2024-01-01')) // true
+ */
+declare function isSameDay(date1: Date, date2: Date): boolean;
+/**
+ * Returns the number of days in the month of the given date.
+ *
+ * @param date - The date.
+ * @returns Number of days in the month (28–31).
+ * @throws {InvalidDateError} If the input date is invalid.
+ *
+ * @example
+ * daysInMonth(new Date('2024-02-01')) // 29 (leap year)
+ */
+declare function daysInMonth(date: Date): number;
+/**
+ * Returns the day of the year (1–366).
+ *
+ * @param date - The date.
+ * @returns Day of the year (1-indexed).
+ * @throws {InvalidDateError} If the input date is invalid.
+ *
+ * @example
+ * dayOfYear(new Date('2024-01-01')) // 1
+ */
+declare function dayOfYear(date: Date): number;
+/**
+ * Returns the ISO week number (1–53).
+ *
+ * The algorithm uses the Thursday of the same week as the reference
+ * to determine which year the week belongs to, per ISO 8601.
+ *
+ * @param date - The date.
+ * @returns The ISO week number.
+ * @throws {InvalidDateError} If the input date is invalid.
+ *
+ * @example
+ * weekOfYear(new Date('2024-01-01')) // 1
+ */
+declare function weekOfYear(date: Date): number;
+/**
+ * Returns the quarter of the year (1–4).
+ *
+ * @param date - The date.
+ * @returns The quarter (1 for Jan–Mar, 2 for Apr–Jun, etc.).
+ * @throws {InvalidDateError} If the input date is invalid.
+ *
+ * @example
+ * quarter(new Date('2024-04-01')) // 2
+ */
+declare function quarter(date: Date): number;
+/**
+ * Returns the latest (maximum) date from an array of dates.
+ *
+ * @param dates - Array of Date objects.
+ * @returns The latest date.
+ * @throws {Error} If the array is empty.
+ * @throws {InvalidDateError} If any date is invalid.
+ *
+ * @example
+ * maxDate([new Date('2024-01-01'), new Date('2025-01-01')]) // 2025-01-01
+ */
+declare function maxDate(dates: Date[]): Date;
+/**
+ * Returns the earliest (minimum) date from an array of dates.
+ *
+ * @param dates - Array of Date objects.
+ * @returns The earliest date.
+ * @throws {Error} If the array is empty.
+ * @throws {InvalidDateError} If any date is invalid.
+ *
+ * @example
+ * minDate([new Date('2024-01-01'), new Date('2025-01-01')]) // 2024-01-01
+ */
+declare function minDate(dates: Date[]): Date;
+/**
+ * Returns the next Monday from the given date.
+ *
+ * @param date - Reference date.
+ * @returns The next Monday.
+ * @throws {InvalidDateError} If the input date is invalid.
+ *
+ * @example
+ * nextMonday(new Date('2024-01-01')) // 2024-01-08 (Monday)
+ */
+declare function nextMonday(date: Date): Date;
+/**
+ * Returns the next Tuesday from the given date.
+ *
+ * @param date - Reference date.
+ * @returns The next Tuesday.
+ * @throws {InvalidDateError} If the input date is invalid.
+ *
+ * @example
+ * nextTuesday(new Date('2024-01-01')) // 2024-01-02 (Tuesday)
+ */
+declare function nextTuesday(date: Date): Date;
+/**
+ * Returns the next Wednesday from the given date.
+ *
+ * @param date - Reference date.
+ * @returns The next Wednesday.
+ * @throws {InvalidDateError} If the input date is invalid.
+ */
+declare function nextWednesday(date: Date): Date;
+/**
+ * Returns the next Thursday from the given date.
+ *
+ * @param date - Reference date.
+ * @returns The next Thursday.
+ * @throws {InvalidDateError} If the input date is invalid.
+ */
+declare function nextThursday(date: Date): Date;
+/**
+ * Returns the next Friday from the given date.
+ *
+ * @param date - Reference date.
+ * @returns The next Friday.
+ * @throws {InvalidDateError} If the input date is invalid.
+ */
+declare function nextFriday(date: Date): Date;
+/**
+ * Returns the next Saturday from the given date.
+ *
+ * @param date - Reference date.
+ * @returns The next Saturday.
+ * @throws {InvalidDateError} If the input date is invalid.
+ */
+declare function nextSaturday(date: Date): Date;
+/**
+ * Returns the next Sunday from the given date.
+ *
+ * @param date - Reference date.
+ * @returns The next Sunday.
+ * @throws {InvalidDateError} If the input date is invalid.
+ */
+declare function nextSunday(date: Date): Date;
+/**
+ * Returns the last (previous) Monday from the given date.
+ *
+ * @param date - Reference date.
+ * @returns The last Monday.
+ * @throws {InvalidDateError} If the input date is invalid.
+ *
+ * @example
+ * lastMonday(new Date('2024-01-03')) // 2024-01-01 (Monday)
+ */
+declare function lastMonday(date: Date): Date;
+/**
+ * Returns the last (previous) Tuesday from the given date.
+ *
+ * @param date - Reference date.
+ * @returns The last Tuesday.
+ * @throws {InvalidDateError} If the input date is invalid.
+ */
+declare function lastTuesday(date: Date): Date;
+/**
+ * Returns the last (previous) Wednesday from the given date.
+ *
+ * @param date - Reference date.
+ * @returns The last Wednesday.
+ * @throws {InvalidDateError} If the input date is invalid.
+ */
+declare function lastWednesday(date: Date): Date;
+/**
+ * Returns the last (previous) Thursday from the given date.
+ *
+ * @param date - Reference date.
+ * @returns The last Thursday.
+ * @throws {InvalidDateError} If the input date is invalid.
+ */
+declare function lastThursday(date: Date): Date;
+/**
+ * Returns the last (previous) Friday from the given date.
+ *
+ * @param date - Reference date.
+ * @returns The last Friday.
+ * @throws {InvalidDateError} If the input date is invalid.
+ *
+ * @example
+ * lastFriday(new Date('2024-01-03')) // 2023-12-29 (Friday)
+ */
+declare function lastFriday(date: Date): Date;
+/**
+ * Returns the last (previous) Saturday from the given date.
+ *
+ * @param date - Reference date.
+ * @returns The last Saturday.
+ * @throws {InvalidDateError} If the input date is invalid.
+ */
+declare function lastSaturday(date: Date): Date;
+/**
+ * Returns the last (previous) Sunday from the given date.
+ *
+ * @param date - Reference date.
+ * @returns The last Sunday.
+ * @throws {InvalidDateError} If the input date is invalid.
+ */
+declare function lastSunday(date: Date): Date;
+/**
+ * Parses a human-readable duration string into milliseconds.
+ *
+ * Supported units:
+ * - `w` — weeks
+ * - `d` — days
+ * - `h` — hours
+ * - `m` — minutes
+ * - `s` — seconds
+ *
+ * @param input - Duration string (e.g. `"1h30m"`, `"2d"`, `"1w2d6h"`).
+ * @returns Total milliseconds.
+ *
+ * @example
+ * parseDuration('1h30m') // 5400000
+ * parseDuration('2d') // 172800000
+ * parseDuration('1w') // 604800000
+ */
+declare function parseDuration(input: string): number;
+/**
+ * Checks if a date is an Indonesian public holiday.
+ *
+ * Includes fixed-date holidays (New Year, Labor Day, Pancasila Day,
+ * Independence Day, National Awakening Day, National Heroes Day, Christmas),
+ * Easter-based holidays (Good Friday, Easter, Ascension), and lookup-based
+ * movable holidays (Chinese New Year, Nyepi, Vesak, Eid al-Fitr,
+ * Eid al-Adha, Islamic New Year, Prophet's Birthday, Isra' Mi'raj).
+ *
+ * Movable holidays (Chinese New Year, Nyepi, Vesak, Islamic holidays) are
+ * precomputed for years 2024–2030. Dates outside this range may return
+ * `false` for those holidays.
+ *
+ * @param date - The date to check.
+ * @returns Whether the date is an Indonesian public holiday.
+ * @throws {InvalidDateError} If the input date is invalid.
+ *
+ * @example
+ * isHolidayIndonesia(new Date('2024-08-17')) // true (Independence Day)
+ * isHolidayIndonesia(new Date('2024-12-25')) // true (Christmas)
+ */
+declare function isHolidayIndonesia(date: Date): boolean;
+/**
+ * Returns the name(s) of Indonesian public holidays for a given date, or an
+ * empty array if the date is not a holiday.
+ *
+ * @param date - The date to check.
+ * @returns Array of holiday names.
+ * @throws {InvalidDateError} If the input date is invalid.
+ *
+ * @example
+ * getIndonesianHolidayNames(new Date('2024-08-17')) // ['Independence Day']
+ */
+declare function getIndonesianHolidayNames(date: Date): string[];
+
+export { type DateDiff, type Duration, InvalidDateError, TIMEZONE_WIB, TIMEZONE_WIT, TIMEZONE_WITA, addBusinessDays, addDays, addMonths, addYears, calculateAge, dateDiff, dayOfYear, daysInMonth, endOfDay, endOfMonth, endOfYear, formatDate, formatDuration, formatInTimezone, getIndonesianHolidayNames, isAfter, isBefore, isBetween, isBusinessDay, isFuture, isHolidayIndonesia, isLeapYear, isPast, isSameDay, isToday, isTomorrow, isWeekend, isYesterday, lastFriday, lastMonday, lastSaturday, lastSunday, lastThursday, lastTuesday, lastWednesday, maxDate, minDate, nextFriday, nextMonday, nextSaturday, nextSunday, nextThursday, nextTuesday, nextWednesday, parseDate, parseDuration, quarter, startOfDay, startOfMonth, startOfYear, timeAgo, timeRemaining, toTimezone, weekOfYear };