@sonill/nepali-dates 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,371 @@
+/**
+ * Date format types for conversion output
+ */
+type DateFormat = 'object' | 'iso' | 'string' | 'array';
+/**
+ * Date pattern types for string formatting
+ */
+type DatePattern = 'YYYY-MM-DD' | 'YYYY/MM/DD' | 'DD-MM-YYYY' | 'DD/MM/YYYY' | 'MM-DD-YYYY' | 'MM/DD/YYYY';
+/**
+ * Locale types for month/day names
+ */
+type Locale = 'en' | 'ne';
+/**
+ * Date object representation
+ */
+interface DateObject {
+    year: number;
+    month: number;
+    day: number;
+}
+/**
+ * Date array representation [year, month, day]
+ */
+type DateArray = [number, number, number];
+/**
+ * Options for date conversion
+ */
+interface ConversionOptions {
+    format?: DateFormat;
+    pattern?: DatePattern;
+}
+/**
+ * Options for date formatting
+ */
+interface FormatOptions {
+    pattern?: DatePattern;
+    locale?: Locale;
+}
+/**
+ * Calendar data structure: year -> array of days in each month
+ */
+type CalendarData = Record<number, number[]>;
+/**
+ * Reference date pair for validation
+ */
+interface ReferenceDatePair {
+    bs: DateObject;
+    ad: DateObject;
+}
+/**
+ * Data range information
+ */
+interface DataRange {
+    minYear: number;
+    maxYear: number;
+    totalYears: number;
+}
+/**
+ * Month navigation result
+ */
+interface MonthNavigation {
+    year: number;
+    month: number;
+}
+/**
+ * Nepali month names
+ */
+declare enum NepaliMonth {
+    Baisakh = 1,
+    Jestha = 2,
+    Ashar = 3,
+    Shrawan = 4,
+    Bhadra = 5,
+    Ashwin = 6,
+    Kartik = 7,
+    Mangsir = 8,
+    Poush = 9,
+    Magh = 10,
+    Falgun = 11,
+    Chaitra = 12
+}
+/**
+ * Nepali month names in English
+ */
+declare const NEPALI_MONTH_NAMES_EN: Record<number, string>;
+/**
+ * Nepali month names in Nepali
+ */
+declare const NEPALI_MONTH_NAMES_NE: Record<number, string>;
+/**
+ * English month names
+ */
+declare const ENGLISH_MONTH_NAMES: Record<number, string>;
+
+/**
+ * Convert Bikram Sambat (BS) date to Anno Domini (AD) date
+ *
+ * @param year - BS year
+ * @param month - BS month (1-12)
+ * @param day - BS day
+ * @param options - Conversion options
+ * @returns AD date in specified format
+ *
+ * @example
+ * bsToAd(2080, 10, 15); // Returns { year: 2024, month: 1, day: 27 }
+ * bsToAd(2080, 10, 15, { format: 'iso' }); // Returns "2024-01-27"
+ * bsToAd(2080, 10, 15, { format: 'array' }); // Returns [2024, 1, 27]
+ */
+declare function bsToAd(year: number, month: number, day: number, options?: ConversionOptions): DateObject | string | DateArray;
+
+/**
+ * Convert Anno Domini (AD) date to Bikram Sambat (BS) date
+ *
+ * @param year - AD year
+ * @param month - AD month (1-12)
+ * @param day - AD day
+ * @param options - Conversion options
+ * @returns BS date in specified format
+ *
+ * @example
+ * adToBs(2024, 1, 27); // Returns { year: 2080, month: 10, day: 15 }
+ * adToBs(2024, 1, 27, { format: 'iso' }); // Returns "2080-10-15"
+ * adToBs(2024, 1, 27, { format: 'array' }); // Returns [2080, 10, 15]
+ */
+declare function adToBs(year: number, month: number, day: number, options?: ConversionOptions): DateObject | string | DateArray;
+
+/**
+ * Get the total number of days in a Nepali month
+ *
+ * @param year - BS year
+ * @param month - BS month (1-12)
+ * @returns Number of days in the month
+ *
+ * @example
+ * getTotalDaysInMonth(2080, 1); // Returns 31
+ */
+declare function getTotalDaysInMonth(year: number, month: number): number;
+/**
+ * Get the total number of days in a Nepali year
+ *
+ * @param year - BS year
+ * @returns Total number of days in the year
+ *
+ * @example
+ * getTotalDaysInYear(2080); // Returns 365
+ */
+declare function getTotalDaysInYear(year: number): number;
+/**
+ * Get the next month
+ *
+ * @param year - BS year
+ * @param month - BS month (1-12)
+ * @returns Next month details
+ *
+ * @example
+ * getNextMonth(2080, 12); // Returns { year: 2081, month: 1 }
+ * getNextMonth(2080, 6); // Returns { year: 2080, month: 7 }
+ */
+declare function getNextMonth(year: number, month: number): MonthNavigation;
+/**
+ * Get the previous month
+ *
+ * @param year - BS year
+ * @param month - BS month (1-12)
+ * @returns Previous month details
+ *
+ * @example
+ * getPrevMonth(2081, 1); // Returns { year: 2080, month: 12 }
+ * getPrevMonth(2080, 7); // Returns { year: 2080, month: 6 }
+ */
+declare function getPrevMonth(year: number, month: number): MonthNavigation;
+/**
+ * Get calendar data for a specific year
+ *
+ * @param year - BS year
+ * @returns Array of days in each month
+ *
+ * @example
+ * getCalendarData(2080); // Returns [31, 32, 31, 32, ...]
+ */
+declare function getCalendarData(year: number): number[];
+/**
+ * Get the available data range
+ *
+ * @returns Data range information
+ *
+ * @example
+ * getDataRange(); // Returns { minYear: 2000, maxYear: 2100, totalYears: 101 }
+ */
+declare function getDataRange(): DataRange;
+/**
+ * Calculate the number of days between two BS dates
+ *
+ * @param fromYear - Starting BS year
+ * @param fromMonth - Starting BS month
+ * @param fromDay - Starting BS day
+ * @param toYear - Ending BS year
+ * @param toMonth - Ending BS month
+ * @param toDay - Ending BS day
+ * @returns Number of days between dates (can be negative if toDate is before fromDate)
+ *
+ * @example
+ * getDaysInRange(2080, 1, 1, 2080, 1, 31); // Returns 30
+ */
+declare function getDaysInRange(fromYear: number, fromMonth: number, fromDay: number, toYear: number, toMonth: number, toDay: number): number;
+/**
+ * Get all calendar data
+ *
+ * @returns Complete calendar data object
+ *
+ * @example
+ * getAllCalendarData(); // Returns { 2000: [...], 2001: [...], ... }
+ */
+declare function getAllCalendarData(): CalendarData;
+
+/**
+ * Format a BS date to string
+ *
+ * @param year - BS year
+ * @param month - BS month (1-12)
+ * @param day - BS day
+ * @param options - Format options
+ * @returns Formatted date string
+ *
+ * @example
+ * formatBsDate(2080, 10, 15); // Returns "2080-10-15"
+ * formatBsDate(2080, 10, 15, { pattern: 'DD/MM/YYYY' }); // Returns "15/10/2080"
+ */
+declare function formatBsDate(year: number, month: number, day: number, options?: FormatOptions): string;
+/**
+ * Format an AD date to string
+ *
+ * @param year - AD year
+ * @param month - AD month (1-12)
+ * @param day - AD day
+ * @param options - Format options
+ * @returns Formatted date string
+ *
+ * @example
+ * formatAdDate(2024, 1, 27); // Returns "2024-01-27"
+ * formatAdDate(2024, 1, 27, { pattern: 'DD/MM/YYYY' }); // Returns "27/01/2024"
+ */
+declare function formatAdDate(year: number, month: number, day: number, options?: FormatOptions): string;
+/**
+ * Get Nepali month name
+ *
+ * @param month - Month number (1-12)
+ * @param locale - Locale ('en' or 'ne')
+ * @returns Month name
+ *
+ * @example
+ * getNepaliMonthName(1); // Returns "Baisakh"
+ * getNepaliMonthName(1, 'ne'); // Returns "बैशाख"
+ */
+declare function getNepaliMonthName(month: number, locale?: Locale): string;
+/**
+ * Get English month name
+ *
+ * @param month - Month number (1-12)
+ * @returns Month name
+ *
+ * @example
+ * getEnglishMonthName(1); // Returns "January"
+ */
+declare function getEnglishMonthName(month: number): string;
+/**
+ * Parse a date string to DateObject
+ *
+ * @param dateString - Date string to parse
+ * @param pattern - Expected pattern
+ * @returns Parsed date object
+ *
+ * @example
+ * parseDate('2080-10-15', 'YYYY-MM-DD'); // Returns { year: 2080, month: 10, day: 15 }
+ * parseDate('15/10/2080', 'DD/MM/YYYY'); // Returns { year: 2080, month: 10, day: 15 }
+ */
+declare function parseDate(dateString: string, pattern?: DatePattern): DateObject;
+/**
+ * Format a date object to ISO string (YYYY-MM-DD)
+ *
+ * @param date - Date object
+ * @returns ISO formatted date string
+ *
+ * @example
+ * toIsoString({ year: 2080, month: 10, day: 15 }); // Returns "2080-10-15"
+ */
+declare function toIsoString(date: DateObject): string;
+/**
+ * Format a date object to array [year, month, day]
+ *
+ * @param date - Date object
+ * @returns Date as array
+ *
+ * @example
+ * toArray({ year: 2080, month: 10, day: 15 }); // Returns [2080, 10, 15]
+ */
+declare function toArray(date: DateObject): [number, number, number];
+
+/**
+ * Check if a year exists in the calendar data
+ */
+declare function hasDataForYear(year: number): boolean;
+/**
+ * Validate a Nepali (BS) date
+ */
+declare function isValidBsDate(year: number, month: number, day: number): boolean;
+/**
+ * Validate an English (AD) date
+ */
+declare function isValidAdDate(year: number, month: number, day: number): boolean;
+/**
+ * Check if a year is a leap year (Gregorian calendar)
+ */
+declare function isLeapYear(year: number): boolean;
+/**
+ * Get the number of days in a month for AD calendar
+ */
+declare function getDaysInAdMonth(year: number, month: number): number;
+
+/**
+ * Nepali Calendar Data (Bikram Sambat)
+ *
+ * Each year maps to an array of 12 numbers representing the days in each month.
+ * Months: [Baisakh, Jestha, Ashar, Shrawan, Bhadra, Ashwin, Kartik, Mangsir, Poush, Magh, Falgun, Chaitra]
+ *
+ * Data Sources:
+ * - Nepal Panchanga Nirnayak Samiti
+ * - Verified against historical records
+ *
+ * Data Range: BS 2000 - 2100 (AD 1943 - 2043)
+ */
+declare const NEPALI_CALENDAR_DATA: CalendarData;
+/**
+ * Get the minimum year in the calendar data
+ */
+declare const MIN_YEAR: number;
+/**
+ * Get the maximum year in the calendar data
+ */
+declare const MAX_YEAR: number;
+
+/**
+ * Base reference date for all calculations
+ * BS 2000-01-01 = AD 1943-04-14
+ *
+ * This is the anchor point for all date conversions.
+ */
+declare const BASE_BS_DATE: {
+    year: number;
+    month: number;
+    day: number;
+};
+declare const BASE_AD_DATE: {
+    year: number;
+    month: number;
+    day: number;
+};
+/**
+ * Reference date pairs for validation and testing
+ *
+ * These are verified BS-AD date pairs used to validate conversion accuracy.
+ * Each pair represents a known accurate conversion point.
+ *
+ * Sources:
+ * - Official Nepal government publications
+ * - Historical records and verified events
+ * - Cross-referenced with multiple calendar systems
+ */
+declare const REFERENCE_DATES: ReferenceDatePair[];
+
+export { BASE_AD_DATE, BASE_BS_DATE, type CalendarData, type ConversionOptions, type DataRange, type DateArray, type DateFormat, type DateObject, type DatePattern, ENGLISH_MONTH_NAMES, type FormatOptions, type Locale, MAX_YEAR, MIN_YEAR, type MonthNavigation, NEPALI_CALENDAR_DATA, NEPALI_MONTH_NAMES_EN, NEPALI_MONTH_NAMES_NE, NepaliMonth, REFERENCE_DATES, type ReferenceDatePair, adToBs, bsToAd, formatAdDate, formatBsDate, getAllCalendarData, getCalendarData, getDataRange, getDaysInAdMonth, getDaysInRange, getEnglishMonthName, getNepaliMonthName, getNextMonth, getPrevMonth, getTotalDaysInMonth, getTotalDaysInYear, hasDataForYear, isLeapYear, isValidAdDate, isValidBsDate, parseDate, toArray, toIsoString };