@catlabtech/mycal-core 0.1.2 → 0.1.3

package/dist/long-weekend.d.ts

@@ -0,0 +1,18 @@
+import type { Holiday, State, LongWeekend, LeaveSuggestion } from "./types.js";
+/**
+ * Natural long weekends for a state in a given year: runs of 3+ consecutive
+ * non-working days (weekend days and/or public holidays) that need no leave.
+ *
+ * Shared by the REST `/holidays/long-weekends` route and the MCP server so the
+ * two cannot diverge.
+ */
+export declare function findLongWeekends(year: number, state: State, holidays: readonly Holiday[]): LongWeekend[];
+/**
+ * Leave optimizer: where can you spend up to `maxLeave` working days to chain
+ * weekends and public holidays into the longest possible continuous break?
+ *
+ * Returns suggestions sorted by efficiency (days off gained per leave day spent),
+ * then by total length. Each suggestion's `leaveDates` are the exact working days
+ * to request off — e.g. "take 2026-09-14 & 2026-09-15 → 2026-09-12…2026-09-16".
+ */
+export declare function optimizeLeave(year: number, state: State, holidays: readonly Holiday[], maxLeave?: number): LeaveSuggestion[];

package/dist/long-weekend.js

@@ -0,0 +1,127 @@
+import { addDays, diffDays, isWeekend } from "./weekend.js";
+import { groupHolidaysByDate } from "./filter.js";
+/**
+ * Natural long weekends for a state in a given year: runs of 3+ consecutive
+ * non-working days (weekend days and/or public holidays) that need no leave.
+ *
+ * Shared by the REST `/holidays/long-weekends` route and the MCP server so the
+ * two cannot diverge.
+ */
+export function findLongWeekends(year, state, holidays) {
+    const holidayMap = groupHolidaysByDate(holidays, state.code);
+    const isOff = (d) => isWeekend(d, state) || holidayMap.has(d);
+    const yearStart = `${year}-01-01`;
+    const yearEnd = `${year}-12-31`;
+    // Scan a little past both year boundaries so a run that is still "off" at
+    // Dec 31 (or already running on Jan 1) is measured in full instead of being
+    // truncated at the boundary. A run is only *reported* when it starts within
+    // the requested year, so a boundary-straddling long weekend is attributed to
+    // exactly one year and never double-counted.
+    const scanStart = addDays(yearStart, -7);
+    const scanEnd = addDays(yearEnd, 7);
+    const result = [];
+    let current = scanStart;
+    while (current <= scanEnd) {
+        if (!isOff(current)) {
+            current = addDays(current, 1);
+            continue;
+        }
+        const startDate = current;
+        const streakHolidays = [];
+        let weekendDays = 0;
+        let totalDays = 0;
+        while (current <= scanEnd && isOff(current)) {
+            if (isWeekend(current, state))
+                weekendDays++;
+            const hs = holidayMap.get(current);
+            if (hs)
+                streakHolidays.push(...hs);
+            totalDays++;
+            current = addDays(current, 1);
+        }
+        if (totalDays >= 3 && startDate >= yearStart && startDate <= yearEnd) {
+            result.push({
+                startDate,
+                endDate: addDays(current, -1),
+                totalDays,
+                holidays: streakHolidays,
+                weekendDays,
+                bridgeDaysNeeded: 0, // natural long weekend — no leave required
+            });
+        }
+    }
+    return result;
+}
+/**
+ * Leave optimizer: where can you spend up to `maxLeave` working days to chain
+ * weekends and public holidays into the longest possible continuous break?
+ *
+ * Returns suggestions sorted by efficiency (days off gained per leave day spent),
+ * then by total length. Each suggestion's `leaveDates` are the exact working days
+ * to request off — e.g. "take 2026-09-14 & 2026-09-15 → 2026-09-12…2026-09-16".
+ */
+export function optimizeLeave(year, state, holidays, maxLeave = 3) {
+    if (!Number.isInteger(maxLeave) || maxLeave < 1)
+        return [];
+    const holidayMap = groupHolidaysByDate(holidays, state.code);
+    const isOff = (d) => isWeekend(d, state) || holidayMap.has(d);
+    const yearEnd = `${year}-12-31`;
+    const suggestions = [];
+    let s = `${year}-01-01`;
+    while (s <= yearEnd) {
+        // A break starts on an off-day whose previous day is a working day.
+        if (!isOff(s) || isOff(addDays(s, -1))) {
+            s = addDays(s, 1);
+            continue;
+        }
+        let leave = 0;
+        let d = s;
+        while (d <= yearEnd) {
+            if (!isOff(d)) {
+                leave++;
+                if (leave > maxLeave)
+                    break;
+            }
+            const next = addDays(d, 1);
+            // Window [s..d] is a complete break when it ends on an off-day followed by
+            // a working day, and at least one leave day was spent inside it.
+            if (leave >= 1 && isOff(d) && !isOff(next)) {
+                const leaveDates = [];
+                const within = [];
+                let c = s;
+                while (c <= d) {
+                    if (!isOff(c))
+                        leaveDates.push(c);
+                    const hs = holidayMap.get(c);
+                    if (hs)
+                        within.push(...hs);
+                    c = addDays(c, 1);
+                }
+                const totalDays = diffDays(s, d) + 1;
+                suggestions.push({
+                    startDate: s,
+                    endDate: d,
+                    totalDays,
+                    leaveDates,
+                    leaveCost: leaveDates.length,
+                    efficiency: Math.round((totalDays / leaveDates.length) * 100) / 100,
+                    holidays: within,
+                });
+            }
+            d = next;
+        }
+        s = addDays(s, 1);
+    }
+    suggestions.sort((a, b) => b.efficiency - a.efficiency ||
+        b.totalDays - a.totalDays ||
+        a.startDate.localeCompare(b.startDate));
+    // Collapse duplicate windows (the same break can be reached from one start).
+    const seen = new Set();
+    return suggestions.filter((x) => {
+        const key = `${x.startDate}:${x.endDate}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}

package/dist/replacement.d.ts

@@ -0,0 +1,2 @@
+import type { Holiday, State } from "./types.js";
+export declare function calculateReplacementHolidays(holidays: readonly Holiday[], state: State): readonly Holiday[];

package/dist/replacement.js

@@ -0,0 +1,69 @@
+import { isWeekend, nextWorkingDay } from "./weekend.js";
+/**
+ * Build the synthetic "Cuti Ganti" (replacement) holiday for a `source` holiday
+ * that has been rolled forward to `replacementDate`. Centralised so the
+ * weekend-clash and same-day-overlap paths cannot drift apart.
+ */
+function makeReplacement(source, replacementDate, stateCode, idSuffix, now) {
+    return {
+        id: `${source.id}-${idSuffix}`,
+        date: replacementDate,
+        name: {
+            ms: `Cuti Ganti ${source.name.ms}`,
+            en: `Replacement for ${source.name.en}`,
+            zh: source.name.zh ? `补假 ${source.name.zh}` : undefined,
+        },
+        type: "replacement",
+        status: source.status,
+        states: [stateCode],
+        isPublicHoliday: true,
+        gazetteLevel: source.gazetteLevel,
+        isReplacementFor: source.id,
+        source: source.source,
+        createdAt: now,
+        updatedAt: now,
+    };
+}
+export function calculateReplacementHolidays(holidays, state) {
+    const stateHolidays = holidays.filter((h) => h.status !== "cancelled" &&
+        (h.states.includes("*") || h.states.includes(state.code)));
+    const holidayDates = new Set(stateHolidays.map((h) => h.date));
+    const replacementDates = new Set();
+    const replacements = [];
+    const now = new Date().toISOString();
+    // 1. Holidays that fall on a weekend roll forward to the next working day.
+    for (const holiday of stateHolidays) {
+        if (holiday.type === "replacement")
+            continue;
+        if (!isWeekend(holiday.date, state))
+            continue;
+        const occupied = new Set([...holidayDates, ...replacementDates]);
+        const replacementDate = nextWorkingDay(holiday.date, state, occupied);
+        replacementDates.add(replacementDate);
+        replacements.push(makeReplacement(holiday, replacementDate, state.code, "replacement", now));
+    }
+    // 2. Two holidays on the same date: the federal (gazette "P") holiday takes the
+    //    day, so the state-level (gazette "N") holiday is the one rolled forward.
+    const dateGroups = new Map();
+    for (const h of stateHolidays) {
+        if (h.type === "replacement")
+            continue;
+        const existing = dateGroups.get(h.date) ?? [];
+        dateGroups.set(h.date, [...existing, h]);
+    }
+    for (const [, group] of dateGroups) {
+        if (group.length <= 1)
+            continue;
+        const stateHoliday = group.find((h) => h.gazetteLevel === "N");
+        if (!stateHoliday)
+            continue;
+        // Skip if the weekend pass already produced a replacement for it.
+        if (replacements.some((r) => r.isReplacementFor === stateHoliday.id))
+            continue;
+        const occupied = new Set([...holidayDates, ...replacementDates]);
+        const replacementDate = nextWorkingDay(stateHoliday.date, state, occupied);
+        replacementDates.add(replacementDate);
+        replacements.push(makeReplacement(stateHoliday, replacementDate, state.code, "overlap-replacement", now));
+    }
+    return replacements;
+}