@catlabtech/mycal-core 0.1.2 → 0.1.3

package/dist/business-days.d.ts

@@ -0,0 +1,7 @@
+import type { Holiday, State, BusinessDaysResult } from "./types.js";
+export declare function countBusinessDays(start: string, end: string, state: State, holidays: readonly Holiday[]): BusinessDaysResult;
+export declare function addBusinessDays(startDate: string, daysToAdd: number, state: State, holidays: readonly Holiday[]): string;
+export declare function subtractBusinessDays(startDate: string, daysToSubtract: number, state: State, holidays: readonly Holiday[]): string;
+export declare function isBusinessDay(date: string, state: State, holidays: readonly Holiday[]): boolean;
+export declare function nextBusinessDay(date: string, state: State, holidays: readonly Holiday[]): string;
+export declare function previousBusinessDay(date: string, state: State, holidays: readonly Holiday[]): string;

package/dist/business-days.js

@@ -0,0 +1,106 @@
+import { addDays, isWeekend } from "./weekend.js";
+import { groupHolidaysByDate } from "./filter.js";
+// Hard backstop so a malformed or malicious caller cannot spin an unbounded
+// loop. The HTTP layer validates and clamps inputs before reaching here; this
+// also protects direct consumers of the library.
+const MAX_SPAN_DAYS = 366 * 100; // ~100 years
+export function countBusinessDays(start, end, state, holidays) {
+    if (start > end) {
+        throw new RangeError(`start (${start}) must be on or before end (${end})`);
+    }
+    // Index holidays by date once — O(D + H) instead of an O(H) scan per day.
+    const holidayMap = groupHolidaysByDate(holidays, state.code);
+    let businessDays = 0;
+    let weekendCount = 0;
+    let holidayCount = 0;
+    let totalDays = 0;
+    const holidayList = [];
+    const seenIds = new Set();
+    let current = start;
+    while (current <= end) {
+        if (++totalDays > MAX_SPAN_DAYS) {
+            throw new RangeError(`date range exceeds the maximum span of ${MAX_SPAN_DAYS} days`);
+        }
+        const weekend = isWeekend(current, state);
+        const dayHolidays = holidayMap.get(current);
+        if (weekend) {
+            weekendCount++;
+        }
+        else if (dayHolidays) {
+            holidayCount++;
+            for (const h of dayHolidays) {
+                if (!seenIds.has(h.id)) {
+                    seenIds.add(h.id);
+                    holidayList.push(h);
+                }
+            }
+        }
+        else {
+            businessDays++;
+        }
+        current = addDays(current, 1);
+    }
+    return {
+        totalDays,
+        businessDays,
+        holidays: holidayCount,
+        weekendDays: weekendCount,
+        holidayList,
+    };
+}
+function assertValidStep(value, label) {
+    if (!Number.isInteger(value)) {
+        throw new RangeError(`${label} must be an integer (received ${value})`);
+    }
+    if (value < 0) {
+        throw new RangeError(`${label} must be non-negative (received ${value})`);
+    }
+    if (value > MAX_SPAN_DAYS) {
+        throw new RangeError(`${label} exceeds the maximum of ${MAX_SPAN_DAYS}`);
+    }
+}
+export function addBusinessDays(startDate, daysToAdd, state, holidays) {
+    assertValidStep(daysToAdd, "daysToAdd");
+    const holidayMap = groupHolidaysByDate(holidays, state.code);
+    let remaining = daysToAdd;
+    let current = startDate;
+    let guard = 0;
+    while (remaining > 0) {
+        if (++guard > MAX_SPAN_DAYS * 2) {
+            throw new RangeError("addBusinessDays exceeded its iteration limit");
+        }
+        current = addDays(current, 1);
+        if (!isWeekend(current, state) && !holidayMap.has(current)) {
+            remaining--;
+        }
+    }
+    return current;
+}
+export function subtractBusinessDays(startDate, daysToSubtract, state, holidays) {
+    assertValidStep(daysToSubtract, "daysToSubtract");
+    const holidayMap = groupHolidaysByDate(holidays, state.code);
+    let remaining = daysToSubtract;
+    let current = startDate;
+    let guard = 0;
+    while (remaining > 0) {
+        if (++guard > MAX_SPAN_DAYS * 2) {
+            throw new RangeError("subtractBusinessDays exceeded its iteration limit");
+        }
+        current = addDays(current, -1);
+        if (!isWeekend(current, state) && !holidayMap.has(current)) {
+            remaining--;
+        }
+    }
+    return current;
+}
+export function isBusinessDay(date, state, holidays) {
+    if (isWeekend(date, state))
+        return false;
+    return !groupHolidaysByDate(holidays, state.code).has(date);
+}
+export function nextBusinessDay(date, state, holidays) {
+    return addBusinessDays(date, 1, state, holidays);
+}
+export function previousBusinessDay(date, state, holidays) {
+    return subtractBusinessDays(date, 1, state, holidays);
+}

package/dist/filter.d.ts

@@ -0,0 +1,18 @@
+import type { Holiday, HolidayType, HolidayStatus } from "./types.js";
+export interface HolidayFilter {
+    readonly year?: number;
+    readonly month?: number;
+    readonly state?: string;
+    readonly type?: HolidayType;
+    readonly status?: HolidayStatus;
+}
+export declare function filterHolidays(holidays: readonly Holiday[], filter: HolidayFilter): readonly Holiday[];
+export declare function findHolidaysByDate(date: string, holidays: readonly Holiday[], stateCode?: string): readonly Holiday[];
+/**
+ * Index holidays by their ISO date for O(1) date lookups, skipping cancelled
+ * holidays and (when `stateCode` is given) holidays that do not apply to that
+ * state. Shared by the business-day and long-weekend scanners so they don't each
+ * re-filter the array on every day.
+ */
+export declare function groupHolidaysByDate(holidays: readonly Holiday[], stateCode?: string): Map<string, Holiday[]>;
+export declare function findNextHoliday(afterDate: string, holidays: readonly Holiday[], stateCode?: string, type?: HolidayType, limit?: number): readonly Holiday[];

package/dist/filter.js

@@ -0,0 +1,75 @@
+export function filterHolidays(holidays, filter) {
+    return holidays.filter((h) => {
+        if (filter.year !== undefined) {
+            const year = parseInt(h.date.slice(0, 4), 10);
+            if (year !== filter.year)
+                return false;
+        }
+        if (filter.month !== undefined) {
+            const month = parseInt(h.date.slice(5, 7), 10);
+            if (month !== filter.month)
+                return false;
+        }
+        if (filter.state !== undefined) {
+            if (!h.states.includes("*") && !h.states.includes(filter.state)) {
+                return false;
+            }
+        }
+        if (filter.type !== undefined && h.type !== filter.type)
+            return false;
+        if (filter.status !== undefined && h.status !== filter.status)
+            return false;
+        return true;
+    });
+}
+export function findHolidaysByDate(date, holidays, stateCode) {
+    return holidays.filter((h) => {
+        if (h.date !== date)
+            return false;
+        if (h.status === "cancelled")
+            return false;
+        if (stateCode && !h.states.includes("*") && !h.states.includes(stateCode)) {
+            return false;
+        }
+        return true;
+    });
+}
+/**
+ * Index holidays by their ISO date for O(1) date lookups, skipping cancelled
+ * holidays and (when `stateCode` is given) holidays that do not apply to that
+ * state. Shared by the business-day and long-weekend scanners so they don't each
+ * re-filter the array on every day.
+ */
+export function groupHolidaysByDate(holidays, stateCode) {
+    const map = new Map();
+    for (const h of holidays) {
+        if (h.status === "cancelled")
+            continue;
+        if (stateCode && !h.states.includes("*") && !h.states.includes(stateCode)) {
+            continue;
+        }
+        const list = map.get(h.date);
+        if (list)
+            list.push(h);
+        else
+            map.set(h.date, [h]);
+    }
+    return map;
+}
+export function findNextHoliday(afterDate, holidays, stateCode, type, limit = 1) {
+    const filtered = holidays
+        .filter((h) => {
+        if (h.date <= afterDate)
+            return false;
+        if (h.status === "cancelled")
+            return false;
+        if (stateCode && !h.states.includes("*") && !h.states.includes(stateCode)) {
+            return false;
+        }
+        if (type !== undefined && h.type !== type)
+            return false;
+        return true;
+    })
+        .sort((a, b) => a.date.localeCompare(b.date));
+    return filtered.slice(0, limit);
+}

package/dist/hijri.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Basic Hijri date utilities.
+ *
+ * Note: Hijri dates for Islamic holidays are approximate until confirmed
+ * by JAKIM rukyah (moon sighting). This module provides reference mapping
+ * only — actual dates should come from the gazette/JAKIM confirmation.
+ */
+export interface HijriMonth {
+    readonly number: number;
+    readonly nameMs: string;
+    readonly nameEn: string;
+    readonly nameAr: string;
+}
+export declare const HIJRI_MONTHS: readonly HijriMonth[];
+/**
+ * Parse a hijri date string like "1 Syawal 1447" → { day, month, year }
+ */
+export declare function parseHijriDate(hijriStr: string): {
+    day: number;
+    month: HijriMonth;
+    year: number;
+} | null;
+/**
+ * Format a hijri date for display: "1 Syawal 1447"
+ */
+export declare function formatHijriDate(day: number, monthNumber: number, year: number): string;
+/**
+ * Key Islamic holidays and their Hijri dates (fixed in the Islamic calendar).
+ * Gregorian dates shift ~11 days earlier each year.
+ */
+export declare const ISLAMIC_HOLIDAY_DATES: readonly {
+    readonly nameMs: string;
+    readonly nameEn: string;
+    readonly hijriMonth: number;
+    readonly hijriDay: number;
+}[];

package/dist/hijri.js

@@ -0,0 +1,59 @@
+/**
+ * Basic Hijri date utilities.
+ *
+ * Note: Hijri dates for Islamic holidays are approximate until confirmed
+ * by JAKIM rukyah (moon sighting). This module provides reference mapping
+ * only — actual dates should come from the gazette/JAKIM confirmation.
+ */
+export const HIJRI_MONTHS = [
+    { number: 1, nameMs: "Muharam", nameEn: "Muharram", nameAr: "محرّم" },
+    { number: 2, nameMs: "Safar", nameEn: "Safar", nameAr: "صفر" },
+    { number: 3, nameMs: "Rabiulawal", nameEn: "Rabi al-Awwal", nameAr: "ربيع الأوّل" },
+    { number: 4, nameMs: "Rabiulakhir", nameEn: "Rabi al-Thani", nameAr: "ربيع الثاني" },
+    { number: 5, nameMs: "Jamadilawal", nameEn: "Jumada al-Ula", nameAr: "جمادى الأولى" },
+    { number: 6, nameMs: "Jamadilakhir", nameEn: "Jumada al-Thani", nameAr: "جمادى الثانية" },
+    { number: 7, nameMs: "Rejab", nameEn: "Rajab", nameAr: "رجب" },
+    { number: 8, nameMs: "Syaaban", nameEn: "Sha'ban", nameAr: "شعبان" },
+    { number: 9, nameMs: "Ramadan", nameEn: "Ramadan", nameAr: "رمضان" },
+    { number: 10, nameMs: "Syawal", nameEn: "Shawwal", nameAr: "شوّال" },
+    { number: 11, nameMs: "Zulkaedah", nameEn: "Dhu al-Qi'dah", nameAr: "ذو القعدة" },
+    { number: 12, nameMs: "Zulhijjah", nameEn: "Dhu al-Hijjah", nameAr: "ذو الحجّة" },
+];
+/**
+ * Parse a hijri date string like "1 Syawal 1447" → { day, month, year }
+ */
+export function parseHijriDate(hijriStr) {
+    const match = hijriStr.match(/^(\d+)\s+(.+?)\s+(\d+)$/);
+    if (!match)
+        return null;
+    const day = parseInt(match[1], 10);
+    const monthName = match[2].toLowerCase();
+    const year = parseInt(match[3], 10);
+    const month = HIJRI_MONTHS.find((m) => m.nameMs.toLowerCase() === monthName ||
+        m.nameEn.toLowerCase() === monthName);
+    if (!month)
+        return null;
+    return { day, month, year };
+}
+/**
+ * Format a hijri date for display: "1 Syawal 1447"
+ */
+export function formatHijriDate(day, monthNumber, year) {
+    const month = HIJRI_MONTHS.find((m) => m.number === monthNumber);
+    if (!month)
+        return `${day} ? ${year}`;
+    return `${day} ${month.nameMs} ${year}`;
+}
+/**
+ * Key Islamic holidays and their Hijri dates (fixed in the Islamic calendar).
+ * Gregorian dates shift ~11 days earlier each year.
+ */
+export const ISLAMIC_HOLIDAY_DATES = [
+    { nameMs: "Awal Muharam", nameEn: "Islamic New Year", hijriMonth: 1, hijriDay: 1 },
+    { nameMs: "Maulidur Rasul", nameEn: "Prophet Muhammad's Birthday", hijriMonth: 3, hijriDay: 12 },
+    { nameMs: "Israk dan Mikraj", nameEn: "Isra' Mi'raj", hijriMonth: 7, hijriDay: 27 },
+    { nameMs: "Nuzul Al-Quran", nameEn: "Revelation of the Quran", hijriMonth: 9, hijriDay: 17 },
+    { nameMs: "Hari Raya Aidilfitri", nameEn: "Eid al-Fitr", hijriMonth: 10, hijriDay: 1 },
+    { nameMs: "Hari Raya Haji", nameEn: "Eid al-Adha", hijriMonth: 12, hijriDay: 10 },
+    { nameMs: "Hari Arafah", nameEn: "Day of Arafah", hijriMonth: 12, hijriDay: 9 },
+];

package/dist/ical.d.ts

@@ -0,0 +1,2 @@
+import type { Holiday, SchoolHoliday } from "./types.js";
+export declare function generateIcal(holidays: readonly Holiday[], schoolHolidays: readonly SchoolHoliday[], calendarName: string, calendarDescription?: string): string;

package/dist/ical.js

@@ -0,0 +1,90 @@
+function escapeIcal(text) {
+    // RFC 5545 §3.3.11: escape backslash, semicolon and comma, then fold every
+    // newline form (CRLF, lone CR, lone LF) to the literal "\n" sequence so a
+    // stray carriage return cannot break the ICS line structure.
+    return text
+        .replace(/[\\;,]/g, (c) => `\\${c}`)
+        .replace(/\r\n|\r|\n/g, "\\n");
+}
+function formatIcalDate(date) {
+    return date.replace(/-/g, "");
+}
+// Machine-readable CATEGORIES (RFC 5545 §3.8.1.2) — the main thing Google's bare
+// Malaysia calendar lacks, where holiday type/scope is buried in free-text.
+function holidayCategories(h) {
+    const cats = ["Public Holiday"];
+    switch (h.type) {
+        case "federal":
+            cats.push("Federal");
+            break;
+        case "state":
+            cats.push("State");
+            break;
+        case "islamic":
+        case "islamic_state":
+            cats.push("Religious", "Islamic");
+            break;
+        case "replacement":
+            cats.push("Replacement");
+            break;
+        case "adhoc":
+            cats.push("Ad-hoc");
+            break;
+    }
+    if (h.status === "tentative")
+        cats.push("Tentative");
+    return cats.map(escapeIcal).join(",");
+}
+function holidayToVevent(h) {
+    const dtstart = formatIcalDate(h.date);
+    const dtend = h.endDate ? formatIcalDate(h.endDate) : formatIcalDate(h.date);
+    return [
+        "BEGIN:VEVENT",
+        `DTSTART;VALUE=DATE:${dtstart}`,
+        `DTEND;VALUE=DATE:${dtend}`,
+        `SUMMARY:${escapeIcal(h.name.en)}`,
+        `DESCRIPTION:${escapeIcal(h.name.ms)}${h.hijriDate ? ` (${h.hijriDate})` : ""}`,
+        `CATEGORIES:${holidayCategories(h)}`,
+        `UID:${h.id}@mycal.my`,
+        "TRANSP:TRANSPARENT",
+        `STATUS:${h.status === "tentative" ? "TENTATIVE" : "CONFIRMED"}`,
+        "END:VEVENT",
+    ].join("\r\n");
+}
+function schoolHolidayToVevent(h) {
+    return [
+        "BEGIN:VEVENT",
+        `DTSTART;VALUE=DATE:${formatIcalDate(h.startDate)}`,
+        `DTEND;VALUE=DATE:${formatIcalDate(h.endDate)}`,
+        `SUMMARY:[School] ${escapeIcal(h.name.en)}`,
+        `DESCRIPTION:${escapeIcal(h.name.ms)}`,
+        "CATEGORIES:School Holiday",
+        `UID:${h.id}@mycal.my`,
+        "TRANSP:TRANSPARENT",
+        "STATUS:CONFIRMED",
+        "END:VEVENT",
+    ].join("\r\n");
+}
+export function generateIcal(holidays, schoolHolidays, calendarName, calendarDescription = "Malaysian public holidays and school calendar — mycal.my") {
+    const header = [
+        "BEGIN:VCALENDAR",
+        "VERSION:2.0",
+        "PRODID:-//MyCal//Malaysia Calendar API//EN",
+        `X-WR-CALNAME:${escapeIcal(calendarName)}`,
+        `NAME:${escapeIcal(calendarName)}`, // RFC 7986
+        `X-WR-CALDESC:${escapeIcal(calendarDescription)}`,
+        `DESCRIPTION:${escapeIcal(calendarDescription)}`, // RFC 7986
+        "X-WR-TIMEZONE:Asia/Kuala_Lumpur",
+        "COLOR:forestgreen", // RFC 7986 (CSS3 colour name)
+        "X-APPLE-CALENDAR-COLOR:#22C55E",
+        "CALSCALE:GREGORIAN",
+        "METHOD:PUBLISH",
+        "REFRESH-INTERVAL;VALUE=DURATION:PT6H",
+        "X-PUBLISHED-TTL:PT6H",
+    ].join("\r\n");
+    const events = [
+        ...holidays.filter((h) => h.status !== "cancelled").map(holidayToVevent),
+        ...schoolHolidays.map(schoolHolidayToVevent),
+    ].join("\r\n");
+    return `${header}\r\n${events}\r\nEND:VCALENDAR\r\n`;
+}