বঙ্গাব্দ (Bongabdo) - Modern Bengali Calendar Library

A modern TypeScript library for converting Gregorian dates to Bengali calendar (বঙ্গাব্দ) format. This is a complete rewrite of the original jQuery plugin in modern TypeScript, making it compatible with any JavaScript/TypeScript project including React, Vue, Angular, and Node.js applications.

Features

• 🚀 Modern TypeScript: Built with TypeScript for better type safety and developer experience
• 📦 Framework Agnostic: Works with any JavaScript/TypeScript project
• ⚛️ React Support: Includes React hooks for easy integration
• 🎯 Flexible Formatting: Customizable date formats with Bengali digits
• 🌍 Bengali Localization: Full support for Bengali language and digits
• 📚 Comprehensive API: Multiple ways to use the library
• 🧪 Well Tested: Comprehensive test coverage
• 📖 Full Documentation: Complete API documentation and examples

Installation

npm install bongabdo

or

yarn add bongabdo

Quick Start

Basic Usage

import { bongabdo } from 'bongabdo';

// Get today's date in Bengali
const today = bongabdo();
console.log(today); // "১৫ শ্রাবণ, ১৪৩২"

// Convert a specific date
const specificDate = bongabdo('2024-01-15');
console.log(specificDate); // "১ মাঘ, ১৪৩০"

With Custom Format

import { bongabdo } from 'bongabdo';

// Custom format with season
const withSeason = bongabdo('2024-01-15', {
  format: 'DD MM, YY (SS)',
  showSeason: true
});
console.log(withSeason); // "১ মাঘ, ১৪৩০ (শীত)"

// Custom format with weekday
const withWeekday = bongabdo('2024-01-15', {
  format: 'DD MM, YY (WW)',
  showWeekDays: true
});
console.log(withWeekday); // "১ মাঘ, ১৪৩০ (সোমবার)"

React Integration

import React from 'react';
import { useBongabdo, useBongabdoLive } from 'bongabdo/react';

function BengaliDateComponent() {
  // Static date
  const { formatted, raw, isLoading, error } = useBongabdo('2024-01-15', {
    format: 'DD MM, YY (SS)',
    showSeason: true
  });

  // Live updating date
  const { formatted: liveDate } = useBongabdoLive({
    format: 'DD MM, YY (WW)',
    showWeekDays: true
  });

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <div>
      <h2>Static Date: {formatted}</h2>
      <h2>Live Date: {liveDate}</h2>
      <p>Raw data: {JSON.stringify(raw)}</p>
    </div>
  );
}

API Reference

Main Functions

bongabdo(dateInput?, options?)

The main function to convert a Gregorian date to Bengali format.

Parameters:

• dateInput (optional): Date | string - The date to convert. Defaults to current date.
• options (optional): BongabdoOptions - Formatting options.

Returns: string - Formatted Bengali date.

getBanglaDate(dateInput?)

Get the raw Bengali date object without formatting.

Parameters:

• dateInput (optional): Date | string - The date to convert. Defaults to current date.

Returns: BanglaDate - Raw Bengali date object.

Format Options

interface BongabdoOptions {
  date?: Date | string;           // Date to convert
  format?: string;                // Format string (default: "DD MM, YY")
  showSeason?: boolean;           // Show season (default: false)
  showWeekDays?: boolean;         // Show weekday (default: false)
  convertToBanglaDigits?: boolean; // Convert numbers to Bengali digits (default: true)
}

Format Tokens

• DD - Date (দিন)
• MM - Month (মাস)
• YY - Year (বছর)
• WW - Weekday (সপ্তাহের দিন) - requires showWeekDays: true
• SS - Season (ঋতু) - requires showSeason: true

Format Examples

// Default format
bongabdo('2024-01-15'); // "১ মাঘ, ১৪৩০"

// Custom formats
bongabdo('2024-01-15', { format: 'DD-MM-YY' }); // "১-মাঘ-১৪৩০"
bongabdo('2024-01-15', { format: 'MM DD, YY' }); // "মাঘ ১, ১৪৩০"
bongabdo('2024-01-15', { format: 'YY/MM/DD' }); // "১৪৩০/মাঘ/১"

// With season
bongabdo('2024-01-15', { 
  format: 'DD MM, YY (SS)', 
  showSeason: true 
}); // "১ মাঘ, ১৪৩০ (শীত)"

// With weekday
bongabdo('2024-01-15', { 
  format: 'DD MM, YY (WW)', 
  showWeekDays: true 
}); // "১ মাঘ, ১৪৩০ (সোমবার)"

// Only specific parts
bongabdo('2024-01-15', { format: 'MM' }); // "মাঘ"
bongabdo('2024-01-15', { format: 'YY' }); // "১৪৩০"
bongabdo('2024-01-15', { format: 'SS', showSeason: true }); // "শীত"

React Hooks

useBongabdo(dateInput?, options?)

React hook for Bengali date conversion.

Returns:

{
  formatted: string;    // Formatted date string
  raw: BanglaDate;      // Raw date object
  isLoading: boolean;   // Loading state
  error: Error | null;  // Error state
}

useBongabdoLive(options?)

React hook for real-time Bengali date updates (updates every second).

Returns: Same as useBongabdo.

Types

interface BanglaDate {
  year: number;    // Bengali year
  date: number;    // Bengali date
  month: string;   // Bengali month name
  day: string;     // Bengali weekday name
  season: string;  // Bengali season name
}

Bengali Calendar Information

The Bengali calendar (বঙ্গাব্দ) is a solar calendar used in Bangladesh and parts of India. Key points:

• New Year: Starts on 14th April (পহেলা বৈশাখ)
• Year Offset: Bengali year = Gregorian year - 593
• Leap Year: Falgun month has 31 days in leap years
• Seasons: 6 seasons (গ্রীষ্ম, বর্ষা, শরৎ, হেমন্ত, শীত, বসন্ত)

Migration from jQuery Plugin

If you're migrating from the original jQuery plugin, here's how to update your code:

Old jQuery Usage:

$('.bongabdo').bongabdo({
  date: '2018-04-14',
  format: 'DD MM, YY',
  showSeason: true
});

New Modern Usage:

import { bongabdo } from 'bongabdo';

const formattedDate = bongabdo('2018-04-14', {
  format: 'DD MM, YY',
  showSeason: true
});

// For DOM manipulation
document.querySelector('.bongabdo').textContent = formattedDate;

Development

Setup

git clone <repository-url>
cd bongabdo
npm install

Build

npm run build

Test

npm test
npm run test:watch

Development Mode

npm run dev

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE file for details.

Acknowledgments

This library is based on the original jQuery plugin by the Bengali developer community. The algorithm follows the official Bengali calendar calculations as documented on Wikipedia and other authoritative sources.