Never worry about API server downtime or domain changes! Access 858+ hand-verified Sri Lankan public holidays, bank holidays, and Poya days (2024–2045) directly in Node.js, Next.js, Express & TypeScript with zero external network dependencies.
Designed for reliability, speed, and resilience against external server downtime.
Bundles all 858+ holiday entries directly inside the package JS. Works seamlessly in offline environments, Docker containers, AWS Lambda, or serverless functions without network calls.
Pure, lightweight JavaScript/TypeScript with 0 external npm dependencies. Ultra-tiny bundle footprint under 45KB with instant microsecond execution.
Includes strict TypeScript interfaces (Holiday, FilterOptions, ClientOptions) with full IDE autocomplete and type checking out of the box.
Need live updates? Use the optional SriLankanHolidayAPI client class to query live REST endpoints while automatically falling back to embedded data if connection drops.
Contains hand-researched official Sri Lanka Gazette dates (2024–2035) and astronomical Full Moon Poya algorithms up to 2045.
Dual CJS (require()) and ESM (import) builds. Compatible with Node.js, Next.js, Express, Bun, Deno, Vite, and React Native.
Ready-to-use examples for modern JavaScript & TypeScript environments.
import {
getUpcomingHoliday,
getNextPoyaDay,
isPublicHoliday
} from 'sri-lankan-holiday-api';
// 1. Get immediate next holiday
const upcoming = getUpcomingHoliday();
console.log('Next Holiday:', upcoming.name, upcoming.date);
// 2. Get next Full Moon Poya Day + Days Countdown
const poya = getNextPoyaDay();
console.log(`Next Poya in ${poya.daysUntil} days: ${poya.name}`);
// 3. Check if today is a Public Holiday
const isTodayPublic = isPublicHoliday('2026-04-13');
console.log('April 13 Public Holiday?', isTodayPublic); // trueconst {
getHolidaysByYear,
searchHolidays
} = require('sri-lankan-holiday-api');
// 1. Get all 2026 Sri Lankan holidays
const holidays2026 = getHolidaysByYear(2026);
console.log(`Found ${holidays2026.length} holidays for 2026`);
// 2. Search holidays by keyword
const vesakHolidays = searchHolidays('Vesak');
console.log('Vesak dates:', vesakHolidays.map(h => h.date));const express = require('express');
const { isPublicHoliday, getTodayHoliday } = require('sri-lankan-holiday-api');
const app = express();
// Middleware: Check if bank processing is open today
app.use((req, res, next) => {
const todayStr = new Date().toISOString().split('T')[0];
if (isPublicHoliday(todayStr)) {
console.log('Notice: Today is a Sri Lankan Public Holiday');
}
next();
});
app.get('/status', (req, res) => {
res.json({
todayHolidays: getTodayHoliday()
});
});import { SriLankanHolidayAPI } from 'sri-lankan-holiday-api';
// Create API client (queries remote domain, falls back to embedded data if server down!)
const client = new SriLankanHolidayAPI({
baseUrl: 'https://holiday.imrishmika.dev',
useOfflineFallback: true, // Auto fallback to local data if network fails
timeout: 4000
});
async function main() {
const holidays = await client.getAllHolidays({ year: 2026 });
console.log('2026 Holidays:', holidays.length);
}All synchronous & asynchronous functions exported by sri-lankan-holiday-api.
| Exported Function | Parameters | Return Type | Description |
|---|---|---|---|
| getAllHolidays(filters?) | FilterOptions | Holiday[] | Get all holidays matching optional year, month, type, religion, category filters. |
| getHolidaysByYear(year) | number | string | Holiday[] | Get all holidays for a specific calendar year (2024–2045). |
| getHolidaysByMonth(year, month) | year, month (1-12) | Holiday[] | Get holidays occurring in a given month. |
| getHolidayByDate(dateStr) | string ("YYYY-MM-DD") | Holiday[] | Find holiday records for an exact calendar date. |
| getTodayHoliday() | none | Holiday[] | Get today's holiday(s) in Sri Lanka timezone (Asia/Colombo). |
| getUpcomingHoliday(publicOnly?) | boolean | Holiday | null | Get the immediate next upcoming holiday from today. |
| getNextPoyaDay() | none | Holiday & { daysUntil } | Get the next Full Moon Poya Day with calculated countdown days. |
| getPoyaDays(year?) | number | string | Holiday[] | Get all Full Moon Poya days for a year. |
| isPublicHoliday(dateStr) | string ("YYYY-MM-DD") | boolean | Returns true if the given date is a official public holiday. |
| isBankHoliday(dateStr) | string ("YYYY-MM-DD") | boolean | Returns true if the given date is a commercial bank holiday. |
| searchHolidays(query) | string | Holiday[] | Full-text search matching name, description, date or tradition type. |
| SriLankanHolidayAPI | ClientOptions | class instance | Async client class for remote API calls with offline fallback. |
1. Vercel Build Integration: When Vercel builds your web project, it runs npm run build. We have configured package.json so that Vercel automatically builds both the Node module files in dist/ and the Next.js web application.
2. Publishing to NPM Registry: To publish or update the package on the official NPM Registry, simply run npm publish in your local terminal (or via GitHub Action). Only the compiled dist/ directory, README.md, and LICENSE will be uploaded to npm—keeping your published module ultra-clean and lightweight!