NPM Package v3.0.0 Published100% Offline Ready

Zero-Dependency Node.js Module for
Sri Lankan Holiday Data

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.

npm install sri-lankan-holiday-api

Why Use the sri-lankan-holiday-api Node Module?

Designed for reliability, speed, and resilience against external server downtime.

100% Offline Ready

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.

Zero Dependencies

Pure, lightweight JavaScript/TypeScript with 0 external npm dependencies. Ultra-tiny bundle footprint under 45KB with instant microsecond execution.

Full TypeScript Support

Includes strict TypeScript interfaces (Holiday, FilterOptions, ClientOptions) with full IDE autocomplete and type checking out of the box.

Hybrid Remote API Client

Need live updates? Use the optional SriLankanHolidayAPI client class to query live REST endpoints while automatically falling back to embedded data if connection drops.

Poya Day & Gazette Verified

Contains hand-researched official Sri Lanka Gazette dates (2024–2035) and astronomical Full Moon Poya algorithms up to 2045.

CommonJS & ES Modules

Dual CJS (require()) and ESM (import) builds. Compatible with Node.js, Next.js, Express, Bun, Deno, Vite, and React Native.

Live Interactive Sandbox

Test Module Methods Live in Browser

Source:sri-lankan-holiday-api Node Module
Network status:0 Network Requests (Offline)
Output JSON Response
// Click "Execute Method" above to view live evaluation results

Integration Code Snippets

Ready-to-use examples for modern JavaScript & TypeScript environments.

ES Modules / TypeScript

import syntax
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); // true

CommonJS (Node.js)

require() syntax
const { 
  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));

Express.js Holiday Checker Middleware

Backend Server
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()
  });
});

Hybrid Remote API Client with Fallback

SriLankanHolidayAPI
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);
}

Complete Exported API Reference

All synchronous & asynchronous functions exported by sri-lankan-holiday-api.

Exported FunctionParametersReturn TypeDescription
getAllHolidays(filters?)FilterOptionsHoliday[]Get all holidays matching optional year, month, type, religion, category filters.
getHolidaysByYear(year)number | stringHoliday[]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()noneHoliday[]Get today's holiday(s) in Sri Lanka timezone (Asia/Colombo).
getUpcomingHoliday(publicOnly?)booleanHoliday | nullGet the immediate next upcoming holiday from today.
getNextPoyaDay()noneHoliday & { daysUntil }Get the next Full Moon Poya Day with calculated countdown days.
getPoyaDays(year?)number | stringHoliday[]Get all Full Moon Poya days for a year.
isPublicHoliday(dateStr)string ("YYYY-MM-DD")booleanReturns true if the given date is a official public holiday.
isBankHoliday(dateStr)string ("YYYY-MM-DD")booleanReturns true if the given date is a commercial bank holiday.
searchHolidays(query)stringHoliday[]Full-text search matching name, description, date or tradition type.
SriLankanHolidayAPIClientOptionsclass instanceAsync client class for remote API calls with offline fallback.
Vercel Hosting & NPM Publishing Guide

How Vercel and NPM Publishing Work Together

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!