dates.bank-holidays

export function bankHolidays(region: UkRegion, year: number): readonly BankHoliday[]

export type UkRegion = "england-and-wales" | "scotland" | "northern-ireland";

/** One day off, as gov.uk lists it. */
export interface BankHoliday {
  readonly date: string;
  /** gov.uk's own wording, e.g. "Boxing Day" */
  readonly title: string;
  /** true when this is a substitute weekday for a holiday that fell at a weekend */
  readonly substitute: boolean;
}

import { bankHolidays } from "#fune/dates.bank-holidays@^1";

import { BANK_HOLIDAYS } from "./dates_bank_holidays_data.ts";  ← this capability’s own data, compiled from data/bank-holidays.json into the same file by fune build
import { type BankHoliday, type UkRegion } from "./dates_bank_holidays_types.ts";

/**
 * The bank holidays for a UK region and year, in date order, as gov.uk
 * publishes them. A year the data does not cover is an error rather than an
 * empty list, because an empty list reads as "no holidays" and a deadline
 * calculation would then count Christmas Day as a working day.
 */
export function bankHolidays(region: UkRegion, year: number): readonly BankHoliday[] {
  if (!Number.isInteger(year)) {
    throw new TypeError(`year must be an integer, received ${year}`);
  }
  let first: number | null = null;
  let last: number | null = null;
  const found: BankHoliday[] = [];
  const prefix = `${String(year).padStart(4, "0")}-`;
  for (const row of BANK_HOLIDAYS) {
    if (row.region !== region) continue;
    const rowYear = Number(row.date.slice(0, 4));
    if (first === null || rowYear < first) first = rowYear;
    if (last === null || rowYear > last) last = rowYear;
    if (row.date.startsWith(prefix)) found.push({ date: row.date, title: row.title, substitute: row.substitute });
  }
  if (first === null || last === null) {
    throw new RangeError(`unknown region "${region}": expected england-and-wales, scotland or northern-ireland`);
  }
  if (year < first || year > last) {
    throw new RangeError(`no bank holiday data for ${region} in ${year}: the published calendar covers ${first} to ${last}`);
  }
  // ISO dates sort correctly as strings.
  return found.sort((a, b) => (a.date < b.date ? -1 : a.date > b.date ? 1 : 0));
}

Install

fune build

With that line in your source, in a TypeScript project (language typescript in fune.project), fune build resolves it and nothing else, pins them in fune.lock, downloads only the TypeScript package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add dates.bank-holidays

The manifest, vectors and README with only the TypeScript implementation. Install it without the registry with fune add ./dates.bank-holidays-1.0.0-typescript.fune, or fetch it from a terminal with fune pull dates.bank-holidays@1.0.0:typescript.

The whole function, every language, is one file too: dates.bank-holidays-1.0.0.fune, 59,370 bytes, sha256 916e69dedcd37c4d3383c26ae79478060310892b261b8a7e8bb073817c9f6298. It installs into a project of any language.

// fune: before dates.bank-holidays

// fune: after dates.bank-holidays

// fune: step dates.bank-holidays after <n|label>

More from the author

The holidays are data, not rules in code. Easter moves, holidays falling on a weekend are substituted by proclamation, and one-off holidays are added at a few months' notice: the Platinum Jubilee (3 June 2022, which also moved the spring holiday to 2 June), the State Funeral of Queen Elizabeth II (19 September 2022), the coronation of King Charles III (8 May 2023), the VE day move of the early May holiday (8 May 2020) and Scotland's World Cup bank holiday (15 June 2026). No formula produces those, which is why this is a table. When gov.uk publishes another year or another one-off holiday, that is a new version of this capability, not a code change.

A year outside the published range is an error, not an empty list. An empty list would read as "no holidays that year", and a deadline calculation would silently count Christmas Day as a working day.

The data deliberately has no `effective` columns. A bank holiday is an event on a date, not a rule that stays in force until superseded, so there is nothing for `history=current` to keep; declaring the columns would let a project-wide history setting prune the whole calendar away.

This lists days, it does not count them. To skip holidays in working-day arithmetic, pass the dates to dates.add-business-days or dates.business-days-between, which take an explicit holiday list so they work for any country and any employer's closure days.

Files