README

Kiahk

Coptic calendar arithmetic — date conversion, Easter, and feast days. A small, exact library for the Coptic Orthodox (Alexandrian) calendar: convert between Gregorian and Coptic dates, compute Coptic Easter (Pascha) using the Julian computus, and look up the major fixed and moveable feasts of the Coptic Orthodox church year. Ported to 9 languages from a single canonical spec in core/ — every port produces identical results against the shared test vectors.

At a glance: Anno Martyrum (AM) era · 13-month year (12×30 days + Nasie) · Julian-style leap rule (Y mod 4 == 3) · Coptic Easter via Meeus's compact Julian computus · English and Arabic month + feast names built in.

Package versions

Downloads & adoption ℹ️

Build status

Ports & distributions

Same algorithms, same core/test-vectors.json contract, distributed through each language's native package manager. Every port version is kept in lockstep — the version badges below should all read the same number.

Language	Source	Install
TypeScript / JavaScript	`js/`	`npm install kiahk`
Python	`py/`	`pip install kiahk`
PHP	`php/`	`composer require wizardlabz/kiahk`
Go	`go/`	`go get github.com/amir-magdy-of-wizardlabz/kiahk/go`
Dart / Flutter	`dart/`	`dart pub add kiahk`
Swift (SwiftPM)	`swift/`	add `https://github.com/amir-magdy-of-wizardlabz/kiahk.git` to `Package.swift`
Swift (CocoaPods)	`swift/`	`pod 'Kiahk'` in `Podfile`
C# / .NET	`csharp/`	`dotnet add package Kiahk`
Kotlin / JVM / Android	`kotlin/`	`implementation("com.wizardlabz:kiahk:0.1.6")` in Gradle
C	`c/`	download tarball or `add_subdirectory(c)` in CMake

See each port's README for full install + quick-start examples, and for English + Arabic month-name rendering.

Canonical spec

core/algorithms.md — pseudocode for Gregorian↔Coptic, Easter, feasts
core/feasts.json — fixed + moveable feast registry
core/coptic_months.json — the 13 Coptic month names (English + Arabic)
core/test-vectors.json — cross-port test contract

Every port must produce identical results against core/test-vectors.json.

FAQ

What is the Coptic calendar?

The Coptic (Alexandrian) calendar is the liturgical calendar of the Coptic Orthodox Church of Alexandria. It derives from the ancient Egyptian civil calendar and was reformed by Augustus in 25 BC. Its era is Anno Martyrum (AM) — "Year of the Martyrs" — counted from 29 August 284 CE (Julian), the year of Diocletian's accession and the persecution of Christians.

What are the months of the Coptic year?

There are 13 months: 12 of exactly 30 days each, plus a short 13th month called Nasie of 5 days (6 in leap years). In order: Thout · Paopi · Hathor · Koiak · Tobi · Meshir · Paremhat · Parmouti · Pashons · Paoni · Epip · Mesori · Nasie. (Arabic: توت · بابة · هاتور · كيهك · طوبة · أمشير · برمهات · برمودة · بشنس · بؤونة · أبيب · مسرى · نسيء.) Available via CopticCalendar.monthName(month, locale) in every port.

When does the Coptic year start?

1 Tout — falling on either 11 September or 12 September in the Gregorian calendar (the later date in the Gregorian year preceding a leap year). The current Coptic year began on 11 September 2025 (Gregorian) and is 1742 AM.

When is Coptic Christmas?

7 January every year in the 20th–21st centuries, because the Coptic calendar is fixed relative to the Julian calendar and the Julian-to-Gregorian offset stays at +13 days through 28 February 2100.

It is kept on 29 Koiak in three years out of four. In a Coptic year that is a multiple of 4 — the year right after a 6-day Nasie — every Coptic date from 1 Tout to the following 29 February sits one Gregorian day later, so 29 Koiak lands on 8 January; the Church observes the Nativity on 28 Koiak in those years so it stays on 7 January (keeping the interval from the Annunciation at 275 days). Kiahk applies that rule, so nativity is 7 January in every year, 2024 and 2028 included. Every other fixed feast does shift with the arithmetic — Epiphany is 20 January 2024, and the Feast of the Cross is 28 September 2023. See core/algorithms.md §3a.

When is Coptic Easter?

Coptic Easter follows the Julian computus — the same calculation used by all Eastern Orthodox churches. It can fall anywhere between April 4 and May 8 in the Gregorian calendar. Examples: 2025 → April 20, 2026 → April 12, 2027 → May 2, 2028 → April 16. Use CopticCalendar.easterDate(gregorianYear) to compute it.

How is Coptic Easter different from Western (Gregorian) Easter?

Both use the same underlying rule ("Sunday after the first full moon on or after the spring equinox") but with different reference frames. Western Easter uses the Gregorian calendar and Gregorian computus; Coptic and Eastern Orthodox Easter use the Julian calendar and Julian computus. The two coincide in some years and can be up to 5 weeks apart in others. Kiahk implements only the Coptic/Julian variant.

What are the major Coptic feasts?

Eleven entries — five fixed feasts, four moveable feasts, and the start of the two major fasts. Every one carries both an English and an Arabic name; the id is the stable key you pass to the API.

`id`	English	العربية	Type	Date
`nativity`	Nativity of Christ	عيد الميلاد المجيد	fixed	29 Koiak — 28 Koiak when the Coptic year is a multiple of 4 (7 January)
`epiphany`	Epiphany (Theophany)	عيد الغطاس	fixed	11 Tobi (19 January)
`annunciation`	Annunciation	عيد البشارة	fixed	29 Paremhat (7 April)
`assumption`	Assumption of Mary	عيد صعود جسد العذراء	fixed	16 Mesori (22 August)
`cross`	Feast of the Cross	عيد الصليب	fixed	17 Thout (27 September)
`nineveh_fast`	Nineveh Fast	صوم نينوى	moveable	Easter − 69 days
`great_lent`	Great Lent (start)	بداية الصوم الكبير	moveable	Easter − 55 days
`palm_sunday`	Palm Sunday	أحد الشعانين	moveable	Easter − 7 days
`easter`	Easter Sunday	عيد القيامة المجيد	moveable	—
`ascension`	Ascension	عيد الصعود	moveable	Easter + 39 days
`pentecost`	Pentecost	عيد العنصرة	moveable	Easter + 49 days

How do I get the Arabic names?

Arabic is a first-class locale in all 9 ports, for both feast names and month names — pass "ar" wherever you'd pass "en". An unrecognised locale raises the port's UnsupportedLocale error rather than silently falling back to English.

// TypeScript / JavaScript
feast.name('ar')                     // عيد القيامة المجيد
CopticCalendar.monthName(4, 'ar')    // كيهك

# Python
feast.name("ar")
CopticCalendar.month_name(4, "ar")

The other ports, exactly as their signatures read:

Port	Feast name	Month name
PHP · Kotlin · Dart	`$feast->name('ar')` / `feast.name("ar")`	`CopticCalendar::monthName(4, 'ar')` / `CopticCalendar.monthName(4, "ar")`
Swift	`try feast.name(locale: "ar")`	`try CopticCalendar.monthName(month: 4, locale: "ar")`
Go	`feast.Name("ar")` → `(string, error)`	`kiahk.CopticMonthName(4, "ar")` → `(string, error)`
C#	`feast.Name("ar")`	`CopticCalendar.MonthName(4, "ar")`
C	`kiahk_feast_name(&feast, "ar", &name)`	`kiahk_coptic_month_name(4, "ar", &name)`

The 13 month names in Arabic are listed under the months question above. Note that Coptic month spellings vary in circulation (بابه / بابة, مسرى / مصرى) — lookup is by month number, so this only affects display.

How does the Coptic leap year rule work?

A Coptic year Y is a leap year if and only if Y mod 4 == 3. This is the Julian-style leap rule (one leap every 4 years, no century exception). The extra day always goes to month 13 (Nasie), giving it 6 days instead of 5.

Why does Kiahk use Julian Day Numbers internally?

The Julian Day Number (JDN) is a continuous integer count of days from a single epoch (noon UTC, 1 January 4713 BC proleptic Julian). Routing every conversion through JDN gives you (a) one well-understood arithmetic primitive instead of N²×N two-calendar formulas, and (b) trivial day-arithmetic for moveable feasts (just add/subtract days). All 9 ports do this — see core/algorithms.md.

Can I use Kiahk in browser JavaScript / on Android / on iOS?

Yes — every port is pure-language with no native dependencies:

Browser JS — the JS port is ESM-only and has zero Node-specific APIs at runtime; works in any modern browser
Android — the Kotlin/JVM port targets JVM 11, Android API 26+ (use Android Gradle Plugin's desugaring for older)
iOS / macOS / tvOS / watchOS / visionOS / Linux — the Swift port is pure-Swift with only Foundation; works on every Apple OS plus Linux (and even Android via SwiftPM)
Server / CLI — all 9 ports work as backend libraries

How do I report a bug or suggest a feature?

Open an issue at https://github.com/amir-magdy-of-wizardlabz/kiahk/issues. If you have a security concern, see SECURITY.md.

Demo

Try it live → https://raw.githack.com/amir-magdy-of-wizardlabz/kiahk/master/demo/index.html

A small browser demo of the JS port lives in demo/. It lets you:

Pick a Gregorian date and see its Coptic equivalent (English + Arabic month names)
Enter a Gregorian year and view every major Coptic feast (en + ar names, fixed vs moveable)

Source: demo/index.html, demo/app.js. See demo/README.md for how to run it locally.

The hosted demo is served via raw.githack.com, a free proxy that serves GitHub files with correct MIME types. It reads master directly, so the link tracks whatever's on master at any given moment.

About those download numbers

Registry download counts are inflated by mirrors and security-scanner bots — sometimes 90%+ of "downloads" for a small package are automated traffic, not human installs. A few things to know about how the badges above compare:

PyPI — the badge points to pepy.tech, which filters most bot traffic and gives the closest thing to a real human-install count.
npm — the badge points to npm-stat.com for daily / per-country breakdown. npm's raw /dm/ counter includes a lot of CI install activity.
Packagist — counts are reasonably honest because Composer caches aggressively.
NuGet / CocoaPods — counts dominated by package-restore in CI; treat as a direction-of-travel indicator, not absolute usage.
Maven Central and pkg.go.dev — don't expose download stats publicly by design. The library is there; you just can't see who's pulling it.
GitHub stars / forks — small but more honest signals than any of the above. Star the repo if you find it useful.

License

Licensed under the MIT License.

Maintained by Amir Magdy at WizardLabz.

wizardlabz / kiahk

Maintainers

Package info

Statistics

Security