@fin.cx/opendata 4.0.0 → 4.2.0

package/ts/holidays/calendar.ts

@@ -0,0 +1,261 @@
+import { HolidayCalendarError } from './classes.holidaycalendarerror.js';
+import { germanStates, holidayCalendarFirstYear, holidayRules } from './data.holidays.js';
+import type { IHolidayRule, THolidayDateRule } from './data.holidays.js';
+import type {
+  IGermanState,
+  IPublicHoliday,
+  IWorkingDayOptions,
+  TGermanStateCode,
+  TIsoDate,
+} from './interfaces.js';
+
+const dayMs = 86_400_000;
+const lastYear = 9999;
+
+interface ICalendarDay {
+  year: number;
+  /** ms since the epoch at 00:00 UTC of the day */
+  utc: number;
+}
+
+const pad = (valueArg: number, lengthArg: number): string => String(valueArg).padStart(lengthArg, '0');
+
+const toIsoDate = (utcArg: number): TIsoDate => {
+  const date = new Date(utcArg);
+  return `${pad(date.getUTCFullYear(), 4)}-${pad(date.getUTCMonth() + 1, 2)}-${pad(date.getUTCDate(), 2)}`;
+};
+
+const utcOf = (yearArg: number, monthArg: number, dayArg: number): number => {
+  const date = new Date(0);
+  date.setUTCFullYear(yearArg, monthArg - 1, dayArg);
+  date.setUTCHours(0, 0, 0, 0);
+  return date.getTime();
+};
+
+const checkYear = (yearArg: number): void => {
+  if (!Number.isInteger(yearArg) || yearArg < holidayCalendarFirstYear || yearArg > lastYear) {
+    throw new HolidayCalendarError(
+      'unsupported_year',
+      `The holiday calendar answers for the years ${holidayCalendarFirstYear} to ${lastYear}, not for ${String(yearArg)}.`,
+    );
+  }
+};
+
+const parseIsoDate = (dateArg: TIsoDate): ICalendarDay => {
+  const match = typeof dateArg === 'string' ? /^(\d{4})-(\d{2})-(\d{2})$/.exec(dateArg) : null;
+  if (!match) {
+    throw new HolidayCalendarError('invalid_date', `A date is written YYYY-MM-DD; ${JSON.stringify(dateArg)} is not.`);
+  }
+  const year = Number(match[1]);
+  const month = Number(match[2]);
+  const day = Number(match[3]);
+  checkYear(year);
+  const utc = utcOf(year, month, day);
+  if (toIsoDate(utc) !== dateArg) {
+    throw new HolidayCalendarError('invalid_date', `${dateArg} is not a date of the calendar.`);
+  }
+  return { year, utc };
+};
+
+const checkState = (stateArg: TGermanStateCode): void => {
+  if (!germanStates.some((stateEntry) => stateEntry.code === stateArg)) {
+    throw new HolidayCalendarError(
+      'unknown_state',
+      `${JSON.stringify(stateArg)} is not the ISO 3166-2 code of a German federal state, such as DE-BY.`,
+    );
+  }
+};
+
+const checkOptions = (optionsArg: IWorkingDayOptions): void => {
+  const policy: unknown = optionsArg?.regionalHolidays;
+  if (policy !== 'count' && policy !== 'ignore') {
+    throw new HolidayCalendarError(
+      'invalid_options',
+      'Say how regional holidays are treated: { regionalHolidays: "count" } or { regionalHolidays: "ignore" }.',
+    );
+  }
+};
+
+/**
+ * Easter Sunday of a year of the Gregorian calendar, by the algorithm of Meeus, Jones and
+ * Butcher. The Easter-based holidays follow from it.
+ */
+export const easterSunday = (yearArg: number): TIsoDate => {
+  checkYear(yearArg);
+  return toIsoDate(easterUtc(yearArg));
+};
+
+const easterUtc = (yearArg: number): number => {
+  const a = yearArg % 19;
+  const b = Math.floor(yearArg / 100);
+  const c = yearArg % 100;
+  const d = Math.floor(b / 4);
+  const e = b % 4;
+  const f = Math.floor((b + 8) / 25);
+  const g = Math.floor((b - f + 1) / 3);
+  const h = (19 * a + b - d - g + 15) % 30;
+  const i = Math.floor(c / 4);
+  const k = c % 4;
+  const l = (32 + 2 * e + 2 * i - h - k) % 7;
+  const m = Math.floor((a + 11 * h + 22 * l) / 451);
+  const month = Math.floor((h + l - 7 * m + 114) / 31);
+  const day = ((h + l - 7 * m + 114) % 31) + 1;
+  return utcOf(yearArg, month, day);
+};
+
+/** the Wednesday before the last Sunday before the first Sunday of Advent (16 to 22 November) */
+const bussUndBettagUtc = (yearArg: number): number => {
+  const christmasEve = utcOf(yearArg, 12, 24);
+  const fourthAdvent = christmasEve - new Date(christmasEve).getUTCDay() * dayMs;
+  const firstAdvent = fourthAdvent - 21 * dayMs;
+  return firstAdvent - 11 * dayMs;
+};
+
+const dateOf = (ruleArg: THolidayDateRule, yearArg: number): number => {
+  switch (ruleArg.kind) {
+    case 'fixed':
+      return utcOf(yearArg, ruleArg.month, ruleArg.day);
+    case 'easter':
+      return easterUtc(yearArg) + ruleArg.offset * dayMs;
+    case 'buss-und-bettag':
+      return bussUndBettagUtc(yearArg);
+  }
+};
+
+const appliesIn = (ruleArg: IHolidayRule, yearArg: number): boolean =>
+  (ruleArg.onlyYear === undefined || ruleArg.onlyYear === yearArg) &&
+  (ruleArg.fromYear === undefined || yearArg >= ruleArg.fromYear);
+
+const holidaysByYearAndState = new Map<string, readonly IPublicHoliday[]>();
+
+const holidaysOf = (yearArg: number, stateArg: TGermanStateCode): readonly IPublicHoliday[] => {
+  const key = `${yearArg}:${stateArg}`;
+  const known = holidaysByYearAndState.get(key);
+  if (known) {
+    return known;
+  }
+  const holidays = holidayRules
+    .filter((ruleArg) => ruleArg.state === stateArg && appliesIn(ruleArg, yearArg))
+    .map((ruleArg) => ({ utc: dateOf(ruleArg.date, yearArg), rule: ruleArg }))
+    .sort((leftArg, rightArg) => leftArg.utc - rightArg.utc)
+    .map(({ utc, rule }): IPublicHoliday => {
+      const holiday: IPublicHoliday = {
+        date: toIsoDate(utc),
+        id: rule.id,
+        name: rule.name,
+        state: rule.state,
+        scope: rule.scope,
+        legalBasis: rule.legalBasis,
+      };
+      if (rule.region !== undefined) {
+        holiday.region = rule.region;
+      }
+      return Object.freeze(holiday);
+    });
+  const frozen = Object.freeze(holidays);
+  holidaysByYearAndState.set(key, frozen);
+  return frozen;
+};
+
+/**
+ * The statutory public holidays of a state in a year, in the order of their dates. Regional
+ * holidays are included with `scope: 'regional'` and the part of the state they apply to.
+ */
+export const getPublicHolidays = (yearArg: number, stateArg: TGermanStateCode): IPublicHoliday[] => {
+  checkYear(yearArg);
+  checkState(stateArg);
+  return [...holidaysOf(yearArg, stateArg)];
+};
+
+/** The statutory public holidays of a state on a date, regional ones included. */
+export const getPublicHolidaysOn = (dateArg: TIsoDate, stateArg: TGermanStateCode): IPublicHoliday[] => {
+  const day = parseIsoDate(dateArg);
+  checkState(stateArg);
+  return holidaysOf(day.year, stateArg).filter((holidayArg) => holidayArg.date === dateArg);
+};
+
+const isHolidayUtc = (utcArg: number, stateArg: TGermanStateCode, optionsArg: IWorkingDayOptions): boolean => {
+  const date = toIsoDate(utcArg);
+  const year = new Date(utcArg).getUTCFullYear();
+  checkYear(year);
+  return holidaysOf(year, stateArg).some(
+    (holidayArg) =>
+      holidayArg.date === date && (holidayArg.scope === 'state' || optionsArg.regionalHolidays === 'count'),
+  );
+};
+
+const isWorkingDayUtc = (utcArg: number, stateArg: TGermanStateCode, optionsArg: IWorkingDayOptions): boolean => {
+  const weekday = new Date(utcArg).getUTCDay();
+  return weekday !== 0 && weekday !== 6 && !isHolidayUtc(utcArg, stateArg, optionsArg);
+};
+
+/** Whether a date is a statutory public holiday in a state. */
+export const isPublicHoliday = (
+  dateArg: TIsoDate,
+  stateArg: TGermanStateCode,
+  optionsArg: IWorkingDayOptions,
+): boolean => {
+  const day = parseIsoDate(dateArg);
+  checkState(stateArg);
+  checkOptions(optionsArg);
+  return isHolidayUtc(day.utc, stateArg, optionsArg);
+};
+
+/**
+ * Whether a date is a working day in a state in the sense of § 193 BGB: neither a Saturday, nor a
+ * Sunday, nor a statutory public holiday.
+ */
+export const isWorkingDay = (dateArg: TIsoDate, stateArg: TGermanStateCode, optionsArg: IWorkingDayOptions): boolean => {
+  const day = parseIsoDate(dateArg);
+  checkState(stateArg);
+  checkOptions(optionsArg);
+  return isWorkingDayUtc(day.utc, stateArg, optionsArg);
+};
+
+/** The first working day after a date (§ 193 BGB: not a Saturday, Sunday or public holiday). */
+export const nextWorkingDay = (dateArg: TIsoDate, stateArg: TGermanStateCode, optionsArg: IWorkingDayOptions): TIsoDate => {
+  const day = parseIsoDate(dateArg);
+  checkState(stateArg);
+  checkOptions(optionsArg);
+  let utc = day.utc + dayMs;
+  while (!isWorkingDayUtc(utc, stateArg, optionsArg)) {
+    utc += dayMs;
+  }
+  return toIsoDate(utc);
+};
+
+/**
+ * The date itself when it is a working day, otherwise the next working day: the day that takes the
+ * place of a fixed day or of the last day of a period under § 193 BGB.
+ */
+export const workingDayOnOrAfter = (
+  dateArg: TIsoDate,
+  stateArg: TGermanStateCode,
+  optionsArg: IWorkingDayOptions,
+): TIsoDate => {
+  const day = parseIsoDate(dateArg);
+  checkState(stateArg);
+  checkOptions(optionsArg);
+  let utc = day.utc;
+  while (!isWorkingDayUtc(utc, stateArg, optionsArg)) {
+    utc += dayMs;
+  }
+  return toIsoDate(utc);
+};
+
+/**
+ * The federal state for a code or a name: `DE-BY`, `BY` or `Bayern`, compared without regard to
+ * case and surrounding whitespace.
+ */
+export const findGermanState = (valueArg: string): IGermanState | undefined => {
+  if (typeof valueArg !== 'string') {
+    return undefined;
+  }
+  const value = valueArg.trim().toLocaleLowerCase('de-DE');
+  return germanStates.find(
+    (stateArg) =>
+      stateArg.code.toLowerCase() === value ||
+      stateArg.code.slice(3).toLowerCase() === value ||
+      stateArg.name.toLocaleLowerCase('de-DE') === value,
+  );
+};

package/ts/holidays/classes.holidaycalendarerror.ts

@@ -0,0 +1,20 @@
+/**
+ * Why a question to the holiday calendar was refused:
+ * - `invalid_date`: the value is not a calendar date written `YYYY-MM-DD`;
+ * - `unsupported_year`: the year lies before the first year the calendar answers for (2018) or
+ *   after 9999;
+ * - `unknown_state`: the value is not the code of a German federal state;
+ * - `invalid_options`: the options do not say how to treat regional holidays.
+ */
+export type THolidayCalendarErrorCode = 'invalid_date' | 'unsupported_year' | 'unknown_state' | 'invalid_options';
+
+/** The typed error of the holiday calendar. */
+export class HolidayCalendarError extends Error {
+  public readonly code: THolidayCalendarErrorCode;
+
+  constructor(code: THolidayCalendarErrorCode, message: string) {
+    super(message);
+    this.name = 'HolidayCalendarError';
+    this.code = code;
+  }
+}

package/ts/holidays/data.holidays.ts

@@ -0,0 +1,177 @@
+/**
+ * The statutory public holidays of the German federal states, taken from the holiday laws of the
+ * states (Feiertagsgesetze) and, for 3 October, from Art. 2 Abs. 2 of the Unification Treaty
+ * (Einigungsvertrag). The provisions were read on 2026-09-24 in the official law portals of the
+ * states; the readme lists them with their links.
+ *
+ * The rules cover the years from 2018 on. Every change of a state's list since then is recorded
+ * with the year it first applies: Reformationstag in Bremen, Hamburg, Niedersachsen and
+ * Schleswig-Holstein (2018), Frauentag in Berlin (2019) and Mecklenburg-Vorpommern (2023),
+ * Weltkindertag in Thüringen (2019), and the one-off holidays of Berlin (2020, 2025, 2028).
+ */
+import type { IGermanState, TGermanStateCode, TPublicHolidayId, TPublicHolidayScope } from './interfaces.js';
+
+/** the first year the calendar answers for */
+export const holidayCalendarFirstYear = 2018;
+
+/** the day the holiday laws were read; later changes need a new release */
+export const holidayLawsReadOn = '2026-09-24';
+
+export const germanStates: readonly IGermanState[] = Object.freeze([
+  { code: 'DE-BW', name: 'Baden-Württemberg' },
+  { code: 'DE-BY', name: 'Bayern' },
+  { code: 'DE-BE', name: 'Berlin' },
+  { code: 'DE-BB', name: 'Brandenburg' },
+  { code: 'DE-HB', name: 'Bremen' },
+  { code: 'DE-HH', name: 'Hamburg' },
+  { code: 'DE-HE', name: 'Hessen' },
+  { code: 'DE-MV', name: 'Mecklenburg-Vorpommern' },
+  { code: 'DE-NI', name: 'Niedersachsen' },
+  { code: 'DE-NW', name: 'Nordrhein-Westfalen' },
+  { code: 'DE-RP', name: 'Rheinland-Pfalz' },
+  { code: 'DE-SL', name: 'Saarland' },
+  { code: 'DE-SN', name: 'Sachsen' },
+  { code: 'DE-ST', name: 'Sachsen-Anhalt' },
+  { code: 'DE-SH', name: 'Schleswig-Holstein' },
+  { code: 'DE-TH', name: 'Thüringen' },
+] as const satisfies readonly IGermanState[]);
+
+/** the provision of each state's holiday law that lists its statutory holidays */
+const holidayListOf: Readonly<Record<TGermanStateCode, string>> = {
+  'DE-BW': '§ 1 FTG (Baden-Württemberg)',
+  'DE-BY': 'Art. 1 Abs. 1 Nr. 1 FTG (Bayern)',
+  'DE-BE': '§ 1 Abs. 1 Gesetz über die Sonn- und Feiertage (Berlin)',
+  'DE-BB': '§ 2 Abs. 1 FTG (Brandenburg)',
+  'DE-HB': '§ 2 Abs. 1 Gesetz über die Sonn-, Gedenk- und Feiertage (Bremen)',
+  'DE-HH': '§ 1 Feiertagsgesetz (Hamburg)',
+  'DE-HE': '§ 1 Abs. 1 HFeiertagsG',
+  'DE-MV': '§ 2 Abs. 1 FTG M-V',
+  'DE-NI': '§ 2 Abs. 1 NFeiertagsG',
+  'DE-NW': '§ 2 Abs. 1 Feiertagsgesetz NW',
+  'DE-RP': '§ 2 Abs. 1 LFtG',
+  'DE-SL': '§ 2 Abs. 1 SFG',
+  'DE-SN': '§ 1 Abs. 1 SächsSFG',
+  'DE-ST': '§ 2 FeiertG LSA',
+  'DE-SH': '§ 2 Abs. 1 SFTG',
+  'DE-TH': '§ 2 Abs. 1 ThürFGtG',
+};
+
+/** how the date of a holiday follows from the year */
+export type THolidayDateRule =
+  | { kind: 'fixed'; month: number; day: number }
+  /** days after Easter Sunday; negative before it */
+  | { kind: 'easter'; offset: number }
+  /** the Wednesday before the last Sunday before the first Sunday of Advent */
+  | { kind: 'buss-und-bettag' };
+
+export interface IHolidayRule {
+  id: TPublicHolidayId;
+  name: string;
+  date: THolidayDateRule;
+  state: TGermanStateCode;
+  scope: TPublicHolidayScope;
+  region?: string;
+  legalBasis: string;
+  /** the first year the holiday applies */
+  fromYear?: number;
+  /** the only year a one-off holiday applies */
+  onlyYear?: number;
+}
+
+const allStates = germanStates.map((stateArg) => stateArg.code);
+
+const fixed = (month: number, day: number): THolidayDateRule => ({ kind: 'fixed', month, day });
+const easter = (offset: number): THolidayDateRule => ({ kind: 'easter', offset });
+
+/** a holiday in the whole of each listed state, by that state's holiday list */
+const statewide = (
+  id: TPublicHolidayId,
+  name: string,
+  date: THolidayDateRule,
+  states: readonly TGermanStateCode[],
+  extra: Partial<Pick<IHolidayRule, 'fromYear' | 'onlyYear'>> = {},
+): IHolidayRule[] =>
+  states.map((state) => ({ id, name, date, state, scope: 'state', legalBasis: holidayListOf[state], ...extra }));
+
+export const holidayRules: readonly IHolidayRule[] = Object.freeze([
+  // in every state
+  ...statewide('neujahr', 'Neujahr', fixed(1, 1), allStates),
+  ...statewide('karfreitag', 'Karfreitag', easter(-2), allStates),
+  ...statewide('ostermontag', 'Ostermontag', easter(1), allStates),
+  ...statewide('tag-der-arbeit', 'Tag der Arbeit', fixed(5, 1), allStates),
+  ...statewide('christi-himmelfahrt', 'Christi Himmelfahrt', easter(39), allStates),
+  ...statewide('pfingstmontag', 'Pfingstmontag', easter(50), allStates),
+  ...allStates.map((state): IHolidayRule => ({
+    id: 'tag-der-deutschen-einheit',
+    name: 'Tag der Deutschen Einheit',
+    date: fixed(10, 3),
+    state,
+    scope: 'state',
+    legalBasis: 'Art. 2 Abs. 2 Einigungsvertrag',
+  })),
+  ...statewide('erster-weihnachtstag', '1. Weihnachtstag', fixed(12, 25), allStates),
+  ...statewide('zweiter-weihnachtstag', '2. Weihnachtstag', fixed(12, 26), allStates),
+
+  // in some states
+  ...statewide('heilige-drei-koenige', 'Heilige Drei Könige', fixed(1, 6), ['DE-BW', 'DE-BY', 'DE-ST']),
+  ...statewide('frauentag', 'Frauentag', fixed(3, 8), ['DE-BE'], { fromYear: 2019 }),
+  ...statewide('frauentag', 'Frauentag', fixed(3, 8), ['DE-MV'], { fromYear: 2023 }),
+  ...statewide('ostersonntag', 'Ostersonntag', easter(0), ['DE-BB']),
+  ...statewide('pfingstsonntag', 'Pfingstsonntag', easter(49), ['DE-BB']),
+  ...statewide('fronleichnam', 'Fronleichnam', easter(60), ['DE-BW', 'DE-BY', 'DE-HE', 'DE-NW', 'DE-RP', 'DE-SL']),
+  ...statewide('mariae-himmelfahrt', 'Mariä Himmelfahrt', fixed(8, 15), ['DE-SL']),
+  ...statewide('weltkindertag', 'Weltkindertag', fixed(9, 20), ['DE-TH'], { fromYear: 2019 }),
+  ...statewide('reformationstag', 'Reformationstag', fixed(10, 31), ['DE-BB', 'DE-MV', 'DE-SN', 'DE-ST', 'DE-TH']),
+  ...statewide('reformationstag', 'Reformationstag', fixed(10, 31), ['DE-HB', 'DE-HH', 'DE-NI', 'DE-SH'], {
+    fromYear: 2018,
+  }),
+  ...statewide('allerheiligen', 'Allerheiligen', fixed(11, 1), ['DE-BW', 'DE-BY', 'DE-NW', 'DE-RP', 'DE-SL']),
+  ...statewide('buss-und-bettag', 'Buß- und Bettag', { kind: 'buss-und-bettag' }, ['DE-SN']),
+
+  // one-off holidays
+  ...statewide('tag-der-befreiung', 'Tag der Befreiung', fixed(5, 8), ['DE-BE'], { onlyYear: 2020 }),
+  ...statewide('tag-der-befreiung', 'Tag der Befreiung', fixed(5, 8), ['DE-BE'], { onlyYear: 2025 }),
+  ...statewide('jahrestag-17-juni-1953', '75. Jahrestag des Aufstandes vom 17. Juni 1953', fixed(6, 17), ['DE-BE'], {
+    onlyYear: 2028,
+  }),
+
+  // in part of a state
+  {
+    id: 'fronleichnam',
+    name: 'Fronleichnam',
+    date: easter(60),
+    state: 'DE-SN',
+    scope: 'regional',
+    region:
+      'die in der Anlage der FronleichnamsVO genannten Gemeinden der früheren Landkreise Bautzen, Hoyerswerda und Kamenz, nach einer Neugliederung nur der jeweilige Gemeindeteil',
+    legalBasis: '§ 1 Abs. 1 SächsSFG i. V. m. § 1 FronleichnamsVO',
+  },
+  {
+    id: 'fronleichnam',
+    name: 'Fronleichnam',
+    date: easter(60),
+    state: 'DE-TH',
+    scope: 'regional',
+    region: 'die Teile Thüringens, in denen Fronleichnam 1994 gesetzlicher Feiertag war',
+    legalBasis: '§ 2 Abs. 2 i. V. m. § 10 Abs. 1 ThürFGtG',
+  },
+  {
+    id: 'augsburger-friedensfest',
+    name: 'Augsburger Friedensfest',
+    date: fixed(8, 8),
+    state: 'DE-BY',
+    scope: 'regional',
+    region: 'Stadt Augsburg',
+    legalBasis: 'Art. 1 Abs. 2 FTG (Bayern)',
+  },
+  {
+    id: 'mariae-himmelfahrt',
+    name: 'Mariä Himmelfahrt',
+    date: fixed(8, 15),
+    state: 'DE-BY',
+    scope: 'regional',
+    region:
+      'Gemeinden mit überwiegend katholischer Bevölkerung, wie das Bayerische Landesamt für Statistik sie nach der letzten Volkszählung feststellt',
+    legalBasis: 'Art. 1 Abs. 1 Nr. 2, Abs. 3 FTG (Bayern)',
+  },
+] satisfies IHolidayRule[]);

package/ts/holidays/index.ts

@@ -0,0 +1,18 @@
+// This entry point stands alone: it imports nothing from the rest of the package, has no
+// dependencies and needs no storage or network.
+export * from './interfaces.js';
+export {
+  HolidayCalendarError,
+  type THolidayCalendarErrorCode,
+} from './classes.holidaycalendarerror.js';
+export { germanStates, holidayCalendarFirstYear, holidayLawsReadOn } from './data.holidays.js';
+export {
+  easterSunday,
+  findGermanState,
+  getPublicHolidays,
+  getPublicHolidaysOn,
+  isPublicHoliday,
+  isWorkingDay,
+  nextWorkingDay,
+  workingDayOnOrAfter,
+} from './calendar.js';

package/ts/holidays/interfaces.ts

@@ -0,0 +1,87 @@
+/** A German federal state, as its ISO 3166-2 subdivision code. */
+export type TGermanStateCode =
+  | 'DE-BW'
+  | 'DE-BY'
+  | 'DE-BE'
+  | 'DE-BB'
+  | 'DE-HB'
+  | 'DE-HH'
+  | 'DE-HE'
+  | 'DE-MV'
+  | 'DE-NI'
+  | 'DE-NW'
+  | 'DE-RP'
+  | 'DE-SL'
+  | 'DE-SN'
+  | 'DE-ST'
+  | 'DE-SH'
+  | 'DE-TH';
+
+/** A federal state with its name. */
+export interface IGermanState {
+  code: TGermanStateCode;
+  /** the state's name, for example `Bayern` */
+  name: string;
+}
+
+/** A plain calendar date, `YYYY-MM-DD`. */
+export type TIsoDate = string;
+
+/** The statutory public holidays the calendar knows. */
+export type TPublicHolidayId =
+  | 'neujahr'
+  | 'heilige-drei-koenige'
+  | 'frauentag'
+  | 'karfreitag'
+  | 'ostersonntag'
+  | 'ostermontag'
+  | 'tag-der-arbeit'
+  | 'tag-der-befreiung'
+  | 'christi-himmelfahrt'
+  | 'pfingstsonntag'
+  | 'pfingstmontag'
+  | 'jahrestag-17-juni-1953'
+  | 'fronleichnam'
+  | 'augsburger-friedensfest'
+  | 'mariae-himmelfahrt'
+  | 'weltkindertag'
+  | 'tag-der-deutschen-einheit'
+  | 'reformationstag'
+  | 'allerheiligen'
+  | 'buss-und-bettag'
+  | 'erster-weihnachtstag'
+  | 'zweiter-weihnachtstag';
+
+/**
+ * Where a holiday applies within its state:
+ * - `state`: in the whole state;
+ * - `regional`: only in part of the state (some municipalities or parts of municipalities), which
+ *   `region` describes. The calendar holds no list of those municipalities.
+ */
+export type TPublicHolidayScope = 'state' | 'regional';
+
+/** One statutory public holiday on one date in one state. */
+export interface IPublicHoliday {
+  date: TIsoDate;
+  id: TPublicHolidayId;
+  /** the German name, for example `Christi Himmelfahrt` */
+  name: string;
+  state: TGermanStateCode;
+  scope: TPublicHolidayScope;
+  /** for a regional holiday, the part of the state where it applies */
+  region?: string;
+  /** the provision that makes the day a statutory holiday, for example `§ 2 Abs. 1 NFeiertagsG` */
+  legalBasis: string;
+}
+
+/**
+ * How a question about working days treats regional holidays, which apply only in part of a state:
+ * - `count`: as holidays, as if the place in question lies in that part. A period then never ends
+ *   on a day that is a holiday at the place, at the price of ending one day later elsewhere;
+ * - `ignore`: as working days, when the place is known to lie outside that part.
+ */
+export type TRegionalHolidayPolicy = 'count' | 'ignore';
+
+export interface IWorkingDayOptions {
+  regionalHolidays: TRegionalHolidayPolicy;
+}