@fin.cx/opendata 3.6.0 → 4.1.0

package/ts/handelsregister/references.ts

@@ -0,0 +1,189 @@
+import { registerTypes } from './constants.js';
+import { registerCourts } from './data.codelists.js';
+import type { IRegisterCourt, IRegisterReference, TRegisterType } from './interfaces.js';
+
+/** a register number split into its digits and its location suffix */
+export interface IRegisterNumberParts {
+  digits: string;
+  /** upper case, for example `HB` */
+  suffix?: string;
+}
+
+/** a register reference read from text; the court is absent when the text names none */
+export interface IParsedRegisterReferenceText {
+  court?: IRegisterCourt;
+  /** the court as the text names it, when it names one */
+  courtText?: string;
+  type: TRegisterType;
+  /** digits and location suffix, for example `35230 HB` */
+  number: string;
+}
+
+const collapse = (textArg: string): string => textArg.replace(/\s+/g, ' ').trim();
+
+/** German letters as a text without them spells them: `Muenchen` is `München` */
+const spelledOut: Readonly<Record<string, string>> = { 'ä': 'ae', 'ö': 'oe', 'ü': 'ue', 'ß': 'ss' };
+
+/** words that name a court or a register rather than its place */
+const courtWords: ReadonlySet<string> = new Set([
+  'amtsgericht',
+  'amtsgerichts',
+  'ag',
+  'registergericht',
+  'registergerichts',
+  'handelsregister',
+  'genossenschaftsregister',
+  'partnerschaftsregister',
+  'vereinsregister',
+  'gesellschaftsregister',
+  'abteilung',
+  'beim',
+  'bei',
+  'des',
+]);
+
+/**
+ * The place a printed court name names, as courts are compared: lower case, German letters spelled
+ * out, punctuation as spaces, and without the words that name a court or a register or the
+ * division of the commercial register. `Handelsregister B des Amtsgerichts Frankfurt a. M.` is
+ * `frankfurt a m`.
+ */
+const placeKey = (textArg: string): string => {
+  const words = textArg
+    .normalize('NFC')
+    .toLocaleLowerCase('de-DE')
+    .replace(/[äöüß]/g, (letterArg) => spelledOut[letterArg] ?? letterArg)
+    .split(/[^\p{L}\p{N}]+/u)
+    .filter((wordArg) => wordArg !== '');
+  return words
+    .filter((wordArg, indexArg) => {
+      const previous = words[indexArg - 1];
+      const division = (previous === 'handelsregister' || previous === 'abteilung') && (wordArg === 'a' || wordArg === 'b');
+      return !courtWords.has(wordArg) && !division;
+    })
+    .join(' ');
+};
+
+/**
+ * Other names under which the register courts are printed, for courts whose name in the official
+ * list carries a qualifier that prints leave out, abbreviate or spell out. Each name here is a name
+ * of that court alone. `Frankfurt` without `am Main` or `(Oder)` is a name of neither of the two.
+ */
+const printedCourtNames: Readonly<Record<string, readonly string[]>> = {
+  'Bad Homburg v.d.H.': ['Bad Homburg', 'Bad Homburg vor der Höhe', 'Bad Homburg v. d. Höhe'],
+  'Berlin (Charlottenburg)': ['Berlin', 'Charlottenburg', 'Charlottenburg (Berlin)'],
+  'Frankfurt am Main': ['Frankfurt a. M.', 'Frankfurt a. Main', 'Frankfurt/M.', 'Frankfurt/Main', 'Frankfurt (Main)'],
+  'Frankfurt (Oder)': ['Frankfurt/O.', 'Frankfurt a. d. O.', 'Frankfurt an der Oder', 'Frankfurt a. d. Oder'],
+  'Freiburg': ['Freiburg im Breisgau', 'Freiburg i. Br.', 'Freiburg/Breisgau', 'Freiburg (Breisgau)'],
+  'Kempten (Allgäu)': ['Kempten'],
+  'Königstein': ['Königstein im Taunus', 'Königstein i. Ts.'],
+  'Landau': ['Landau in der Pfalz', 'Landau i. d. Pfalz', 'Landau/Pfalz'],
+  'Limburg': ['Limburg an der Lahn', 'Limburg a. d. Lahn'],
+  'Ludwigshafen a.Rhein (Ludwigshafen)': ['Ludwigshafen', 'Ludwigshafen am Rhein'],
+  'Offenbach am Main': ['Offenbach', 'Offenbach a. M.'],
+  'Oldenburg (Oldenburg)': ['Oldenburg', 'Oldenburg (Oldb.)', 'Oldenburg i. O.'],
+  'St. Ingbert (St Ingbert)': ['St. Ingbert', 'Sankt Ingbert'],
+  'St. Wendel (St Wendel)': ['St. Wendel', 'Sankt Wendel'],
+  'Weiden i. d. OPf.': ['Weiden', 'Weiden in der Oberpfalz'],
+};
+
+/** every place key of a list of courts with the courts it names */
+const courtsByPlaceKey = (courtsArg: readonly IRegisterCourt[]): ReadonlyMap<string, readonly IRegisterCourt[]> => {
+  const byKey = new Map<string, IRegisterCourt[]>();
+  for (const court of courtsArg) {
+    const keys = new Set([court.name, ...(printedCourtNames[court.name] ?? [])].map(placeKey));
+    for (const key of keys) {
+      if (key !== '') {
+        byKey.set(key, [...(byKey.get(key) ?? []), court]);
+      }
+    }
+  }
+  return byKey;
+};
+
+let officialCourtKeys: ReadonlyMap<string, readonly IRegisterCourt[]> | undefined;
+
+/**
+ * Finds a register court by its code or by its name as the portal or a business prints it: `H1101`,
+ * `Bremen`, `AG Bremen`, `Amtsgericht Bremen – Registergericht`, `Registergericht Bremen`,
+ * `Handelsregister B des Amtsgerichts Bremen`, `Amtsgericht Frankfurt a. M.`, `Frankfurt (Oder)`,
+ * `Kempten (Allgäu)` or `Kempten`, `Freiburg i. Br.`, `AG Berlin` or `Charlottenburg`. Umlauts may
+ * be spelled out (`Muenchen`). Returns undefined unless exactly one court fits: a place the list
+ * does not know, and `Frankfurt` alone, name no court.
+ */
+export const findRegisterCourt = (
+  codeOrNameArg: string,
+  courtsArg: readonly IRegisterCourt[] = registerCourts
+): IRegisterCourt | undefined => {
+  if (typeof codeOrNameArg !== 'string') {
+    return undefined;
+  }
+  const text = collapse(codeOrNameArg);
+  if (!text) {
+    return undefined;
+  }
+  const byCode = courtsArg.find((courtArg) => courtArg.code.toUpperCase() === text.toUpperCase());
+  if (byCode) {
+    return byCode;
+  }
+  const keys =
+    courtsArg === registerCourts
+      ? (officialCourtKeys ??= courtsByPlaceKey(registerCourts))
+      : courtsByPlaceKey(courtsArg);
+  const courts = keys.get(placeKey(text)) ?? [];
+  return courts.length === 1 ? courts[0] : undefined;
+};
+
+/** returns the canonical register type for `hrb`, `HRB`, `gnr` …, or undefined */
+export const toRegisterType = (textArg: string): TRegisterType | undefined =>
+  registerTypes.find((typeArg) => typeArg.toLowerCase() === collapse(textArg).toLowerCase());
+
+/** splits `35230 HB`, `35230HB` or `35230` into digits and location suffix */
+export const parseRegisterNumber = (textArg: string): IRegisterNumberParts | undefined => {
+  const match = /^(\d{1,9})\s*([A-Za-zÄÖÜäöü]{1,5})?$/.exec(collapse(textArg));
+  if (!match) {
+    return undefined;
+  }
+  return match[2] ? { digits: match[1], suffix: match[2].toLocaleUpperCase('de-DE') } : { digits: match[1] };
+};
+
+export const formatRegisterNumber = (partsArg: IRegisterNumberParts): string =>
+  partsArg.suffix ? `${partsArg.digits} ${partsArg.suffix}` : partsArg.digits;
+
+/**
+ * Reads a register reference as businesses print it: `Amtsgericht Bremen HRB 35230 HB`,
+ * `AG Bremen, HRB 35230`, `HRB 35230 HB`. Returns undefined for text it cannot read. A court name
+ * that fits no register court leaves `court` absent and keeps the text in `courtText`.
+ */
+export const parseRegisterReferenceText = (
+  textArg: string,
+  courtsArg: readonly IRegisterCourt[] = registerCourts
+): IParsedRegisterReferenceText | undefined => {
+  const text = collapse(textArg);
+  const match =
+    /^(.*?)[\s,;:]*\b(HRA|HRB|GnR|PR|VR|GsR)\b\.?\s*(?:Nr\.?\s*)?(\d{1,9}(?:\s*[A-Za-zÄÖÜäöü]{1,5})?)(?=\s|$)(?:\s+früher\s+Amtsgericht\s+.+)?$/i.exec(
+      text
+    );
+  if (!match) {
+    return undefined;
+  }
+  const type = toRegisterType(match[2]);
+  const number = parseRegisterNumber(match[3]);
+  if (!type || !number) {
+    return undefined;
+  }
+  const courtText = collapse(match[1].replace(/[,;:]+$/, ''));
+  const result: IParsedRegisterReferenceText = { type, number: formatRegisterNumber(number) };
+  if (courtText) {
+    result.courtText = courtText;
+    const court = findRegisterCourt(courtText, courtsArg);
+    if (court) {
+      result.court = court;
+    }
+  }
+  return result;
+};
+
+/** `Amtsgericht Bremen HRB 35230 HB` */
+export const formatRegisterReference = (referenceArg: IRegisterReference): string =>
+  `Amtsgericht ${referenceArg.court.name} ${referenceArg.type} ${referenceArg.number}`;

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';