A Ruby gem for handling statutory and custom holidays with date range queries, region support, and core extensions.
Holidays is a Ruby gem that provides functionality to deal with statutory and custom holidays. It extends Ruby's built-in Date and Time classes, allowing developers to check for holidays on specific dates, within ranges, and across multiple regions. The gem solves the problem of managing holiday logic in applications that require date-aware scheduling, calendar features, or region-specific business rules.
Ruby developers building applications that need to handle holidays, such as scheduling tools, payroll systems, calendar apps, or international services requiring region-specific date logic. It's particularly useful for teams working with multiple countries or custom holiday sets.
Developers choose this gem for its comprehensive region support, flexibility with custom holiday definitions, and seamless integration with Ruby's core date classes. It stands out by offering both formal and informal holiday handling, observed date logic, and performance optimizations like caching, all maintained as a reliable open-source project.
A collection of Ruby methods to deal with statutory and other holidays. You deserve a holiday!
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.
Supports holidays for multiple countries and sub-regions, allowing queries like Holidays.on(Date.new(2008, 1, 1), :us, :fr) to check across regions simultaneously, as shown in the README examples.
Includes options for informal and observed holidays with flags like :informal and :observed, enabling precise control over holiday inclusion, such as fetching Valentine's Day or shifted Canada Day.
Allows loading custom holiday definition files on the fly via Holidays.load_custom, letting teams define company-specific or regional holidays without modifying core gem files.
Extends Ruby's Date and Time classes with holiday methods, making checks intuitive with examples like d.holidays(:is) or d.holiday?(:ca) for Iceland or Canada.
Offers in-memory caching with Holidays.cache_between to pre-calculate holidays for date ranges, improving lookup speed in high-frequency applications as detailed in the caching section.
The library explicitly states it ignores time zones and assumes all dates are in the same zone, which can lead to inaccuracies in global or distributed applications.
Holiday definitions are based on static files, and the README notes that definition changes are considered 'minor' bumps, meaning holiday results can change without code modifications, potentially breaking assumptions.
Caching is only in-memory, making it unsuitable for distributed systems or applications that restart frequently, as highlighted in the caching section without options for persistent storage.
To use core extensions, developers must modify Ruby's Date and Time classes by including modules, which could conflict with other libraries or be undesirable in certain codebases.