bangla-stdlib

A canonical, Bangladesh-correct standard library for Bangla numbers, dates, currency, and linguistic formatting.

Principles

• Accuracy over convenience - Follows Bangladesh standards precisely
• Bangladesh standards only - No regional variations
• Deterministic output - Same input always produces same output
• Zero runtime dependencies - Pure TypeScript/JavaScript
• Long-term stability - API designed for consistency
• Production-ready - Comprehensive validation, error handling, and test coverage

Installation

npm install bangla-stdlib
# or
pnpm add bangla-stdlib
# or
yarn add bangla-stdlib

Features

📊 Numbers

• Convert numbers to Bengali digits (০-৯)
• Convert Bengali digits to numbers
• Number formatting with customizable options
• Number validation and sanitization
• Convert numbers to Bengali words
• Format numbers with units (হাজার, লক্ষ, কোটি)
• Batch operations for arrays

📅 Calendar

• Bengali calendar (বঙ্গাব্দ) support
• Convert between Gregorian and Bengali dates
• Accurate leap year calculations
• Format Bengali dates with weekdays
• Date arithmetic (add days, calculate differences)
• Date validation and comparison

🗓️ Date Formatting

• Format dates with Bengali digits and month names
• Parse Bengali date strings
• Multiple format support (with/without year, weekday)
• Date validation and sanitization
• Date comparison and range checking

💰 Currency

• Format currency in Taka (৳)
• Parse currency strings
• Currency validation
• Currency math operations (add, subtract, multiply, divide)
• Tax and discount calculations
• Amount splitting and comparison

📆 Month Names

• All 12 Bengali month names
• Convert between month numbers and names
• Month validation
• Month navigation (next, previous)
• Month ranges and comparisons

🗓️ Weekday Names

• All 7 Bengali weekday names
• Convert between day numbers and names
• Weekday validation
• Weekday navigation

🌦️ Seasons

• All 6 Bengali seasons (ঋতু)
• Season detection from dates
• Season validation and comparison

⏰ Time Formatting

• Format time in Bengali
• 12-hour and 24-hour support
• Bengali period names (সকাল, দুপুর, বিকাল, etc.)

🔢 Ordinal Numbers

• Convert numbers to Bengali ordinals (প্রথম, দ্বিতীয়, তৃতীয়, etc.)
• Ordinal validation
• Special handling for 1-25 and multiples of 10

📱 Phone Numbers

• Validate Bangladeshi phone numbers
• Format phone numbers with customizable options
• Operator detection (Grameenphone, Banglalink, Robi, etc.)
• Country code handling

🔤 Text Utilities

• Validate Bengali-only text
• Detect Bengali digits and characters
• Count Bengali characters
• Extract/remove Bengali content
• Mixed content detection
• Text sanitization

Quick Start

import {
  toBanglaNumber,
  formatCurrency,
  toBengali,
  formatDate,
  toBanglaMonth,
  getWeekdayName,
  getSeason,
  formatTime,
  toOrdinal,
  formatPhone,
} from 'bangla-stdlib';

// Numbers
toBanglaNumber(123); // "১২৩"
toBanglaNumber(3.14); // "৩.১৪"

// Currency
formatCurrency(1500); // "১,৫০০ টাকা"
formatCurrency(2500, { symbol: true }); // "৳২,৫০০"

// Bengali Calendar
const bengaliDate = toBengali(new Date(2024, 3, 14));
// { year: 1431, month: 1, day: 1 } - Pohela Boishakh

// Date Formatting
formatDate(new Date(), { includeWeekday: true });
// "মঙ্গলবার ৭ পৌষ ২০২৫"

// Months
toBanglaMonth(1); // "বৈশাখ"

// Weekdays
getWeekdayName(new Date()); // "মঙ্গলবার"

// Seasons
getSeason(new Date()); // "শীত" (Winter)

// Time
formatTime(new Date()); // "সকাল ১০:৩০"

// Ordinals
toOrdinal(1); // "প্রথম"
toOrdinal(21); // "একুশতম"

// Phone Numbers
formatPhone('01712345678'); // "০১৭১-২৩৪৫৬৭৮"

API Documentation

Numbers

toBanglaNumber(number: number | string): string

Converts a number or numeric string to Bengali digits.

toBanglaNumber(123); // "১২৩"
toBanglaNumber(3.14); // "৩.১৪"
toBanglaNumber("456"); // "৪৫৬"

fromBanglaNumber(banglaNumber: string): number

Converts a Bengali digit string to a number.

fromBanglaNumber("১২৩"); // 123
fromBanglaNumber("৩.১৪"); // 3.14

formatNumber(number: number, options?): string

Formats a number with thousands separators in Bengali.

formatNumber(123456); // "১,২৩,৪৫৬"
formatNumber(1234.56, {
  minimumFractionDigits: 2,
  maximumFractionDigits: 2
}); // "১,২৩৪.৫৬"

toWords(number: number): string

Converts a number to Bengali words.

toWords(123); // "এক শত তেইশ"
toWords(1000); // "এক হাজার"

formatWithUnits(number: number): string

Formats large numbers with Bengali units.

formatWithUnits(1000); // "১ হাজার"
formatWithUnits(100000); // "১ লক্ষ"
formatWithUnits(10000000); // "১ কোটি"

Currency

formatCurrency(amount: number, options?): string

Formats a number as Bengali currency.

formatCurrency(1500); // "১,৫০০ টাকা"
formatCurrency(2500, { symbol: true }); // "৳২,৫০০"
formatCurrency(1234.56, {
  useBanglaDigits: false,
  symbol: true
}); // "৳1,234.56"

parseCurrency(currencyString: string): number

Parses a Bengali currency string to a number.

parseCurrency("১,৫০০ টাকা"); // 1500
parseCurrency("৳২,৫০০"); // 2500
parseCurrency("1,234.56"); // 1234.56

Currency Math Operations

import { addCurrency, subtractCurrency, multiplyCurrency, divideCurrency } from 'bangla-stdlib';

addCurrency(100.50, 200.75); // 301.25
subtractCurrency(500, 150.25); // 349.75
multiplyCurrency(100, 1.5); // 150.00
divideCurrency(300, 3); // 100.00

Tax and Discount Calculations

import { calculateTax, applyDiscount } from 'bangla-stdlib';

calculateTax(1000, 15); // 150 (15% tax)
applyDiscount(1000, 10); // 900 (10% discount applied)

Bengali Calendar

toBengali(date: Date): { year: number; month: number; day: number }

Converts a Gregorian date to Bengali calendar.

toBengali(new Date(2024, 3, 14));
// { year: 1431, month: 1, day: 1 } - Pohela Boishakh

fromBengali(bengaliDate): Date

Converts a Bengali calendar date to Gregorian.

fromBengali({ year: 1431, month: 1, day: 1 });
// Date object for April 14, 2024

getBengaliDate(date: Date, options?): string

Formats a date as Bengali calendar with Bengali text.

getBengaliDate(new Date(), { includeWeekday: true });
// "মঙ্গলবার ২৪ পৌষ ১৪৩১"

Date Arithmetic

import { addDaysToBengaliDate, getBengaliDateDifference } from 'bangla-stdlib';

addDaysToBengaliDate({ year: 1431, month: 1, day: 1 }, 10);
// { year: 1431, month: 1, day: 11 }

getBengaliDateDifference(
  { year: 1431, month: 1, day: 1 },
  { year: 1431, month: 1, day: 10 }
); // 9 days

Date Formatting

formatDate(date: Date, options?): string

Formats a date with Bengali digits and month names.

formatDate(new Date(2024, 0, 15)); // "১৫ বৈশাখ ২০২৪"
formatDate(new Date(), { includeWeekday: true, includeYear: false });
// "মঙ্গলবার ৭ পৌষ"

parseDate(dateString: string): Date

Parses a Bengali date string to a Date object.

parseDate("১৫ বৈশাখ ১৪৩১"); // Date object
parseDate("১৫/০৪/২০২৪"); // Date object
parseDate("15-04-2024"); // Date object

Months

toBanglaMonth(monthNumber: number): string

Converts a month number (1-12) to Bengali month name.

toBanglaMonth(1); // "বৈশাখ"
toBanglaMonth(6); // "আশ্বিন"
toBanglaMonth(12); // "চৈত্র"

fromBanglaMonth(monthName: string): number

Converts a Bengali month name to number.

fromBanglaMonth("বৈশাখ"); // 1
fromBanglaMonth("আশ্বিন"); // 6

getMonthName(date: Date): string

Gets the Bengali month name from a Date object.

getMonthName(new Date(2024, 0, 15)); // "বৈশাখ"

Month Navigation

import { getNextMonth, getPreviousMonth, getMonthRange } from 'bangla-stdlib';

getNextMonth(1); // 2
getNextMonth(12); // 1 (wraps around)
getNextMonth("বৈশাখ"); // "জ্যৈষ্ঠ"

getPreviousMonth(2); // 1
getPreviousMonth(1); // 12 (wraps around)

getMonthRange(1, 3); // [1, 2, 3]
getMonthRange("বৈশাখ", "আষাঢ়"); // ["বৈশাখ", "জ্যৈষ্ঠ", "আষাঢ়"]

Weekdays

getWeekdayName(date: Date): string

Gets the Bengali weekday name from a Date object.

getWeekdayName(new Date()); // "মঙ্গলবার"

toBanglaWeekday(dayNumber: number): string

Converts a day number (0-6) to Bengali weekday name.

toBanglaWeekday(0); // "রবিবার" (Sunday)
toBanglaWeekday(1); // "সোমবার" (Monday)
toBanglaWeekday(6); // "শনিবার" (Saturday)

fromBanglaWeekday(weekdayName: string): number

Converts a Bengali weekday name to number.

fromBanglaWeekday("রবিবার"); // 0
fromBanglaWeekday("সোমবার"); // 1

Seasons

getSeason(date: Date): string

Gets the Bengali season for a given date.

getSeason(new Date(2024, 0, 15)); // "শীত" (Winter)
getSeason(new Date(2024, 6, 15)); // "বর্ষা" (Monsoon)

getSeasonName(seasonNumber: number): string

Gets the Bengali season name by number (1-6).

getSeasonName(1); // "গ্রীষ্ম" (Summer)
getSeasonName(3); // "বর্ষা" (Monsoon)
getSeasonName(5); // "শীত" (Winter)

Time

formatTime(date: Date, options?): string

Formats time in Bengali with period names.

formatTime(new Date()); // "সকাল ১০:৩০"
formatTime(new Date(), { use24Hour: true }); // "১০:৩০"
formatTime(new Date(), { showSeconds: true }); // "সকাল ১০:৩০:১৫"

Ordinal Numbers

toOrdinal(number: number): string

Converts a number to Bengali ordinal.

toOrdinal(1); // "প্রথম"
toOrdinal(2); // "দ্বিতীয়"
toOrdinal(3); // "তৃতীয়"
toOrdinal(21); // "একুশতম"
toOrdinal(100); // "শততম"

Phone Numbers

validatePhone(phoneNumber: string): boolean

Validates a Bangladeshi phone number.

validatePhone("01712345678"); // true
validatePhone("01812345678"); // true
validatePhone("1234567890"); // false

formatPhone(phoneNumber: string, options?): string

Formats a phone number with customizable options.

formatPhone("01712345678"); // "০১৭১-২৩৪৫৬৭৮"
formatPhone("01712345678", { style: "spaced" }); // "০১৭১ ২৩৪ ৫৬৭৮"
formatPhone("01712345678", {
  style: "compact",
  includeCountryCode: true
}); // "+৮৮০১৭১২৩৪৫৬৭৮"

getOperator(phoneNumber: string): string | null

Detects the mobile operator from a phone number.

getOperator("01712345678"); // "Grameenphone"
getOperator("01812345678"); // "Robi"
getOperator("01912345678"); // "Banglalink"

Text Utilities

validateBangla(text: string): boolean

Validates if text contains only Bengali characters and whitespace.

validateBangla("বাংলা"); // true
validateBangla("বাংলা ভাষা"); // true
validateBangla("Hello বাংলা"); // false

isBanglaText(text: string): boolean

Checks if text contains any Bengali characters.

isBanglaText("বাংলা"); // true
isBanglaText("Hello বাংলা"); // true
isBanglaText("Hello"); // false

isBanglaDigit(char: string): boolean

Checks if a character is a Bengali digit.

isBanglaDigit("৫"); // true
isBanglaDigit("5"); // false

Content Analysis

import {
  countBengaliCharacters,
  getBengaliPercentage,
  extractBengaliChars,
  splitBengaliContent
} from 'bangla-stdlib';

countBengaliCharacters("Hello বাংলা"); // 5
getBengaliPercentage("Hello বাংলা"); // 50
extractBengaliChars("Hello বাংলা World"); // "বাংলা"
splitBengaliContent("Hello বাংলা");
// { bengali: "বাংলা", nonBengali: "Hello" }

Validation and Error Handling

All modules include comprehensive validation functions that don't throw errors, making them safe for UI contexts:

import {
  isValidMonthNumber,
  sanitizePhoneNumber,
  isValidCurrency,
  isValidDate,
  isValidBengaliDate,
} from 'bangla-stdlib';

// Safe validation
if (isValidMonthNumber(13)) {
  // Won't execute - 13 is invalid
}

// Sanitization with fallbacks
const phone = sanitizePhoneNumber(userInput); // Returns empty string if invalid
const amount = sanitizeCurrency(userInput); // Returns null if invalid

Batch Operations

Process arrays efficiently:

import {
  batchToBanglaNumber,
  batchFormatCurrency,
  batchToBanglaMonth,
} from 'bangla-stdlib';

batchToBanglaNumber([1, 2, 3, 4, 5]);
// ["১", "২", "৩", "৪", "৫"]

batchFormatCurrency([100, 200, 300]);
// ["১০০ টাকা", "২০০ টাকা", "৩০০ টাকা"]

batchToBanglaMonth([1, 6, 12]);
// ["বৈশাখ", "আশ্বিন", "চৈত্র"]

TypeScript Support

Fully typed with TypeScript. All functions have comprehensive type definitions:

import type {
  BengaliDate,
  FormatCurrencyOptions,
  FormatDateOptions,
  FormatPhoneOptions,
} from 'bangla-stdlib';

const options: FormatCurrencyOptions = {
  useBanglaDigits: true,
  symbol: true,
  word: false,
};

const bengaliDate: BengaliDate = {
  year: 1431,
  month: 1,
  day: 1,
};

Performance

• All functions are optimized for performance
• Zero runtime dependencies
• Tree-shakeable - only import what you need
• Suitable for high-frequency operations

// Performance benchmarks (1000 operations):
// - toBanglaNumber: ~0.75ms
// - formatCurrency: ~2.13ms
// - toBengali: ~1.5ms
// - formatDate: ~1.8ms

Browser Support

Works in all modern browsers and Node.js environments:

• Chrome/Edge 90+
• Firefox 88+
• Safari 14+
• Node.js 14+

Development

# Install dependencies
pnpm install

# Run tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Build
pnpm build

# Type check
pnpm typecheck

# Lint
pnpm lint

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.

Guidelines

• Follow Bangladesh standards precisely
• Maintain deterministic behavior
• Add comprehensive tests for new features
• Update documentation
• Ensure zero runtime dependencies

License

MIT © Mahmudul Alam

Acknowledgments

Thanks to all contributors and the Bengali language community for their support in maintaining accurate standards.

Made with ❤️ for the Bengali-speaking community