holiday_co 1.0.1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9166d0bbc45b36c157119cef9469f17d8974651c1bde43dd53c918d026534404
-  data.tar.gz: 5c0099db1b7377200a2f3bfdc81130e3609ac99d978c84400311ce135fcf757b
+  metadata.gz: d26e0ed39b140dc05c8d82ef874b7793ebe17b4215c60c216f9c3b7a3afa9481
+  data.tar.gz: 97f70e6d2aae69a87054a402e9450a40e5c2a263d4dac2b37bb129f47a8b1873
 SHA512:
-  metadata.gz: 22dbf800d65123ff86e12e93da9ec72b629faa90b7d9cd2fe4e587bd1169762921786c353ecd782ed5a756c995a57e28114b5781ecfc62bb9440ec1807f30497
-  data.tar.gz: a8e16af3be4156af15dfdb1ae01e2817ea8c01b56f9faf5bb6dd8c59cae081685f67a74b5a5963f37749b380693362eeb2641d592deb2e1fe15f9afcb1cbe402
+  metadata.gz: e8640a73dfec13370288daaedf5730c5edcb7e85392417aab1a657f18ceb5c189ca385a1b2211cbd2b0f7d83b8aaba453fca3075be603c78fa618b74a5f50388
+  data.tar.gz: ba25e51996ae422b4eac1a34eb5c2c8001d515f0455aa505e4535b0425f412f3f02ce0942fe9931afed1dadad3bdfdf42f8181bd270c5f310dcbbe7768fbf683

data/lib/holiday_co/cache.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module HolidayCo
+  # A tiny thread-safe LRU cache used to memoize per-year holiday calculations,
+  # so holidays are only ever calculated once per year per process.
+  class Cache
+    DEFAULT_MAX_SIZE = 64
+
+    attr_reader :max_size
+
+    def initialize(max_size: DEFAULT_MAX_SIZE)
+      raise ArgumentError, "max_size must be a positive integer" unless max_size.is_a?(Integer) && max_size.positive?
+
+      @max_size = max_size
+      @store = {}
+      @mutex = Mutex.new
+    end
+
+    def fetch(key)
+      @mutex.synchronize do
+        if @store.key?(key)
+          # Re-insert on hit so insertion order tracks recency.
+          @store[key] = @store.delete(key)
+        else
+          value = yield
+          @store[key] = value
+          @store.shift while @store.size > @max_size
+          value
+        end
+      end
+    end
+
+    def size
+      @mutex.synchronize { @store.size }
+    end
+
+    def clear!
+      @mutex.synchronize { @store.clear }
+      nil
+    end
+  end
+
+  class << self
+    attr_writer :cache_enabled
+    attr_reader :cache_size
+
+    def configure
+      yield self if block_given?
+    end
+
+    def cache_enabled?
+      @cache_enabled
+    end
+
+    def cache_size=(size)
+      @cache_size = size
+      @cache = nil
+    end
+
+    def cache
+      @cache ||= Cache.new(max_size: cache_size)
+    end
+
+    def clear_cache!
+      cache.clear!
+    end
+  end
+
+  @cache_enabled = true
+  @cache_size = Cache::DEFAULT_MAX_SIZE
+end

data/lib/holiday_co/calculate_holidays/fixed.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+#  Dates are in YYYY-MM-DD format
+module HolidayCo
+  module CalculateHolidays
+    class Fixed
+      FIXED_HOLIDAYS = {
+        "Año Nuevo" => "%4s-01-01",
+        "Día del trabajo" => "%4s-05-01",
+        "Día de la independencia" => "%4s-07-20",
+        "Batalla de Boyacá" => "%4s-08-07",
+        "Inmaculada Concepción" => "%4s-12-08",
+        "Navidad" => "%4s-12-25"
+      }
+
+      def self.for(year)
+        FIXED_HOLIDAYS.map do |holiday, date|
+          {
+            :name => holiday,
+            :date => date % year
+          }
+        end
+      end
+    end
+  end
+end

data/lib/holiday_co/calculate_holidays/movable.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "date"
+
+module NextMondayRefinement
+  refine Date do
+    def next_monday
+      from_now = 1 - wday
+      from_now += 7 unless from_now > 0
+      self + from_now
+    end
+  end
+end
+
+#  Dates are in YYYY-MM-DD format
+module HolidayCo
+  module CalculateHolidays
+    class Movable
+      using NextMondayRefinement
+
+      # Holidays that are moved to the following Monday
+      # if they don"t fall on a Monday.
+      MOVABLE_HOLIDAYS = {
+        "Epifanía" => "%4s-01-06",
+        "Día de San José" => "%4s-03-19",
+        "San Pedro y San Pablo" => "%4s-06-29",
+        "Día de la Virgen del Rosario de Chiquinquirá" => "%4s-07-09",
+        "Asunción de la Virgen" => "%4s-08-15",
+        "Día de la raza" => "%4s-10-12",
+        "Todos los Santos" => "%4s-11-01",
+        "Independencia de Cartagena" => "%4s-11-11"
+      }
+
+      # Holidays introduced after 1983, keyed by the first year they apply.
+      # Ley 2578 de 2026 declared the Día de la Virgen del Rosario de Chiquinquirá.
+      EFFECTIVE_SINCE = {
+        "Día de la Virgen del Rosario de Chiquinquirá" => 2026
+      }
+
+      def self.for(year)
+        MOVABLE_HOLIDAYS.filter_map do |holiday, date|
+          next if year.to_i < EFFECTIVE_SINCE.fetch(holiday, 0)
+
+          day = Date.parse(date % year)
+          date = day.monday? ? day : day.next_monday
+          {
+            :name => holiday,
+            :date => date.to_s
+          }
+        end
+      end
+    end
+  end
+end

data/lib/holiday_co/calculate_holidays/pascua.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "date"
+require_relative "../utils"
+
+#  Dates are in YYYY-MM-DD format
+module HolidayCo
+  module CalculateHolidays
+    class Pascua
+      PASCUA_HOLIDAYS = {
+        "Jueves Santo" => {
+          operation: :-,
+          days: 3
+        },
+        "Viernes Santo" => {
+          operation: :-,
+          days: 2
+        },
+        "Ascención de Jesús" => {
+          operation: :+,
+          days: 43
+        },
+        "Corpus Christi" => {
+          operation: :+,
+          days: 64
+        },
+        "Sagrado Corazón de Jesús" => {
+          operation: :+,
+          days: 71
+        }
+      }
+
+      def self.for(year)
+        pascua_day = Date.parse(HolidayCo.pascua_day_per_year(year.to_i)[year.to_s])
+        PASCUA_HOLIDAYS.map do |holiday, ops|
+          {
+            :name => holiday,
+            :date => pascua_day.public_send(ops[:operation], ops[:days]).to_s
+          }
+        end
+      end
+    end
+  end
+end

data/lib/holiday_co/errors.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module HolidayCo
+  class YearDataNotAvailableError < StandardError
+    def message
+      "Colombian holidays can only be calculated for years #{AVAILABLE_YEARS.first} through #{AVAILABLE_YEARS.last}."
+    end
+  end
+end

data/lib/holiday_co/holiday_calculator.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative 'cache'
+require_relative 'calculate_holidays/fixed'
+require_relative 'calculate_holidays/movable'
+require_relative 'calculate_holidays/pascua'
+
+# Source of Calculation Rules: https://www.festivos.com.co/calculo
+module HolidayCo
+  class HolidayCalculator
+    attr_reader :year
+
+    def self.for(year)
+      year = year.to_i
+      return new(year).calculate unless HolidayCo.cache_enabled?
+
+      HolidayCo.cache.fetch(year) { new(year).calculate }
+    end
+
+    def initialize(year)
+      @year = year
+    end
+
+    # Results are deep-frozen: they are shared through the cache across
+    # callers and threads, so they must be immutable.
+    def calculate
+      [fixed_holidays, pascua_holidays, movable_holidays]
+        .flatten
+        .sort_by! { |h| h[:date] }
+        .each { |h| h[:date].freeze; h.freeze }
+        .freeze
+    end
+
+    private
+
+    def fixed_holidays
+      HolidayCo::CalculateHolidays::Fixed.for(year)
+    end
+
+    def pascua_holidays
+      HolidayCo::CalculateHolidays::Pascua.for(year)
+    end
+
+    def movable_holidays
+      HolidayCo::CalculateHolidays::Movable.for(year)
+    end
+  end
+end

data/lib/holiday_co/models/year.rb

@@ -1,14 +1,9 @@
 # frozen_string_literal: true
 
-require "yaml"
+require_relative "../errors"
+require_relative "../holiday_calculator"
 
 module HolidayCo
-  class YearDataNotAvailableError < StandardError
-    def message
-      "There is no data file available for the specified year (yet)."
-    end
-  end
-
   class Year
     attr_reader :year
 
@@ -19,10 +14,7 @@ module HolidayCo
     def holidays
       raise YearDataNotAvailableError unless year_data_available?
 
-      YAML
-        .load_file(File.expand_path("../../../../data/years/#{year}.yml", __FILE__))
-        .fetch("holidays", [])
-        .map { |h| h.transform_keys(&:to_sym) }
+      HolidayCalculator.for(year)
     end
 
     def holiday_names
@@ -36,13 +28,11 @@ module HolidayCo
     private
 
     def year_data_available?
-      available_years.include?(year)
+      available_years.include?(year.to_i)
     end
 
     def available_years
-      YAML
-        .load_file(File.expand_path("../../../../data/years.yml", __FILE__))
-        .map(&:to_s)
+      HolidayCo::AVAILABLE_YEARS
     end
   end
 end

data/lib/holiday_co/utils.rb

@@ -1,9 +1,13 @@
 require "date"
+require_relative "errors"
 
 module HolidayCo
   # Colombian time zone is 5 hours behind UTC.
   UTC_OFFSET = "-05:00".freeze
 
+  # Colombian Holidays started in 1983
+  AVAILABLE_YEARS = (1983..9999).freeze
+
   def self.current_time
     Time.now.getlocal(UTC_OFFSET)
   end
@@ -15,4 +19,70 @@ module HolidayCo
   def self.current_date
     current_time.to_date
   end
+
+  def self.pascua_day_per_year(year)
+    raise YearDataNotAvailableError unless AVAILABLE_YEARS.cover?(year)
+
+    calculate_pascua_day_per_year(year)
+  end
+
+  private
+
+  def self.calculate_pascua_day_per_year(year)
+    # The "Día de Pascua" (aka Domingo de Resurrección) plays a crucial role in determining
+    # 5 of the 18 holidays, but its calculation is unique. For more details, check out:
+    # https://blogs.elespectador.com/actualidad/algoritmo-calcular-las-fechas-la-semana-santa-ano
+    # This calculation is based on an astronomical algorithm that takes into account the lunar cycle,
+    # leap years, and the position of weekdays, which is used to calculate the exact date of
+    # pascua each year
+
+    lunar_cycle_position = year % 19 # a: Position in the lunar cycle
+    leap_year_indicator = year % 4  # b: Leap year indicator
+    week_day_position = year % 7    # c: Day of the week
+
+    century = year / 100            # d: Century of the year
+    leap_year_adjustment = (13 + 8 * century) / 25  # e: Adjustment for leap years in centuries
+    century_quarters = century / 4  # m: Adjustment for century quarters
+
+    lunar_adjustment = (15 - leap_year_adjustment + century - century_quarters) % 30  # n: Lunar adjustment for Easter date
+    weekday_adjustment = (4 + century - century_quarters) % 7  # p: Adjustment for weekday of March 22
+
+    march_22_offset = (19 * lunar_cycle_position + lunar_adjustment) % 30  # q: Lunar cycle position and adjustment
+
+    final_weekday_adjustment = (
+      (2 * leap_year_indicator) +
+      (4 * week_day_position) +
+      (6 * march_22_offset) +
+      weekday_adjustment
+    ) % 7  # r: Final weekday adjustment
+
+    pascua_offset = march_22_offset + final_weekday_adjustment
+    day, month = calculate_pascua_offset(pascua_offset)
+    day = adjust_day_for_pascua(day, month, march_22_offset, final_weekday_adjustment, lunar_cycle_position)
+
+    generate_pascua_date(year, month, day)
+  end
+
+  def self.calculate_pascua_offset(pascua_offset)
+    pascua_offset <= 9 ? [pascua_offset + 22, "03"] : [pascua_offset - 9, "04"]
+  end
+
+  def self.exception_date?(day, month)
+    [26, 25].include?(day) && month == "04"
+  end
+
+  def self.pascua_correction?(day, march_22_offset, days_to_sunday, lunar_cycle_position)
+    day == 26 || march_22_offset == 28 && days_to_sunday == 6 && lunar_cycle_position > 10
+  end
+
+  def self.adjust_day_for_pascua(day, month, march_22_offset, days_to_sunday, lunar_cycle_position)
+    return day unless exception_date?(day, month)
+    return day unless pascua_correction?(day, march_22_offset, days_to_sunday, lunar_cycle_position)
+
+    day -= 7
+  end
+
+  def self.generate_pascua_date(year, month, day)
+    { "#{year}" => "#{year}-#{month}-#{format('%02d', day)}" }
+  end
 end

data/lib/holiday_co/version.rb

@@ -1,3 +1,3 @@
 module HolidayCo
-  VERSION = "1.0.1"
+  VERSION = "2.0.0"
 end

data/lib/holiday_co.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "holiday_co/errors"
+require_relative "holiday_co/cache"
 require_relative "holiday_co/utils"
 require_relative "holiday_co/version"
 require_relative "holiday_co/models/day"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: holiday_co
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 2.0.0
 platform: ruby
 authors:
 - Gabriel Coronado
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-11-30 00:00:00.000000000 Z
+date: 2026-07-15 00:00:00.000000000 Z
 dependencies: []
 description: A simple gem to handle holidays in Colombia
 email:
@@ -17,12 +17,13 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- data/years.yml
-- data/years/2023.yml
-- data/years/2024.yml
-- data/years/2025.yml
-- data/years/2026.yml
 - lib/holiday_co.rb
+- lib/holiday_co/cache.rb
+- lib/holiday_co/calculate_holidays/fixed.rb
+- lib/holiday_co/calculate_holidays/movable.rb
+- lib/holiday_co/calculate_holidays/pascua.rb
+- lib/holiday_co/errors.rb
+- lib/holiday_co/holiday_calculator.rb
 - lib/holiday_co/models/day.rb
 - lib/holiday_co/models/year.rb
 - lib/holiday_co/utils.rb
@@ -39,7 +40,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="

data/data/years/2023.yml

@@ -1,39 +0,0 @@
-description: Lista de festivos Colombianos 2023
-source: https://www.festivos.com.co/
-holidays:
-- name: Año Nuevo
-  date: '2023-01-01'
-- name: Epifanía
-  date: '2023-01-09'
-- name: Día de San José
-  date: '2023-03-20'
-- name: Jueves Santo
-  date: '2023-04-06'
-- name: Viernes Santo
-  date: '2023-04-07'
-- name: Día del trabajo
-  date: '2023-05-01'
-- name: Ascención de Jesús
-  date: '2023-05-22'
-- name: Corpus Christi
-  date: '2023-06-12'
-- name: Sagrado Corazón de Jesús
-  date: '2023-06-19'
-- name: San Pedro y San Pablo
-  date: '2023-07-03'
-- name: Día de la independencia
-  date: '2023-07-20'
-- name: Batalla de Boyacá
-  date: '2023-08-07'
-- name: Asunción de la Virgen
-  date: '2023-08-21'
-- name: Día de la raza
-  date: '2023-10-16'
-- name: Todos los Santos
-  date: '2023-11-06'
-- name: Independencia de Cartagena
-  date: '2023-11-13'
-- name: Inmaculada Concepción
-  date: '2023-12-08'
-- name: Navidad
-  date: '2023-12-25'

data/data/years/2024.yml

@@ -1,39 +0,0 @@
-description: Lista de festivos Colombianos 2024
-source: https://www.festivos.com.co/
-holidays:
-- name: Año Nuevo
-  date: '2024-01-01'
-- name: Epifanía
-  date: '2024-01-08'
-- name: Día de San José
-  date: '2024-03-25'
-- name: Jueves Santo
-  date: '2024-03-28'
-- name: Viernes Santo
-  date: '2024-03-29'
-- name: Día del trabajo
-  date: '2024-05-01'
-- name: Ascención de Jesús
-  date: '2024-05-13'
-- name: Corpus Christi
-  date: '2024-06-03'
-- name: Sagrado Corazón de Jesús
-  date: '2024-06-10'
-- name: San Pedro y San Pablo
-  date: '2024-07-01'
-- name: Día de la independencia
-  date: '2024-07-20'
-- name: Batalla de Boyacá
-  date: '2024-08-07'
-- name: Asunción de la Virgen
-  date: '2024-08-19'
-- name: Día de la raza
-  date: '2024-10-14'
-- name: Todos los Santos
-  date: '2024-11-04'
-- name: Independencia de Cartagena
-  date: '2024-11-11'
-- name: Inmaculada Concepción
-  date: '2024-12-08'
-- name: Navidad
-  date: '2024-12-25'

data/data/years/2025.yml

@@ -1,43 +0,0 @@
-description: Lista de festivos Colombianos 2025
-source: https://www.festivos.com.co/
-holidays:
-- name: Año Nuevo
-  date: '2024-01-01'
-- name: Epifanía
-  date: '2024-01-08'
-- name: Año Nuevo
-  date: '2025-01-01'
-- name: Epifanía
-  date: '2025-01-06'
-- name: Día de San José
-  date: '2025-03-24'
-- name: Jueves Santo
-  date: '2025-04-17'
-- name: Viernes Santo
-  date: '2025-04-18'
-- name: Día del trabajo
-  date: '2025-05-01'
-- name: Ascención de Jesús
-  date: '2025-06-02'
-- name: Corpus Christi
-  date: '2025-06-23'
-- name: Sagrado Corazón de Jesús
-  date: '2025-06-30'
-- name: San Pedro y San Pablo
-  date: '2025-06-30'
-- name: Día de la independencia
-  date: '2025-07-20'
-- name: Batalla de Boyacá
-  date: '2025-08-07'
-- name: Asunción de la Virgen
-  date: '2025-08-18'
-- name: Día de la raza
-  date: '2025-10-13'
-- name: Todos los Santos
-  date: '2025-11-03'
-- name: Independencia de Cartagena
-  date: '2025-11-17'
-- name: Inmaculada Concepción
-  date: '2025-12-08'
-- name: Navidad
-  date: '2025-12-25'

data/data/years/2026.yml

@@ -1,39 +0,0 @@
-description: Lista de festivos Colombianos 2026
-source: https://www.festivos.com.co/
-holidays:
-  - name: Año Nuevo
-    date: '2026-01-01'
-  - name: Reyes Magos
-    date: '2026-01-12'
-  - name: Día de San José
-    date: '2026-03-23'
-  - name: Jueves Santo
-    date: '2026-04-02'
-  - name: Viernes Santo
-    date: '2026-04-03'
-  - name: Día del Trabajo
-    date: '2026-05-01'
-  - name: Ascensión de Jesús
-    date: '2026-05-18'
-  - name: Corpus Christi
-    date: '2026-06-08'
-  - name: Sagrado Corazón de Jesús
-    date: '2026-06-15'
-  - name: San Pedro y San Pablo
-    date: '2026-06-29'
-  - name: Día de la Independencia
-    date: '2026-07-20'
-  - name: Batalla de Boyacá
-    date: '2026-08-07'
-  - name: Asunción de la Virgen
-    date: '2026-08-17'
-  - name: Día de la Raza
-    date: '2026-10-12'
-  - name: Todos los Santos
-    date: '2026-11-02'
-  - name: Independencia de Cartagena
-    date: '2026-11-16'
-  - name: Inmaculada Concepción
-    date: '2026-12-08'
-  - name: Navidad
-    date: '2026-12-25'

data/data/years.yml

@@ -1,6 +0,0 @@
-# List any new supported year here (in addition to adding the .yml in years)
-
-- 2023
-- 2024
-- 2025
-- 2026