@fineanmol/holiday-optimizer 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fineanmol
+
+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,109 @@
+# Holiday Optimizer 🏖️
+
+Optimize your vacation days using Dynamic Programming! Maximize your total days off by strategically placing breaks around weekends and public holidays.
+
+**Live Demo:** [Try it here](https://fineanmol.github.io/holiday-optimizer/)
+
+## Install (npm)
+
+```bash
+npm install @fineanmol/holiday-optimizer
+```
+
+```javascript
+import { optimize, formatReport, getPreset } from "@fineanmol/holiday-optimizer";
+
+const params = getPreset("germany");
+const result = optimize(params);
+console.log(formatReport(result, params));
+```
+
+## What It Does
+
+This tool helps you plan your vacations optimally. Given:
+
+- Your total paid leave days
+- Public holidays in your country
+- Your preferences (minimum/maximum break length, spacing between breaks)
+
+It finds the best schedule that maximizes your total days off by leveraging weekends and holidays.
+
+## Features
+
+- 🎯 **Dynamic Programming Algorithm** - Finds optimal vacation schedule
+- 🌍 **Multi-Country Support** - Pre-configured holidays for Germany and India (easily extensible)
+- ⚙️ **Customizable Constraints** - Set your own min/max break lengths and spacing
+- 📊 **Detailed Reports** - See exactly which dates to take off and how many days you'll get
+- 💻 **Zero Server Cost** - Runs entirely in the browser using GitHub Pages
+
+## How It Works
+
+The optimizer uses three key techniques:
+
+1. **Dominance Pruning** - For each starting day, keeps only the most efficient break options
+2. **Binary Search** - Efficiently finds next valid break that satisfies spacing constraints
+3. **Dynamic Programming** - Optimizes for maximum total days off within your constraints
+
+## Usage
+
+1. Select your country from the dropdown
+2. Set your preferences:
+   - Year to optimize
+   - Start date
+   - Total paid leave days
+   - Minimum break length (days)
+   - Maximum break length (days)
+   - Time between breaks (days)
+3. Click "Calculate Optimal Schedule"
+4. Review your optimized vacation plan!
+
+## Example
+
+With **19 paid leave days** and default settings:
+
+- **Result:** ~52 total days off
+- **Breaks:** ~12 breaks throughout the year
+- **Distribution:** Approximately 1 break per month
+
+## Adding New Countries
+
+To add holidays for a new country, edit `country-presets.js`:
+
+```javascript
+newCountry: {
+  name: "Country Name",
+  year: 2026,
+  defaultPTO: 10,
+  holidays: [
+    { date: "2026-01-01", name: "New Year's Day" },
+    // ... more holidays
+  ]
+}
+```
+
+The country will automatically appear in the dropdown!
+
+## Algorithm Details
+
+- **Time Complexity:** O(n × m × P) where n = candidates, m = max break length, P = PTO days
+- **Space Complexity:** O(n × P) for DP table
+- **Optimization Goal:** Maximize total days off (including weekends and holidays)
+
+## Tech Stack
+
+- Pure JavaScript (ES6 modules)
+- No dependencies
+- Works in all modern browsers
+- GitHub Pages compatible
+
+## Inspiration
+
+Inspired by [Ankit's vacation optimizer](https://gist.github.com/ag5826000/478d3607df0eff50278d57429f2308e9) - converted from Python to JavaScript for browser deployment.
+
+## License
+
+MIT License - feel free to use and modify!
+
+---
+
+**Made with ❤️ to help you maximize your vacation time!**

package/country-presets.js

@@ -0,0 +1,104 @@
+export const countryPresets = {
+  germany: {
+    name: "Germany (Berlin)",
+    year: 2026,
+    defaultPTO: 19,
+    holidays: [
+      { date: "2026-01-01", name: "Neujahr" },
+      { date: "2026-03-08", name: "Internationaler Frauentag (Berlin)" },
+      { date: "2026-04-03", name: "Karfreitag" },
+      { date: "2026-04-06", name: "Ostermontag" },
+      { date: "2026-05-01", name: "Tag der Arbeit" },
+      { date: "2026-05-14", name: "Christi Himmelfahrt" },
+      { date: "2026-05-25", name: "Pfingstmontag" },
+      { date: "2026-10-03", name: "Tag der Deutschen Einheit" },
+      { date: "2026-10-31", name: "Reformationstag (Berlin)" },
+      { date: "2026-12-25", name: "1. Weihnachtstag" },
+      { date: "2026-12-26", name: "2. Weihnachtstag" },
+    ],
+  },
+
+  india: {
+    name: "India",
+    year: 2026,
+    defaultPTO: 10,
+    holidays: [
+      { date: "2026-01-26", name: "Republic Day" },
+      { date: "2026-03-08", name: "Holi" },
+      { date: "2026-03-29", name: "Good Friday" },
+      { date: "2026-04-14", name: "Ambedkar Jayanti" },
+      { date: "2026-04-17", name: "Ram Navami" },
+      { date: "2026-05-01", name: "Labour Day" },
+      { date: "2026-06-17", name: "Eid ul-Fitr" },
+      { date: "2026-08-15", name: "Independence Day" },
+      { date: "2026-08-26", name: "Raksha Bandhan" },
+      { date: "2026-09-05", name: "Janmashtami" },
+      { date: "2026-10-02", name: "Gandhi Jayanti" },
+      { date: "2026-10-12", name: "Dussehra" },
+      { date: "2026-10-20", name: "Eid ul-Adha" },
+      { date: "2026-10-29", name: "Diwali" },
+      { date: "2026-11-14", name: "Guru Nanak Jayanti" },
+      { date: "2026-12-25", name: "Christmas" },
+    ],
+  },
+};
+
+/**
+ * Get all available country keys
+ * @returns {string[]} Array of country keys
+ */
+export function getAvailableCountries() {
+  return Object.keys(countryPresets);
+}
+
+/**
+ * Get country information (name, key pairs)
+ * @returns {Array<{key: string, name: string}>} Array of country info objects
+ */
+export function getCountryList() {
+  return Object.entries(countryPresets).map(([key, preset]) => ({
+    key,
+    name: preset.name,
+  }));
+}
+
+/**
+ * Get preset configuration for a country
+ * @param {string} countryKey - Key from countryPresets (e.g., 'germany', 'india')
+ * @param {number} customPTO - Optional custom PTO days (overrides default)
+ * @param {number} customYear - Optional custom year (overrides preset year)
+ * @returns {Object} Configuration object ready for optimizer
+ */
+export function getPreset(countryKey, customPTO = null, customYear = null) {
+  const preset = countryPresets[countryKey];
+  if (!preset) {
+    throw new Error(
+      `Unknown country preset: ${countryKey}. Available: ${getAvailableCountries().join(
+        ", "
+      )}`
+    );
+  }
+
+  const year = customYear ?? preset.year;
+
+  const holidays = preset.holidays.filter((h) => {
+    const holidayYear = parseInt(h.date.split("-")[0]);
+    return holidayYear === year;
+  });
+
+  return {
+    numberOfDays: customPTO ?? preset.defaultPTO,
+    year: year,
+    holidays: holidays,
+    companyDaysOff: [],
+  };
+}
+
+/**
+ * Check if a country preset exists
+ * @param {string} countryKey - Key to check
+ * @returns {boolean} True if preset exists
+ */
+export function hasPreset(countryKey) {
+  return countryKey in countryPresets;
+}

package/index.js

@@ -0,0 +1,8 @@
+export { optimize, formatReport } from "./vacation_optimizer.js";
+export {
+  countryPresets,
+  getAvailableCountries,
+  getCountryList,
+  getPreset,
+  hasPreset,
+} from "./country-presets.js";

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@fineanmol/holiday-optimizer",
+  "version": "1.0.0",
+  "description": "Optimize vacation days using dynamic programming — maximize time off around weekends and public holidays.",
+  "type": "module",
+  "main": "./index.js",
+  "exports": {
+    ".": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "vacation_optimizer.js",
+    "country-presets.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "vacation",
+    "pto",
+    "holiday",
+    "optimizer",
+    "planning",
+    "calendar",
+    "leave"
+  ],
+  "author": "fineanmol",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fineanmol/holiday-optimizer.git"
+  },
+  "bugs": {
+    "url": "https://github.com/fineanmol/holiday-optimizer/issues"
+  },
+  "homepage": "https://github.com/fineanmol/holiday-optimizer#readme",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/vacation_optimizer.js

@@ -0,0 +1,427 @@
+class Day {
+  constructor({ date, isWeekend, isPublicHoliday, isCompanyDay }) {
+    this.date = date;
+    this.is_weekend = isWeekend;
+    this.is_public_holiday = isPublicHoliday;
+    this.is_company_day = isCompanyDay;
+
+    this.is_pto = false;
+    this.is_part_of_break = false;
+  }
+}
+
+class Break {
+  constructor({
+    start_date,
+    end_date,
+    total_days,
+    pto_days,
+    weekends,
+    public_holidays,
+    company_days,
+    days,
+  }) {
+    this.start_date = start_date;
+    this.end_date = end_date;
+    this.total_days = total_days;
+    this.pto_days = pto_days;
+    this.weekends = weekends;
+    this.public_holidays = public_holidays;
+    this.company_days = company_days;
+    this.days = days;
+  }
+}
+
+class Stats {
+  constructor({
+    total_days_off,
+    total_paid_leave,
+    total_public_holidays,
+    total_weekends,
+    total_company_days,
+  }) {
+    this.total_days_off = total_days_off;
+    this.total_paid_leave = total_paid_leave;
+    this.total_public_holidays = total_public_holidays;
+    this.total_weekends = total_weekends;
+    this.total_company_days = total_company_days;
+  }
+}
+
+class Result {
+  constructor({ days, breaks, stats }) {
+    this.days = days;
+    this.breaks = breaks;
+    this.stats = stats;
+  }
+}
+
+function pad2(n) {
+  return String(n).padStart(2, "0");
+}
+
+function formatDate(d) {
+  const y = d.getFullYear();
+  const m = pad2(d.getMonth() + 1);
+  const day = pad2(d.getDate());
+  return `${y}-${m}-${day}`;
+}
+
+function parseISO(iso) {
+  const [y, m, d] = iso.split("-").map(Number);
+  return new Date(y, m - 1, d);
+}
+
+function addDays(d, n) {
+  const copy = new Date(d.getTime());
+  copy.setDate(copy.getDate() + n);
+  return copy;
+}
+
+function compareISO(a, b) {
+  if (a < b) return -1;
+  if (a > b) return 1;
+  return 0;
+}
+
+function isFixedOff(day) {
+  return day.is_weekend || day.is_public_holiday || day.is_company_day;
+}
+
+function buildCalendar(params) {
+  const yr = params.year ?? new Date().getFullYear();
+  const today = new Date();
+
+  let start;
+  if (params.startDate) {
+    start = parseISO(params.startDate);
+  } else {
+    start =
+      yr === today.getFullYear()
+        ? new Date(today.getFullYear(), today.getMonth(), today.getDate())
+        : new Date(yr, 0, 1);
+  }
+  const end = new Date(yr, 11, 31);
+
+  const holidays = new Set((params.holidays ?? []).map((h) => h.date));
+  const company = new Set((params.companyDaysOff ?? []).map((c) => c.date));
+
+  const days = [];
+  let d = start;
+
+  while (d <= end) {
+    const ds = formatDate(d);
+    const weekday = d.getDay();
+    const isWeekend = weekday === 0 || weekday === 6;
+
+    days.push(
+      new Day({
+        date: ds,
+        isWeekend,
+        isPublicHoliday: holidays.has(ds),
+        isCompanyDay: company.has(ds),
+      })
+    );
+
+    d = addDays(d, 1);
+  }
+
+  return days;
+}
+
+function generateCandidates(cal, minLen, maxLen) {
+  const candidates = [];
+  const n = cal.length;
+
+  for (let i = 0; i < n; i++) {
+    for (let L = minLen; L <= maxLen; L++) {
+      if (i + L > n) break;
+      const seg = cal.slice(i, i + L);
+      const ptoUsed = seg.reduce((acc, d) => acc + (isFixedOff(d) ? 0 : 1), 0);
+      if (ptoUsed === 0) continue;
+
+      candidates.push({
+        start_idx: i,
+        end_idx: i + L - 1,
+        total_days: L,
+        pto_used: ptoUsed,
+        eff: L / ptoUsed,
+        segment: seg,
+      });
+    }
+  }
+
+  return candidates;
+}
+
+function pruneCandidates(cands, maxPTO) {
+  cands = cands.filter((c) => c.pto_used <= maxPTO);
+
+  const byStart = new Map();
+  for (const c of cands) {
+    if (!byStart.has(c.start_idx)) byStart.set(c.start_idx, []);
+    byStart.get(c.start_idx).push(c);
+  }
+
+  const pruned = [];
+  for (const [start, items] of byStart.entries()) {
+    items.sort(
+      (a, b) => a.pto_used - b.pto_used || b.total_days - a.total_days
+    );
+
+    const best = [];
+    for (const cand of items) {
+      const dominated = best.some(
+        (b) =>
+          b.end_idx >= cand.end_idx &&
+          b.pto_used <= cand.pto_used &&
+          b.total_days >= cand.total_days
+      );
+      if (!dominated) best.push(cand);
+    }
+    pruned.push(...best);
+  }
+
+  pruned.sort((a, b) => a.start_idx - b.start_idx);
+  return pruned;
+}
+
+function binarySearchNext(cands, startPos) {
+  let lo = 0;
+  let hi = cands.length;
+  while (lo < hi) {
+    const mid = Math.floor((lo + hi) / 2);
+    if (cands[mid].start_idx < startPos) lo = mid + 1;
+    else hi = mid;
+  }
+  return lo;
+}
+
+function dpSelect(cands, maxPTO, spacing) {
+  if (!cands.length || maxPTO <= 0) return [];
+
+  const nextIndices = cands.map((c) =>
+    binarySearchNext(cands, c.end_idx + 1 + spacing)
+  );
+  const n = cands.length;
+
+  const dpDays = Array.from({ length: n + 1 }, () => Array(maxPTO + 1).fill(0));
+  const dpChoice = Array.from({ length: n + 1 }, () =>
+    Array.from({ length: maxPTO + 1 }, () => [])
+  );
+
+  for (let idx = n - 1; idx >= 0; idx--) {
+    const cand = cands[idx];
+    const cost = cand.pto_used;
+    const totalDays = cand.total_days;
+    const jump = nextIndices[idx];
+
+    for (let p = 0; p <= maxPTO; p++) {
+      let bestDays = dpDays[idx + 1][p];
+      let bestChoice = dpChoice[idx + 1][p];
+
+      if (cost <= p) {
+        const takeDays = totalDays + dpDays[jump][p - cost];
+        if (takeDays > bestDays) {
+          bestDays = takeDays;
+          bestChoice = [idx, ...dpChoice[jump][p - cost]];
+        }
+      }
+
+      dpDays[idx][p] = bestDays;
+      dpChoice[idx][p] = bestChoice;
+    }
+  }
+
+  const choice = dpChoice[0][maxPTO];
+  return choice.map((i) => cands[i]);
+}
+
+function forceExtend(cal, breaks, remaining) {
+  if (remaining <= 0) return remaining;
+
+  for (const br of breaks) {
+    const endDate = parseISO(br.end_date);
+    const nextDay = addDays(endDate, 1);
+    const nextISO = formatDate(nextDay);
+
+    const idx = cal.findIndex((d) => d.date === nextISO);
+    if (
+      idx !== -1 &&
+      remaining > 0 &&
+      !cal[idx].is_part_of_break &&
+      !isFixedOff(cal[idx])
+    ) {
+      cal[idx].is_part_of_break = true;
+      cal[idx].is_pto = true;
+
+      br.days.push(cal[idx]);
+      br.end_date = cal[idx].date;
+      br.total_days += 1;
+      br.pto_days += 1;
+      remaining -= 1;
+    }
+  }
+  return remaining;
+}
+
+function addForcedSegments(cal, remaining) {
+  const forced = [];
+  let i = 0;
+  const n = cal.length;
+
+  while (i < n && remaining > 0) {
+    if (cal[i].is_part_of_break || isFixedOff(cal[i])) {
+      i++;
+      continue;
+    }
+
+    const seg = [];
+    while (
+      i < n &&
+      remaining > 0 &&
+      !cal[i].is_part_of_break &&
+      !isFixedOff(cal[i])
+    ) {
+      cal[i].is_part_of_break = true;
+      cal[i].is_pto = true;
+      seg.push(cal[i]);
+      remaining--;
+      i++;
+    }
+
+    if (seg.length) {
+      forced.push(
+        new Break({
+          start_date: seg[0].date,
+          end_date: seg[seg.length - 1].date,
+          total_days: seg.length,
+          pto_days: seg.length,
+          weekends: seg.filter((d) => d.is_weekend).length,
+          public_holidays: seg.filter((d) => d.is_public_holiday).length,
+          company_days: seg.filter((d) => d.is_company_day).length,
+          days: seg,
+        })
+      );
+    }
+
+    i++;
+  }
+
+  return forced;
+}
+
+function optimize(params) {
+  const maxPTO = Number(params.numberOfDays);
+  const minLen = params.minBreak ?? 4;
+  const maxLen = params.maxBreak ?? 9;
+  const spacing = params.timeBetweenBreaks ?? 21;
+
+  const cal = buildCalendar(params);
+  let candidates = generateCandidates(cal, minLen, maxLen);
+  candidates = pruneCandidates(candidates, maxPTO);
+
+  const chosen = dpSelect(candidates, maxPTO, spacing);
+
+  const breaks = [];
+  for (const seg of chosen) {
+    for (let idx = seg.start_idx; idx <= seg.end_idx; idx++) {
+      cal[idx].is_part_of_break = true;
+      if (!isFixedOff(cal[idx])) cal[idx].is_pto = true;
+    }
+
+    const segmentDays = seg.segment;
+    breaks.push(
+      new Break({
+        start_date: segmentDays[0].date,
+        end_date: segmentDays[segmentDays.length - 1].date,
+        total_days: seg.total_days,
+        pto_days: seg.pto_used,
+        weekends: segmentDays.filter((d) => d.is_weekend).length,
+        public_holidays: segmentDays.filter((d) => d.is_public_holiday).length,
+        company_days: segmentDays.filter((d) => d.is_company_day).length,
+        days: [...segmentDays],
+      })
+    );
+  }
+
+  let usedPTO = breaks.reduce((acc, b) => acc + b.pto_days, 0);
+  let remaining = maxPTO - usedPTO;
+
+  let prevRemaining = remaining + 1;
+  while (remaining > 0 && remaining < prevRemaining) {
+    prevRemaining = remaining;
+    remaining = forceExtend(cal, breaks, remaining);
+
+    const extra = addForcedSegments(cal, remaining);
+    breaks.push(...extra);
+
+    usedPTO = breaks.reduce((acc, b) => acc + b.pto_days, 0);
+    remaining = maxPTO - usedPTO;
+  }
+
+  const stats = new Stats({
+    total_days_off: breaks.reduce((acc, b) => acc + b.total_days, 0),
+    total_paid_leave: breaks.reduce((acc, b) => acc + b.pto_days, 0),
+    total_public_holidays: breaks.reduce(
+      (acc, b) => acc + b.public_holidays,
+      0
+    ),
+    total_weekends: breaks.reduce((acc, b) => acc + b.weekends, 0),
+    total_company_days: breaks.reduce((acc, b) => acc + b.company_days, 0),
+  });
+
+  return new Result({ days: cal, breaks, stats });
+}
+
+function formatReport(res, params) {
+  const lines = [];
+  lines.push("Holiday Optimizer Report (JavaScript)");
+  lines.push("=====================================");
+  lines.push(`Year: ${params.year ?? new Date().getFullYear()}`);
+  lines.push(`Requested Paid Leave Days: ${params.numberOfDays}`);
+  lines.push("");
+
+  lines.push("Summary");
+  lines.push("-------");
+  lines.push(`Total Days Off: ${res.stats.total_days_off}`);
+  lines.push(`Total Paid Leave Used: ${res.stats.total_paid_leave}`);
+  lines.push(`Public Holidays in Breaks: ${res.stats.total_public_holidays}`);
+  lines.push(`Weekends in Breaks: ${res.stats.total_weekends}`);
+  if (res.stats.total_company_days > 0) {
+    lines.push(`Company Days in Breaks: ${res.stats.total_company_days}`);
+  }
+  lines.push("");
+
+  lines.push("Breaks");
+  lines.push("------");
+  if (!res.breaks.length) {
+    lines.push("No breaks were scheduled.");
+  } else {
+    res.breaks.forEach((br, idx) => {
+      const companyPart = br.company_days
+        ? ` | Company ${br.company_days}`
+        : "";
+      lines.push(`Break ${idx + 1}: ${br.start_date} → ${br.end_date}`);
+      lines.push(
+        `  • Total ${br.total_days} days | Paid Leave ${br.pto_days} | ` +
+          `Weekends ${br.weekends} | Public ${br.public_holidays}${companyPart}`
+      );
+
+      const ptoDates = br.days.filter((d) => d.is_pto).map((d) => d.date);
+      // if (ptoDates.length) {
+      //   lines.push(`  • Paid leave dates: ${ptoDates.join(", ")}`);
+      // }
+      lines.push("");
+    });
+  }
+
+  const ptoFlat = res.days.filter((d) => d.is_pto).map((d) => d.date);
+  lines.push("Paid Leave Dates (all)");
+  lines.push("----------------------");
+  lines.push(ptoFlat.length ? ptoFlat.join(", ") : "None");
+
+  return lines.join("\n");
+}
+
+export { optimize, formatReport };