bangabda

A TypeScript package for converting between Gregorian dates and the West Bengal Bengali calendar (Bangabda / বাংলা সন).

The package now includes a working implementation for:

• Gregorian → Bengali conversion.
• Bengali → Gregorian conversion.
• English and Bangla locale output.
• UTC-normalized date handling.
• Optional Date extension helpers.
• Precomputed support for a fixed Bengali year range.

Scope note: bangabda targets the West Bengal / Indian revised Bengali calendar rules implemented in this repository. It should not be treated as a drop-in calendar engine for the Bangladesh calendar variant without validating the expected results for your use case.

Installation

npm install bangabda

Requirements:

• Node.js 18+
• A runtime or bundler that can consume the published ESM/CJS package output

Quick start

Convert Gregorian to Bengali

import { toBengali } from 'bangabda';

const result = toBengali('2025-02-24');

console.log(result.year); // 1431
console.log(result.month); // 10
console.log(result.day); // 12
console.log(result.monthName); // Falgun
console.log(result.rituName); // Spring

Convert Bengali to Gregorian

import { toGregorian } from 'bangabda';

const gregorian = toGregorian({
  year: 1431,
  month: 10,
  day: 12,
});

console.log(gregorian.toISOString()); // 2025-02-24T00:00:00.000Z

Use Bangla locale output

import { bn, toBengali } from 'bangabda';

const result = toBengali('2025-02-24', bn);

console.log(result.monthName); // ফাল্গুন
console.log(result.rituName); // বসন্ত
console.log(result.dayLabel); // ১২
console.log(result.yearLabel); // ১৪৩১

API reference

toBengali(input, locale?)

Converts a Gregorian date-like input into a Bengali date object.

Signature

function toBengali(input: Date | string | number, locale?: Locale): BengaliDate;

Accepted input

• Date
• ISO-like date string accepted by the JavaScript Date constructor
• timestamp number accepted by the JavaScript Date constructor

Behavior

• Invalid input throws TypeError.
• The input is normalized to UTC midnight before conversion.
• The returned object includes both structural fields (year, month, day) and localized labels.

toGregorian(input)

Converts a Bengali date triple into a UTC-normalized Gregorian Date.

Signature

function toGregorian(input: { year: number; month: 0|1|2|3|4|5|6|7|8|9|10|11; day: number }): Date;

Behavior

• month must be an integer from 0 to 11.
• day must be valid for the provided Bengali year and month.
• Invalid month/day values throw RangeError.
• Returned dates are pinned to 00:00:00.000Z.

Locales

The package currently exports two locale objects:

• en
• bn

Each locale provides:

• month names
• season (ritu) labels
• localized digits

Leap-year helpers

isBengaliLeapYear(year: number): boolean
isGregorianLeapYear(year: number): boolean

Metadata and utility exports

The package also exports calendar metadata and utilities, including:

• SUPPORTED_BENGALI_YEAR_RANGE
• POILA_BOISHAKH
• MONTHS
• MONTHS_BN
• MONTH_INDEXES
• MONTH_START_OFFSETS
• COMMON_MONTH_LENGTHS
• LEAP_MONTH_LENGTHS
• RITUS_BY_MONTH
• createUTCDate
• normalizeDateInput
• toUTCDateKey
• addUTCDays
• differenceInUTCDays
• getMonthLengths
• getMonthLength
• getMonthStartOffset
• getYearData

BengaliDate object shape

toBengali() returns a BengaliDate object with this shape:

interface BengaliDate {
  year: number;
  month: 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11;
  day: number;
  monthName: string;
  ritu: 'grishma' | 'barsha' | 'sharat' | 'hemanta' | 'sheet' | 'basanta';
  rituName: string;
  dayLabel: string;
  yearLabel: string;
  locale: Locale;
  gregorianDate: Date;
}

Field notes

| Field | Meaning | | --- | --- | | year | Bengali year, for example 1431. | | month | Zero-based Bengali month index. 0 = Boishakh, 11 = Chaitra. | | day | One-based day of month. | | monthName | Localized month label from the selected locale. | | ritu | Canonical season key. | | rituName | Localized season label. | | dayLabel | Day rendered with locale digits. | | yearLabel | Year rendered with locale digits. | | locale | The locale object used during formatting. | | gregorianDate | UTC-normalized Gregorian Date used for conversion. |

Locale examples

English locale

import { en, toBengali } from 'bangabda';

const result = toBengali('2025-02-24', en);

console.log(result);
/*
{
  year: 1431,
  month: 10,
  day: 12,
  monthName: 'Falgun',
  ritu: 'basanta',
  rituName: 'Spring',
  dayLabel: '12',
  yearLabel: '1431',
  ...
}
*/

Bangla locale

import { bn, toBengali } from 'bangabda';

const result = toBengali('2025-02-24', bn);

console.log(result.monthName); // ফাল্গুন
console.log(result.rituName); // বসন্ত
console.log(result.dayLabel); // ১২
console.log(result.yearLabel); // ১৪৩১

Supported year range

The implementation uses a precomputed supported range of:

• Bengali years: 1400 through 1500
• Corresponding Gregorian coverage: 1993-04-15 through 2094-04-14

If you request a year outside that Bengali range, the package throws a RangeError.

Date-extension usage

The package ships an optional Date extension entrypoint.

import { extendDate } from 'bangabda/extensions';
import { bn } from 'bangabda';

extendDate();

const bengali = new Date('2025-02-24T12:34:56.000Z').toBengali(bn);
const gregorian = Date.fromBengali({
  year: bengali.year,
  month: bengali.month,
  day: bengali.day,
});

Added globals

After calling extendDate() once, these helpers become available:

interface Date {
  toBengali(locale?: Locale): BengaliDate;
}

interface DateConstructor {
  fromBengali(input: Pick<BengaliDate, 'year' | 'month' | 'day'>): Date;
}

Notes:

• extendDate() is idempotent.
• This API mutates the global Date object, so it is best used intentionally in app-level setup code.
• If you prefer avoiding global mutation, use toBengali() and toGregorian() directly.

West Bengal vs Bangladesh note

This package is designed around the West Bengal / Indian Bengali calendar behavior implemented in the library data tables and conversion logic.

That means:

• Poila Boishakh is derived from this implementation's West Bengal-oriented rules.
• Month lengths and leap-year handling are aligned to this package's current rule set.
• If you need Bangladesh-specific calendar behavior, validate every relevant boundary before adopting this package in production.

In short: use bangabda for the West Bengal-oriented rules it currently implements, not as a universal Bengali calendar abstraction.

Contributing

Contributions are welcome.

Typical local workflow:

npm install
npm run lint
npm run typecheck
npm test
npm run build

When contributing:

1. Add or update tests for any conversion-rule change.
2. Prefer UTC-safe logic for all date calculations.
3. Keep README examples aligned with the actual exported API.
4. Document any supported-range or rule-set changes clearly.

License

This project is licensed under the MIT License.

See LICENSE for the full text.