nepali-date-library 1.1.5 → 1.1.7

package/ReadMe.md

@@ -1,362 +1,1162 @@
 # NepaliDate Library
 
-## Overview
-The `NepaliDate` library provides a proper way to work with Nepali (Bikram Sambat) dates in TypeScript/JavaScript. It allows you to create, manipulate, format, and convert between Nepali and Gregorian dates with support for fiscal years, quarters, and extensive date operations.
+A comprehensive TypeScript/JavaScript library for working with Nepali (Bikram Sambat) dates. This library provides full support for creating, manipulating, formatting, and converting between Nepali and Gregorian dates, with additional features for fiscal years, quarters, and extensive date operations.
+
+## Features
+
+- 🗓️ **Complete Nepali Calendar Support** - Accurate Bikram Sambat calendar from 1976 BS to 2100 BS
+- 🔄 **Flexible Date Conversion** - Convert between AD and BS dates with custom format support
+- 📅 **Date Manipulation** - Add/subtract days, months, and years with proper overflow handling
+- 🌐 **Localization Support** - Full English and Nepali language support for months and days
+- 📊 **Fiscal Year Support** - Built-in fiscal year and quarter calculations
+- 🎯 **Date Range Operations** - Start/end of day, week, month, year calculations
+- ⚡ **TypeScript Ready** - Full type safety and IntelliSense support
+- 🧮 **Calendar Generation** - Generate calendar grids for UI components
+- 🎨 **Custom Format Support** - Parse and format dates in multiple patterns
 
 ## Installation
-```sh
+
+```bash
 npm install nepali-date-library
 ```
 
-## Importing the Library
-```ts
+## Quick Start
+
+```typescript
 import { NepaliDate, ADtoBS, BStoAD } from 'nepali-date-library';
-```
 
-## Class: `NepaliDate`
+// Create today's date in Nepali calendar
+const today = new NepaliDate();
+console.log(today.toString()); // 2081/10/15
 
-### Constructors
-```ts
-new NepaliDate();
-new NepaliDate(date: Date | NepaliDate | number | string);
-new NepaliDate(year: number, month: number, day: number);
+// Convert between calendars with default formats
+const bsDate = ADtoBS('2025-02-22');  // "2081-10-10"
+const adDate = BStoAD('2081-10-14');  // "2025-02-26"
+
+// Convert with custom formats
+const customBS = ADtoBS('22/02/2025', 'DD/MM/YYYY', 'YYYY.MM.DD');  // "2081.10.10"
+const customAD = BStoAD('10.10.2081', 'DD.MM.YYYY', 'MM-DD-YYYY');  // "10-10-2025"
+
+// Format dates
+const formatted = today.format('MMMM DD, YYYY'); // "Magh 15, 2081"
+const nepali = today.format('mmmm dd, yyyy');    // "माघ १५, २०८१"
 ```
-- Creates a `NepaliDate` instance.
-- Accepts either no arguments (current date), a JavaScript `Date`, another `NepaliDate`, a timestamp, or a formatted date string.
-- Can also accept year, month (0-11), and day (1-32) as separate arguments.
 
-### Date Conversion Functions
+## API Reference
 
-#### Pre-built Conversion Functions
-```ts
-import { ADtoBS, BStoAD } from 'nepali-date-library';
+### Importing
 
-// Convert AD to BS
-const bsDate = ADtoBS('2025-02-22');  // Returns: '2081-10-10'
+```typescript
+// Main classes and functions
+import { NepaliDate, ADtoBS, BStoAD } from 'nepali-date-library';
 
-// Convert BS to AD
-const adDate = BStoAD('2081-10-14');  // Returns: '2025-02-26'
+// Constants
+import { 
+  NEPALI_DATE_MAP, 
+  NUMBER_NP,
+  WEEK_EN, WEEK_NP, WEEK_SHORT_EN, WEEK_SHORT_NP,
+  MONTH_EN, MONTH_NP, MONTH_SHORT_EN, MONTH_SHORT_NP 
+} from 'nepali-date-library';
 ```
 
-#### Class Method
-```ts
-const nepaliDate = new NepaliDate();
-const adDate = nepaliDate.getEnglishDate();  // Returns JavaScript Date object
+### Date Conversion Utilities
+
+#### `ADtoBS(adDate: string, inputFormat?: string, outputFormat?: string): string`
+
+Converts an Anno Domini (AD) date to a Bikram Sambat (BS) date with custom format support.
+
+**Parameters:**
+- `adDate` - The AD date string
+- `inputFormat` - The input date format pattern (default: "YYYY-MM-DD")
+- `outputFormat` - The output date format pattern (default: "YYYY-MM-DD")
+
+**Returns:** The corresponding BS date in the specified output format
+
+**Supported Input/Output Formats:**
+- `YYYY-MM-DD`, `YYYY/MM/DD`, `YYYY.MM.DD`
+- `DD-MM-YYYY`, `DD/MM/YYYY`, `DD.MM.YYYY`
+- `MM-DD-YYYY`, `MM/DD/YYYY`, `MM.DD.YYYY`
+- `DD MM YYYY`, `YYYY MM DD`
+
+```typescript
+// Default format conversion
+const bsDate = ADtoBS('2025-02-22');  // "2081-10-10"
+
+// Custom input format
+const bsDate2 = ADtoBS('22/02/2025', 'DD/MM/YYYY');  // "2081-10-10"
+
+// Custom input and output formats
+const bsDate3 = ADtoBS('22.02.2025', 'DD.MM.YYYY', 'YYYY/MM/DD');  // "2081/10/10"
+
+// US format to Nepali format
+const bsDate4 = ADtoBS('02-22-2025', 'MM-DD-YYYY', 'DD.MM.YYYY');  // "10.10.2081"
 ```
 
----
+#### `BStoAD(bsDate: string, inputFormat?: string, outputFormat?: string): string`
+
+Converts a Bikram Sambat (BS) date to an Anno Domini (AD) date with custom format support.
+
+**Parameters:**
+- `bsDate` - The BS date string (supports both English and Nepali numerals)
+- `inputFormat` - The input date format pattern (default: "YYYY-MM-DD")
+- `outputFormat` - The output date format pattern (default: "YYYY-MM-DD")
+
+**Returns:** The corresponding AD date in the specified output format
+
+```typescript
+// Default format conversion
+const adDate = BStoAD('2081-10-14');  // "2025-02-26"
 
-### Getters
-```ts
-getYear(): number;          // Returns Nepali year
-getMonth(): number;         // Returns Nepali month (0-11)
-getDate(): number;          // Returns Nepali day (1-32)
-getDay(): number;           // Returns day of week (0-6, 0 = Sunday)
-getHours(): number;         // Returns hour (0-23)
-getMinutes(): number;       // Returns minutes (0-59)
-getSeconds(): number;       // Returns seconds (0-59)
-getMilliseconds(): number;  // Returns milliseconds (0-999)
-getTime(): number;          // Returns timestamp in milliseconds
+// Custom input format
+const adDate2 = BStoAD('14/10/2081', 'DD/MM/YYYY');  // "2025-02-26"
+
+// Custom input and output formats
+const adDate3 = BStoAD('14.10.2081', 'DD.MM.YYYY', 'MM/DD/YYYY');  // "02/26/2025"
+
+// Nepali numerals support
+const adDate4 = BStoAD('२०८१-१०-१४');  // "2025-02-26"
+
+// Mixed format conversion
+const adDate5 = BStoAD('10 14 2081', 'MM DD YYYY', 'DD-MM-YYYY');  // "26-02-2025"
 ```
 
----
+### NepaliDate Class
+
+#### Constructors
+
+```typescript
+// Current date
+const today = new NepaliDate();
+
+// From JavaScript Date
+const fromDate = new NepaliDate(new Date());
 
-### Setters
-```ts
-setYear(year: number): void;
-setMonth(month: number): void;
-setDate(day: number): void;
-set(year: number, month: number, day: number): void;
+// From string
+const fromString = new NepaliDate('2081-10-15');
+
+// From components (year, month 0-11, day 1-32)
+const fromComponents = new NepaliDate(2081, 9, 15);
+
+// From timestamp
+const fromTimestamp = new NepaliDate(1645123200000);
+
+// From another NepaliDate
+const copy = new NepaliDate(existingNepaliDate);
 ```
-- Updates the Nepali date components and synchronizes the internal timestamp.
 
----
+#### Properties
 
-### Parsing
-```ts
-parse(dateString: string): void;
+```typescript
+public timestamp: Date;    // Equivalent JavaScript Date
+public year: number;       // Nepali year (BS)
+public month: number;      // Nepali month (0-11)
+public day: number;        // Nepali day (1-32)
 ```
-- Parses a date string and updates the current instance
-- Supports formats: YYYY-MM-DD, YYYY/MM/DD, or YYYY.MM.DD
 
----
+#### Basic Getters
+
+```typescript
+const date = new NepaliDate();
+
+date.getYear();          // Returns Nepali year
+date.getMonth();         // Returns Nepali month (0-11)
+date.getDate();          // Returns Nepali day (1-32)
+date.getDay();           // Returns day of week (0-6, 0=Sunday)
+date.getHours();         // Returns hour (0-23)
+date.getMinutes();       // Returns minutes (0-59)
+date.getSeconds();       // Returns seconds (0-59)
+date.getMilliseconds();  // Returns milliseconds (0-999)
+date.getTime();          // Returns timestamp
+date.getEnglishDate();   // Returns equivalent JavaScript Date
+```
+
+#### Setters
+
+```typescript
+const date = new NepaliDate();
 
-### Formatting
-```ts
-format(formatStr: string): string;
-toString(): string;  // Returns format: YYYY/MM/DD (1-indexed month)
+date.setYear(2082);           // Set Nepali year
+date.setMonth(5);             // Set Nepali month (0-11)
+date.setDate(15);             // Set Nepali day (1-32)
+date.set(2081, 9, 15);        // Set all components at once
 ```
 
-#### Available Format Tokens:
-- **English Formats:**
-  - `YYYY` - Full Year (e.g., 2080)
-  - `MM` - Month with leading zero (01-12)
-  - `M` - Month without leading zero (1-12)
-  - `MMM` - Short month name (Bai, Cha)
-  - `MMMM` - Long month name (Baisakh, Chaitra)
-  - `DD` - Day with leading zero (01-32)
-  - `D` - Day without leading zero (1-32)
-  - `DDD` - Short day name (Sun, Sat)
-  - `DDDD` - Full day name (Sunday)
+#### Formatting
 
-- **Nepali Formats:**
-  - `yyyy` - Full Year (e.g., २०८१)
-  - `mm` - Month with leading zero (०१-१२)
-  - `m` - Month without leading zero (१-१२)
-  - `mmm` - Short month name (बै, चै)
-  - `mmmm` - Long month name (बैशाख, चैत्र)
-  - `dd` - Day with leading zero (०१-३२)
-  - `d` - Day without leading zero (१-३२)
-  - `ddd` - Short day name (आइत, शनि)
-  - `dddd` - Full day name (आइतबार)
+The `format()` method supports extensive formatting options:
 
----
+```typescript
+const date = new NepaliDate(2081, 9, 15);
+
+// English formats
+date.format('YYYY-MM-DD');        // "2081-10-15"
+date.format('MMMM DD, YYYY');     // "Magh 15, 2081"
+date.format('MMM D, YYYY');       // "Mag 15, 2081"
+date.format('DDDD, MMMM DD');     // "Monday, Magh 15"
+
+// Nepali formats  
+date.format('yyyy-mm-dd');        // "२०८१-१०-१५"
+date.format('mmmm dd, yyyy');     // "माघ १५, २०८१"
+date.format('dddd, mmmm dd');     // "सोमबार, माघ १५"
+```
+
+**Format Tokens:**
+
+| Token | Description | Example |
+|-------|-------------|---------|
+| `YYYY` | 4-digit year | 2081 |
+| `MM` | Month with leading zero | 01-12 |
+| `M` | Month without leading zero | 1-12 |
+| `MMMM` | Full month name | Baisakh |
+| `MMM` | Short month name | Bai |
+| `DD` | Day with leading zero | 01-32 |
+| `D` | Day without leading zero | 1-32 |
+| `DDDD` | Full day name | Sunday |
+| `DDD` | Short day name | Sun |
+| `yyyy` | 4-digit year (Nepali) | २०८१ |
+| `mm` | Month with leading zero (Nepali) | ०१-१२ |
+| `m` | Month without leading zero (Nepali) | १-१२ |
+| `mmmm` | Full month name (Nepali) | बैशाख |
+| `mmm` | Short month name (Nepali) | बै |
+| `dd` | Day with leading zero (Nepali) | ०१-३२ |
+| `d` | Day without leading zero (Nepali) | १-३२ |
+| `dddd` | Full day name (Nepali) | आइतबार |
+| `ddd` | Short day name (Nepali) | आइत |
+
+#### Date Manipulation
+
+All manipulation methods return new instances (immutable):
+
+```typescript
+const date = new NepaliDate(2081, 9, 15);
 
-### Date Manipulation
-```ts
-addDays(days: number): NepaliDate;
-addMonths(months: number): NepaliDate;
-addYears(years: number): NepaliDate;
+const futureDate = date.addDays(10);      // 10 days later
+const pastDate = date.addMonths(-2);      // 2 months earlier
+const nextYear = date.addYears(1);        // 1 year later
+
+// Original date remains unchanged
+console.log(date.toString());        // "2081/10/15"
+console.log(futureDate.toString());  // "2081/10/25"
 ```
-- Adds a specified number of days, months, or years to the date and returns a new `NepaliDate` instance.
 
----
+#### Date Comparison
 
-### Date Information Methods
+```typescript
+const date1 = new NepaliDate(2081, 5, 10);
+const date2 = new NepaliDate(2081, 5, 15);
 
-#### `daysInMonth(): number`
-Returns the number of days in the current month.
+date1.isAfter(date2);           // false
+date1.isBefore(date2);          // true
+date1.isEqual(date2);           // false
+date1.isSame(date2, 'month');   // true
+date1.isSame(date2, 'year');    // true
 
-#### `isLeapYear(): boolean`
-Checks if the current year is a leap year in the Nepali calendar.
+// Calculate differences
+date1.diff(date2, 'day');       // -5
+date1.diff(date2, 'month');     // 0
+date1.diff(date2, 'year');      // 0
+```
 
-#### `getWeeksInMonth(): number`
-Calculates the number of weeks in the current month.
+#### Date Range Operations
 
----
+```typescript
+const date = new NepaliDate(2081, 5, 15);
 
-### Date Comparison Methods
+// Day boundaries
+const startOfDay = date.startOfDay();     // 00:00:00
+const endOfDay = date.endOfDay();         // 23:59:59.999
 
-#### `diff(date: NepaliDate, unit: 'year' | 'month' | 'day'): number`
-Calculates the difference between two `NepaliDate` instances.
+// Week boundaries (default: Sunday start)
+const startOfWeek = date.startOfWeek();   // Previous/current Sunday
+const endOfWeek = date.endOfWeek();       // Following/current Saturday
 
-#### `isAfter(date: NepaliDate): boolean`
-Checks if this date comes after the specified date.
+// Week boundaries (Monday start)
+const startOfWeekMon = date.startOfWeek(1); // Previous/current Monday
+const endOfWeekMon = date.endOfWeek(1);     // Following/current Sunday
 
-#### `isBefore(date: NepaliDate): boolean`
-Checks if this date comes before the specified date.
+// Month boundaries
+const startOfMonth = date.startOfMonth(); // 1st day of month
+const endOfMonth = date.endOfMonth();     // Last day of month
 
-#### `isEqual(date: NepaliDate): boolean`
-Checks if this date is exactly equal to the specified date (year, month, day).
+// Year boundaries
+const startOfYear = date.startOfYear();   // 1st Baisakh
+const endOfYear = date.endOfYear();       // Last day of Chaitra
+```
 
-#### `isSame(date: NepaliDate, unit: 'year' | 'month' | 'day'): boolean`
-Checks if this date is the same as the specified date for the given unit.
+#### Calendar Year Quarters
 
----
+```typescript
+// Get current quarter (1-4)
+const currentQuarter = new NepaliDate().getCurrentQuarter();
 
-### Date Range Methods
+// Get specific quarter dates
+const q1 = NepaliDate.getQuarter(1, 2081);
+console.log(q1.start.toString()); // "2081/1/1"  (1st Baisakh)
+console.log(q1.end.toString());   // "2081/3/32" (Last day of Asar)
 
-#### `startOfDay(): NepaliDate`
-Returns a new `NepaliDate` representing the start of the current day (00:00:00).
+// Get all quarters for a year
+const quarters = NepaliDate.getQuarters(2081);
+console.log(quarters.Q1); // {start: NepaliDate, end: NepaliDate}
+console.log(quarters.Q2); // {start: NepaliDate, end: NepaliDate}
+console.log(quarters.Q3); // {start: NepaliDate, end: NepaliDate}
+console.log(quarters.Q4); // {start: NepaliDate, end: NepaliDate}
+```
 
-#### `endOfDay(): NepaliDate`
-Returns a new `NepaliDate` representing the end of the current day (23:59:59.999).
+**Quarter Mapping (Calendar Year):**
+- **Q1:** Baisakh, Jestha, Asar (months 0-2)
+- **Q2:** Shrawan, Bhadra, Aswin (months 3-5)
+- **Q3:** Kartik, Mangsir, Poush (months 6-8)
+- **Q4:** Magh, Falgun, Chaitra (months 9-11)
 
-#### `startOfWeek(startOfWeek: number = 0): NepaliDate`
-Returns a new `NepaliDate` representing the start of the week containing this date.
-- `startOfWeek`: Day to consider as start of week (0-6, where 0 = Sunday, 1 = Monday, etc.)
+#### Fiscal Year Operations
 
-#### `endOfWeek(startOfWeek: number = 0): NepaliDate`
-Returns a new `NepaliDate` representing the end of the week containing this date.
+The Nepali fiscal year starts from **Shrawan 1st** (month 3, day 1).
 
-#### `startOfMonth(): NepaliDate`
-Returns a new `NepaliDate` representing the first day of the current month.
+```typescript
+// Get current fiscal year
+const currentFY = NepaliDate.getCurrentFiscalYear();
 
-#### `endOfMonth(): NepaliDate`
-Returns a new `NepaliDate` representing the last day of the current month.
+// Get current fiscal year quarter (1-4)
+const date = new NepaliDate();
+const fyQuarter = date.getCurrentFiscalYearQuarter();
 
-#### `startOfYear(): NepaliDate`
-Returns a new `NepaliDate` representing the first day of the current Nepali year (1st Baisakh).
+// Get current fiscal year quarter dates
+const quarterDates = date.getCurrentFiscalYearQuarterDates();
+console.log(quarterDates.start.toString());
+console.log(quarterDates.end.toString());
 
-#### `endOfYear(): NepaliDate`
-Returns a new `NepaliDate` representing the last day of the current Nepali year (last day of Chaitra).
+// Get specific fiscal year quarter
+const fyQ1 = NepaliDate.getFiscalYearQuarter(1, 2081);
+console.log(fyQ1.start.toString()); // "2081/4/1" (1st Shrawan)
+console.log(fyQ1.end.toString());   // "2081/6/30" (Last day of Aswin)
 
----
+// Get all fiscal year quarters
+const fyQuarters = NepaliDate.getFiscalYearQuarters(2081);
+```
 
-### Quarter and Fiscal Year Methods
+**Fiscal Year Quarter Mapping:**
+- **Q1:** Shrawan, Bhadra, Aswin (months 3-5)
+- **Q2:** Kartik, Mangsir, Poush (months 6-8)
+- **Q3:** Magh, Falgun, Chaitra (months 9-11)
+- **Q4:** Baisakh, Jestha, Asar (months 0-2) *[spans to next calendar year]*
 
-#### `getCurrentQuarter(): number`
-Returns the quarter number (1-4) for the current date.
+#### Date Information
 
-#### `getCurrentFiscalYearQuarter(): number`
-Returns the current fiscal year quarter number (1-4) for the current date.
-- Fiscal year starts from Shrawan 1st (month 3, day 1)
+```typescript
+const date = new NepaliDate(2081, 4, 15); // Bhadra 15, 2081
 
-#### `getCurrentFiscalYearQuarterDates(): { start: NepaliDate; end: NepaliDate }`
-Returns the start and end dates of the current fiscal year quarter.
+date.daysInMonth();        // 31 (days in Bhadra 2081)
+date.isLeapYear();         // true/false
+date.getWeeksInMonth();    // Number of weeks in current month
+date.isValid();            // true/false
 
----
+// Static validation
+NepaliDate.isValid(2081, 4, 32); // false (invalid day)
+NepaliDate.isValid(2081, 4, 31); // true
+```
 
-### Static Methods
+#### Calendar Generation
 
-#### Date Range Utilities
-```ts
-static minimum(): Date;  // Returns earliest supported date
-static maximum(): Date;  // Returns latest supported date
+Generate calendar data for building UI components:
+
+```typescript
+const calendarData = NepaliDate.getCalendarDays(2081, 4); // Bhadra 2081
+
+console.log(calendarData);
+// {
+//   prevRemainingDays: 2,           // Days from previous month
+//   prevMonth: {
+//     year: 2081, 
+//     month: 3, 
+//     days: [30, 31]               // Last days of previous month
+//   },
+//   currentMonth: {
+//     year: 2081, 
+//     month: 4, 
+//     days: [1, 2, 3, ..., 31]     // All days of current month
+//   },
+//   nextMonth: {
+//     year: 2081, 
+//     month: 5, 
+//     days: [1, 2, 3, 4, 5]       // First days of next month
+//   },
+//   remainingDays: 5               // Days from next month
+// }
 ```
 
-#### Validation
-```ts
-static isValid(year: number, month: number, day: number): boolean;
-isValid(): boolean;  // Instance method
+#### Utility Methods
+
+```typescript
+// Get name utilities
+NepaliDate.getMonthName(0, false, false); // "Baisakh"
+NepaliDate.getMonthName(0, true, false);  // "Bai"
+NepaliDate.getMonthName(0, false, true);  // "बैशाख"
+NepaliDate.getMonthName(0, true, true);   // "बै"
+
+NepaliDate.getDayName(0, false, false);   // "Sunday"
+NepaliDate.getDayName(0, true, false);    // "Sun"
+NepaliDate.getDayName(0, false, true);    // "आइतबार"
+NepaliDate.getDayName(0, true, true);     // "आइत"
+
+// Date boundaries
+NepaliDate.minimum();         // Earliest supported date
+NepaliDate.maximum();         // Latest supported date
+
+// Clone instance
+const copy = date.clone();    // Deep copy of NepaliDate
 ```
 
-#### Name Utilities
-```ts
-static getMonthName(month: number, short: boolean = false, nepali: boolean = false): string;
-static getDayName(day: number, short: boolean = false, nepali: boolean = false): string;
+## Advanced Format Examples
+
+### Multi-Format Date Conversion
+
+```typescript
+import { ADtoBS, BStoAD } from 'nepali-date-library';
+
+// Converting from various AD formats to BS
+const europeanToBS = ADtoBS('22/02/2025', 'DD/MM/YYYY');        // "2081-10-10"
+const americanToBS = ADtoBS('02-22-2025', 'MM-DD-YYYY');        // "2081-10-10"
+const dotFormatToBS = ADtoBS('2025.02.22', 'YYYY.MM.DD');       // "2081-10-10"
+const spaceFormatToBS = ADtoBS('22 02 2025', 'DD MM YYYY');     // "2081-10-10"
+
+// Converting with custom output formats
+const customOutput1 = ADtoBS('2025-02-22', 'YYYY-MM-DD', 'DD/MM/YYYY'); // "10/10/2081"
+const customOutput2 = ADtoBS('22/02/2025', 'DD/MM/YYYY', 'YYYY.MM.DD'); // "2081.10.10"
+
+// Converting from various BS formats to AD
+const bsSlashToAD = BStoAD('10/10/2081', 'DD/MM/YYYY');         // "2025-02-22"
+const bsDotToAD = BStoAD('2081.10.10', 'YYYY.MM.DD');          // "2025-02-22"
+const bsSpaceToAD = BStoAD('10 10 2081', 'DD MM YYYY');        // "2025-02-22"
+
+// Converting with custom AD output formats
+const adCustom1 = BStoAD('2081-10-10', 'YYYY-MM-DD', 'MM/DD/YYYY'); // "02/22/2025"
+const adCustom2 = BStoAD('10/10/2081', 'DD/MM/YYYY', 'DD.MM.YYYY'); // "22.02.2025"
 ```
 
-#### Calendar Generation
-```ts
-static getCalendarDays(year: number, month: number): {
-  prevRemainingDays: number,
-  prevMonth: { year: number, month: number, days: number[] },
-  currentMonth: { year: number, month: number, days: number[] },
-  nextMonth: { year: number, month: number, days: number[] },
-  remainingDays: number
+### Handling Different Date Sources
+
+```typescript
+// API data conversion utility
+function convertAPIDate(dateStr: string, sourceFormat: string, targetCalendar: 'AD' | 'BS', targetFormat: string = 'YYYY-MM-DD') {
+  try {
+    if (targetCalendar === 'BS') {
+      return ADtoBS(dateStr, sourceFormat, targetFormat);
+    } else {
+      return BStoAD(dateStr, sourceFormat, targetFormat);
+    }
+  } catch (error) {
+    throw new Error(`Date conversion failed: ${error.message}`);
+  }
 }
+
+// Usage examples
+const dbDate = convertAPIDate('2025/02/22', 'YYYY/MM/DD', 'BS', 'DD-MM-YYYY');  // "10-10-2081"
+const userInput = convertAPIDate('22.10.2081', 'DD.MM.YYYY', 'AD', 'MM/DD/YYYY'); // "02/26/2025"
+const csvDate = convertAPIDate('02 22 2025', 'MM DD YYYY', 'BS', 'YYYY/MM/DD');   // "2081/10/10"
 ```
-Generates calendar days for a given month, including trailing/leading days from adjacent months.
 
-#### Quarter Methods
-```ts
-static getQuarter(quarter: number, year?: number): { start: NepaliDate; end: NepaliDate };
-static getQuarters(year?: number): {
-  Q1: { start: NepaliDate; end: NepaliDate };
-  Q2: { start: NepaliDate; end: NepaliDate };
-  Q3: { start: NepaliDate; end: NepaliDate };
-  Q4: { start: NepaliDate; end: NepaliDate };
-};
+### Nepali Numeral Support
+
+The library automatically handles Nepali numerals in input:
+
+```typescript
+// Both of these work identically
+const withEnglishNumerals = BStoAD('2081-10-14');
+const withNepaliNumerals = BStoAD('२०८१-१०-१४');
+
+// Mixed numerals are also supported
+const mixedNumerals = BStoAD('२०८१-10-१४');
+
+// All produce the same result: "2025-02-26"
 ```
 
-#### Fiscal Year Methods
-```ts
-static getCurrentFiscalYear(): number;
-static getFiscalYearQuarter(quarter: number, fiscalYear?: number): { start: NepaliDate; end: NepaliDate };
-static getFiscalYearQuarters(fiscalYear?: number): {
-  Q1: { start: NepaliDate; end: NepaliDate };
-  Q2: { start: NepaliDate; end: NepaliDate };
-  Q3: { start: NepaliDate; end: NepaliDate };
-  Q4: { start: NepaliDate; end: NepaliDate };
-};
+### Constants
+
+#### Calendar Data
+
+```typescript
+// Complete calendar mapping (1976-2100 BS)
+NEPALI_DATE_MAP: Array<{
+  year: number;
+  days: number[];        // Days in each month [31, 32, 31, ...]
+  totalDays: number;     // Total days in year
+  daysTillNow: number;   // Cumulative days from epoch
+}>
 ```
 
-#### Utility Methods
-```ts
-clone(): NepaliDate;  // Creates a copy of the current instance
+#### Week Names
+
+```typescript
+// English
+WEEK_EN: ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"]
+WEEK_SHORT_EN: ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"]
+
+// Nepali  
+WEEK_NP: ['आइतबार', 'सोमबार', 'मंगलबार', 'बुधबार', 'बिहिबार', 'शुक्रबार', 'शनिबार']
+WEEK_SHORT_NP: ['आइत', 'सोम', 'मंगल', 'बुध', 'बिहि', 'शुक्र', 'शनि']
 ```
 
----
+#### Month Names
 
-## Example Usage
+```typescript
+// English
+MONTH_EN: ["Baisakh", "Jestha", "Asar", "Shrawan", "Bhadra", "Aswin", "Kartik", "Mangsir", "Poush", "Magh", "Falgun", "Chaitra"]
+MONTH_SHORT_EN: ["Bai", "Jes", "Asa", "Shr", "Bhd", "Asw", "Kar", "Man", "Pou", "Mag", "Fal", "Cha"]
 
-### Basic Usage
-```ts
-const today = new NepaliDate();
-console.log(today.toString()); // 2081/10/15
+// Nepali
+MONTH_NP: ['बैशाख', 'जेठ', 'असार', 'श्रावण', 'भाद्र', 'आश्विन', 'कार्तिक', 'मंसिर', 'पौष', 'माघ', 'फाल्गुण', 'चैत्र']
+MONTH_SHORT_NP: ['बै', 'जे', 'अ', 'श्रा', 'भा', 'आ', 'का', 'मं', 'पौ', 'मा', 'फा', 'चै']
+```
+
+#### Numbers
 
-const formatted = today.format('YYYY-MM-DD');
-console.log(formatted); // 2081-10-15
+```typescript
+// Nepali numerals (0-9)
+NUMBER_NP: ['०', '१', '२', '३', '४', '५', '६', '७', '८', '९']
 
-const nepaliFormatted = today.format('yyyy-mm-dd');
-console.log(nepaliFormatted); // २०८१-१०-१५
+// Usage example
+function toNepaliNumber(num: string): string {
+  return num.split('').map(digit => NUMBER_NP[parseInt(digit)] || digit).join('');
+}
+
+console.log(toNepaliNumber('2081')); // "२०८१"
 ```
 
-### Date Manipulation
-```ts
-const date = new NepaliDate(2081, 9, 15);
-const futureDate = date.addDays(10);
-const pastDate = date.addMonths(-2);
+## Examples
+
+### Basic Date Operations
+
+```typescript
+import { NepaliDate } from 'nepali-date-library';
+
+const date = new NepaliDate(2081, 9, 15); // Magh 15, 2081
+
+// Formatting
+console.log(date.toString());                    // "2081/10/15"
+console.log(date.format('YYYY-MM-DD'));         // "2081-10-15"
+console.log(date.format('MMMM DD, YYYY'));      // "Magh 15, 2081"
+console.log(date.format('dddd, mmmm dd, yyyy')); // "सोमबार, माघ १५, २०८१"
+
+// Date arithmetic
+const nextWeek = date.addDays(7);
+const nextMonth = date.addMonths(1);
 const nextYear = date.addYears(1);
+
+console.log(nextWeek.format('YYYY-MM-DD'));  // "2081-10-22"
+console.log(nextMonth.format('YYYY-MM-DD')); // "2081-11-15"
+console.log(nextYear.format('YYYY-MM-DD'));  // "2082-10-15"
 ```
 
-### Date Comparison
-```ts
-const date1 = new NepaliDate(2081, 5, 10);
-const date2 = new NepaliDate(2081, 5, 15);
+### Working with Different Date Formats
 
-console.log(date1.isBefore(date2)); // true
-console.log(date1.diff(date2, 'day')); // -5
-console.log(date1.isSame(date2, 'month')); // true
-```
+```typescript
+import { ADtoBS, BStoAD } from 'nepali-date-library';
 
-### Working with Quarters
-```ts
-// Get current quarter
-const currentQuarter = new NepaliDate().getCurrentQuarter();
+// Database integration - handle various formats
+function handleDatabaseDate(dateStr: string, sourceFormat: string): string {
+  // Convert to standard BS format for storage
+  return ADtoBS(dateStr, sourceFormat, 'YYYY-MM-DD');
+}
 
-// Get fiscal year quarter
-const fiscalQuarter = new NepaliDate().getCurrentFiscalYearQuarter();
+// User interface - display in user's preferred format
+function displayUserDate(bsDate: string, userPreference: string): string {
+  return BStoAD(bsDate, 'YYYY-MM-DD', userPreference);
+}
 
-// Get all quarters for a year
-const quarters = NepaliDate.getQuarters(2081);
-console.log(quarters.Q1); // { start: NepaliDate, end: NepaliDate }
+// Examples
+const dbDate1 = handleDatabaseDate('22/02/2025', 'DD/MM/YYYY');  // "2081-10-10"
+const dbDate2 = handleDatabaseDate('02.22.2025', 'MM.DD.YYYY');  // "2081-10-10"
 
-// Get fiscal year quarters
-const fiscalQuarters = NepaliDate.getFiscalYearQuarters(2081);
+const userDate1 = displayUserDate('2081-10-10', 'DD/MM/YYYY');   // "22/02/2025"
+const userDate2 = displayUserDate('2081-10-10', 'MM-DD-YYYY');   // "02-22-2025"
 ```
 
-### Calendar Generation
-```ts
-const calendarData = NepaliDate.getCalendarDays(2081, 4);
-console.log(calendarData.currentMonth.days); // [1, 2, 3, ..., 30]
-console.log(calendarData.prevMonth.days); // Days from previous month
+### Working with Localized Names
+
+```typescript
+import { MONTH_EN, MONTH_NP, WEEK_EN, WEEK_NP, NUMBER_NP } from 'nepali-date-library';
+
+const date = new NepaliDate();
+
+// Get localized month and day names
+const monthNameEn = MONTH_EN[date.getMonth()];
+const monthNameNp = MONTH_NP[date.getMonth()];
+const dayNameEn = WEEK_EN[date.getDay()];
+const dayNameNp = WEEK_NP[date.getDay()];
+
+// Convert to Nepali numerals
+const nepaliYear = date.getYear().toString()
+  .split('')
+  .map(digit => NUMBER_NP[parseInt(digit)])
+  .join('');
+
+console.log(`${dayNameEn}, ${monthNameEn} ${date.getDate()}, ${date.getYear()}`);
+// "Monday, Magh 15, 2081"
+
+console.log(`${dayNameNp}, ${monthNameNp} ${NUMBER_NP[1]}${NUMBER_NP[5]}, ${nepaliYear}`);
+// "सोमबार, माघ १५, २०८१"
 ```
 
-### Date Range Operations
-```ts
-const date = new NepaliDate(2081, 5, 15);
+### Fiscal Year Operations
+
+```typescript
+import { NepaliDate } from 'nepali-date-library';
 
-const startOfWeek = date.startOfWeek(); // Sunday of current week
-const endOfWeek = date.endOfWeek(); // Saturday of current week
-const startOfMonth = date.startOfMonth(); // 1st day of current month
-const endOfYear = date.endOfYear(); // Last day of current year
+// Current fiscal year info
+const currentFY = NepaliDate.getCurrentFiscalYear();
+console.log(`Current Fiscal Year: ${currentFY}`);
+
+const date = new NepaliDate();
+const currentFYQuarter = date.getCurrentFiscalYearQuarter();
+console.log(`Current FY Quarter: Q${currentFYQuarter}`);
+
+// Get all fiscal year quarters
+const fyQuarters = NepaliDate.getFiscalYearQuarters(2081);
+
+Object.entries(fyQuarters).forEach(([quarter, dates]) => {
+  console.log(`${quarter}: ${dates.start.format('YYYY-MM-DD')} to ${dates.end.format('YYYY-MM-DD')}`);
+});
+
+// Output:
+// Q1: 2081-04-01 to 2081-06-30 (Shrawan to Aswin)
+// Q2: 2081-07-01 to 2081-09-30 (Kartik to Poush)  
+// Q3: 2081-10-01 to 2081-12-30 (Magh to Chaitra)
+// Q4: 2082-01-01 to 2082-03-32 (Baisakh to Asar)
 ```
 
-### Validation
-```ts
-// Static validation
-console.log(NepaliDate.isValid(2081, 4, 32)); // false (day out of range)
+### Building a Calendar Component
+
+```typescript
+import { NepaliDate, WEEK_EN, MONTH_EN } from 'nepali-date-library';
+
+function generateCalendar(year: number, month: number) {
+  const calendarData = NepaliDate.getCalendarDays(year, month);
+  
+  // Create 6-week calendar grid
+  const calendar = [];
+  let dayIndex = 0;
+  
+  for (let week = 0; week < 6; week++) {
+    const weekDays = [];
+    
+    for (let day = 0; day < 7; day++) {
+      if (week === 0 && day < calendarData.prevRemainingDays) {
+        // Previous month days
+        weekDays.push({
+          day: calendarData.prevMonth.days[day],
+          isCurrentMonth: false,
+          isPrevMonth: true,
+          date: new NepaliDate(
+            calendarData.prevMonth.year, 
+            calendarData.prevMonth.month, 
+            calendarData.prevMonth.days[day]
+          )
+        });
+      } else if (dayIndex < calendarData.currentMonth.days.length) {
+        // Current month days
+        weekDays.push({
+          day: calendarData.currentMonth.days[dayIndex],
+          isCurrentMonth: true,
+          isPrevMonth: false,
+          date: new NepaliDate(year, month, calendarData.currentMonth.days[dayIndex])
+        });
+        dayIndex++;
+      } else {
+        // Next month days
+        const nextDayIndex = dayIndex - calendarData.currentMonth.days.length;
+        weekDays.push({
+          day: calendarData.nextMonth.days[nextDayIndex],
+          isCurrentMonth: false,
+          isPrevMonth: false,
+          date: new NepaliDate(
+            calendarData.nextMonth.year, 
+            calendarData.nextMonth.month, 
+            calendarData.nextMonth.days[nextDayIndex]
+          )
+        });
+      }
+    }
+    calendar.push(weekDays);
+  }
+  
+  return {
+    month: MONTH_EN[month],
+    year: year,
+    weeks: calendar,
+    weekHeaders: WEEK_EN
+  };
+}
 
-// Instance validation
-const date = new NepaliDate(2081, 5, 10);
-console.log(date.isValid()); // true
+// Usage
+const calendar = generateCalendar(2081, 9); // Magh 2081
+console.log(calendar.month); // "Magh"
+console.log(calendar.weeks); // 6 weeks of calendar data
 ```
 
-### Name Utilities
-```ts
-// Month names
-console.log(NepaliDate.getMonthName(0, false, false)); // "Baisakh"
-console.log(NepaliDate.getMonthName(0, true, true)); // "बै"
+### Date Conversion Workflow
 
-// Day names
-console.log(NepaliDate.getDayName(0, false, true)); // "आइतबार"
-console.log(NepaliDate.getDayName(1, true, false)); // "Mon"
+```typescript
+import { NepaliDate, ADtoBS, BStoAD } from 'nepali-date-library';
+
+// Convert user input
+function handleDateConversion(inputDate: string, fromCalendar: 'AD' | 'BS') {
+  try {
+    if (fromCalendar === 'AD') {
+      const bsDate = ADtoBS(inputDate);
+      const nepaliDate = new NepaliDate(bsDate);
+      
+      return {
+        converted: bsDate,
+        formatted: nepaliDate.format('MMMM DD, YYYY'),
+        nepaliFormatted: nepaliDate.format('mmmm dd, yyyy'),
+        dayName: nepaliDate.format('DDDD')
+      };
+    } else {
+      const adDate = BStoAD(inputDate);
+      const jsDate = new Date(adDate);
+      
+      return {
+        converted: adDate,
+        formatted: jsDate.toLocaleDateString('en-US', { 
+          year: 'numeric', 
+          month: 'long', 
+          day: 'numeric' 
+        })
+      };
+    }
+  } catch (error) {
+    throw new Error(`Invalid date: ${error.message}`);
+  }
+}
+
+// Examples
+console.log(handleDateConversion('2025-02-22', 'AD'));
+// { converted: "2081-10-10", formatted: "Magh 10, 2081", ... }
+
+console.log(handleDateConversion('2081-10-14', 'BS'));
+// { converted: "2025-02-26", formatted: "February 26, 2025" }
 ```
 
----
+### Advanced Date Range Queries
+
+```typescript
+import { NepaliDate } from 'nepali-date-library';
+
+// Find all Fridays in a month
+function getFridaysInMonth(year: number, month: number): NepaliDate[] {
+  const fridays: NepaliDate[] = [];
+  const startOfMonth = new NepaliDate(year, month, 1);
+  const endOfMonth = startOfMonth.endOfMonth();
+  
+  let current = startOfMonth.clone();
+  
+  // Find first Friday
+  while (current.getDay() !== 5) { // 5 = Friday
+    current = current.addDays(1);
+  }
+  
+  // Collect all Fridays
+  while (current.isBefore(endOfMonth) || current.isEqual(endOfMonth)) {
+    fridays.push(current.clone());
+    current = current.addDays(7);
+  }
+  
+  return fridays;
+}
+
+// Usage
+const fridaysInMagh = getFridaysInMonth(2081, 9);
+fridaysInMagh.forEach(friday => {
+  console.log(friday.format('DDDD, MMMM DD')); // "Friday, Magh 3", etc.
+});
+```
 
 ## Error Handling
-- Throws an error if an invalid date format is used in constructor or parse method
-- Throws an error if the Nepali date is out of the supported range
-- Validates input parameters and throws appropriate errors for invalid values
+
+The library provides comprehensive error handling:
+
+```typescript
+try {
+  // Invalid date format
+  const invalid1 = ADtoBS('25-02-22'); // Throws: Invalid date format
+  
+  // Out of range
+  const invalid2 = new NepaliDate(1975, 0, 1); // Throws: Year out of range
+  
+  // Invalid day for month
+  const invalid3 = new NepaliDate(2081, 4, 32); // Throws: Invalid date
+  
+  // Invalid quarter
+  const invalid4 = NepaliDate.getQuarter(5, 2081); // Throws: Quarter must be 1-4
+  
+} catch (error) {
+  console.error(error.message);
+}
+
+// Safe validation
+if (NepaliDate.isValid(2081, 9, 15)) {
+  const safeDate = new NepaliDate(2081, 9, 15);
+  console.log('Date created successfully');
+}
+```
 
 ## Supported Date Range
-The library supports Nepali dates within a specific range. Use `NepaliDate.minimum()` and `NepaliDate.maximum()` to get the supported date boundaries.
 
-## Acknowledgements
-This project was inspired by [nepali-date](https://github.com/sharingapples/nepali-date).
+- **Start:** 1976 BS (Bikram Sambat year 1976)
+- **End:** 2100 BS (Bikram Sambat year 2100)
+- **Total:** 125 years of accurate calendar data
+
+```typescript
+const minDate = NepaliDate.minimum(); // JavaScript Date for 1976/1/1 BS
+const maxDate = NepaliDate.maximum(); // JavaScript Date for 2100/12/31 BS
+```
+
+## Important Notes
+
+### Month Indexing
+- **Internal storage and input:** Months are 0-indexed (0-11) like JavaScript Date
+- **Display:** `toString()` method shows months as 1-12 for readability
+- **Baisakh = 0, Jestha = 1, ..., Chaitra = 11**
+
+### Immutability
+All date manipulation methods return new instances rather than modifying existing ones:
+
+```typescript
+const original = new NepaliDate(2081, 9, 15);
+const modified = original.addDays(10);
+
+console.log(original.toString());  // "2081/10/15" (unchanged)
+console.log(modified.toString());  // "2081/10/25" (new instance)
+```
+
+### Thread Safety
+The library is designed for functional programming patterns and is safe for concurrent use.
+
+## Migration from Other Libraries
+
+If you're migrating from other Nepali date libraries:
+
+```typescript
+// Instead of: nepaliDate.getBS()
+const nepaliDate = new NepaliDate();
+console.log(nepaliDate.toString());
+
+// Instead of: nepaliDate.getAD() 
+console.log(nepaliDate.getEnglishDate());
+
+// Instead of: nepaliDate.format('YYYY-MM-DD')
+console.log(nepaliDate.format('YYYY-MM-DD'));
+```
+
+## TypeScript Support
+
+The library is written in TypeScript and provides full type definitions:
+
+```typescript
+import { NepaliDate } from 'nepali-date-library';
+
+// Full IntelliSense support
+const date: NepaliDate = new NepaliDate();
+const quarter: number = date.getCurrentQuarter(); // Type-safe
+const formatted: string = date.format('YYYY-MM-DD'); // Type-safe
+```
+
+## Browser Compatibility
+
+- **Modern Browsers:** Chrome 60+, Firefox 55+, Safari 10.1+, Edge 79+
+- **Node.js:** Version 12+
+- **Dependencies:** None (zero external dependencies)
+
+## Contributing
+
+We welcome contributions! Please feel free to submit issues and enhancement requests.
 
 ## License
-MIT License
+
+MIT License - see LICENSE file for details.
+
+## Acknowledgments
+
+This project was inspired by [nepali-date](https://github.com/sharingapples/nepali-date) and provides enhanced functionality with TypeScript support and additional features.
+
+## Performance Considerations
+
+### Memory Usage
+- Minimal memory footprint with efficient date calculations
+- Calendar data is pre-computed and stored in constants
+- No unnecessary object creation in core operations
+
+### Computation Speed
+- Fast date conversions using pre-calculated lookup tables
+- O(1) complexity for most operations
+- Optimized algorithms for date arithmetic
+
+## Common Use Cases
+
+### E-commerce Applications
+```typescript
+// Calculate delivery dates in Nepali calendar
+function calculateDeliveryDate(orderDate: string, deliveryDays: number) {
+  const bsOrderDate = new NepaliDate(ADtoBS(orderDate));
+  const deliveryDate = bsOrderDate.addDays(deliveryDays);
+  
+  return {
+    nepali: deliveryDate.format('MMMM DD, YYYY'),
+    english: deliveryDate.format('mmmm dd, yyyy'),
+    dayOfWeek: deliveryDate.format('DDDD')
+  };
+}
+
+const delivery = calculateDeliveryDate('2025-02-20', 5);
+console.log(delivery);
+// { nepali: "Magh 13, 2081", english: "माघ १३, २०८१", dayOfWeek: "Wednesday" }
+```
+
+### Financial Applications
+```typescript
+// Calculate fiscal year quarters for reporting
+function getFiscalYearReport(fiscalYear: number) {
+  const quarters = NepaliDate.getFiscalYearQuarters(fiscalYear);
+  
+  return Object.entries(quarters).map(([quarter, dates]) => ({
+    quarter,
+    startDate: dates.start.format('YYYY-MM-DD'),
+    endDate: dates.end.format('YYYY-MM-DD'),
+    daysInQuarter: dates.start.diff(dates.end, 'day') * -1 + 1
+  }));
+}
+
+const report = getFiscalYearReport(2081);
+console.log(report);
+```
+
+### Event Planning
+```typescript
+// Find next occurrence of a specific weekday
+function findNextWeekday(startDate: NepaliDate, targetDay: number): NepaliDate {
+  let current = startDate.addDays(1);
+  
+  while (current.getDay() !== targetDay) {
+    current = current.addDays(1);
+  }
+  
+  return current;
+}
+
+// Find all Saturdays in a month for scheduling
+function getSaturdaysInMonth(year: number, month: number): NepaliDate[] {
+  const saturdays: NepaliDate[] = [];
+  const monthStart = new NepaliDate(year, month, 1);
+  const monthEnd = monthStart.endOfMonth();
+  
+  let current = monthStart.clone();
+  
+  // Find first Saturday
+  while (current.getDay() !== 6) {
+    current = current.addDays(1);
+  }
+  
+  // Collect all Saturdays
+  while (current.getDate() <= monthEnd.getDate() && current.getMonth() === month) {
+    saturdays.push(current.clone());
+    current = current.addDays(7);
+  }
+  
+  return saturdays;
+}
+```
+
+### Age Calculation
+```typescript
+// Calculate age in Nepali calendar
+function calculateNepaliAge(birthDate: string): {
+  years: number;
+  months: number;
+  days: number;
+  totalDays: number;
+} {
+  const birth = new NepaliDate(birthDate);
+  const today = new NepaliDate();
+  
+  let years = today.getYear() - birth.getYear();
+  let months = today.getMonth() - birth.getMonth();
+  let days = today.getDate() - birth.getDate();
+  
+  // Adjust for negative days
+  if (days < 0) {
+    months--;
+    const prevMonth = today.addMonths(-1);
+    days += prevMonth.daysInMonth();
+  }
+  
+  // Adjust for negative months
+  if (months < 0) {
+    years--;
+    months += 12;
+  }
+  
+  const totalDays = birth.diff(today, 'day') * -1;
+  
+  return { years, months, days, totalDays };
+}
+
+const age = calculateNepaliAge('2060-05-15');
+console.log(`Age: ${age.years} years, ${age.months} months, ${age.days} days`);
+```
+
+## Integration Examples
+
+### React Component
+```typescript
+import React, { useState } from 'react';
+import { NepaliDate, MONTH_EN } from 'nepali-date-library';
+
+const NepaliDatePicker: React.FC = () => {
+  const [selectedDate, setSelectedDate] = useState(new NepaliDate());
+  
+  const handleDateChange = (year: number, month: number, day: number) => {
+    if (NepaliDate.isValid(year, month, day)) {
+      setSelectedDate(new NepaliDate(year, month, day));
+    }
+  };
+  
+  return (
+    <div>
+      <h3>Selected Date: {selectedDate.format('MMMM DD, YYYY')}</h3>
+      <p>In Nepali: {selectedDate.format('mmmm dd, yyyy')}</p>
+      <p>Day: {selectedDate.format('DDDD')}</p>
+      <p>Gregorian: {selectedDate.getEnglishDate().toLocaleDateString()}</p>
+      
+      {/* Add your date picker UI here */}
+    </div>
+  );
+};
+```
+
+### Express.js API Endpoint
+```typescript
+import express from 'express';
+import { NepaliDate, ADtoBS, BStoAD } from 'nepali-date-library';
+
+const app = express();
+
+app.get('/api/convert/:fromCalendar/:date', (req, res) => {
+  try {
+    const { fromCalendar, date } = req.params;
+    
+    if (fromCalendar === 'ad') {
+      const bsDate = ADtoBS(date);
+      const nepaliDate = new NepaliDate(bsDate);
+      
+      res.json({
+        original: date,
+        converted: bsDate,
+        formatted: {
+          english: nepaliDate.format('MMMM DD, YYYY'),
+          nepali: nepaliDate.format('mmmm dd, yyyy')
+        },
+        dayOfWeek: nepaliDate.format('DDDD'),
+        quarter: nepaliDate.getCurrentQuarter(),
+        fiscalYear: NepaliDate.getCurrentFiscalYear(),
+        isLeapYear: nepaliDate.isLeapYear()
+      });
+    } else if (fromCalendar === 'bs') {
+      const adDate = BStoAD(date);
+      const jsDate = new Date(adDate);
+      
+      res.json({
+        original: date,
+        converted: adDate,
+        formatted: jsDate.toLocaleDateString('en-US', {
+          year: 'numeric',
+          month: 'long', 
+          day: 'numeric'
+        })
+      });
+    } else {
+      res.status(400).json({ error: 'Invalid calendar type. Use "ad" or "bs"' });
+    }
+  } catch (error) {
+    res.status(400).json({ error: error.message });
+  }
+});
+
+// Fiscal year endpoints
+app.get('/api/fiscal-year/:year/quarters', (req, res) => {
+  try {
+    const year = parseInt(req.params.year);
+    const quarters = NepaliDate.getFiscalYearQuarters(year);
+    
+    const response = Object.entries(quarters).map(([quarter, dates]) => ({
+      quarter,
+      startDate: dates.start.format('YYYY-MM-DD'),
+      endDate: dates.end.format('YYYY-MM-DD'),
+      startFormatted: dates.start.format('MMMM DD, YYYY'),
+      endFormatted: dates.end.format('MMMM DD, YYYY')
+    }));
+    
+    res.json(response);
+  } catch (error) {
+    res.status(400).json({ error: error.message });
+  }
+});
+```
+
+## Testing
+
+### Unit Test Examples
+```typescript
+import { NepaliDate, ADtoBS, BStoAD } from 'nepali-date-library';
+
+describe('NepaliDate Library', () => {
+  test('should convert AD to BS correctly', () => {
+    expect(ADtoBS('2025-02-22')).toBe('2081-10-10');
+    expect(ADtoBS('2024-12-15')).toBe('2081-08-30');
+  });
+  
+  test('should convert BS to AD correctly', () => {
+    expect(BStoAD('2081-10-14')).toBe('2025-02-26');
+    expect(BStoAD('2081-05-15')).toBe('2024-08-30');
+  });
+  
+  test('should handle date arithmetic correctly', () => {
+    const date = new NepaliDate(2081, 9, 15);
+    const futureDate = date.addDays(10);
+    
+    expect(futureDate.getDate()).toBe(25);
+    expect(futureDate.getMonth()).toBe(9);
+    expect(futureDate.getYear()).toBe(2081);
+  });
+  
+  test('should validate dates correctly', () => {
+    expect(NepaliDate.isValid(2081, 4, 31)).toBe(true);
+    expect(NepaliDate.isValid(2081, 4, 32)).toBe(false);
+    expect(NepaliDate.isValid(2081, 12, 1)).toBe(false); // Month out of range
+  });
+  
+  test('should handle fiscal year calculations', () => {
+    const currentFY = NepaliDate.getCurrentFiscalYear();
+    const quarters = NepaliDate.getFiscalYearQuarters(currentFY);
+    
+    expect(Object.keys(quarters)).toEqual(['Q1', 'Q2', 'Q3', 'Q4']);
+    expect(quarters.Q1.start.getMonth()).toBe(3); // Shrawan (index 3)
+  });
+});
+```
+
+## Frequently Asked Questions
+
+### Why are months 0-indexed?
+To maintain consistency with JavaScript's Date object and provide seamless integration with existing JavaScript/TypeScript codebases.
+
+### How accurate are the date conversions?
+The library uses official Nepali calendar data from 1976 BS to 2100 BS and constantly updates the maps every year, ensuring high accuracy for all supported date ranges.
+
+### Can I use this library for historical dates before 1976 BS?
+No, the library only supports dates from 1976 BS onwards due to available calendar data limitations.
+
+### How do I handle timezone differences?
+The library works with the local timezone of the JavaScript environment. For UTC operations, convert the underlying JavaScript Date to UTC before processing.
+
+### Is the library suitable for server-side applications?
+Yes, the library is designed to work seamlessly in both browser and Node.js environments.