@fineanmol/public-holidays 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,65 @@
+# @fineanmol/public-holidays
+
+Small, **zero-runtime-dependency** lookups for **public holidays** bundled as versioned data. Use it in Node or any bundler that supports ES modules.
+
+**Pairs well with** [`@fineanmol/holiday-optimizer`](https://www.npmjs.com/package/@fineanmol/holiday-optimizer) for PTO planning.
+
+## Install
+
+```bash
+npm install @fineanmol/public-holidays
+```
+
+## Regions
+
+| `regionId`         | Notes |
+|--------------------|--------|
+| `germany-berlin`   | Berlin-specific days included where applicable |
+| `india`            | National / commonly observed set; **states differ** — confirm locally for payroll |
+
+Data is shipped per **calendar year** in `src/data.js` (`byYear`). Add new years as you maintain the package.
+
+## API
+
+```js
+import {
+  listRegions,
+  holidaysInYear,
+  isHoliday,
+  holidayOn,
+  nextHoliday,
+  previousHoliday,
+  toISODate,
+} from "@fineanmol/public-holidays";
+```
+
+- **`listRegions()`** — `{ id, name }[]`
+- **`holidaysInYear(regionId, year)`** — `{ date: 'YYYY-MM-DD', name }[]`
+- **`isHoliday(date, regionId)`** — `boolean` (`date`: `Date` or ISO `YYYY-MM-DD`)
+- **`holidayOn(date, regionId)`** — holiday object or `null`
+- **`nextHoliday(fromDate, regionId)`** — first holiday **on or after** `fromDate`, or `null`
+- **`previousHoliday(fromDate, regionId)`** — last holiday **on or before** `fromDate`, or `null`
+- **`toISODate(date)`** — normalize to `YYYY-MM-DD` (local calendar day for `Date`)
+
+## Example
+
+```js
+import { isHoliday, nextHoliday, holidaysInYear } from "@fineanmol/public-holidays";
+
+holidaysInYear("germany-berlin", 2026).length;
+// → 11
+
+isHoliday("2026-10-03", "germany-berlin");
+// → true
+
+nextHoliday("2026-10-02", "germany-berlin");
+// → { date: '2026-10-03', name: 'Tag der Deutschen Einheit' }
+```
+
+## Disclaimer
+
+Holiday rules change. This package is for **apps and planning**, not legal or payroll advice. Verify official sources for compliance.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@fineanmol/public-holidays",
+  "version": "1.0.0",
+  "description": "Zero-dependency public holiday lookups (Germany Berlin, India, …) with versioned yearly data.",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    }
+  },
+  "files": [
+    "src/index.js",
+    "src/index.d.ts",
+    "src/data.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "holidays",
+    "public-holidays",
+    "calendar",
+    "india",
+    "germany",
+    "berlin",
+    "bank-holiday",
+    "pto"
+  ],
+  "author": "fineanmol",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fineanmol/holiday-optimizer.git",
+    "directory": "packages/public-holidays"
+  },
+  "bugs": {
+    "url": "https://github.com/fineanmol/holiday-optimizer/issues"
+  },
+  "homepage": "https://github.com/fineanmol/holiday-optimizer/tree/main/packages/public-holidays#readme",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/data.js

@@ -0,0 +1,49 @@
+/**
+ * Versioned public-holiday tables. Extend `byYear` when you add a new calendar year.
+ * India list is a national / commonly observed set; states differ — verify locally.
+ */
+export const REGIONS = {
+  "germany-berlin": {
+    id: "germany-berlin",
+    name: "Germany (Berlin)",
+    byYear: {
+      2026: [
+        { 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: {
+    id: "india",
+    name: "India (national / commonly observed)",
+    byYear: {
+      2026: [
+        { 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" },
+      ],
+    },
+  },
+};

package/src/index.d.ts

@@ -0,0 +1,31 @@
+export type Holiday = { date: string; name: string };
+
+export type Region = {
+  id: string;
+  name: string;
+  byYear: Record<number, Holiday[]>;
+};
+
+export function toISODate(d: Date | string): string;
+
+export function listRegions(): { id: string; name: string }[];
+
+export function getRegion(regionId: string): Region | undefined;
+
+export function holidaysInYear(regionId: string, year: number): Holiday[];
+
+export function isHoliday(date: Date | string, regionId: string): boolean;
+
+export function holidayOn(date: Date | string, regionId: string): Holiday | null;
+
+export function nextHoliday(
+  fromDate: Date | string,
+  regionId: string
+): Holiday | null;
+
+export function previousHoliday(
+  fromDate: Date | string,
+  regionId: string
+): Holiday | null;
+
+export const REGIONS: Record<string, Region>;

package/src/index.js

@@ -0,0 +1,119 @@
+import { REGIONS } from "./data.js";
+
+/** @typedef {{ date: string, name: string }} Holiday */
+
+/**
+ * @param {Date | string} d
+ * @returns {string} YYYY-MM-DD (local calendar date when `Date` is used)
+ */
+export function toISODate(d) {
+  if (typeof d === "string") {
+    if (/^\d{4}-\d{2}-\d{2}$/.test(d)) return d;
+    throw new TypeError(`Expected ISO date string YYYY-MM-DD, got: ${d}`);
+  }
+  if (!(d instanceof Date) || Number.isNaN(d.getTime())) {
+    throw new TypeError("Expected a valid Date");
+  }
+  const y = d.getFullYear();
+  const m = String(d.getMonth() + 1).padStart(2, "0");
+  const day = String(d.getDate()).padStart(2, "0");
+  return `${y}-${m}-${day}`;
+}
+
+/**
+ * @returns {{ id: string, name: string }[]}
+ */
+export function listRegions() {
+  return Object.values(REGIONS).map(({ id, name }) => ({ id, name }));
+}
+
+/**
+ * @param {string} regionId
+ * @returns {{ id: string, name: string, byYear: Record<number, Holiday[]> } | undefined}
+ */
+export function getRegion(regionId) {
+  return REGIONS[regionId];
+}
+
+/**
+ * @param {string} regionId
+ * @param {number} year
+ * @returns {Holiday[]}
+ */
+export function holidaysInYear(regionId, year) {
+  const region = REGIONS[regionId];
+  if (!region) return [];
+  const list = region.byYear[year];
+  return list ? [...list] : [];
+}
+
+/**
+ * @param {Date | string} date
+ * @param {string} regionId
+ * @returns {boolean}
+ */
+export function isHoliday(date, regionId) {
+  return holidayOn(date, regionId) != null;
+}
+
+/**
+ * @param {Date | string} date
+ * @param {string} regionId
+ * @returns {Holiday | null}
+ */
+export function holidayOn(date, regionId) {
+  const iso = toISODate(date);
+  const year = Number(iso.slice(0, 4));
+  const list = holidaysInYear(regionId, year);
+  return list.find((h) => h.date === iso) ?? null;
+}
+
+/**
+ * First holiday on or after `fromDate` (inclusive), or `null` if none in bundled data.
+ * @param {Date | string} fromDate
+ * @param {string} regionId
+ * @returns {Holiday | null}
+ */
+export function nextHoliday(fromDate, regionId) {
+  const iso = toISODate(fromDate);
+  const region = REGIONS[regionId];
+  if (!region) return null;
+
+  /** @type {Holiday[]} */
+  let merged = [];
+  for (const y of Object.keys(region.byYear)
+    .map(Number)
+    .sort((a, b) => a - b)) {
+    merged = merged.concat(holidaysInYear(regionId, y));
+  }
+  merged.sort((a, b) => a.date.localeCompare(b.date));
+  return merged.find((h) => h.date >= iso) ?? null;
+}
+
+/**
+ * Last holiday on or before `fromDate` (inclusive), or `null` if none in bundled data.
+ * @param {Date | string} fromDate
+ * @param {string} regionId
+ * @returns {Holiday | null}
+ */
+export function previousHoliday(fromDate, regionId) {
+  const iso = toISODate(fromDate);
+  const region = REGIONS[regionId];
+  if (!region) return null;
+
+  /** @type {Holiday[]} */
+  let merged = [];
+  for (const y of Object.keys(region.byYear)
+    .map(Number)
+    .sort((a, b) => a - b)) {
+    merged = merged.concat(holidaysInYear(regionId, y));
+  }
+  merged.sort((a, b) => a.date.localeCompare(b.date));
+  let last = null;
+  for (const h of merged) {
+    if (h.date <= iso) last = h;
+  }
+  return last;
+}
+
+export { REGIONS } from "./data.js";