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.

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	Package	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.

• 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.

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.

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.

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.

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.

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.

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.

The seven major fixed feasts and the moveable feasts derived from Easter:

Plus the start of major fasts: Nineveh Fast (Easter − 69 days) and Great Lent (Easter − 55 days).

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.

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.

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

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

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.

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.

Licensed under the MIT License.

Maintained by Amir Magdy at WizardLabz.