@indodev/toolkit 0.3.3 → 0.4.0

package/dist/datetime/index.d.ts

@@ -0,0 +1,412 @@
+/**
+ * Custom error classes for datetime module
+ *
+ * @module datetime/types
+ * @packageDocumentation
+ */
+/**
+ * Error thrown when an invalid date is provided to a function.
+ * Extends native Error with a `code` property for programmatic error handling.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   formatDate('invalid');
+ * } catch (error) {
+ *   if (error instanceof InvalidDateError) {
+ *     console.log(error.code); // 'INVALID_DATE'
+ *   }
+ * }
+ * ```
+ */
+declare class InvalidDateError extends Error {
+    /** Error code for programmatic identification */
+    readonly code: "INVALID_DATE";
+    constructor(message?: string);
+}
+/**
+ * Error thrown when an invalid date range is provided.
+ * Extends native Error with a `code` property for programmatic error handling.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   formatDateRange(new Date('2026-01-05'), new Date('2026-01-01'));
+ * } catch (error) {
+ *   if (error instanceof InvalidDateRangeError) {
+ *     console.log(error.code); // 'INVALID_DATE_RANGE'
+ *   }
+ * }
+ * ```
+ */
+declare class InvalidDateRangeError extends Error {
+    /** Error code for programmatic identification */
+    readonly code: "INVALID_DATE_RANGE";
+    constructor(message?: string);
+}
+/**
+ * Date formatting style options
+ */
+type DateStyle = 'full' | 'long' | 'medium' | 'short' | 'weekday' | 'month';
+/**
+ * Options for getAge function
+ */
+interface AgeOptions {
+    /**
+     * Reference date to calculate age from.
+     * Defaults to current date at function call time.
+     * @defaultValue new Date()
+     */
+    fromDate?: Date | string | number;
+    /**
+     * Return age as formatted string instead of object.
+     * @defaultValue false
+     */
+    asString?: boolean;
+}
+/**
+ * Age calculation result object
+ */
+interface AgeResult {
+    /** Full years */
+    years: number;
+    /** Remaining months (0-11) */
+    months: number;
+    /** Remaining days (0-30) */
+    days: number;
+}
+
+/**
+ * Constants for Indonesian datetime formatting
+ *
+ * @module datetime/constants
+ * @packageDocumentation
+ */
+/** Full Indonesian month names (1-indexed: index 0 = empty, 1 = Januari) */
+declare const MONTH_NAMES: readonly string[];
+/** Short Indonesian month names (3-letter abbreviation) */
+declare const MONTH_NAMES_SHORT: readonly string[];
+/** Full Indonesian day names */
+declare const DAY_NAMES: readonly string[];
+/** Short Indonesian day names (3-letter abbreviation) */
+declare const DAY_NAMES_SHORT: readonly string[];
+/** Mapping of IANA timezone names to Indonesian abbreviations */
+declare const TIMEZONE_MAP: Readonly<Record<string, 'WIB' | 'WITA' | 'WIT'>>;
+/** Valid UTC offset hours that map to Indonesian timezones */
+declare const VALID_UTC_OFFSETS: readonly number[];
+
+/**
+ * Date calculation utilities
+ *
+ * @module datetime/calc
+ * @packageDocumentation
+ */
+/**
+ * Check if a year is a leap year.
+ *
+ * A year is a leap year if:
+ * - Divisible by 4, but not by 100, OR
+ * - Divisible by 400
+ *
+ * @param year - The year to check
+ * @returns `true` if leap year, `false` otherwise (including invalid inputs)
+ *
+ * @example
+ * ```typescript
+ * isLeapYear(2024); // true
+ * isLeapYear(2023); // false
+ * isLeapYear(1900); // false (divisible by 100 but not 400)
+ * isLeapYear(2000); // true (divisible by 400)
+ * isLeapYear(NaN);  // false
+ * isLeapYear(3.5);  // false (non-integer)
+ * ```
+ */
+declare function isLeapYear(year: number): boolean;
+/**
+ * Get the number of days in a month.
+ *
+ * Accounts for leap years in February.
+ *
+ * @param month - Month number (1-12, 1-indexed)
+ * @param year - Full year (e.g., 2026)
+ * @returns Number of days in the month, or 0 for invalid inputs
+ *
+ * @example
+ * ```typescript
+ * daysInMonth(1, 2026);  // 31 (January)
+ * daysInMonth(2, 2024);  // 29 (February, leap year)
+ * daysInMonth(2, 2023);  // 28 (February, non-leap year)
+ * daysInMonth(4, 2026);  // 30 (April)
+ * daysInMonth(13, 2026); // 0 (invalid month)
+ * daysInMonth(2, NaN);   // 0 (invalid year)
+ * ```
+ */
+declare function daysInMonth(month: number, year: number): number;
+/**
+ * Type guard to check if a value is a valid Date object.
+ *
+ * Returns `true` only for Date instances that represent a valid date
+ * (i.e., not `Invalid Date`). Returns `false` for null, undefined,
+ * invalid dates, and non-Date values.
+ *
+ * @param date - Value to check
+ * @returns `true` if valid Date object, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * isValidDate(new Date());           // true
+ * isValidDate(new Date('invalid'));  // false
+ * isValidDate(null);                 // false
+ * isValidDate(undefined);            // false
+ * isValidDate('2024-01-01');         // false (string, not Date)
+ * isValidDate(1704067200000);        // false (number, not Date)
+ * ```
+ */
+declare function isValidDate(date: unknown): date is Date;
+/**
+ * Check if a date falls on a weekend (Saturday or Sunday).
+ *
+ * Note: This only checks Saturday/Sunday and does not account for
+ * industry-specific Saturday work schedules.
+ *
+ * @param date - Date object to check
+ * @returns `true` if Saturday or Sunday, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * isWeekend(new Date('2026-01-03')); // true (Saturday)
+ * isWeekend(new Date('2026-01-04')); // true (Sunday)
+ * isWeekend(new Date('2026-01-05')); // false (Monday)
+ * ```
+ */
+declare function isWeekend(date: Date): boolean;
+/**
+ * Check if a date falls on a working day (Monday-Friday).
+ *
+ * Note: This only checks Monday-Friday and does not account for
+ * national holidays (holiday lists require periodic updates and
+ * are not included per project mandates).
+ *
+ * @param date - Date object to check
+ * @returns `true` if Monday-Friday, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * isWorkingDay(new Date('2026-01-05')); // true (Monday)
+ * isWorkingDay(new Date('2026-01-03')); // false (Saturday)
+ * isWorkingDay(new Date('2026-01-04')); // false (Sunday)
+ * ```
+ */
+declare function isWorkingDay(date: Date): boolean;
+/**
+ * Calculate age from a birth date.
+ *
+ * Accounts for leap years and month length variations.
+ * Can return as an object { years, months, days } or as a formatted string.
+ *
+ * @param birthDate - Birth date (Date, string, or number timestamp)
+ * @param options - Options for age calculation
+ * @returns Age as object or formatted string (based on asString option)
+ * @throws {InvalidDateError} If birthDate or fromDate is invalid
+ *
+ * @example
+ * ```typescript
+ * // Get age as object
+ * getAge('1990-06-15'); // { years: 36, months: 9, days: 21 }
+ * getAge(new Date('1990-06-15'), { fromDate: new Date('2024-06-15') });
+ * // { years: 34, months: 0, days: 0 }
+ *
+ * // Get age as string
+ * getAge('1990-06-15', { asString: true });
+ * // '36 Tahun 9 Bulan 21 Hari'
+ *
+ * getAge(new Date('2020-01-01'), { fromDate: new Date('2020-01-15'), asString: true });
+ * // '15 Hari'
+ * ```
+ */
+declare function getAge(birthDate: Date | string | number, options?: {
+    fromDate?: Date | string | number;
+    asString?: boolean;
+}): {
+    years: number;
+    months: number;
+    days: number;
+} | string;
+
+/**
+ * Date parsing utilities for Indonesian formats
+ *
+ * @module datetime/parse
+ * @packageDocumentation
+ */
+/**
+ * Parse a date string in Indonesian format (DD-MM-YYYY) or ISO format (YYYY-MM-DD).
+ *
+ * Strict parsing rules:
+ * - Accepts delimiters: `/`, `-`, `.`
+ * - DD-MM-YYYY format: Day first (1-31), 4-digit year required
+ * - ISO auto-detection: If first segment is 4 digits AND > 31, treated as YYYY-MM-DD
+ * - Leap year validation: Feb 29 is only valid in leap years
+ * - 2-digit years NOT supported
+ * - Time components NOT supported
+ *
+ * @param dateStr - Date string to parse
+ * @returns Date object if valid, `null` if invalid
+ *
+ * @example
+ * ```typescript
+ * // Indonesian format (DD-MM-YYYY)
+ * parseDate('02-01-2026');    // Date(2026, 0, 2) - Jan 2, 2026
+ * parseDate('02/01/2026');    // Date(2026, 0, 2)
+ * parseDate('02.01.2026');    // Date(2026, 0, 2)
+ *
+ * // ISO format auto-detected (YYYY-MM-DD)
+ * parseDate('2026-01-02');    // Date(2026, 0, 2)
+ *
+ * // Invalid inputs return null
+ * parseDate('29-02-2023');    // null (not a leap year)
+ * parseDate('02-01-26');      // null (2-digit year)
+ * parseDate('02-01-2026 14:30'); // null (time component)
+ * parseDate('invalid');       // null
+ * ```
+ */
+declare function parseDate(dateStr: string): Date | null;
+
+/**
+ * Date formatting utilities for Indonesian locale
+ *
+ * @module datetime/format
+ * @packageDocumentation
+ */
+
+/**
+ * Format a date with Indonesian locale.
+ *
+ * @param date - Date to format (Date, string, or number timestamp in milliseconds)
+ * @param style - Formatting style (default: 'long')
+ * @returns Formatted date string
+ * @throws {InvalidDateError} If the date is invalid
+ *
+ * @example
+ * ```typescript
+ * formatDate(new Date('2026-01-02'), 'full');   // 'Jumat, 2 Januari 2026'
+ * formatDate(new Date('2026-01-02'), 'long');   // '2 Januari 2026'
+ * formatDate(new Date('2026-01-02'), 'medium'); // '2 Jan 2026'
+ * formatDate(new Date('2026-01-02'), 'short');  // '02/01/2026'
+ * formatDate(new Date('2026-01-02'), 'weekday'); // 'Jumat'
+ * formatDate(new Date('2026-01-02'), 'month');  // 'Januari'
+ * ```
+ */
+declare function formatDate(date: Date | string | number, style?: DateStyle): string;
+/**
+ * Format a date range with Indonesian locale and smart redundancy removal.
+ *
+ * Removes redundant month/year information when dates share them.
+ *
+ * @param start - Start date
+ * @param end - End date
+ * @param style - Formatting style (default: 'long')
+ * @returns Formatted date range string
+ * @throws {InvalidDateError} If either date is invalid
+ * @throws {InvalidDateRangeError} If end date is before start date
+ *
+ * @example
+ * ```typescript
+ * // Same day
+ * formatDateRange(
+ *   new Date('2026-01-02'),
+ *   new Date('2026-01-02')
+ * ); // '2 Januari 2026'
+ *
+ * // Same month & year
+ * formatDateRange(
+ *   new Date('2026-01-02'),
+ *   new Date('2026-01-05')
+ * ); // '2 - 5 Januari 2026'
+ *
+ * // Same year
+ * formatDateRange(
+ *   new Date('2026-01-30'),
+ *   new Date('2026-02-02')
+ * ); // '30 Januari - 2 Februari 2026'
+ *
+ * // Different year
+ * formatDateRange(
+ *   new Date('2025-12-30'),
+ *   new Date('2026-01-02')
+ * ); // '30 Desember 2025 - 2 Januari 2026'
+ * ```
+ */
+declare function formatDateRange(start: Date, end: Date, style?: Exclude<DateStyle, 'weekday' | 'month'>): string;
+
+/**
+ * Relative time formatting for Indonesian locale
+ *
+ * @module datetime/relative
+ * @packageDocumentation
+ */
+/**
+ * Format a date as relative time in Indonesian.
+ *
+ * Returns human-readable relative time like "Baru saja", "X menit yang lalu",
+ * "Kemarin", or falls back to formatted date for older dates.
+ *
+ * @param date - Date to format (Date, string, or number timestamp in milliseconds)
+ * @param baseDate - Reference date for comparison (default: current date)
+ * @returns Relative time string in Indonesian
+ * @throws {InvalidDateError} If either date is invalid
+ *
+ * @example
+ * ```typescript
+ * // Assuming today is 2026-01-02 12:00:00
+ * toRelativeTime(new Date('2026-01-02 11:59:00')); // 'Baru saja'
+ * toRelativeTime(new Date('2026-01-02 11:00:00')); // '1 jam yang lalu'
+ * toRelativeTime(new Date('2026-01-01 12:00:00')); // 'Kemarin'
+ * toRelativeTime(new Date('2025-12-30 12:00:00')); // '3 hari yang lalu'
+ * toRelativeTime(new Date('2025-12-01 12:00:00')); // '1 Desember 2025'
+ * ```
+ */
+declare function toRelativeTime(date: Date | string | number, baseDate?: Date): string;
+
+/**
+ * Timezone utilities for Indonesian locale
+ *
+ * @module datetime/timezone
+ * @packageDocumentation
+ */
+/**
+ * Map IANA timezone names or UTC offsets to Indonesian abbreviations (WIB/WITA/WIT).
+ *
+ * Supported mappings:
+ * - UTC+7 / Asia/Jakarta / Asia/Pontianak → "WIB"
+ * - UTC+8 / Asia/Makassar / Asia/Denpasar → "WITA"
+ * - UTC+9 / Asia/Jayapura → "WIT"
+ *
+ * @param input - IANA timezone name (case-sensitive), offset in hours, or offset string
+ * @returns Indonesian timezone abbreviation or null if not Indonesian
+ *
+ * @example
+ * ```typescript
+ * // IANA timezone names
+ * getIndonesianTimezone('Asia/Jakarta');    // 'WIB'
+ * getIndonesianTimezone('Asia/Makassar');   // 'WITA'
+ * getIndonesianTimezone('Asia/Jayapura');   // 'WIT'
+ *
+ * // Offset as number (hours)
+ * getIndonesianTimezone(7);                 // 'WIB'
+ * getIndonesianTimezone(8);                 // 'WITA'
+ * getIndonesianTimezone(9);                 // 'WIT'
+ *
+ * // Offset as string
+ * getIndonesianTimezone('+07:00');          // 'WIB'
+ * getIndonesianTimezone('+0700');           // 'WIB'
+ * getIndonesianTimezone('+08:00');          // 'WITA'
+ *
+ * // Non-Indonesian returns null
+ * getIndonesianTimezone('America/New_York'); // null
+ * getIndonesianTimezone(-5);                 // null
+ * ```
+ */
+declare function getIndonesianTimezone(input: string | number): 'WIB' | 'WITA' | 'WIT' | null;
+
+export { type AgeOptions, type AgeResult, DAY_NAMES, DAY_NAMES_SHORT, type DateStyle, InvalidDateError, InvalidDateRangeError, MONTH_NAMES, MONTH_NAMES_SHORT, TIMEZONE_MAP, VALID_UTC_OFFSETS, daysInMonth, formatDate, formatDateRange, getAge, getIndonesianTimezone, isLeapYear, isValidDate, isWeekend, isWorkingDay, parseDate, toRelativeTime };