make_a_calendar_toolkit 0.1.0

data/lib/make_a_calendar/scheduling/fiscal.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "date"
+
+module MakeACalendar
+  FiscalPeriod = Struct.new(:number, :start_date, :end_date, :quarter, :weeks, keyword_init: true) do
+    def to_h
+      { number: number, start_date: start_date.iso8601, end_date: end_date.iso8601, quarter: quarter, weeks: weeks }
+    end
+  end
+
+  class FiscalCalendar
+    attr_reader :label_year, :start_date, :end_date, :pattern, :periods
+
+    def initialize(year:, pattern: :four_four_five, extra_week: :last_period, label: :ending_year)
+      @label_year = Integer(year)
+      @pattern = normalize_pattern(pattern).freeze
+      raise ArgumentError, "extra_week must be :last_period or :first_period" unless %i[last_period first_period].include?(extra_week.to_sym)
+      raise ArgumentError, "label must be :ending_year or :starting_year" unless %i[ending_year starting_year].include?(label.to_sym)
+      start_year = label.to_sym == :ending_year ? @label_year - 1 : @label_year
+      next_start_year = start_year + 1
+      @start_date = nearest_sunday(Date.new(start_year, 2, 1))
+      next_start = nearest_sunday(Date.new(next_start_year, 2, 1))
+      weeks = ((next_start - @start_date).to_i / 7)
+      raise Error, "retail fiscal year must have 52 or 53 weeks" unless [52, 53].include?(weeks)
+      @end_date = next_start - 1
+      lengths = @pattern * 4
+      if weeks == 53
+        extra_week.to_sym == :last_period ? lengths[-1] += 1 : lengths[0] += 1
+      end
+      cursor = @start_date
+      @periods = lengths.each_with_index.map do |period_weeks, index|
+        period_end = cursor + (period_weeks * 7) - 1
+        period = FiscalPeriod.new(number: index + 1, start_date: cursor, end_date: period_end,
+                                  quarter: index / 3 + 1, weeks: period_weeks).freeze
+        cursor = period_end + 1
+        period
+      end.freeze
+      freeze
+    end
+
+    def period_for(date)
+      date = DateMath.date(date)
+      periods.find { |period| date >= period.start_date && date <= period.end_date }
+    end
+
+    def to_h
+      { label_year: label_year, start_date: start_date.iso8601, end_date: end_date.iso8601,
+        weeks: ((end_date - start_date + 1).to_i / 7), pattern: pattern, periods: periods.map(&:to_h) }
+    end
+
+    private
+
+    def normalize_pattern(value)
+      key = value.to_s.downcase.delete("_").delete("-")
+      patterns = { "445" => [4, 4, 5], "454" => [4, 5, 4], "544" => [5, 4, 4],
+                   "fourfourfive" => [4, 4, 5], "fourfivefour" => [4, 5, 4], "fivefourfour" => [5, 4, 4] }
+      patterns.fetch(key) { raise ArgumentError, "pattern must be 445, 454, or 544" }
+    end
+
+    def nearest_sunday(date)
+      before = date - date.wday
+      after = before + 7
+      (date - before).to_i <= (after - date).to_i ? before : after
+    end
+  end
+end

data/lib/make_a_calendar/scheduling/holidays.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "date"
+
+module MakeACalendar
+  Holiday = Struct.new(:name, :date, :observed_date, keyword_init: true) do
+    def to_h
+      { name: name, date: date.iso8601, observed_date: observed_date.iso8601 }
+    end
+  end
+
+  module Holidays
+    module_function
+
+    def us_federal(year)
+      year = Integer(year)
+      holidays = []
+      add = lambda do |name, day|
+        observed = day.saturday? ? day - 1 : (day.sunday? ? day + 1 : day)
+        holidays << Holiday.new(name: name, date: day, observed_date: observed).freeze
+      end
+      add.call("New Year's Day", Date.new(year, 1, 1)) if year >= 1870
+      add.call("Birthday of Martin Luther King, Jr.", nth_weekday(year, 1, 1, 3)) if year >= 1986
+      washington = year >= 1971 ? nth_weekday(year, 2, 1, 3) : Date.new(year, 2, 22)
+      add.call("Washington's Birthday", washington) if year >= 1879
+      memorial = year >= 1971 ? last_weekday(year, 5, 1) : Date.new(year, 5, 30)
+      add.call("Memorial Day", memorial) if year >= 1888
+      add.call("Juneteenth National Independence Day", Date.new(year, 6, 19)) if year >= 2021
+      add.call("Independence Day", Date.new(year, 7, 4)) if year >= 1870
+      add.call("Labor Day", nth_weekday(year, 9, 1, 1)) if year >= 1894
+      add.call("Columbus Day", nth_weekday(year, 10, 1, 2)) if year >= 1971
+      veterans = (1971..1977).cover?(year) ? nth_weekday(year, 10, 1, 4) : Date.new(year, 11, 11)
+      add.call("Veterans Day", veterans) if year >= 1938
+      thanksgiving = year >= 1939 ? nth_weekday(year, 11, 4, 4) : last_weekday(year, 11, 4)
+      add.call("Thanksgiving Day", thanksgiving) if year >= 1863
+      add.call("Christmas Day", Date.new(year, 12, 25)) if year >= 1870
+      holidays.freeze
+    end
+
+    def for_years(first_year, last_year = first_year)
+      (Integer(first_year)..Integer(last_year)).flat_map { |year| us_federal(year) }
+    end
+
+    def observed_dates(first_year, last_year = first_year)
+      # Include adjacent legal years because a Saturday New Year's Day is observed on Dec 31.
+      for_years(Integer(first_year) - 1, Integer(last_year) + 1).map(&:observed_date).uniq.freeze
+    end
+
+    def nth_weekday(year, month, wday, occurrence)
+      first = Date.new(year, month, 1)
+      first + ((wday - first.wday) % 7) + 7 * (occurrence - 1)
+    end
+
+    def last_weekday(year, month, wday)
+      last = (Date.new(year, month, 1) >> 1) - 1
+      last - ((last.wday - wday) % 7)
+    end
+    private_class_method :nth_weekday, :last_weekday
+  end
+end

data/lib/make_a_calendar/scheduling/recurring.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "date"
+
+module MakeACalendar
+  module Scheduling
+    module_function
+
+    def pay_dates(start_date:, end_date:, frequency:, anchor: nil, adjust: :none, weekend: [0, 6], holidays: [])
+      first = DateMath.date(start_date)
+      last = DateMath.date(end_date)
+      raise ArgumentError, "schedule range is limited to 100 years" if (last - first).abs > BusinessDays::MAX_RANGE_DAYS
+      dates = case frequency.to_sym
+              when :weekly, :biweekly
+                interval = frequency.to_sym == :weekly ? 7 : 14
+                cursor = DateMath.date(anchor || first)
+                cursor += interval while cursor < first
+                list = []
+                while cursor <= last
+                  list << cursor
+                  cursor += interval
+                end
+                list
+              when :semi_monthly
+                semi_monthly_dates(first, last, anchor)
+              when :monthly
+                monthly_dates(first, last, anchor)
+              else
+                raise ArgumentError, "frequency must be weekly, biweekly, semi_monthly, or monthly"
+              end
+      dates.map do |date|
+        case adjust.to_sym
+        when :none then date
+        when :following then move_to_workday(date, 1, weekend, holidays)
+        when :preceding then move_to_workday(date, -1, weekend, holidays)
+        when :modified_following
+          moved = move_to_workday(date, 1, weekend, holidays)
+          moved.month == date.month ? moved : move_to_workday(date, -1, weekend, holidays)
+        else raise ArgumentError, "adjust must be none, following, preceding, or modified_following"
+        end
+      end.uniq.freeze
+    end
+
+    def shift_dates(start_date:, end_date:, pattern:, anchor: nil)
+      first = DateMath.date(start_date)
+      last = DateMath.date(end_date)
+      raise ArgumentError, "schedule range is limited to 100 years" if (last - first).abs > BusinessDays::MAX_RANGE_DAYS
+      cycle = pattern.is_a?(String) ? pattern.split("-").map { |part| Integer(part) } : pattern.map { |part| Integer(part) }
+      raise ArgumentError, "pattern must contain positive on/off lengths" if cycle.empty? || cycle.any? { |part| part <= 0 }
+      anchor_date = DateMath.date(anchor || first)
+      DateMath.each_date(first, last).map do |date|
+        offset = (date - anchor_date).to_i % cycle.sum
+        segment_start = 0
+        segment_index = cycle.index do |segment_length|
+          covered = offset < segment_start + segment_length
+          segment_start += segment_length unless covered
+          covered
+        end
+        on_duty = segment_index.even?
+        { date: date, on_duty: on_duty, cycle_day: offset + 1 }.freeze
+      end.freeze
+    end
+
+    def semi_monthly_dates(first, last, anchor)
+      day = anchor ? DateMath.date(anchor).day : 15
+      dates = []
+      cursor = Date.new(first.year, first.month, 1)
+      while cursor <= last
+        month_end = (cursor >> 1) - 1
+        [Date.new(cursor.year, cursor.month, [day, month_end.day].min), month_end].each do |date|
+          dates << date if date >= first && date <= last
+        end
+        cursor = cursor >> 1
+      end
+      dates.uniq.sort
+    end
+
+    def monthly_dates(first, last, anchor)
+      requested_day = anchor ? DateMath.date(anchor).day : 1
+      dates = []
+      cursor = Date.new(first.year, first.month, 1)
+      while cursor <= last
+        month_end = (cursor >> 1) - 1
+        date = Date.new(cursor.year, cursor.month, [requested_day, month_end.day].min)
+        dates << date if date >= first && date <= last
+        cursor = cursor >> 1
+      end
+      dates
+    end
+
+    def move_to_workday(date, direction, weekend, holidays)
+      current = date
+      weekend_days = weekend.map { |day| DateMath.weekday_index(day) }
+      holiday_dates = holidays.map { |holiday| holiday.respond_to?(:observed_date) ? holiday.observed_date : DateMath.date(holiday) }
+      current += direction while weekend_days.include?(current.wday) || holiday_dates.include?(current)
+      current
+    end
+    private_class_method :semi_monthly_dates, :monthly_dates, :move_to_workday
+  end
+end

data/lib/make_a_calendar/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module MakeACalendar
+  VERSION = "0.1.0".freeze
+end

data/lib/make_a_calendar.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "date"
+require_relative "make_a_calendar/version"
+require_relative "make_a_calendar/errors"
+require_relative "make_a_calendar/core/date_math"
+require_relative "make_a_calendar/scheduling/holidays"
+require_relative "make_a_calendar/scheduling/business_days"
+require_relative "make_a_calendar/scheduling/recurring"
+require_relative "make_a_calendar/scheduling/fiscal"
+require_relative "make_a_calendar/converters"
+require_relative "make_a_calendar/calendar"
+require_relative "make_a_calendar/export/ics"
+
+module MakeACalendar
+  module_function
+
+  # Build an immutable month grid. Weekdays use Sunday=0 through Saturday=6.
+  def month(year:, month:, week_start: :sunday, fixed_rows: nil, holidays: [])
+    Calendar.new(year: year, month: month, week_start: week_start, fixed_rows: fixed_rows, holidays: holidays)
+  end
+
+  # Build a twelve-month printable calendar.
+  def year(year:, week_start: :sunday, holidays: [])
+    YearCalendar.new(year: year, week_start: week_start, holidays: holidays)
+  end
+
+  # Count workdays in an inclusive date range by default.
+  def business_days_between(from, to, **options)
+    BusinessDays.between(from, to, **options)
+  end
+
+  # Add business days; the start date is not counted when days is nonzero.
+  def add_business_days(date, days, **options)
+    BusinessDays.add(date, days, **options)
+  end
+
+  # Return the US federal holiday rules for a calendar year.
+  def federal_holidays(year)
+    Holidays.us_federal(year)
+  end
+
+  # Create an NRF-style retail fiscal calendar named for its ending year.
+  def fiscal_calendar(year:, pattern: :four_four_five, extra_week: :last_period, label: :ending_year)
+    FiscalCalendar.new(year: year, pattern: pattern, extra_week: extra_week, label: label)
+  end
+
+  # Build date-only events as an RFC 5545 iCalendar string.
+  def to_ics(events, name: "Make a Calendar Toolkit")
+    ICS.calendar(events, name: name)
+  end
+end