Coptic Calendar

high-precision, polymorphic library for the Coptic liturgical calendar, featuring advanced date arithmetic and a modular plugin system for the Synaxarium, liturgical feasts, and canonical rites.

Features

• Universal Polymorphism: Convert from native Date, ISO strings, timestamps, elements, or custom Temporal-like objects.
• Fluent Arithmetic: Perform elegant date manipulations with add, subtract, and with.
• Localization: Full translation support for English, Arabic, and Coptic (Bohairic).
• Extensible Architecture: Modular plugin system allows lightweight core or full liturgical immersion.
• TypeScript Native: Zero-dependency, ESM-first library with strict type safety.

Installation

npm install coptic-calendar

Usage

Basic Conversion

import { CopticDate } from 'coptic-calendar';

// Polymorphic .from() supports Dates, strings, timestamps, and elements
const date = CopticDate.from({ year: 1740, month: 5, day: 23 });

// Access calendar components
console.log(`Coptic Date: ${date.year}-${date.month}-${date.day}`); // "1740-5-23"
console.log(`Is Leap Year: ${date.inLeapYear}`); // false

// Multi-language localization support
console.log(date.toLocaleString({ locale: 'en' })); // "23 Tobi 1740"
console.log(date.toLocaleString({ locale: 'ar' })); // "٢٣ طوبة ١٧٤٠"

Date Arithmetic & Comparison

const start = CopticDate.from('2024-01-01'); // 22 Kiahk 1740

// Addition and Subtraction
const nextMonth = start.add({ months: 1 }); // 22 Tobi 1740
const lastYear = start.subtract({ years: 1 }); // 22 Kiahk 1739

// Fluent modification
const specificDay = start.with({ day: 15 }); // 15 Kiahk 1740

// Comparison
if (start.equals(nextMonth)) { /* ... */ } // false
const order = CopticDate.compare(start, nextMonth); // -1 (start < nextMonth)

Plugin System

The library is lightweight by default, but can be extended with specialized plugins for ecclesiastical data.

Synaxarium Plugin

Provides daily saint commemorations and historical readings.

import { CopticDate } from 'coptic-calendar';
import { synaxariumPlugin } from 'coptic-calendar/plugins/synaxarium';

CopticDate.extend(synaxariumPlugin);

const date = CopticDate.from('2024-04-19'); // 12 Paremoude 1740
console.log(date.synaxarium({ locale: 'en' })); 
// ["The Departure of St. Alexander, Bishop of Jerusalem.", ...]

Occasions Plugin

Calculates all liturgical feasts and fasts, including the moving Paschal cycle.

import { CopticDate } from 'coptic-calendar';
import { occasionsPlugin } from 'coptic-calendar/plugins/occasions';

CopticDate.extend(occasionsPlugin);

const date = CopticDate.from('2024-04-19');
console.log(date.occasions({ locale: 'en' })); // ["Great Lent"]

// Find specific occasions
const easter = date.when('Easter');
console.log(`Easter is on: ${easter.toString()}`); // "1740-8-27"

Typicon Plugin

Derives the active canonical Typicon configuration (season, tune, etc.) for any date.

import { CopticDate } from 'coptic-calendar';
import { typiconPlugin } from 'coptic-calendar/plugins/typicon';

CopticDate.extend(typiconPlugin);

const date = CopticDate.from('2024-04-19');
const rite = date.rite({ locale: 'en' });

console.log(`Season: ${rite.season}`);   // "Great Lent"
console.log(`Tune: ${rite.tune}`);       // "Lenten"
console.log(`Metanoias: ${rite.hasMetanoias}`); // true

Contribution

We welcome contributions! Please follow these steps:

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under The Unlicense - see the LICENSE file for details.