bn-calendar 1.2.0 → 1.2.2

package/README.md

@@ -85,17 +85,109 @@ yarn add bn-calendar
 
 ## Import
 
-```ts
-// Main class
+```typescript
 import { BanglaCalendar } from 'bn-calendar';
+```
+
+---
+
+## Table of Contents
+
+- [Quick Examples](#quick-examples)
+- [API Reference](#api-reference)
+  - [Constructor](#constructor)
+  - [Constructor Signatures](#constructor-signatures)
+  - [Parameters](#parameters)
+  - [Behavior](#behavior)
+  - [Examples](#examples)
+  - [Properties](#properties)
+    - [variant](#variant)
+    - [year](#year)
+    - [month](#month)
+    - [date](#date)
+    - [gregorian](#gregorian)
+    - [weekDay](#weekday)
+    - [isoWeekDay](#isoweekday)
+  - [Instance Methods](#instance-methods)
+    - [format()](#format)
+    - [valueOf()](#valueof)
+    - [isLeapYear()](#isleapyear)
+    - [toDate()](#todate)
+    - [getSeasonName()](#getseasonname)
+    - [getMonthName()](#getmonthname)
+    - [getDayName()](#getdayname)
+    - [startOfMonth()](#startofmonth)
+    - [endOfMonth()](#endofmonth)
+    - [startOfYear()](#startofyear)
+    - [endOfYear()](#endofyear)
+    - [daysInMonth()](#daysinmonth)
+    - [toJSON()](#tojson)
+    - [toString()](#tostring)
+    - [toStringEn()](#tostringen)
+    - [addDays()](#adddays)
+    - [addWeeks()](#addweeks)
+    - [addMonths()](#addmonths)
+    - [addYears()](#addyears)
+    - [$hasVariantConfig()](#hasvariantconfig)
+  - [Static Methods](#static-methods)
+    - [isBanglaYear()](#isbanglayear)
+    - [isBanglaYearEn()](#isbanglayearen)
+    - [isBanglaMonth()](#isbanglamonth)
+    - [isBanglaMonthEn()](#isbanglamonthen)
+    - [isBanglaDate()](#isbangladate)
+    - [isBanglaDateEn()](#isbangladateen)
+    - [isBanglaDateString()](#isbangladatestring)
+  - [Symbol Methods](#symbol-methods)
+    - [[Symbol.toPrimitive]](#symboltoprimitive)
+    - [[Symbol.toStringTag]](#symboltostringtag)
+- [Detailed Examples](#detailed-examples)
+  - [Basic Usage](#basic-usage)
+  - [Date Conversion](#date-conversion)
+  - [Month Operations](#month-operations)
+- [Aliases](#aliases)
+- [Type Definitions](#type-definitions)
+- [Bangla Digit Conversion Utilities](#bangla-digit-conversion-utilities)
+  - [Import](#import)
+  - [banglaToDigit()](#banglatodigit)
+  - [digitToBangla()](#digittobangla)
+  - [Type Definitions](#type-definitions-1)
+- [Related Packages](#-related-packages)
+- [License](#license)
 
-// Utilities
-import { banglaToDigit, digitToBangla } from 'bn-calendar/utils';
+---
+
+## Quick Examples
+
+**`BanglaCalendar`** - The class to create, manipulate, and convert dates between the Bangla and Gregorian calendar systems.
+
+> It supports two calendar variants: `'revised-2019'` (default) and `'revised-1966'`.
+
+```typescript
+// Create from current date
+const today = new BanglaCalendar();
+
+// Create from Bangla date string (Bangla digit)
+const date0 = new BanglaCalendar('১৪৩২-১১-০৮');
+
+// Create from Gregorian date
+const date1 = new BanglaCalendar('2023-04-14'); // Latin digit
+const date2 = new BanglaCalendar(new Date('2023-04-14')); // Date object
+
+// Create with specific Bangla date using Latin digits
+const date3 = new BanglaCalendar(1430, 1, 1);
+
+// Create with specific Bangla date using Bangla digits
+const date4 = new BanglaCalendar('১৪৩০', '১', '১');
+
+// Create with specific variant
+const date5 = new BanglaCalendar('১৪৩০', '১', '১', { variant: 'revised-1966' });
 ```
 
 ---
 
-## Constructor
+## API Reference
+
+### Constructor
 
 Creates a new `BanglaCalendar` instance from various input formats.
 
@@ -208,49 +300,9 @@ new BanglaCalendar('১৪৩০', '১', '১', { variant: 'revised-1966' });
 
 ---
 
-## Available Methods
-
-- **Instance Methods**
-  - [valueOf](#valueof)
-  - [isLeapYear](#isleapyear)
-  - [toDate](#todate)
-  - [getSeasonName](#getseasonname)
-  - [getMonthName](#getmonthname)
-  - [getDayName](#getdayname)
-  - [startOfMonth](#startofmonth)
-  - [endOfMonth](#endofmonth)
-  - [startOfYear](#startofyear)
-  - [endOfYear](#endofyear)
-  - [daysInMonth](#daysinmonth)
-  - [toJSON](#tojson)
-  - [toString](#tostring)
-  - [toStringEn](#tostringen)
-  - [format](#format)
-  - [addDays](#adddays)
-  - [addWeeks](#addweeks)
-  - [addMonths](#addmonths)
-  - [addYears](#addyears)
-  - [$hasVariantConfig](#hasvariantconfig)
-
-- **Static Methods**
-  - [isBanglaYear](#isbanglayear)
-  - [isBanglaYearEn](#isbanglayear)
-  - [isBanglaMonth](#isbanglamonth)
-  - [isBanglaMonthEn](#isbanglamonthen)
-  - [isBanglaDate](#isbangladate)
-  - [isBanglaDateEn](#isbangladateen)
-  - [isBanglaDateString](#isbangladatestring)
-
-- **Symbol Methods**
-
-  - [Symbol.toPrimitive](#symboltoprimitive)
-  - [Symbol.toStringTag](#symboltostringtag)
-
----
-
-## Properties
+### Properties
 
-### variant
+#### variant
 
 ```typescript
 readonly variant: BnCalendarVariant
@@ -272,7 +324,7 @@ console.log(cal2019.isLeapYear()); // Follows Gregorian rules
 console.log(cal1966.isLeapYear()); // Follows Bangla year % 4 === 2 rule
 ```
 
-### year
+#### year
 
 ```typescript
 readonly year: Readonly<{
@@ -293,7 +345,7 @@ const banglaYear: string = bnCal.year.bn; // Type: BanglaYear
 const latinYear: number = bnCal.year.en;  // Type: number
 ```
 
-### month
+#### month
 
 ```typescript
 readonly month: Readonly<{
@@ -317,7 +369,7 @@ console.log(bnCal.getMonthName('en')); // 'Bhadro'
 const monthNumber: number = bnCal.month.en; // Type: NumberRange<1, 12>
 ```
 
-### date
+#### date
 
 ```typescript
 readonly date: Readonly<{
@@ -337,7 +389,7 @@ console.log(bnCal.date.en);  // 15 (Latin digits)
 const dayNumber: number = bnCal.date.en; // Type: NumberRange<1, 31>
 ```
 
-### gregorian
+#### gregorian
 
 ```typescript
 readonly gregorian: Readonly<{
@@ -364,7 +416,7 @@ const fromGregorian = new BanglaCalendar(new Date(2023, 3, 14)); // April 14, 20
 console.log(fromGregorian.toJSON()); // '১৪৩০-০১-০১'
 ```
 
-### weekDay
+#### weekDay
 
 ```typescript
 readonly weekDay: Enumerate<7>
@@ -390,7 +442,7 @@ if (bnCal.weekDay === 0) {
 }
 ```
 
-### isoWeekDay
+#### isoWeekDay
 
 ```typescript
 readonly isoWeekDay: NumberRange<1, 7>
@@ -419,67 +471,80 @@ console.log(mondayDate.toJSON()); // Get Monday's date
 
 ---
 
-## Examples
+### Instance Methods
 
-### Basic Usage
-
-```typescript
-const today = new BanglaCalendar();
-console.log(today.toString()); // "শুক্রবার, ১ বৈশাখ, ১৪৩০ [গ্রীষ্ম]"
-console.log(today.toJSON());   // "১৪৩০-০১-০১"
+#### format()
 
-const specificDate = new BanglaCalendar('১৪৩২-১১-০৮');
-console.log(specificDate.getMonthName()); // "ফাল্গুন"
-```
+Formats the current date as a Bangla calendar date string using customizable tokens.
 
-### Date Conversion
+##### Signature
 
 ```typescript
-const bnDate = new BanglaCalendar('১৪৩০', '১', '১');
-const gregorianDate = bnDate.toDate();
-console.log(gregorianDate.toISOString()); // "2023-04-14T00:00:00.000Z"
+format(format?: BanglaDateFormat): string
 ```
 
-### Month Operations
+##### Parameters
+
+- `format`: Format string using tokens (default: `'ddd, DD mmmm (SS), YYYY বঙ্গাব্দ'`)
+
+##### Return Value
+
+Formatted Bangla date string according to the specified format.
+
+##### Examples
 
 ```typescript
-const date = new BanglaCalendar('১৪৩০', '৫', '১৫');
-console.log(date.startOfMonth().toString()); // "১ জ্যৈষ্ঠ ১৪৩০"
-console.log(date.endOfMonth().toString());   // "৩১ জ্যৈষ্ঠ ১৪৩০"
+const bnCal = new BanglaCalendar('2023-04-14');
+
+bnCal.format();
+// Returns: 'শুক্রবার, বৈশাখ ০১ (গ্রীষ্মকাল), ১৪৩০ বঙ্গাব্দ'
+
+bnCal.format('YYYY-MM-DD');
+// Returns: '১৪৩০-০১-০১'
+
+bnCal.format('mmmm DD, YYYY');
+// Returns: 'বৈশাখ ০১, ১৪৩০'
 ```
 
----
+##### Format Tokens
 
-## Aliases
+- **Year**: `YYYY`/`yyyy` (full year), `YY`/`yy` (last 2 digits)
+- **Month**: `M`/`MM` (padded), `mmm` (short name), `mmmm` (full name)
+- **Day**: `D`/`DD` (padded), `Do` (cardinal)
+- **Weekday**: `d` (short), `dd` (without 'বার'), `ddd` (full)
+- **Season**: `S` (season), `SS` (season with 'কাল' suffix)
 
-`BanglaCalendar` can also be imported using **BnCalendar** and **Bongabdo** aliases.
+##### Escaping Text
 
----
+To output raw text (not interpreted as a token), wrap it in square brackets:
+
+- `[আজ] ddd` → `আজ রবিবার`
+- `[year ]YYYY` → `year ২০২৫`
 
-## API Reference for BanglaCalendar
+---
 
-## valueOf()
+#### valueOf()
 
 Gets the numeric timestamp (in milliseconds) for the current Bangla date.
 
-### Signature
+##### Signature
 
 ```typescript
 valueOf(): number
 ```
 
-### Return Value
+##### Return Value
 
 Unix timestamp in milliseconds representing the Gregorian equivalent of the current Bangla date.
 
-### Example
+##### Example
 
 ```typescript
 const bnCal = new BanglaCalendar('১৪৩০', '১', '১');
 const timestamp = bnCal.valueOf(); // 1681430400000 (equivalent to April 14, 2023)
 ```
 
-### Remarks
+##### Remarks
 
 - Internally calls [**`toDate().getTime()`**](#todate) to convert the Bangla date to Gregorian and get its timestamp
 - The time component is normalized to midnight UTC during conversion
@@ -487,81 +552,81 @@ const timestamp = bnCal.valueOf(); // 1681430400000 (equivalent to April 14, 202
 
 ---
 
-## isLeapYear()
+#### isLeapYear()
 
 Checks if the current Bangla year is a leap year according to the selected calendar variant.
 
-### Signature
+##### Signature
 
 ```typescript
 isLeapYear(): boolean
 ```
 
-### Return Value
+##### Return Value
 
 `true` if the year is a leap year, `false` otherwise.
 
-### Example
+##### Example
 
 ```typescript
 const date = new BanglaCalendar(1430, 1, 1);
 const isLeap = date.isLeapYear(); // false
 ```
 
-### Remarks
+##### Remarks
 
 - **Revised-2019**: Follows Gregorian leap year rules (divisible by 4, not by 100 unless also divisible by 400)
 - **Revised-1966**: Leap year when `bnYear % 4 === 2`
 
 ---
 
-## toDate()
+#### toDate()
 
 Converts the Bangla calendar date to a JavaScript Date object.
 
-### Signature
+##### Signature
 
 ```typescript
 toDate(): Date
 ```
 
-### Return Value
+##### Return Value
 
 Gregorian Date object equivalent to the Bangla date.
 
-### Example
+##### Example
 
 ```typescript
 const bnDate = new BanglaCalendar('১৪৩০', '১', '১');
 const gregorianDate = bnDate.toDate(); // Date for April 14, 2023
 ```
 
-### Remarks
+##### Remarks
 
 - Time component is always set to `00:00:00` in UTC
 - Accounts for calendar variant and leap year rules
 
 ---
 
-## getSeasonName()
+#### getSeasonName()
 
 Gets the Bangla season name for the current date.
 
-### Signature
+##### Signature
 
 ```typescript
 getSeasonName<Locale extends $BnEn = 'bn'>(locale?: Locale): BanglaSeasonName<Locale>
 ```
 
-### Parameters
+##### Parameters
 
 - `locale`: Output locale (`'bn'` for Bengali, `'en'` for English). Defaults to `'bn'`.
 
-### Return Value
+##### Return Value
 
 Name of the season in the specified locale.
 
-### Example
+##### Example
 
 ```typescript
 const bnCal = new BanglaCalendar('2023-04-14');
@@ -569,7 +634,7 @@ bnCal.getSeasonName(); // "গ্রীষ্ম"
 bnCal.getSeasonName('en'); // "Grisma (Summer)"
 ```
 
-### Seasons
+##### Seasons
 
 - গ্রীষ্ম (Summer): Mid-April to Mid-June
 - বর্ষা (Monsoon): Mid-June to Mid-August
@@ -580,25 +645,25 @@ bnCal.getSeasonName('en'); // "Grisma (Summer)"
 
 ---
 
-## getMonthName()
+#### getMonthName()
 
 Gets the Bangla name of the month for the current date.
 
-### Signature
+##### Signature
 
 ```typescript
 getMonthName<Locale extends $BnEn = 'bn'>(locale?: Locale): BanglaMonthName<Locale>
 ```
 
-### Parameters
+##### Parameters
 
 - `locale`: Output locale (`'bn'` for Bengali, `'en'` for English). Defaults to `'bn'`.
 
-### Return Value
+##### Return Value
 
 Name of the month in the specified locale.
 
-### Example
+##### Example
 
 ```typescript
 const bnCal = new BanglaCalendar('2023-04-14');
@@ -608,25 +673,25 @@ bnCal.getMonthName('en'); // "Boishakh"
 
 ---
 
-## getDayName()
+#### getDayName()
 
 Gets the Bangla name of the weekday for the current date.
 
-### Signature
+##### Signature
 
 ```typescript
 getDayName<Locale extends $BnEn = 'bn'>(locale?: Locale): BanglaDayName<Locale>
 ```
 
-### Parameters
+##### Parameters
 
 - `locale`: Output locale (`'bn'` for Bengali, `'en'` for English). Defaults to `'bn'`.
 
-### Return Value
+##### Return Value
 
 Name of the weekday in the specified locale.
 
-### Example
+##### Example
 
 ```typescript
 const bnCal = new BanglaCalendar('2023-04-14'); // Friday
@@ -636,77 +701,77 @@ bnCal.getDayName('en'); // "Shukrobar (Friday)"
 
 ---
 
-## startOfMonth()
+#### startOfMonth()
 
 Gets a new BanglaCalendar instance representing the first day of the current month.
 
-### Signature
+##### Signature
 
 ```typescript
 startOfMonth(): BanglaCalendar
 ```
 
-### Return Value
+##### Return Value
 
 A BanglaCalendar instance set to the 1st day of the current month.
 
-### Example
+##### Example
 
 ```typescript
 const bnCal = new BanglaCalendar('১৪৩০', '৫', '১৫');
 const startOfMonth = bnCal.startOfMonth(); // ১ জ্যৈষ্ঠ ১৪৩০
 ```
 
-### Remarks
+##### Remarks
 
 - Preserves the calendar variant of the original
 - Time component is set to midnight UTC
 
 ---
 
-## endOfMonth()
+#### endOfMonth()
 
 Gets a new `BanglaCalendar` instance representing the last day of the current month.
 
-### Signature
+##### Signature
 
 ```typescript
 endOfMonth(): BanglaCalendar
 ```
 
-### Return Value
+##### Return Value
 
 A `BanglaCalendar` instance set to the last day of the current month.
 
-### Example
+##### Example
 
 ```typescript
 const bnCal = new BanglaCalendar('১৪৩০', '৫', '১৫');
 const endOfMonth = bnCal.endOfMonth(); // ৩১ জ্যৈষ্ঠ ১৪৩০
 ```
 
-### Remarks
+##### Remarks
 
 - Accounts for month length variations (29/30/31 days)
 - Includes leap year adjustments
 
 ---
 
-## startOfYear()
+#### startOfYear()
 
 Gets a new `BanglaCalendar` instance representing the first day of the current year (১ বৈশাখ).
 
-### Signature
+##### Signature
 
 ```typescript
 startOfYear(): BanglaCalendar
 ```
 
-### Return Value
+##### Return Value
 
 A `BanglaCalendar` instance set to ১ বৈশাখ of the current year.
 
-### Example
+##### Example
 
 ```typescript
 const bnCal = new BanglaCalendar('১৪৩০', '৫', '১৫');
@@ -715,21 +780,21 @@ const startOfYear = bnCal.startOfYear(); // ১ বৈশাখ ১৪৩০
 
 ---
 
-## endOfYear()
+#### endOfYear()
 
 Gets a new `BanglaCalendar` instance representing the last day of the current year (৩০ চৈত্র).
 
-### Signature
+##### Signature
 
 ```typescript
 endOfYear(): BanglaCalendar
 ```
 
-### Return Value
+##### Return Value
 
 A `BanglaCalendar` instance set to ৩০ চৈত্র of the current year.
 
-### Example
+##### Example
 
 ```typescript
 const bnCal = new BanglaCalendar('১৪৩০', '৫', '১৫');
@@ -738,25 +803,25 @@ const endOfYear = bnCal.endOfYear(); // ৩০ চৈত্র ১৪৩০
 
 ---
 
-## daysInMonth()
+#### daysInMonth()
 
 Gets the number of days in a Bangla month.
 
-### Signature
+##### Signature
 
 ```typescript
 daysInMonth(month?: NumberRange<1, 12>): NumberRange<29, 31>
 ```
 
-### Parameters
+##### Parameters
 
 - `month`: Optional Bangla month (1-12 in Latin digits). If not provided, uses the current month.
 
-### Return Value
+##### Return Value
 
 Number of days in the specified month (29, 30, or 31).
 
-### Example
+##### Example
 
 ```typescript
 const bnCal = new BanglaCalendar('১৪৩০', '১', '১');
@@ -766,76 +831,76 @@ bnCal.daysInMonth(12); // 30 (চৈত্র has 30 days)
 
 ---
 
-## toJSON()
+#### toJSON()
 
 Returns a string representation of the Bangla date in ISO-like format (`YYYY-MM-DD` with Bangla digits).
 
-### Signature
+##### Signature
 
 ```typescript
 toJSON(): string
 ```
 
-### Return Value
+##### Return Value
 
 Bangla date string in the format: `"YYYY-MM-DD"` (e.g., `"১৪৩০-০১-০১"`).
 
-### Example
+##### Example
 
 ```typescript
 const bnCal = new BanglaCalendar('2023-04-14');
 console.log(bnCal.toJSON()); // "১৪৩০-০১-০১"
 ```
 
-### Remarks
+##### Remarks
 
 - Automatically called by `JSON.stringify()`
 - Output follows: `"বছর-মাস-দিন"` with zero-padded Bangla digits
 
 ---
 
-## toString()
+#### toString()
 
 Returns a string representation of the Bangla date in Bengali format.
 
-### Signature
+##### Signature
 
 ```typescript
 toString(): string
 ```
 
-### Return Value
+##### Return Value
 
 Bangla date string in the format: "শুক্রবার, ১৫ জ্যৈষ্ঠ, ১৪৩০ [গ্রীষ্ম]".
 
-### Example
+##### Example
 
 ```typescript
 const bnCal = new BanglaCalendar('2023-04-14');
 console.log(bnCal.toString()); // "শুক্রবার, ১ বৈশাখ, ১৪৩০ [গ্রীষ্ম]"
 ```
 
-### Remarks
+##### Remarks
 
 - Equivalent to [toStringEn()](#tostringen) with `'bn'` locale
 
 ---
 
-## toStringEn()
+#### toStringEn()
 
 Returns a string representation of the Bangla date in English/Latin format.
 
-### Signature
+##### Signature
 
 ```typescript
 toStringEn(): string
 ```
 
-### Return Value
+##### Return Value
 
 Bangla date string in the format: "Shukrobar (Friday), 15 Joishtho, 1430 [Grisma (Summer)]".
 
-### Example
+##### Example
 
 ```typescript
 const bnCal = new BanglaCalendar('2023-04-14');
@@ -844,75 +909,25 @@ console.log(bnCal.toStringEn()); // "Shukrobar (Friday), 1 Boishakh, 1430 [Grism
 
 ---
 
-## format()
-
-Formats the current date as a Bangla calendar date string using customizable tokens.
-
-### Signature
-
-```typescript
-format(format?: BanglaDateFormat): string
-```
-
-### Parameters
-
-- `format`: Format string using tokens (default: `'ddd, DD mmmm (SS), YYYY বঙ্গাব্দ'`)
-
-### Return Value
-
-Formatted Bangla date string according to the specified format.
-
-### Examples
-
-```typescript
-const bnCal = new BanglaCalendar('2023-04-14');
-
-bnCal.format();
-// Returns: 'শুক্রবার, বৈশাখ ০১ (গ্রীষ্মকাল), ১৪৩০ বঙ্গাব্দ'
-
-bnCal.format('YYYY-MM-DD');
-// Returns: '১৪৩০-০১-০১'
-
-bnCal.format('mmmm DD, YYYY');
-// Returns: 'বৈশাখ ০১, ১৪৩০'
-```
-
-### Format Tokens
-
-- **Year**: `YYYY`/`yyyy` (full year), `YY`/`yy` (last 2 digits)
-- **Month**: `M`/`MM` (padded), `mmm` (short name), `mmmm` (full name)
-- **Day**: `D`/`DD` (padded), `Do` (cardinal)
-- **Weekday**: `d` (short), `dd` (without 'বার'), `ddd` (full)
-- **Season**: `S` (season), `SS` (season with 'কাল' suffix)
-
-### Escaping Text
-
-To output raw text (not interpreted as a token), wrap it in square brackets:
-
-- `[আজ] ddd` → `আজ রবিবার`
-- `[year ]YYYY` → `year ২০২৫`
-
----
-
-## addDays()
+#### addDays()
 
 Adds (or subtracts) days to (or from) the current Bangla date.
 
-### Signature
+##### Signature
 
 ```typescript
 addDays(days: number): BanglaCalendar
 ```
 
-### Parameters
+##### Parameters
 
 - `days`: Number of days to add (negative values subtract days)
 
-### Return Value
+##### Return Value
 
 A new `BanglaCalendar` instance with the adjusted date.
 
-### Example
+##### Example
 
 ```typescript
 const bnCal = new BanglaCalendar('১৪৩০', '১', '১'); // ১ বৈশাখ ১৪৩০
@@ -929,7 +944,7 @@ const lateDate = new BanglaCalendar('১৪৩০', '১২', '২৫');
 lateDate.addDays(10); // ৫ বৈশাখ ১৪৩১
 ```
 
-### Remarks
+##### Remarks
 
 - Preserves the calendar variant of the original instance
 - Handles month and year transitions automatically
@@ -939,25 +954,25 @@ lateDate.addDays(10); // ৫ বৈশাখ ১৪৩১
 
 ---
 
-## addWeeks()
+#### addWeeks()
 
 Adds (or subtracts) weeks to (or from) the current Bangla date.
 
-### Signature
+##### Signature
 
 ```typescript
 addWeeks(weeks: number): BanglaCalendar
 ```
 
-### Parameters
+##### Parameters
 
 - `weeks`: Number of weeks to add (negative values subtract weeks)
 
-### Return Value
+##### Return Value
 
 A new `BanglaCalendar` instance with the adjusted date.
 
-### Example
+##### Example
 
 ```typescript
 const bnCal = new BanglaCalendar('১৪৩০', '১', '১'); // ১ বৈশাখ ১৪৩০
@@ -970,7 +985,7 @@ bnCal.addWeeks(5);   // ৫ জ্যৈষ্ঠ ১৪৩০
 bnCal.addWeeks(-1);  // ২৪ চৈত্র ১৪২৯
 ```
 
-### Remarks
+##### Remarks
 
 - Each week is treated as exactly 7 days
 - Preserves the calendar variant of the original instance
@@ -980,28 +995,28 @@ bnCal.addWeeks(-1);  // ২৪ চৈত্র ১৪২৯
 
 ---
 
-## addMonths()
+#### addMonths()
 
 Adds (or subtracts) months to (or from) the current Bangla date.
 
-### Signature
+##### Signature
 
 ```typescript
 addMonths(months: number, overflow?: boolean): BanglaCalendar
 ```
 
-### Parameters
+##### Parameters
 
 - `months`: Number of months to add (negative values subtract months)
 - `overflow`: Controls behavior when day doesn't exist in target month (default: `true`)
   - `true`: Invalid dates overflow to the next month
   - `false`: Clamps to the last valid day of the target month
 
-### Return Value
+##### Return Value
 
 A new `BanglaCalendar` instance with the adjusted date.
 
-### Example
+##### Example
 
 ```typescript
 const normal = new BanglaCalendar('১৪৩০', '২', '১৫');
@@ -1018,7 +1033,7 @@ edgeCase.addMonths(-1);        // ১ আশ্বিন ১৪৩০
 edgeCase.addMonths(-1, false); // ৩১ ভাদ্র ১৪৩০
 ```
 
-### Remarks
+##### Remarks
 
 - When `overflow=true` (default): Follows JavaScript `Date` behavior where invalid dates overflow
 - When `overflow=false`: Clamps to the last valid day of the target month
@@ -1028,28 +1043,28 @@ edgeCase.addMonths(-1, false); // ৩১ ভাদ্র ১৪৩০
 
 ---
 
-## addYears()
+#### addYears()
 
 Adds (or subtracts) years to (or from) the current Bangla date.
 
-### Signature
+##### Signature
 
 ```typescript
 addYears(years: number, overflow?: boolean): BanglaCalendar
 ```
 
-### Parameters
+##### Parameters
 
 - `years`: Number of years to add (negative values subtract years)
 - `overflow`: Controls behavior for leap year adjustments (default: `true`)
   - `true`: Allows date overflow when day doesn't exist in target year
   - `false`: Clamps to last valid day of month in non-leap years
 
-### Return Value
+##### Return Value
 
 A new `BanglaCalendar` instance with the adjusted date.
 
-### Example
+##### Example
 
 ```typescript
 const bnCal = new BanglaCalendar('১৪৩০', '১', '১৫'); // ১৫ বৈশাখ ১৪৩০
@@ -1066,7 +1081,7 @@ const leapDay = new BanglaCalendar('১৪৩১', '১১', '৩০'); // ৩
 leapDay.addYears(1, false); // ২৯ ফাল্গুন ১৪৩২ (non-leap year has 29 days)
 ```
 
-### Remarks
+##### Remarks
 
 - Preserves the calendar variant of the original instance
 - Negative values subtract years from the current date
@@ -1076,25 +1091,25 @@ leapDay.addYears(1, false); // ২৯ ফাল্গুন ১৪৩২ (non-le
 
 ---
 
-## $hasVariantConfig()
+#### $hasVariantConfig()
 
 Checks if a value is a configuration object that contains a valid calendar `variant`.
 
-### Signature
+##### Signature
 
 ```typescript
 $hasVariantConfig(value: unknown): value is { variant: BnCalendarVariant }
 ```
 
-### Parameters
+##### Parameters
 
 - `value`: The value to check
 
-### Return Value
+##### Return Value
 
 `true` if the value contains a valid `variant` property, `false` otherwise.
 
-### Example
+##### Example
 
 ```typescript
 const bnCal = new BanglaCalendar();
@@ -1109,7 +1124,7 @@ bnCal.$hasVariantConfig({}); // false
 bnCal.$hasVariantConfig(null); // false
 ```
 
-### Remarks
+##### Remarks
 
 - This method is used internally by the constructor to extract variant configuration from various parameter positions
 - Can be useful for type-checking configuration objects before passing them to the constructor
@@ -1117,19 +1132,19 @@ bnCal.$hasVariantConfig(null); // false
 
 ---
 
-## Static Methods
+### Static Methods
 
-## isBanglaYear()
+#### isBanglaYear()
 
 Checks whether a value is a valid Bangla year in Bangla digits (`০–৯৯৯৯`).
 
-### Signature
+##### Signature
 
 ```typescript
 static isBanglaYear(value: unknown): value is BanglaYear
 ```
 
-### Example
+##### Example
 
 ```typescript
 BanglaCalendar.isBanglaYear('১৪৩০'); // true
@@ -1139,17 +1154,17 @@ BanglaCalendar.isBanglaYear('1430');  // false (Latin digits)
 
 ---
 
-## isBanglaYearEn()
+#### isBanglaYearEn()
 
 Checks whether a value is a valid Bangla year in Latin digits (`0–9999`).
 
-### Signature
+##### Signature
 
 ```typescript
 static isBanglaYearEn(value: number): boolean
 ```
 
-### Example
+##### Example
 
 ```typescript
 BanglaCalendar.isBanglaYearEn(1430);  // true
@@ -1159,17 +1174,17 @@ BanglaCalendar.isBanglaYearEn(-1);    // false
 
 ---
 
-## isBanglaMonth()
+#### isBanglaMonth()
 
 Checks whether a value is a valid Bangla month in Bangla digits (`১–১২`).
 
-### Signature
+##### Signature
 
 ```typescript
 static isBanglaMonth(value: unknown): value is BanglaMonth
 ```
 
-### Example
+##### Example
 
 ```typescript
 BanglaCalendar.isBanglaMonth('১');  // true
@@ -1179,17 +1194,17 @@ BanglaCalendar.isBanglaMonth('১৩'); // false
 
 ---
 
-## isBanglaMonthEn()
+#### isBanglaMonthEn()
 
 Checks whether a value is a valid Bangla month in Latin digits (`1–12`).
 
-### Signature
+##### Signature
 
 ```typescript
 static isBanglaMonthEn(value: unknown): value is NumberRange<1, 12>
 ```
 
-### Example
+##### Example
 
 ```typescript
 BanglaCalendar.isBanglaMonthEn(1);  // true
@@ -1199,17 +1214,17 @@ BanglaCalendar.isBanglaMonthEn(13); // false
 
 ---
 
-## isBanglaDate()
+#### isBanglaDate()
 
 Checks whether a value is a valid Bangla date of month in Bangla digits (`১–৩১`).
 
-### Signature
+##### Signature
 
 ```typescript
 static isBanglaDate(value: unknown): value is BanglaDate
 ```
 
-### Example
+##### Example
 
 ```typescript
 BanglaCalendar.isBanglaDate('১');   // true
@@ -1219,17 +1234,17 @@ BanglaCalendar.isBanglaDate('৩২');  // false
 
 ---
 
-## isBanglaDateEn()
+#### isBanglaDateEn()
 
 Checks whether a value is a valid Bangla date of month in Latin digits (`1–31`).
 
-### Signature
+##### Signature
 
 ```typescript
 static isBanglaDateEn(value: unknown): value is NumberRange<1, 31>
 ```
 
-### Example
+##### Example
 
 ```typescript
 BanglaCalendar.isBanglaDateEn(1);   // true
@@ -1239,17 +1254,17 @@ BanglaCalendar.isBanglaDateEn(32);  // false
 
 ---
 
-## isBanglaDateString()
+#### isBanglaDateString()
 
 Checks whether a string follows the Bangla date format pattern (`YYYY-MM-DD` with Bangla digits).
 
-### Signature
+##### Signature
 
 ```typescript
 static isBanglaDateString(value: unknown): value is string
 ```
 
-### Example
+##### Example
 
 ```typescript
 BanglaCalendar.isBanglaDateString('১৪৩০-০১-০১'); // true
@@ -1257,38 +1272,40 @@ BanglaCalendar.isBanglaDateString('1430-01-01'); // false (Latin digits)
 BanglaCalendar.isBanglaDateString('১৪৩০-১৩-০১'); // false (invalid month)
 ```
 
-### Remarks
+##### Remarks
 
 - Accepts both zero-padded and non-padded Bangla digits
 - Validates year, month, and date components separately
 
 ---
 
-## [Symbol.toPrimitive]
+### Symbol Methods
+
+#### [Symbol.toPrimitive]
 
 Converts the `BanglaCalendar` instance to a primitive value based on the provided hint.
 
-### Signature
+##### Signature
 
 ```typescript
 [Symbol.toPrimitive](hint: string): string | number
 ```
 
-### Parameters
+##### Parameters
 
 - `hint`: The conversion hint - either `'number'` or `'string'` (defaults to `'string'`)
 
-### Return Value
+##### Return Value
 
 - If `hint` is `'number'`: Returns the timestamp (same as [valueOf()](#valueof))
 - Otherwise: Returns the ISO-like Bangla date string (same as [toJSON()](#tojson))
 
-### Behavior
+##### Behavior
 
 - **`hint === 'number'`**: Returns numeric timestamp via [valueOf()](#valueof)
 - **`hint === 'string'` or any other hint**: Returns formatted string via [toJSON()](#tojson)
 
-### Example
+##### Example
 
 ```typescript
 const bnCal = new BanglaCalendar('১৪৩০', '১', '১');
@@ -1307,7 +1324,7 @@ bnCal[Symbol.toPrimitive]('string');  // "১৪৩০-০১-০১"
 bnCal[Symbol.toPrimitive]('default'); // "১৪৩০-০১-০১"
 ```
 
-### Remarks
+##### Remarks
 
 - This method enables implicit type conversion in JavaScript/TypeScript
 - Follows standard JavaScript object-to-primitive conversion protocol
@@ -1315,21 +1332,21 @@ bnCal[Symbol.toPrimitive]('default'); // "১৪৩০-০১-০১"
 
 ---
 
-## [Symbol.toStringTag]
+#### [Symbol.toStringTag]
 
 Provides a string tag used by `Object.prototype.toString()`.
 
-### Signature
+##### Signature
 
 ```typescript
 get [Symbol.toStringTag](): string
 ```
 
-### Return Value
+##### Return Value
 
 ISO-like Bangla date string in the format `"YYYY-MM-DD"` with Bangla digits.
 
-### Example
+##### Example
 
 ```typescript
 const bnCal = new BanglaCalendar('১৪৩০', '১', '১');
@@ -1350,7 +1367,7 @@ Object.prototype.toString.call(bnCal); // "[object ১৪৩০-০১-০১]"
 bnCal[Symbol.toStringTag];            // "১৪৩০-০১-০১"
 ```
 
-### Remarks
+##### Remarks
 
 - Returns the same value as [toJSON()](#tojson) method
 - Used by `Object.prototype.toString()` to identify the object type
@@ -1358,7 +1375,129 @@ bnCal[Symbol.toStringTag];            // "১৪৩০-০১-০১"
 
 ---
 
-## Utilities
+## Detailed Examples
+
+### Basic Usage
+
+```typescript
+const today = new BanglaCalendar();
+console.log(today.toString()); // "শুক্রবার, ১ বৈশাখ, ১৪৩০ [গ্রীষ্ম]"
+console.log(today.toJSON());   // "১৪৩০-০১-০১"
+
+const specificDate = new BanglaCalendar('১৪৩২-১১-০৮');
+console.log(specificDate.getMonthName()); // "ফাল্গুন"
+```
+
+### Date Conversion
+
+```typescript
+const bnDate = new BanglaCalendar('১৪৩০', '১', '১');
+const gregorianDate = bnDate.toDate();
+console.log(gregorianDate.toISOString()); // "2023-04-14T00:00:00.000Z"
+```
+
+### Month Operations
+
+```typescript
+const date = new BanglaCalendar('১৪৩০', '৫', '১৫');
+console.log(date.startOfMonth().toString()); // "১ জ্যৈষ্ঠ ১৪৩০"
+console.log(date.endOfMonth().toString());   // "৩১ জ্যৈষ্ঠ ১৪৩০"
+```
+
+---
+
+## Aliases
+
+`BanglaCalendar` can also be imported using **BnCalendar** and **Bongabdo** aliases.
+
+```typescript
+import { BnCalendar, Bongabdo } from 'bn-calendar';
+
+const bnCal = new BnCalendar('১৪৩০', '১', '১');
+const bongabdoCal = new Bongabdo('১৪৩০', '১', '১');
+
+// Same as new BanglaCalendar('১৪৩০', '১', '১')
+```
+
+---
+
+## Type Definitions
+
+### LocaleCode
+
+```typescript
+type $BnEn = 'bn' | 'en'
+```
+
+Supported locale codes for Bangla calendar output.
+
+### BanglaYear
+
+```typescript
+type BanglaYear = BanglaDigit | `${$BnOnes}${BanglaDigit}` | `${$BnOnes}${BanglaDigit}${BanglaDigit}` | Repeat<BanglaDigit, 4>
+```
+
+Bangla year from `০-৯৯৯৯`.
+
+### BanglaMonth
+
+```typescript
+type BanglaMonth = $BnOnes | $BnOnesPadded | '১০' | '১১' | '১২'
+```
+
+Bangla month from `১-১২`.
+
+### BanglaDate
+
+```typescript
+type BanglaDate = $BnOnes | $BnOnesPadded | `১${BanglaDigit}` | `২${BanglaDigit}` | '৩০' | '৩১'
+```
+
+Bangla date of month from `১-৩১`.
+
+### BnCalendarVariant
+
+```typescript
+type BnCalendarVariant = 'revised-2019' | 'revised-1966'
+```
+
+Calendar variant types.
+
+### BnCalendarConfig
+
+```typescript
+interface BnCalendarConfig {
+  variant?: BnCalendarVariant;
+}
+```
+
+Configuration object for Bangla Calendar system.
+
+### BanglaDateFormat
+
+```typescript
+type BanglaDateFormat = LooseLiteral<DateFormatToken | DateWithSeasonToken>
+```
+
+Format tokens for Bangla date formatting.
+
+---
+
+## Bangla Digit Conversion Utilities
+
+> Allows you to convert between Bangla (Bengali) digits (`০-৯`) and Latin (Arabic) digits (`0-9`). Internally `BanglaCalendar` class uses these functions to convert between Bangla and Latin digits.
+
+### Import
+
+```typescript
+import { banglaToDigit, digitToBangla } from 'bn-calendar/utils'
+```
+
+---
+
+> [!NOTE]
+>
+> `banglaToDigit()` and `digitToBangla()` functions are imported from the [**nhb-toolbox**](https://toolbox.nazmul-nhb.dev/) package.
 
 The digit conversion utilities provide seamless conversion between Bangla (Bengali) digits (`০-৯`) and Latin (Arabic) digits (`0-9`). These functions are essential for applications that need to handle multilingual numeric representations, particularly in Bengali-language interfaces.
 
@@ -1508,125 +1647,6 @@ type BnDigitResult<Force extends boolean> = Force extends true ? number : string
 
 ---
 
-### Complete Examples
-
-#### Example 1: Form Processing
-
-```typescript
-// User inputs Bangla digits in a form
-const userInput = '২৫০০';
-const numericValue = banglaToDigit(userInput); // 2500
-
-// Process the number
-const discounted = numericValue * 0.9; // 2250
-
-// Display result in Bangla
-const displayValue = digitToBangla(discounted); // "২২৫০"
-```
-
-#### Example 2: Multilingual Price Display
-
-```typescript
-function formatPrice(price: number, locale: 'bn' | 'en' = 'en'): string {
-  if (locale === 'bn') {
-    const banglaPrice = digitToBangla(price);
-    return `৳${banglaPrice}`;
-  }
-  return `$${price.toFixed(2)}`;
-}
-
-formatPrice(1250, 'bn'); // "৳১২৫০"
-formatPrice(1250, 'en'); // "$1250.00"
-```
-
-#### Example 3: Phone Number Formatting
-
-```typescript
-// Standardize phone number input
-function formatPhoneNumber(phone: string): string {
-  // Convert any Bangla digits to Latin
-  const latinPhone = banglaToDigit(phone, false); // "01712345678"
-
-  // Format with hyphens
-  return `${latinPhone.slice(0, 3)}-${latinPhone.slice(3, 6)}-${latinPhone.slice(6)}`;
-}
-
-formatPhoneNumber('০১৭১২৩৪৫৬৭৮'); // "017-123-45678"
-```
-
-> [!TIP]
-> **Best Practices**
->
-> - **Use `banglaToDigit()` with `forceNumber = true`** when you need to perform calculations
-> - **Use `banglaToDigit()` with `forceNumber = false`** when you need to preserve text formatting
-> - **Use `digitToBangla()` with `preserveNonDigit = true`** for displaying formatted text
-> - **Use `digitToBangla()` with `preserveNonDigit = false`** for generating clean numeric strings
-> - **Always validate input** before conversion to handle edge cases
-
----
-
-## Type Definitions
-
-### LocaleCode
-
-```typescript
-type $BnEn = 'bn' | 'en'
-```
-
-Supported locale codes for Bangla calendar output.
-
-### BanglaYear
-
-```typescript
-type BanglaYear = BanglaDigit | `${$BnOnes}${BanglaDigit}` | `${$BnOnes}${BanglaDigit}${BanglaDigit}` | Repeat<BanglaDigit, 4>
-```
-
-Bangla year from `০-৯৯৯৯`.
-
-### BanglaMonth
-
-```typescript
-type BanglaMonth = $BnOnes | $BnOnesPadded | '১০' | '১১' | '১২'
-```
-
-Bangla month from `১-১২`.
-
-### BanglaDate
-
-```typescript
-type BanglaDate = $BnOnes | $BnOnesPadded | `১${BanglaDigit}` | `২${BanglaDigit}` | '৩০' | '৩১'
-```
-
-Bangla date of month from `১-৩১`.
-
-### BnCalendarVariant
-
-```typescript
-type BnCalendarVariant = 'revised-2019' | 'revised-1966'
-```
-
-Calendar variant types.
-
-### BnCalendarConfig
-
-```typescript
-interface BnCalendarConfig {
-  variant?: BnCalendarVariant;
-}
-```
-
-Configuration object for Bangla Calendar system.
-
-### BanglaDateFormat
-
-```typescript
-type BanglaDateFormat = LooseLiteral<DateFormatToken | DateWithSeasonToken>
-```
-
-Format tokens for Bangla date formatting.
-
----
-
 ## 🔗 Related Packages
 
 <div style={{ display: 'flex', alignItems: 'center', gap: '0.5rem' }}>