bangla-stdlib 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mahmudul Alam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,631 @@
+# bangla-stdlib
+
+A canonical, Bangladesh-correct standard library for Bangla numbers, dates, currency, and linguistic formatting.
+
+[![NPM Version](https://img.shields.io/npm/v/bangla-stdlib.svg)](https://www.npmjs.com/package/bangla-stdlib)
+[![License](https://img.shields.io/npm/l/bangla-stdlib.svg)](https://github.com/devmahmud/bangla-stdlib/blob/main/LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue.svg)](https://www.typescriptlang.org/)
+
+## 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
+
+```bash
+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
+
+```typescript
+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.
+
+```typescript
+toBanglaNumber(123); // "১২৩"
+toBanglaNumber(3.14); // "৩.১৪"
+toBanglaNumber("456"); // "৪৫৬"
+```
+
+#### `fromBanglaNumber(banglaNumber: string): number`
+Converts a Bengali digit string to a number.
+
+```typescript
+fromBanglaNumber("১২৩"); // 123
+fromBanglaNumber("৩.১৪"); // 3.14
+```
+
+#### `formatNumber(number: number, options?): string`
+Formats a number with thousands separators in Bengali.
+
+```typescript
+formatNumber(123456); // "১,২৩,৪৫৬"
+formatNumber(1234.56, {
+  minimumFractionDigits: 2,
+  maximumFractionDigits: 2
+}); // "১,২৩৪.৫৬"
+```
+
+#### `toWords(number: number): string`
+Converts a number to Bengali words.
+
+```typescript
+toWords(123); // "এক শত তেইশ"
+toWords(1000); // "এক হাজার"
+```
+
+#### `formatWithUnits(number: number): string`
+Formats large numbers with Bengali units.
+
+```typescript
+formatWithUnits(1000); // "১ হাজার"
+formatWithUnits(100000); // "১ লক্ষ"
+formatWithUnits(10000000); // "১ কোটি"
+```
+
+### Currency
+
+#### `formatCurrency(amount: number, options?): string`
+Formats a number as Bengali currency.
+
+```typescript
+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.
+
+```typescript
+parseCurrency("১,৫০০ টাকা"); // 1500
+parseCurrency("৳২,৫০০"); // 2500
+parseCurrency("1,234.56"); // 1234.56
+```
+
+#### Currency Math Operations
+
+```typescript
+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
+
+```typescript
+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.
+
+```typescript
+toBengali(new Date(2024, 3, 14));
+// { year: 1431, month: 1, day: 1 } - Pohela Boishakh
+```
+
+#### `fromBengali(bengaliDate): Date`
+Converts a Bengali calendar date to Gregorian.
+
+```typescript
+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.
+
+```typescript
+getBengaliDate(new Date(), { includeWeekday: true });
+// "মঙ্গলবার ২৪ পৌষ ১৪৩১"
+```
+
+#### Date Arithmetic
+
+```typescript
+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.
+
+```typescript
+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.
+
+```typescript
+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.
+
+```typescript
+toBanglaMonth(1); // "বৈশাখ"
+toBanglaMonth(6); // "আশ্বিন"
+toBanglaMonth(12); // "চৈত্র"
+```
+
+#### `fromBanglaMonth(monthName: string): number`
+Converts a Bengali month name to number.
+
+```typescript
+fromBanglaMonth("বৈশাখ"); // 1
+fromBanglaMonth("আশ্বিন"); // 6
+```
+
+#### `getMonthName(date: Date): string`
+Gets the Bengali month name from a Date object.
+
+```typescript
+getMonthName(new Date(2024, 0, 15)); // "বৈশাখ"
+```
+
+#### Month Navigation
+
+```typescript
+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.
+
+```typescript
+getWeekdayName(new Date()); // "মঙ্গলবার"
+```
+
+#### `toBanglaWeekday(dayNumber: number): string`
+Converts a day number (0-6) to Bengali weekday name.
+
+```typescript
+toBanglaWeekday(0); // "রবিবার" (Sunday)
+toBanglaWeekday(1); // "সোমবার" (Monday)
+toBanglaWeekday(6); // "শনিবার" (Saturday)
+```
+
+#### `fromBanglaWeekday(weekdayName: string): number`
+Converts a Bengali weekday name to number.
+
+```typescript
+fromBanglaWeekday("রবিবার"); // 0
+fromBanglaWeekday("সোমবার"); // 1
+```
+
+### Seasons
+
+#### `getSeason(date: Date): string`
+Gets the Bengali season for a given date.
+
+```typescript
+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).
+
+```typescript
+getSeasonName(1); // "গ্রীষ্ম" (Summer)
+getSeasonName(3); // "বর্ষা" (Monsoon)
+getSeasonName(5); // "শীত" (Winter)
+```
+
+### Time
+
+#### `formatTime(date: Date, options?): string`
+Formats time in Bengali with period names.
+
+```typescript
+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.
+
+```typescript
+toOrdinal(1); // "প্রথম"
+toOrdinal(2); // "দ্বিতীয়"
+toOrdinal(3); // "তৃতীয়"
+toOrdinal(21); // "একুশতম"
+toOrdinal(100); // "শততম"
+```
+
+### Phone Numbers
+
+#### `validatePhone(phoneNumber: string): boolean`
+Validates a Bangladeshi phone number.
+
+```typescript
+validatePhone("01712345678"); // true
+validatePhone("01812345678"); // true
+validatePhone("1234567890"); // false
+```
+
+#### `formatPhone(phoneNumber: string, options?): string`
+Formats a phone number with customizable options.
+
+```typescript
+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.
+
+```typescript
+getOperator("01712345678"); // "Grameenphone"
+getOperator("01812345678"); // "Robi"
+getOperator("01912345678"); // "Banglalink"
+```
+
+### Text Utilities
+
+#### `validateBangla(text: string): boolean`
+Validates if text contains only Bengali characters and whitespace.
+
+```typescript
+validateBangla("বাংলা"); // true
+validateBangla("বাংলা ভাষা"); // true
+validateBangla("Hello বাংলা"); // false
+```
+
+#### `isBanglaText(text: string): boolean`
+Checks if text contains any Bengali characters.
+
+```typescript
+isBanglaText("বাংলা"); // true
+isBanglaText("Hello বাংলা"); // true
+isBanglaText("Hello"); // false
+```
+
+#### `isBanglaDigit(char: string): boolean`
+Checks if a character is a Bengali digit.
+
+```typescript
+isBanglaDigit("৫"); // true
+isBanglaDigit("5"); // false
+```
+
+#### Content Analysis
+
+```typescript
+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:
+
+```typescript
+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:
+
+```typescript
+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:
+
+```typescript
+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
+
+```typescript
+// 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
+
+```bash
+# 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