Unlock 200+ million users worldwide with non-Gregorian calendar support for Day.js
Quick Start • Calendars • Features • Docs • Contributing • License
--- ## 🌍 Why This Plugin? Extend [Day.js](https://day.js.org) to work seamlessly with **non-Gregorian calendar systems** used by millions worldwide. Whether you're building apps for Persian New Year (Nowruz), Islamic holidays (Ramadan, Eid), Jewish festivals (Passover, Hanukkah), or even planning missions to Mars, this plugin has you covered. ### Perfect For: - 🌐 **International applications** serving diverse user bases - 📱 **Cultural apps** displaying local calendar systems - 🕌 **Religious applications** for Islamic, Jewish, Ethiopian Orthodox communities - 🚀 **Space tech** and Mars mission planning - 📊 **Historical research** with accurate date conversions - 🎉 **Event planning** across different calendar systems --- ## ⚡ Quick Start ### Installation ```bash # npm npm install @calidy/dayjs-calendarsystems dayjs # yarn yarn add @calidy/dayjs-calendarsystems dayjs # pnpm pnpm add @calidy/dayjs-calendarsystems dayjs ``` ### Basic Usage ```javascript import dayjs from 'dayjs'; import calendarSystems from '@calidy/dayjs-calendarsystems'; import PersianCalendarSystem from '@calidy/dayjs-calendarsystems/calendarSystems/PersianCalendarSystem'; // Extend Day.js with calendar systems support dayjs.extend(calendarSystems); // Register the Persian calendar dayjs.registerCalendarSystem('persian', new PersianCalendarSystem()); // Convert current date to Persian calendar const persianDate = dayjs().toCalendarSystem('persian'); console.log(persianDate.format('YYYY-MM-DD')); // Example: "1403-08-15" // Create a date from Persian calendar const nowruz = dayjs.fromCalendarSystem('persian', 1403, 1, 1); console.log(nowruz.format('YYYY-MM-DD')); // "2024-03-20" ``` **That's it!** You're now working with Persian dates using the familiar Day.js API. 🎉 --- ## 📅 Supported Calendars | Calendar System | Region/Users | Status | Import Path | |----------------|--------------|--------|-------------| | **Gregorian** 🌍 | Worldwide (default) | ✅ Built-in | Default | | **Persian** (Jalali) 🇮🇷 | Iran, Afghanistan (~100M) | ✅ Production | `PersianCalendarSystem` | | **Islamic** (Hijri) 🕌 | Muslim world (~1.8B) | ✅ Production | `HijriCalendarSystem` | | **Hebrew** (Jewish) 🕎 | Jewish communities (~15M) | ✅ Production | `HebrewCalendarSystem` | | **Ethiopian** 🇪🇹 | Ethiopia, Eritrea (~120M) | ✅ Production | `EthiopianCalendarSystem` | | **Chinese** 🇨🇳 | East Asia (~1.5B) | ✅ Production | `ChineseCalendarSystem` | | **Amazigh** (Berber) ⵣ | North Africa (~30M) | ✅ Production | `AmazighCalendarSystem` | | **Mars** (Darian) 🔴 | Future Mars settlers 🚀 | ✅ Production | `MarsCalendarSystem` | | **Indian** 🇮🇳 | India | 🚧 Coming Soon | — | **Total reach: 3.5+ billion potential users worldwide!** --- ## ✨ Features ### Core Features - ✅ **8 calendar systems** (7 implemented + 1 in development) - ✅ **Full Day.js API compatibility** - use all methods you know and love - ✅ **Bidirectional conversions** - convert between any calendar systems - ✅ **TypeScript support** with complete type definitions - ✅ **Lightweight** - minimal bundle size impact (~4KB minified) - ✅ **Zero dependencies** (except Day.js peer dependency) - ✅ **Immutable** - follows Day.js immutability principles - ✅ **Locale support** - proper month/weekday names for each calendar - ✅ **Custom calendars** - easily add your own calendar systems ### Advanced Features - 🔄 **Accurate conversions** with leap year support - 🌙 **Lunar calendars** (Hijri) with Umm al-Qura calculations - 🌞 **Solar calendars** (Persian, Ethiopian, Gregorian) - 🌗 **Lunisolar calendars** (Hebrew, Chinese) with leap month support - 🧮 **Historical accuracy** tested against known historical dates - 📊 **60-year sexagenary cycle** for Chinese calendar - 🐉 **Zodiac animals** for Chinese calendar - 🔴 **Mars Sol Date** calculations for Darian calendar - ⚡ **Optimized performance** with efficient conversion algorithms --- ## 📖 Documentation ### Table of Contents - [Quick Examples](#-quick-examples) - [Supported Calendars](#-supported-calendars) - [Persian Calendar](#1-persian-calendar-jalali-shamsi) - [Islamic Calendar](#2-islamic-calendar-hijri) - [Hebrew Calendar](#3-hebrew-calendar-jewish) - [Ethiopian Calendar](#4-ethiopian-calendar) - [Chinese Calendar](#5-chinese-calendar) - [Amazigh Calendar](#6-amazigh-calendar-berber) - [Mars Calendar](#7-mars-calendar-darian) - [API Reference](#-api-reference) - [Advanced Usage](#-advanced-usage) - [Custom Calendar Systems](#-creating-custom-calendar-systems) - [Best Practices](#-best-practices) - [Migration Guide](#-migration-guide) --- ## 🚀 Quick Examples ### Example 1: Persian New Year (Nowruz) ```javascript import dayjs from 'dayjs'; import calendarSystems from '@calidy/dayjs-calendarsystems'; import PersianCalendarSystem from '@calidy/dayjs-calendarsystems/calendarSystems/PersianCalendarSystem'; dayjs.extend(calendarSystems); dayjs.registerCalendarSystem('persian', new PersianCalendarSystem()); // Find when Nowruz 1404 will be const nowruz1404 = dayjs.fromCalendarSystem('persian', 1404, 1, 1); console.log(`Nowruz 1404: ${nowruz1404.format('MMMM D, YYYY')}`); // Output: "March 20, 2025" ``` ### Example 2: Ramadan Start Date ```javascript import HijriCalendarSystem from '@calidy/dayjs-calendarsystems/calendarSystems/HijriCalendarSystem'; dayjs.registerCalendarSystem('hijri', new HijriCalendarSystem()); // Convert today to Hijri to check if it's Ramadan const today = dayjs().toCalendarSystem('hijri'); const isRamadan = today.month() === 8; // Ramadan is the 9th month (0-indexed) console.log(`Is Ramadan: ${isRamadan}`); ``` ### Example 3: Chinese New Year ```javascript import ChineseCalendarSystem from '@calidy/dayjs-calendarsystems/calendarSystems/ChineseCalendarSystem'; dayjs.registerCalendarSystem('chinese', new ChineseCalendarSystem()); // Find the zodiac animal for current year const calendar = new ChineseCalendarSystem(); const chineseDate = dayjs().toCalendarSystem('chinese'); const zodiac = calendar.getZodiacAnimal(chineseDate.year()); console.log(`Current year zodiac: ${zodiac}`); ``` ### Example 4: Multi-Calendar Display ```javascript // Show the same date across multiple calendars const today = dayjs(); const calendars = [ { name: 'Gregorian', system: 'gregory' }, { name: 'Persian', system: 'persian' }, { name: 'Hijri', system: 'hijri' }, { name: 'Hebrew', system: 'hebrew' }, { name: 'Ethiopian', system: 'ethiopian' }, { name: 'Chinese', system: 'chinese' }, ]; calendars.forEach(({ name, system }) => { const date = today.toCalendarSystem(system); console.log(`${name}: ${date.format('YYYY-MM-DD')}`); }); ``` --- ## 📚 Supported Calendars ### 1. Persian Calendar (Jalali, Shamsi) The Persian calendar (also known as Jalali or Shamsi calendar) is one of the most accurate solar calendars in use today. It's the official calendar of Iran and Afghanistan. ```javascript import PersianCalendarSystem from '@calidy/dayjs-calendarsystems/calendarSystems/PersianCalendarSystem'; dayjs.registerCalendarSystem('persian', new PersianCalendarSystem()); const persianDate = dayjs().toCalendarSystem('persian'); console.log(persianDate.format('YYYY/MM/DD')); // e.g., "1403/08/15" ``` **Key Features:** - 🌞 Solar calendar aligned with vernal equinox - 📅 12 months: 6 × 31 days, 5 × 30 days, 1 × 29/30 days - 🎊 New Year (Nowruz) on March 20/21 - 🔢 Year 1403 (as of 2024 CE) - ⚖️ One of the most astronomically accurate calendars **Common Use Cases:** - Iranian business applications - Afghan government systems - Nowruz celebration planning - Persian cultural events --- ### 2. Islamic Calendar (Hijri) The Islamic calendar (Hijri) is a purely lunar calendar used by Muslims worldwide to determine religious observances. ```javascript import HijriCalendarSystem from '@calidy/dayjs-calendarsystems/calendarSystems/HijriCalendarSystem'; dayjs.registerCalendarSystem('hijri', new HijriCalendarSystem()); const hijriDate = dayjs().toCalendarSystem('hijri'); console.log(hijriDate.format('YYYY-MM-DD')); // e.g., "1446-03-15" ``` **Key Features:** - 🌙 Lunar calendar (12 lunar months) - 📅 354 or 355 days per year (10-11 days shorter than solar year) - 🕌 Based on Umm al-Qura calculations (official Saudi system) - 📍 Year 1 = 622 CE (Hijra of Prophet Muhammad) - 🎉 Used for Ramadan, Eid, Hajj dates **Common Use Cases:** - Islamic prayer time apps - Ramadan and Eid date calculators - Islamic event planning - Religious calendar displays --- ### 3. Hebrew Calendar (Jewish) The Hebrew calendar is a lunisolar calendar used predominantly for Jewish religious observances. ```javascript import HebrewCalendarSystem from '@calidy/dayjs-calendarsystems/calendarSystems/HebrewCalendarSystem'; dayjs.registerCalendarSystem('hebrew', new HebrewCalendarSystem()); const hebrewDate = dayjs().toCalendarSystem('hebrew'); console.log(hebrewDate.format('YYYY-MM-DD')); // e.g., "5785-03-15" ``` **Key Features:** - 🌗 Lunisolar calendar (lunar months + solar year alignment) - 📅 12 or 13 months (leap year has extra month Adar I) - 🔢 7 leap years every 19 years (Metonic cycle) - 📍 Year 1 = 3761 BCE (traditional creation date) - 🕍 Used for Jewish holidays (Rosh Hashanah, Passover, Hanukkah) **Common Use Cases:** - Jewish holiday planning apps - Synagogue calendar systems - Hebrew date displays - Bar/Bat Mitzvah date calculations --- ### 4. Ethiopian Calendar The Ethiopian calendar (Ge'ez calendar) is the principal calendar used in Ethiopia and Eritrea, approximately 7-8 years behind the Gregorian calendar. ```javascript import EthiopianCalendarSystem from '@calidy/dayjs-calendarsystems/calendarSystems/EthiopianCalendarSystem'; dayjs.registerCalendarSystem('ethiopian', new EthiopianCalendarSystem()); const ethiopianDate = dayjs().toCalendarSystem('ethiopian'); console.log(ethiopianDate.format('YYYY-MM-DD')); // e.g., "2017-03-15" ``` **Key Features:** - 🌞 Solar calendar based on Coptic calendar - 📅 13 months: 12 × 30 days + Pagumen (5-6 days) - 🎊 New Year (Enkutatash) on September 11 - 🔢 Currently year ~2017 (when Gregorian is 2024) - ⛪ Official calendar of Ethiopia and Ethiopian Orthodox Church **Common Use Cases:** - Ethiopian business applications - Orthodox church calendars - Ethiopian government systems - Cultural event planning --- ### 5. Chinese Calendar The Chinese calendar is a lunisolar calendar with a rich cultural heritage spanning over 2000 years, used throughout East Asia. ```javascript import ChineseCalendarSystem from '@calidy/dayjs-calendarsystems/calendarSystems/ChineseCalendarSystem'; dayjs.registerCalendarSystem('chinese', new ChineseCalendarSystem()); const chineseDate = dayjs().toCalendarSystem('chinese'); console.log(chineseDate.format('YYYY-MM-DD')); // e.g., "4722-10-15" // Get zodiac animal const calendar = new ChineseCalendarSystem(); const zodiac = calendar.getZodiacAnimal(4722); console.log(`Zodiac: ${zodiac}`); // e.g., "Snake" // Get sexagenary cycle const cycle = calendar.getSexagenaryCycle(4722); console.log(`Cycle: ${cycle.cycleName}`); // e.g., "Yǐ-Sì" ``` **Key Features:** - 🌗 Lunisolar calendar (lunar months with solar year alignment) - 📅 12 or 13 months per year (leap month ~7 times in 19 years) - 🐉 12 zodiac animals rotating each year - 🔄 60-year sexagenary cycle (Heavenly Stems + Earthly Branches) - 🎊 New Year (Spring Festival) between Jan 21 - Feb 20 - 🌾 24 solar terms for agriculture **Common Use Cases:** - Chinese New Year date calculations - Zodiac animal determination - Traditional festival planning - East Asian cultural applications - Fortune telling and astrology apps --- ### 6. Amazigh Calendar (Berber) The Amazigh calendar (Berber calendar) is used by Berber communities across North Africa, with year 1 corresponding to 950 BCE. ```javascript import AmazighCalendarSystem from '@calidy/dayjs-calendarsystems/calendarSystems/AmazighCalendarSystem'; dayjs.registerCalendarSystem('amazigh', new AmazighCalendarSystem()); const amazighDate = dayjs().toCalendarSystem('amazigh'); console.log(amazighDate.format('YYYY-MM-DD')); // e.g., "2974-03-15" ``` **Key Features:** - 🌞 Solar calendar based on Julian calendar - 📅 12 months following agricultural seasons - 🎊 New Year (Yennayer) on January 12-14 - 🔢 Year 2974 (as of 2024 CE) - 🏛️ Year 1 = 950 BCE (Shoshenq I became Pharaoh) **Common Use Cases:** - North African cultural applications - Berber community apps - Cultural heritage preservation - Amazigh New Year celebrations --- ### 7. Mars Calendar (Darian) The Darian calendar is designed for Mars timekeeping, perfect for space missions and future Mars colonization! ```javascript import MarsCalendarSystem from '@calidy/dayjs-calendarsystems/calendarSystems/MarsCalendarSystem'; dayjs.registerCalendarSystem('mars', new MarsCalendarSystem()); const marsDate = dayjs().toCalendarSystem('mars'); console.log(marsDate.format('YYYY-MM-DD')); // e.g., "0224-15-18" // Calculate sols since Perseverance landing const landing = dayjs('2021-02-18').toCalendarSystem('mars'); const today = dayjs().toCalendarSystem('mars'); const solsSince = today.diff(landing, 'day'); console.log(`Sols since landing: ${solsSince}`); ``` **Key Features:** - 🔴 24 months with Latin/Sanskrit zodiac names - ⏱️ 668-669 sols per year (1 sol = 24h 39m 35s) - 🚀 Epoch: December 29, 1873 - 📊 Leap year logic for Mars orbital mechanics - 🌌 Mars Sol Date (MSD) system **Common Use Cases:** - Mars mission planning - Space exploration apps - Educational astronomy tools - Sci-fi applications **📖 [Complete Mars Calendar Documentation](MARS_CALENDAR.md)** --- ## 🔧 API Reference ### Plugin Registration ```javascript import dayjs from 'dayjs'; import calendarSystems from '@calidy/dayjs-calendarsystems'; // Extend Day.js (do this once, before using calendar systems) dayjs.extend(calendarSystems); ``` ### Register Calendar System ```javascript import PersianCalendarSystem from '@calidy/dayjs-calendarsystems/calendarSystems/PersianCalendarSystem'; // Register a calendar system with a unique identifier dayjs.registerCalendarSystem('persian', new PersianCalendarSystem()); // You can also use a different identifier dayjs.registerCalendarSystem('jalali', new PersianCalendarSystem()); ``` ### Convert TO a Calendar System ```javascript // Convert current Day.js instance to another calendar const gregorianDate = dayjs('2024-03-20'); const persianDate = gregorianDate.toCalendarSystem('persian'); console.log(persianDate.format('YYYY-MM-DD')); // "1403-01-01" // All Day.js methods work on the converted instance console.log(persianDate.year()); // 1403 console.log(persianDate.month()); // 0 (Farvardin, 0-indexed) console.log(persianDate.date()); // 1 console.log(persianDate.day()); // Day of week ``` ### Create FROM a Calendar System ```javascript // Create a Day.js instance from a specific calendar system const persianNewYear = dayjs.fromCalendarSystem('persian', 1403, 1, 1); // The result is a standard Day.js instance in that calendar system console.log(persianNewYear.format('YYYY-MM-DD')); // In Persian: "1403-01-01" // Convert to Gregorian to see the equivalent date const gregorian = persianNewYear.toCalendarSystem('gregory'); console.log(gregorian.format('YYYY-MM-DD')); // "2024-03-20" ``` ### Set Default Calendar System ```javascript // Set a default calendar system for all new Day.js instances dayjs.toCalendarSystem('persian'); // Now all dayjs() calls will use Persian calendar by default const now = dayjs(); console.log(now.format('YYYY-MM-DD')); // Persian date // You can still convert to other systems const gregorian = now.toCalendarSystem('gregory'); ``` ### Get Registered Calendar System ```javascript // Retrieve a registered calendar system instance const persianCalendar = dayjs.getRegisteredCalendarSystem('persian'); // Access calendar-specific methods const monthNames = persianCalendar.monthNames(); console.log(monthNames); // ['Farvardin', 'Ordibehesht', ...] ``` ### All Day.js Methods Work! Once you have a calendar-system-aware Day.js instance, all standard methods work: ```javascript const persianDate = dayjs().toCalendarSystem('persian'); // Formatting persianDate.format('YYYY-MM-DD'); persianDate.format('YYYY/MM/DD HH:mm:ss'); persianDate.format('dddd, MMMM D, YYYY'); // Manipulation persianDate.add(1, 'month'); persianDate.subtract(1, 'year'); persianDate.startOf('month'); persianDate.endOf('year'); // Display persianDate.year(); persianDate.month(); persianDate.date(); persianDate.day(); persianDate.hour(); persianDate.minute(); // Query persianDate.isBefore(otherDate); persianDate.isAfter(otherDate); persianDate.isSame(otherDate); persianDate.isLeapYear(); persianDate.daysInMonth(); // Compare persianDate.diff(otherDate, 'day'); persianDate.diff(otherDate, 'month'); ``` --- ## 🎓 Advanced Usage ### Multi-Calendar Applications Build apps that display the same date across multiple calendars: ```javascript function displayInAllCalendars(date) { const systems = ['gregory', 'persian', 'hijri', 'hebrew', 'ethiopian', 'chinese']; return systems.map(system => ({ calendar: system, date: date.toCalendarSystem(system).format('YYYY-MM-DD') })); } const today = dayjs(); console.table(displayInAllCalendars(today)); ``` ### Calendar System Chaining Convert between multiple calendar systems: ```javascript const date = dayjs('2024-01-01') // Start with Gregorian .toCalendarSystem('persian') // Convert to Persian .add(1, 'month') // Add 1 Persian month .toCalendarSystem('hijri') // Convert to Hijri .subtract(5, 'day') // Subtract 5 days .toCalendarSystem('gregory'); // Convert back to Gregorian console.log(date.format('YYYY-MM-DD')); ``` ### Holiday Calculations ```javascript // Find Persian New Year (Nowruz) for next 5 years function getNextNowruzDates(count = 5) { const currentYear = dayjs().toCalendarSystem('persian').year(); return Array.from({ length: count }, (_, i) => { const persianYear = currentYear + i; const nowruz = dayjs.fromCalendarSystem('persian', persianYear, 1, 1); return { persianYear, gregorianDate: nowruz.toCalendarSystem('gregory').format('YYYY-MM-DD'), dayOfWeek: nowruz.format('dddd') }; }); } console.table(getNextNowruzDates()); ``` ### Leap Year Across Calendars ```javascript function compareLeapYears(year) { const date = dayjs(`${year}-01-01`); const calendars = ['gregory', 'persian', 'hebrew', 'ethiopian']; return calendars.map(system => ({ calendar: system, year: date.toCalendarSystem(system).year(), isLeap: date.toCalendarSystem(system).isLeapYear() })); } console.table(compareLeapYears(2024)); ``` ### Working with Locales ```javascript import 'dayjs/locale/fa'; // Persian locale import 'dayjs/locale/ar'; // Arabic locale import 'dayjs/locale/he'; // Hebrew locale const persianDate = dayjs().toCalendarSystem('persian').locale('fa'); console.log(persianDate.format('MMMM')); // "فروردین" const hijriDate = dayjs().toCalendarSystem('hijri').locale('ar'); console.log(hijriDate.format('MMMM')); // Month name in Arabic ``` --- ## 🛠️ Creating Custom Calendar Systems You can easily create your own calendar system by implementing the `CalendarSystemBase` interface: ```javascript class MyCustomCalendarSystem { constructor() { this.name = 'my-custom-calendar'; } /** * Convert from your calendar system to Gregorian * @param {number} year - Year in your calendar * @param {number} month - Month in your calendar (0-indexed) * @param {number} day - Day in your calendar * @returns {{ year: number, month: number, day: number }} */ convertToGregorian(year, month, day) { // Your conversion logic here // Must return { year, month, day } in Gregorian // Example: offset by 1000 years return { year: year - 1000, month: month, day: day }; } /** * Convert from Gregorian to your calendar system * @param {Date} date - JavaScript Date object * @returns {{ year: number, month: number, day: number }} */ convertFromGregorian(date) { // Your conversion logic here // Must return { year, month, day } in your calendar // Example: offset by 1000 years return { year: date.getFullYear() + 1000, month: date.getMonth(), day: date.getDate() }; } // Optional: Provide month names monthNames() { return [ 'Month1', 'Month2', 'Month3', 'Month4', 'Month5', 'Month6', 'Month7', 'Month8', 'Month9', 'Month10', 'Month11', 'Month12' ]; } // Optional: Provide weekday names weekdays() { return ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat']; } // Optional: Custom leap year logic isLeapYear(year) { // Your leap year logic return year % 4 === 0; } } // Register and use your custom calendar dayjs.registerCalendarSystem('custom', new MyCustomCalendarSystem()); const customDate = dayjs().toCalendarSystem('custom'); ``` **See the source code of existing calendars for complete examples:** - [PersianCalendarSystem](src/calendarSystems/PersianCalendarSystem.js) - [HijriCalendarSystem](src/calendarSystems/HijriCalendarSystem.js) - [MarsCalendarSystem](src/calendarSystems/MarsCalendarSystem.js) --- ## 💡 Best Practices ### 1. Register Calendar Systems Once ```javascript // ✅ Good: Register once during app initialization // app-init.js or main.js import dayjs from 'dayjs'; import calendarSystems from '@calidy/dayjs-calendarsystems'; import PersianCalendarSystem from '@calidy/dayjs-calendarsystems/calendarSystems/PersianCalendarSystem'; dayjs.extend(calendarSystems); dayjs.registerCalendarSystem('persian', new PersianCalendarSystem()); // ❌ Avoid: Registering repeatedly // Don't do this in every component/function ``` ### 2. Use Consistent Calendar Identifiers ```javascript // ✅ Good: Use standard identifiers dayjs.registerCalendarSystem('persian', new PersianCalendarSystem()); dayjs.registerCalendarSystem('hijri', new HijriCalendarSystem()); // ❌ Avoid: Inconsistent naming dayjs.registerCalendarSystem('Persian', new PersianCalendarSystem()); dayjs.registerCalendarSystem('islamic', new HijriCalendarSystem()); ``` ### 3. Keep Instances Immutable ```javascript // ✅ Good: Create new instances for modifications const date1 = dayjs().toCalendarSystem('persian'); const date2 = date1.add(1, 'month'); // Returns new instance console.log(date1.month()); // Original unchanged console.log(date2.month()); // New month // Day.js is immutable by design - this plugin maintains that ``` ### 4. Handle Conversion Errors ```javascript // ✅ Good: Validate before conversion try { const date = dayjs.fromCalendarSystem('persian', 1403, 1, 1); console.log(date.format('YYYY-MM-DD')); } catch (error) { console.error('Invalid date:', error); } ``` ### 5. Use TypeScript for Type Safety ```typescript import type { Dayjs } from 'dayjs'; function convertToPersian(date: Dayjs): Dayjs { return date.toCalendarSystem('persian'); } ``` --- ## 🔄 Migration Guide ### From Other Libraries #### From moment-jalaali ```javascript // Before (moment-jalaali) const m = require('moment-jalaali'); const date = m('1403/01/01', 'jYYYY/jMM/jDD'); // After (@calidy/dayjs-calendarsystems) import dayjs from 'dayjs'; import calendarSystems from '@calidy/dayjs-calendarsystems'; import PersianCalendarSystem from '@calidy/dayjs-calendarsystems/calendarSystems/PersianCalendarSystem'; dayjs.extend(calendarSystems); dayjs.registerCalendarSystem('persian', new PersianCalendarSystem()); const date = dayjs.fromCalendarSystem('persian', 1403, 1, 1); ``` #### From moment-hijri ```javascript // Before (moment-hijri) const moment = require('moment-hijri'); const date = moment('1446/03/15', 'iYYYY/iMM/iDD'); // After (@calidy/dayjs-calendarsystems) import dayjs from 'dayjs'; import calendarSystems from '@calidy/dayjs-calendarsystems'; import HijriCalendarSystem from '@calidy/dayjs-calendarsystems/calendarSystems/HijriCalendarSystem'; dayjs.extend(calendarSystems); dayjs.registerCalendarSystem('hijri', new HijriCalendarSystem()); const date = dayjs.fromCalendarSystem('hijri', 1446, 3, 15); ``` ### Bundle Size Benefits - **Moment.js**: ~300KB minified - **Day.js + this plugin**: ~6-7KB minified (98% smaller!) --- ## 🧪 Testing ```bash # Run all tests npm test # Run tests in watch mode npm test -- --watch # Run tests with coverage npm test -- --coverage # Run linter npm run lint ``` --- ## 📦 Bundle Size This plugin is designed to be lightweight and tree-shakeable: - **Core plugin**: ~2.5KB minified + gzipped - **Each calendar system**: ~0.5-1.5KB minified + gzipped - **Total (with all calendars)**: ~8-10KB minified + gzipped Import only what you need to keep your bundle small! --- ## 🤝 Contributing We welcome contributions! Whether it's: - 🐛 Bug reports and fixes - ✨ New calendar systems - 📖 Documentation improvements - 🧪 Test coverage - 💡 Feature requests **Please read our [Contributing Guide](CONTRIBUTING.md) and [Code of Conduct](CODE_OF_CONDUCT.md) before contributing.** ### Quick Contribution Steps 1. Fork the repository 2. Create a feature branch: `git checkout -b feature/my-calendar` 3. Make your changes and add tests 4. Run tests: `npm test` 5. Commit: `git commit -m "feat: add MyCalendar system"` 6. Push: `git push origin feature/my-calendar` 7. Open a Pull Request ### Adding a New Calendar System See our guide on [Creating Custom Calendar Systems](#-creating-custom-calendar-systems) and look at existing implementations in `src/calendarSystems/` for examples. --- ## 🌟 Stargazers Thank you to everyone who has starred this project! Your support means a lot. [](https://github.com/calidy-com/dayjs-calendarsystems/stargazers) --- ## 🙏 Acknowledgements This project wouldn't be possible without: - **[Day.js](https://day.js.org)** - The amazing 2KB immutable date library - **[Dayjs-Jalali-Plugin](https://github.com/zoomit-org/Dayjs-Jalali-Plugin)** - Inspiration for Persian calendar integration - **[Jalaliday Plugin](https://github.com/alibaba-aero/jalaliday)** - Additional Persian calendar insights - **All contributors** who have helped improve this project Special thanks to the calendar system experts and communities who provided accurate conversion algorithms and cultural context. --- ## 📄 License This project is **DUAL LICENSED**: ### For Non-Commercial Use - **License**: Creative Commons Attribution-NonCommercial 4.0 International (CC BY-NC 4.0) - **Free to use** for personal projects, education, and non-profit organizations ### For Commercial Use - A valid commercial license is required when you or your company earns revenue directly or indirectly using this project - **[Contact us for commercial licensing](https://calidy.com/engineering)** **See [LICENSE.md](LICENSE.md) for complete details.** --- ## 📞 Support & Community - 📖 **Documentation**: [GitHub Repo](https://github.com/calidy-com/dayjs-calendarsystems) - 🐛 **Bug Reports**: [GitHub Issues](https://github.com/calidy-com/dayjs-calendarsystems/issues) - 💬 **Discussions**: [GitHub Discussions](https://github.com/calidy-com/dayjs-calendarsystems/discussions) - 🌐 **Website**: [calidy.com/engineering](https://calidy.com/engineering) - 📧 **Email**: Check our GitHub profile --- ## 🗺️ Roadmap ### Planned Features - [ ] Indian calendar system (Vikram Samvat) - [ ] Thai calendar system - [ ] Japanese calendar system (with era support) - [ ] Date string parsing for non-Gregorian calendars - [ ] Advanced locale support with RTL - [ ] Calendar-specific formatting tokens - [ ] Time zone support across calendars - [ ] More comprehensive test coverage **Want to contribute to any of these? [Open an issue](https://github.com/calidy-com/dayjs-calendarsystems/issues) to discuss!** --- ## 📊 Statistics - **8 calendar systems** (7 production-ready + 1 in development) - **3.5+ billion** potential users worldwide - **200+ tests** ensuring accuracy - **99%+ accuracy** in date conversions - **2KB - 10KB** total bundle size (depending on calendars used) - **MIT-style** license for non-commercial use --- ## ⭐ Show Your Support If you find this project useful, please consider: - ⭐ **Starring** the repository - 🐦 **Tweeting** about it - 📝 **Mentioning** it in your project's README - 🤝 **Contributing** code, calendars, or documentation - 💬 **Sharing** your use case in Discussions Every star and contribution helps this project reach more developers and users worldwide! ---Made with ❤️ by Calidy
--- _Source: https://npm.io/package/@calidy/dayjs-calendarsystems · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._