@timestamp-js/calendar-islamic 0.1.0-rc.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jeff Galbraith
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,46 @@
+# @timestamp-js/calendar-islamic
+
+Islamic/Hijri calendar adapters for `@timestamp-js/core`.
+
+The initial adapter is `islamicCivilCalendar`, a deterministic tabular Islamic civil/Hijri calendar.
+It does not model observational Hijri calendars or Umm al-Qura adjustments.
+
+```ts
+import {
+  createCalendarDayList,
+  getCalendarEndOfMonth,
+  getCalendarEndOfWeek,
+  getCalendarStartOfMonth,
+  getCalendarStartOfWeek,
+  gregorianCalendar,
+  parseCalendarTimestamp,
+} from '@timestamp-js/core'
+import { islamicCivilCalendar } from '@timestamp-js/calendar-islamic'
+
+const ramadan = { year: 1445, month: 9, day: 1 }
+const gregorian = gregorianCalendar.fromEpochDay(islamicCivilCalendar.toEpochDay(ramadan))
+
+gregorian // { year: 2024, month: 3, day: 11 }
+
+const visible = parseCalendarTimestamp('1445-09-15', islamicCivilCalendar)!
+const weekdays = [0, 1, 2, 3, 4, 5, 6]
+
+const weekStart = getCalendarStartOfWeek(visible, weekdays, islamicCivilCalendar)
+const weekEnd = getCalendarEndOfWeek(visible, weekdays, islamicCivilCalendar)
+const weekDays = createCalendarDayList(weekStart, weekEnd, visible, islamicCivilCalendar)
+
+weekStart.date // '1445-09-14'
+weekEnd.date // '1445-09-20'
+weekDays.length // 7
+
+const monthStart = getCalendarStartOfMonth(visible, islamicCivilCalendar)
+const monthEnd = getCalendarEndOfMonth(visible, islamicCivilCalendar)
+const monthDays = createCalendarDayList(monthStart, monthEnd, visible, islamicCivilCalendar)
+
+monthStart.date // '1445-09-01'
+monthEnd.date // '1445-09-30'
+monthDays.length // 30
+```
+
+This package is early calendar-adapter work. Treat the adapter contract as release-candidate API
+until `@timestamp-js/core` reaches a stable `1.0.0`.

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+import type { CalendarSystem } from '@timestamp-js/core';
+/**
+ * Returns true when a tabular Islamic civil year is a leap year.
+ *
+ * @param year Islamic civil year number.
+ * @returns True when the year contains a leap day in Dhu al-Hijjah.
+ * @category calendar
+ */
+export declare function isIslamicCivilLeapYear(year: number): boolean;
+/**
+ * Returns days in a tabular Islamic civil month.
+ *
+ * @param year Islamic civil year number.
+ * @param month Islamic civil month number, where Muharram is `1`.
+ * @returns Number of days in the month, or `0` for an invalid month number.
+ * @category calendar
+ */
+export declare function islamicCivilDaysInMonth(year: number, month: number): number;
+/**
+ * Deterministic tabular Islamic civil calendar.
+ *
+ * This adapter intentionally models the arithmetic/civil Hijri calendar. It
+ * does not model observational calendars or Umm al-Qura adjustments.
+ */
+export declare const islamicCivilCalendar: CalendarSystem;
+/**
+ * Alias for the default Islamic adapter exported by this package.
+ */
+export declare const islamicCalendar: CalendarSystem;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAqB,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAoB3E;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAG5D;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAY3E;AAED;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,EAAE,cA0EjC,CAAA;AAEF;;GAEG;AACH,eAAO,MAAM,eAAe,gBAAuB,CAAA"}

package/dist/index.js

@@ -0,0 +1,113 @@
+import { gregorianCalendar } from '@timestamp-js/core';
+const ISLAMIC_EPOCH_DAY = gregorianCalendar.toEpochDay({ year: 622, month: 7, day: 19 });
+const MONTHS_IN_YEAR = 12;
+function assertPositiveYear(year) {
+    if (year < 1) {
+        throw new RangeError('Islamic calendar years start at 1 AH.');
+    }
+}
+function daysBeforeYear(year) {
+    assertPositiveYear(year);
+    return (year - 1) * 354 + Math.floor((3 + 11 * year) / 30);
+}
+function daysBeforeMonth(month) {
+    return Math.ceil(29.5 * (month - 1));
+}
+/**
+ * Returns true when a tabular Islamic civil year is a leap year.
+ *
+ * @param year Islamic civil year number.
+ * @returns True when the year contains a leap day in Dhu al-Hijjah.
+ * @category calendar
+ */
+export function isIslamicCivilLeapYear(year) {
+    assertPositiveYear(year);
+    return (11 * year + 14) % 30 < 11;
+}
+/**
+ * Returns days in a tabular Islamic civil month.
+ *
+ * @param year Islamic civil year number.
+ * @param month Islamic civil month number, where Muharram is `1`.
+ * @returns Number of days in the month, or `0` for an invalid month number.
+ * @category calendar
+ */
+export function islamicCivilDaysInMonth(year, month) {
+    assertPositiveYear(year);
+    if (month < 1 || month > MONTHS_IN_YEAR) {
+        return 0;
+    }
+    if (month === 12 && isIslamicCivilLeapYear(year) === true) {
+        return 30;
+    }
+    return month % 2 === 1 ? 30 : 29;
+}
+/**
+ * Deterministic tabular Islamic civil calendar.
+ *
+ * This adapter intentionally models the arithmetic/civil Hijri calendar. It
+ * does not model observational calendars or Umm al-Qura adjustments.
+ */
+export const islamicCivilCalendar = Object.freeze({
+    id: 'islamic-civil',
+    intlCalendar: 'islamic-civil',
+    label: 'Islamic Civil',
+    monthsInYear() {
+        return MONTHS_IN_YEAR;
+    },
+    isLeapYear(year) {
+        return isIslamicCivilLeapYear(year);
+    },
+    daysInMonth(year, month) {
+        return islamicCivilDaysInMonth(year, month);
+    },
+    toEpochDay(date) {
+        assertPositiveYear(date.year);
+        return (ISLAMIC_EPOCH_DAY + daysBeforeYear(date.year) + daysBeforeMonth(date.month) + date.day - 1);
+    },
+    fromEpochDay(epochDay) {
+        const days = epochDay - ISLAMIC_EPOCH_DAY;
+        let year = Math.floor((30 * days + 10646) / 10631);
+        while (year > 1 && this.toEpochDay({ year, month: 1, day: 1 }) > epochDay) {
+            year -= 1;
+        }
+        while (this.toEpochDay({ year: year + 1, month: 1, day: 1 }) <= epochDay) {
+            year += 1;
+        }
+        let dayOfYear = epochDay - this.toEpochDay({ year, month: 1, day: 1 });
+        let month = 1;
+        while (month < MONTHS_IN_YEAR) {
+            const daysInCurrentMonth = this.daysInMonth(year, month);
+            if (dayOfYear < daysInCurrentMonth) {
+                break;
+            }
+            dayOfYear -= daysInCurrentMonth;
+            month += 1;
+        }
+        return {
+            year,
+            month,
+            day: dayOfYear + 1,
+        };
+    },
+    addDays(date, amount) {
+        return this.fromEpochDay(this.toEpochDay(date) + amount);
+    },
+    nextDay(date) {
+        return this.addDays(date, 1);
+    },
+    prevDay(date) {
+        return this.addDays(date, -1);
+    },
+    getDayOfYear(date) {
+        return this.toEpochDay(date) - this.toEpochDay({ year: date.year, month: 1, day: 1 }) + 1;
+    },
+    getWeekday(date) {
+        return gregorianCalendar.getWeekday(gregorianCalendar.fromEpochDay(this.toEpochDay(date)));
+    },
+});
+/**
+ * Alias for the default Islamic adapter exported by this package.
+ */
+export const islamicCalendar = islamicCivilCalendar;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@timestamp-js/calendar-islamic",
+  "version": "0.1.0-rc.1",
+  "description": "Islamic/Hijri calendar adapters for Timestamp.",
+  "keywords": [
+    "calendar",
+    "date",
+    "hijri",
+    "islamic",
+    "timestamp",
+    "typescript"
+  ],
+  "homepage": "https://github.com/hawkeye64/timestamp#readme",
+  "bugs": {
+    "url": "https://github.com/hawkeye64/timestamp/issues"
+  },
+  "license": "MIT",
+  "author": "Jeff <galbraith64@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hawkeye64/timestamp.git"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@timestamp-js/core": "0.1.0-rc.1"
+  },
+  "devDependencies": {
+    "@types/node": "26.0.1",
+    "oxfmt": "0.56.0",
+    "oxlint": "1.71.0",
+    "typescript": "6.0.3",
+    "vitest": "4.1.9"
+  },
+  "engines": {
+    "node": ">=22.13",
+    "pnpm": ">=11.5.0"
+  },
+  "scripts": {
+    "clean": "rm -rf dist node_modules",
+    "prebuild": "pnpm --filter @timestamp-js/core build",
+    "build": "tsc -p tsconfig.build.json",
+    "format": "oxfmt",
+    "format:check": "oxfmt --check",
+    "lint": "oxlint",
+    "lint:fix": "oxlint --fix",
+    "pretest": "pnpm --filter @timestamp-js/core build",
+    "test": "vitest run",
+    "pretypecheck": "pnpm --filter @timestamp-js/core build",
+    "typecheck": "tsc -p tsconfig.build.json --noEmit",
+    "verify": "pnpm format:check && pnpm lint && pnpm typecheck && pnpm test && pnpm build"
+  }
+}