From fe9c2c932c61cf59e93ee0362168e919361e696c Mon Sep 17 00:00:00 2001 From: Aric Camarata Date: Sat, 30 May 2026 18:32:26 -0400 Subject: [PATCH] docs: update TypeDoc sidebar and CI coverage job (pending from prior wave) --- .github/wiki/_Sidebar.md | 19 +++++ .github/workflows/ci.yml | 21 +++++ README.md | 177 +++++---------------------------------- 3 files changed, 62 insertions(+), 155 deletions(-) diff --git a/.github/wiki/_Sidebar.md b/.github/wiki/_Sidebar.md index 0e9d49e..7422e86 100644 --- a/.github/wiki/_Sidebar.md +++ b/.github/wiki/_Sidebar.md @@ -13,6 +13,25 @@ - [Architecture](Architecture) - [Benchmarks](benchmarks/index) +**API — Per Function** +- [toHijriDate](api/toHijriDate) +- [fromHijriDate](api/fromHijriDate) +- [isValidHijriDate](api/isValidHijriDate) +- [getHijriYear](api/getHijriYear) +- [getHijriMonth](api/getHijriMonth) +- [getHijriDay](api/getHijriDay) +- [getDaysInHijriMonth](api/getDaysInHijriMonth) +- [getHijriQuarter](api/getHijriQuarter) +- [getHijriMonthName](api/getHijriMonthName) +- [getHijriWeekdayName](api/getHijriWeekdayName) +- [formatHijriDate](api/formatHijriDate) +- [addHijriMonths](api/addHijriMonths) +- [addHijriYears](api/addHijriYears) +- [startOfHijriMonth](api/startOfHijriMonth) +- [endOfHijriMonth](api/endOfHijriMonth) +- [isSameHijriMonth](api/isSameHijriMonth) +- [isSameHijriYear](api/isSameHijriYear) + **Community** - [Contributing](CONTRIBUTING) - [Code of Conduct](CODE_OF_CONDUCT) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 5743612..11110e0 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -78,3 +78,24 @@ jobs: grep "README.md" pack-output.txt grep "CHANGELOG.md" pack-output.txt grep "LICENSE" pack-output.txt + + coverage: + name: Coverage + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Enable corepack + run: corepack enable + - uses: actions/setup-node@v4 + with: + node-version: 24 + cache: pnpm + - run: pnpm install --frozen-lockfile + - run: pnpm run build + - run: pnpm run coverage + - name: Upload to Codecov + uses: codecov/codecov-action@v4 + with: + files: ./coverage/lcov.info + token: ${{ secrets.CODECOV_TOKEN }} + fail_ci_if_error: false diff --git a/README.md b/README.md index 7491968..fb3382b 100644 --- a/README.md +++ b/README.md @@ -4,9 +4,9 @@ [![CI](https://github.com/acamarata/date-fns-hijri/actions/workflows/ci.yml/badge.svg)](https://github.com/acamarata/date-fns-hijri/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) -date-fns-style functions for Hijri calendar operations. Works with any date library. +date-fns-style functions for Hijri calendar operations. Each function is a pure, stateless utility. Pass a `Date`, get a result. No classes, no global configuration. -Each function is a pure, stateless utility. No classes. No configuration object. Pass a `Date`, get a result. Pass options to switch calendar systems. The API mirrors date-fns conventions so the learning curve is minimal. +Built on [hijri-core](https://github.com/acamarata/hijri-core). Supports Umm al-Qura (UAQ) and FCNA/ISNA calendar systems. ## Installation @@ -14,7 +14,7 @@ Each function is a pure, stateless utility. No classes. No configuration object. pnpm add date-fns-hijri hijri-core ``` -`hijri-core` is a peer dependency. It provides the underlying calendar engine and must be installed alongside this package. +`hijri-core` is a peer dependency. It provides the underlying calendar engine. ## Quick Start @@ -27,164 +27,35 @@ import { getHijriMonthName, } from 'date-fns-hijri'; -// Convert a Gregorian date to Hijri -const hijri = toHijriDate(new Date(2023, 2, 23)); -// { hy: 1444, hm: 9, hd: 1 } - 1 Ramadan 1444 - -// Convert back -const gregorian = fromHijriDate(1444, 9, 1); -// Date: 2023-03-23T00:00:00.000Z +// Convert Gregorian to Hijri +const hijri = toHijriDate(new Date(2023, 2, 23, 12)); +// { hy: 1444, hm: 9, hd: 1 } — 1 Ramadan 1444 // Format with Hijri tokens -const label = formatHijriDate(new Date(2023, 2, 23), 'iDD iMMMM iYYYY'); -// '01 Ramadan 1444' - -// Get the month name directly -const name = getHijriMonthName(9); -// 'Ramadan' - -// Add months in the Hijri calendar -const nextMonth = addHijriMonths(new Date(2023, 2, 23), 1); -// Date in Shawwal 1444 -``` - -## API - -All functions accept an optional `options` argument for selecting the calendar system. When omitted, Umm al-Qura (UAQ) is used. - -### Conversion - -| Function | Signature | Description | -| --- | --- | --- | -| `toHijriDate` | `(date: Date, options?) => HijriDate \| null` | Convert Gregorian to Hijri. Returns `null` if out of range. | -| `fromHijriDate` | `(hy, hm, hd, options?) => Date` | Convert Hijri to Gregorian. Throws if invalid. | - -### Validation - -| Function | Signature | Description | -| --- | --- | --- | -| `isValidHijriDate` | `(hy, hm, hd, options?) => boolean` | Check if a Hijri date exists in the calendar table. | - -### Field Getters - -| Function | Signature | Description | -| --- | --- | --- | -| `getHijriYear` | `(date, options?) => number \| null` | Hijri year. Null if out of range. | -| `getHijriMonth` | `(date, options?) => number \| null` | Hijri month (1-12). Null if out of range. | -| `getHijriDay` | `(date, options?) => number \| null` | Hijri day of month. Null if out of range. | -| `getDaysInHijriMonth` | `(hy, hm, options?) => number` | Days in a Hijri month (29 or 30). | -| `getHijriQuarter` | `(date, options?) => number \| null` | Quarter (1-4). Null if out of range. | - -### Names - -| Function | Signature | Description | -| --- | --- | --- | -| `getHijriMonthName` | `(hm, length?) => string` | English month name. `length`: `'long'` (default), `'medium'`, `'short'`. | -| `getHijriWeekdayName` | `(date, length?) => string` | Arabic weekday name. `length`: `'long'` (default), `'short'`. | - -### Formatting - -| Function | Signature | Description | -| --- | --- | --- | -| `formatHijriDate` | `(date, formatStr, options?) => string` | Format a date with Hijri tokens. Returns `''` if out of range. | - -### Arithmetic - -| Function | Signature | Description | -| --- | --- | --- | -| `addHijriMonths` | `(date, months, options?) => Date` | Add N Hijri months. Clamps day to month length. | -| `addHijriYears` | `(date, years, options?) => Date` | Add N Hijri years. Clamps day to month length. | - -### Month Boundaries - -| Function | Signature | Description | -| --- | --- | --- | -| `startOfHijriMonth` | `(date, options?) => Date` | First day of the containing Hijri month. | -| `endOfHijriMonth` | `(date, options?) => Date` | Last day of the containing Hijri month. | - -### Comparisons - -| Function | Signature | Description | -| --- | --- | --- | -| `isSameHijriMonth` | `(dateA, dateB, options?) => boolean` | Both dates in the same Hijri month. | -| `isSameHijriYear` | `(dateA, dateB, options?) => boolean` | Both dates in the same Hijri year. | - -## Calendar Systems - -Two calendar systems are available via the `options.calendar` property. - -**Umm al-Qura (default):** -The official calendar of Saudi Arabia. Covers 1318–1500 AH (1900–2076 CE). Tabular data; deterministic. - -```typescript -import { toHijriDate } from 'date-fns-hijri'; - -const uaq = toHijriDate(new Date(2023, 2, 23)); -// uses UAQ by default -``` - -**FCNA/ISNA:** -The calendar used by the Fiqh Council of North America. Astronomical calculation; extends slightly beyond UAQ's range. - -```typescript -const fcna = toHijriDate(new Date(2023, 2, 23), { calendar: 'fcna' }); -``` - -## Format Tokens - -| Token | Output | Example | -| --- | --- | --- | -| `iYYYY` | 4-digit Hijri year | `1444` | -| `iYY` | 2-digit Hijri year | `44` | -| `iMMMM` | Long month name | `Ramadan` | -| `iMMM` | Medium month name | `Ramadan` | -| `iMM` | Zero-padded month | `09` | -| `iM` | Month number | `9` | -| `iDD` | Zero-padded day | `01` | -| `iD` | Day number | `1` | -| `iEEEE` | Long weekday name | `Yawm al-Khamis` | -| `iEEE` | Short weekday name | `Kham` | -| `iE` | Numeric weekday (1=Sun) | `5` | -| `ioooo` | Long era | `AH` | -| `iooo` | Short era | `AH` | - -Non-token text in the format string passes through unchanged: - -```typescript -formatHijriDate(new Date(2023, 2, 23), 'iYYYY-iMM-iDD') -// '1444-09-01' - -formatHijriDate(new Date(2023, 2, 23), 'iD iMMMM iYYYY ioooo') +const label = formatHijriDate(new Date(2023, 2, 23, 12), 'iD iMMMM iYYYY ioooo'); // '1 Ramadan 1444 AH' + +// Add Hijri months +const eid = addHijriMonths(new Date(2023, 2, 23, 12), 1); +// Date in Shawwal 1444 + +// Get the month name +getHijriMonthName(9); // 'Ramadan' ``` -## TypeScript - -Full type definitions are included. Re-exported from `hijri-core`: - -```typescript -import type { HijriDate, ConversionOptions } from 'date-fns-hijri'; - -const h: HijriDate = { hy: 1444, hm: 9, hd: 1 }; -const opts: ConversionOptions = { calendar: 'fcna' }; -``` - -## Architecture - -A thin adapter over [hijri-core](https://github.com/acamarata/hijri-core). Each function is a stateless wrapper that delegates to the registered calendar engine. No global state, no configuration object: pass options per call. - -For more detail see the [Architecture wiki page](https://github.com/acamarata/date-fns-hijri/wiki/Architecture). - ## Documentation -Full API reference, architecture notes, and examples: [Wiki](https://github.com/acamarata/date-fns-hijri/wiki) +Full API reference, guides, and examples: **[Wiki](https://github.com/acamarata/date-fns-hijri/wiki)** + +- [API Reference](https://github.com/acamarata/date-fns-hijri/wiki/API-Reference) — all 17 functions with signatures and examples +- [Architecture](https://github.com/acamarata/date-fns-hijri/wiki/Architecture) — design decisions and hijri-core integration +- [Quick Start](https://github.com/acamarata/date-fns-hijri/wiki/guides/quickstart) ## Related -- [hijri-core](https://github.com/acamarata/hijri-core) - Zero-dependency Hijri engine powering this library -- [luxon-hijri](https://github.com/acamarata/luxon-hijri) - Hijri support for Luxon DateTime objects -- [pray-calc](https://github.com/acamarata/pray-calc) - Islamic prayer times -- [nrel-spa](https://github.com/acamarata/nrel-spa) - Solar position algorithm +- [hijri-core](https://github.com/acamarata/hijri-core) — the calendar engine powering this library +- [luxon-hijri](https://github.com/acamarata/luxon-hijri) — Hijri support for Luxon DateTime objects +- [pray-calc](https://github.com/acamarata/pray-calc) — Islamic prayer times ## Compatibility @@ -193,10 +64,6 @@ Full API reference, architecture notes, and examples: [Wiki](https://github.com/ - TypeScript definitions bundled - Works in browsers and all major bundlers -## Acknowledgments - -Calendar data and algorithms provided by [hijri-core](https://github.com/acamarata/hijri-core). The Umm al-Qura table is derived from data published by the King Abdulaziz City for Science and Technology (KACST). FCNA new moon calculations follow Jean Meeus, "Astronomical Algorithms," 2nd ed., Chapter 49. - ## License MIT. Copyright (c) 2026 Aric Camarata.