Public holidays, computed by rule, for the pickers to mark days.
Koyomi.Holidays.list("PT", 2027)
#=> [%Koyomi.Holiday{date: ~D[2027-01-01], name: "Ano Novo", english: "New Year's Day", country: "PT"}, ...]
range = Date.range(~D[2027-12-01], ~D[2028-01-31])
Koyomi.Holidays.to_client(["PT", "GB"], range, "pt-PT")
#=> %{"2027-12-25" => "Natal · Christmas Day", ...}A source of holidays is a country code (see countries/0, in any case)
or a module that implements Koyomi.Holidays.Provider, for the
holidays of a region or the days a business is closed. Each built-in
country is such a module too, such as Koyomi.Holidays.PT.
What is listed
The national public holidays: the days off that the law gives in the
whole country. Regional, local and religious days that only some
people keep are not listed, nor are days off by custom (such as
Christmas Eve in many countries). The module of each country says what
it keeps and leaves out, for example Koyomi.Holidays.CH for
Switzerland, where the cantons set the holidays.
The rules are those in force in 2026. A holiday that began or ended since 2010 is listed only in the years it was kept (Juneteenth in the United States from 2021). Older changes are not followed: earlier years follow the rules of 2010. One-off holidays (a coronation, a jubilee) are not listed.
Each holiday has a name in the main language of its country and an
english name. A few countries have several official languages; their
module names the language chosen: English for Canada, Dutch for
Belgium, German for Switzerland, Finnish for Finland, Hindi for India,
English for Ireland and South Africa.
Weekends
Where the law gives another day off when a holiday falls on a weekend (substitute days in the United Kingdom, 振替休日 in Japan, observed days in the United States, Mondayisation in Australia and New Zealand), the holiday stays on its date and a second entry marks the day off, such as "Christmas Day (substitute day)". Where the law moves the holiday itself (Argentina's movable holidays), only the day it moves to is listed.
Summary
Types
A country code, such as "PT", or a Koyomi.Holidays.Provider module.
Functions
Returns the holidays of one source or a list of sources within range,
across years, sorted by date. Holidays on the same day keep the order
of the sources.
Returns the codes of the countries with built-in holidays (ISO 3166-1 alpha-2), sorted.
Returns the holidays of a source in year, sorted by date. Holidays on
the same day keep the order of the source.
Returns the holidays within range as a map from ISO 8601 date to
name, for the picker in the browser.
Types
A country code, such as "PT", or a Koyomi.Holidays.Provider module.
Functions
@spec between(source() | [source()], Date.Range.t()) :: [Koyomi.Holiday.t()]
Returns the holidays of one source or a list of sources within range,
across years, sorted by date. Holidays on the same day keep the order
of the sources.
Examples
iex> range = Date.range(~D[2027-12-24], ~D[2028-01-01])
iex> for holiday <- Koyomi.Holidays.between(["PT", "DE"], range),
...> do: {holiday.date, holiday.name}
[
{~D[2027-12-25], "Natal"},
{~D[2027-12-25], "1. Weihnachtstag"},
{~D[2027-12-26], "2. Weihnachtstag"},
{~D[2028-01-01], "Ano Novo"},
{~D[2028-01-01], "Neujahr"}
]@spec countries() :: [String.t()]
Returns the codes of the countries with built-in holidays (ISO 3166-1 alpha-2), sorted.
Examples
iex> "JP" in Koyomi.Holidays.countries()
true@spec list(source(), integer()) :: [Koyomi.Holiday.t()]
Returns the holidays of a source in year, sorted by date. Holidays on
the same day keep the order of the source.
Raises ArgumentError for an unknown country code, a module that is
not a provider, or a provider that returns entries of another shape.
Examples
iex> [first | _] = Koyomi.Holidays.list("pt", 2027)
iex> {first.date, first.name, first.english, first.country}
{~D[2027-01-01], "Ano Novo", "New Year's Day", "PT"}@spec to_client(source() | [source()], Date.Range.t(), String.t()) :: %{ required(String.t()) => String.t() }
Returns the holidays within range as a map from ISO 8601 date to
name, for the picker in the browser.
A holiday has its name when the language of locale (such as "pt" in
"pt-PT" or "pt_BR") is the language of its country, and its english
name otherwise. "no" and "nn" count as Norwegian Bokmål ("nb"). The
holidays of a provider without language/0 always have their name.
Several holidays on one day are joined with " · ", without repeats.
Examples
iex> range = Date.range(~D[2027-12-25], ~D[2027-12-25])
iex> Koyomi.Holidays.to_client(["PT", "DE"], range, "pt-PT")
%{"2027-12-25" => "Natal · Christmas Day"}