finrb 1.1.0 → 1.3.0

data/lib/finrb/amortization.rb

@@ -1,10 +1,14 @@
 # frozen_string_literal: true
 
+require_relative 'calendars'
 require_relative 'cashflows'
+require_relative 'day_count'
 require_relative 'decimal'
 require_relative 'precision'
+require_relative 'schedule'
 require_relative 'transaction'
 require_relative 'validation'
+require 'date'
 
 module Finrb
   # the Amortization class provides an interface for working with loan amortizations.
@@ -19,41 +23,49 @@ module Finrb
   #   rate = Rate.new(0.0425, :apr, :duration => (5 * 12))
   #   extra_payments = Finrb::Amortization.new(250000, rate){ |period| period.payment - 150 }
   class Amortization
+    FREQUENCY_MONTHS = Schedule::FREQUENCY_MONTHS
+    STUB_CONVENTIONS = Schedule::STUB_CONVENTIONS
+    public_constant :FREQUENCY_MONTHS, :STUB_CONVENTIONS
+
     # Immutable breakdown of one amortization period. Payments retain finrb's
     # cashflow sign convention and are negative; the other monetary fields are
     # non-negative.
     class Entry
       ATTRIBUTES = %i[period opening_balance payment interest principal additional_payment balloon_payment interest_only closing_balance].freeze
       MONETARY_ATTRIBUTES = ATTRIBUTES - %i[period interest_only]
-      private_constant :ATTRIBUTES, :MONETARY_ATTRIBUTES
+      DATE_ATTRIBUTE = :date
+      private_constant :ATTRIBUTES, :DATE_ATTRIBUTE, :MONETARY_ATTRIBUTES
 
-      attr_reader(*ATTRIBUTES)
+      attr_reader(*ATTRIBUTES, DATE_ATTRIBUTE)
 
-      def initialize(period:, opening_balance:, payment:, interest:, principal:, additional_payment:, balloon_payment:, interest_only:, closing_balance:)
+      def initialize(period:, opening_balance:, payment:, interest:, principal:, additional_payment:, balloon_payment:, interest_only:, closing_balance:, date: nil)
         raise(ArgumentError, 'period must be a non-negative integer.') unless period.is_a?(Integer) && !period.negative?
         raise(ArgumentError, 'interest_only must be true or false.') unless [true, false].include?(interest_only)
+        raise(ArgumentError, 'date must be a Date or nil.') unless date.nil? || date.instance_of?(Date)
 
         @period = period
         @interest_only = interest_only
+        @date = date
         MONETARY_ATTRIBUTES.each do |name|
           value = binding.local_variable_get(name)
-          instance_variable_set("@#{name}", Validation.decimal(value, name: name.to_s))
+          instance_variable_set("@#{name}", Validation.decimal(value, name: name.to_s.tr('_', ' ')))
         end
         freeze
       end
 
       def ==(other)
-        other.instance_of?(self.class) && ATTRIBUTES.all? { |name| public_send(name) == other.public_send(name) }
+        other.instance_of?(self.class) && ([DATE_ATTRIBUTE] + ATTRIBUTES).all? { |name| public_send(name) == other.public_send(name) }
       end
       alias eql? ==
 
       def hash
-        attributes = ATTRIBUTES.map { |name| public_send(name) }
-        attributes.hash
+        [date, *ATTRIBUTES.map { |name| public_send(name) }].hash
       end
 
       def to_h
-        ATTRIBUTES.to_h { |name| [name, public_send(name)] }
+        attributes = ATTRIBUTES.to_h { |name| [name, public_send(name)] }
+        attributes[DATE_ATTRIBUTE] = date unless date.nil?
+        attributes
       end
 
       alias interest_only? interest_only
@@ -71,7 +83,7 @@ module Finrb
     attr_reader :origination_fee
     # @return [Integer] number of leading periods that pay interest but no scheduled principal
     attr_reader :interest_only_periods
-    # @return [Flt::DecNum] the required monthly payment.  For loans with more than one rate, returns nil
+    # @return [Flt::DecNum] the required regular payment. For loans with more than one rate, returns nil
     attr_reader :payment
     # @return [Flt::DecNum] the principal amount of the loan
     attr_reader :principal
@@ -79,6 +91,18 @@ module Finrb
     attr_reader :rates
     # @return [Array<Entry>] immutable period-by-period loan breakdown
     attr_reader :schedule
+    # @return [Date, nil] the date from which payment dates are generated
+    attr_reader :start_date
+    # @return [Finrb::Calendars::Base, nil] the calendar used to adjust dated payments
+    attr_reader :calendar
+    # @return [Symbol, nil] business-day convention used when adjusting dated payments
+    attr_reader :business_day_convention
+    # @return [Symbol] day-count convention used for dated interest accrual
+    attr_reader :day_count
+    # @return [Symbol] interval between dated payments
+    attr_reader :frequency
+    # @return [Symbol] final partial-period handling
+    attr_reader :stub
 
     # @return [Flt::DecNum] the periodic payment due on a loan
     # @param [Flt::DecNum] principal the initial amount of the loan or investment
@@ -91,16 +115,14 @@ module Finrb
     #   Amortization.payment(200000, rate.monthly, rate.duration) #=> Flt::DecNum('-926.23')
     # @see https://en.wikipedia.org/wiki/Amortization_calculator
     def self.payment(principal, rate, periods, balloon: 0)
-      principal = Validation.decimal(principal, name: 'principal')
-      raise(ArgumentError, 'principal must be positive.') unless principal.positive?
+      principal = Validation.positive_decimal(principal, name: 'principal', message: 'principal must be positive.')
 
       balloon = Validation.decimal(balloon, name: 'balloon')
       raise(ArgumentError, 'balloon must be non-negative and no greater than principal.') unless balloon.between?(0, principal)
 
-      rate = Validation.decimal(rate, name: 'rate')
-      raise(ArgumentError, 'periodic rate must be greater than -1.') if rate <= -1
+      rate = Validation.decimal_greater_than(rate, minimum: -1, name: 'periodic rate')
 
-      periods = Validation.positive_integer(periods, name: 'periods')
+      periods = Validation.positive_integer(periods, name: 'period count')
 
       if rate.zero?
         # simplified formula to avoid division-by-zero when interest rate is zero
@@ -116,12 +138,19 @@ module Finrb
     # @param [Flt::DecNum] principal the initial amount of the loan or investment
     # @param [Rate] rates the applicable interest rates
     # @param [Proc] block
-    def initialize(principal, *rates, balloon: 0, interest_only_periods: 0, origination_fee: 0, finance_origination_fee: false, &block)
-      @principal = Validation.decimal(principal, name: 'principal')
-      raise(ArgumentError, 'principal must be positive.') unless @principal.positive?
+    # @param [Finrb::Calendars::Base, nil] calendar optional market calendar for dated payment adjustment
+    # @param [Symbol, nil] business_day_convention required when calendar is supplied
+    # @param [Symbol] frequency dated payment interval; rate durations remain in months
+    # @param [Symbol] stub explicit handling for a final partial dated period
+    def initialize(principal, *rates, balloon: 0, interest_only_periods: 0, origination_fee: 0, finance_origination_fee: false, start_date: nil, calendar: nil, business_day_convention: nil, day_count: DayCount::DEFAULT, frequency: :monthly, stub: :none, &block)
+      @principal = Validation.positive_decimal(principal, name: 'principal', message: 'principal must be positive.')
+      raise(ArgumentError, 'start_date must be a Date or nil.') unless start_date.nil? || start_date.instance_of?(Date)
+
+      validate_day_count!(start_date, day_count)
 
-      @origination_fee = Validation.decimal(origination_fee, name: 'origination_fee')
-      raise(ArgumentError, 'origination_fee must be non-negative.') if @origination_fee.negative?
+      validate_calendar_options!(start_date, calendar, business_day_convention)
+
+      @origination_fee = Validation.non_negative_decimal(origination_fee, name: 'origination fee')
       raise(ArgumentError, 'finance_origination_fee must be true or false.') unless [true, false].include?(finance_origination_fee)
       raise(ArgumentError, 'an unfinanced origination_fee must be less than principal.') if !finance_origination_fee && @origination_fee >= @principal
 
@@ -138,12 +167,16 @@ module Finrb
       @rates     = rates
       @block     = block
 
-      # compute the total duration from all of the rates.
-      @periods = rates.sum(&:duration)
+      initialize_schedule(start_date, frequency, stub, rates, calendar, business_day_convention)
+
       valid_interest_only = interest_only_periods.is_a?(Integer) && interest_only_periods.between?(0, @periods - 1)
       raise(ArgumentError, 'interest_only_periods must be a non-negative integer shorter than the loan term.') unless valid_interest_only
 
       @interest_only_periods = interest_only_periods
+      @start_date = start_date
+      @calendar = calendar
+      @business_day_convention = business_day_convention
+      @day_count = day_count
       @period = 0
 
       compute
@@ -153,7 +186,7 @@ module Finrb
     # @return [Numeric] -1, 0, or +1
     # @param [Amortization] other
     def ==(other)
-      (principal == other.principal) && (origination_fee == other.origination_fee) && (finance_origination_fee? == other.finance_origination_fee?) && (balloon == other.balloon) && (interest_only_periods == other.interest_only_periods) && (rates == other.rates) && (payments == other.payments)
+      (principal == other.principal) && (start_date == other.start_date) && (calendar == other.calendar) && (business_day_convention == other.business_day_convention) && (day_count == other.day_count) && (frequency == other.frequency) && (stub == other.stub) && (origination_fee == other.origination_fee) && (finance_origination_fee? == other.finance_origination_fee?) && (balloon == other.balloon) && (interest_only_periods == other.interest_only_periods) && (rates == other.rates) && (payments == other.payments)
     end
 
     attr_reader :finance_origination_fee
@@ -168,13 +201,31 @@ module Finrb
       @transactions.filter_map { |trans| trans.difference if trans.payment? }
     end
 
+    # Calculate the effective annual yield implied by borrower proceeds and
+    # scheduled loan payments. This is a cashflow-equivalent borrowing yield,
+    # not a jurisdiction-specific legal APR.
+    # @param [Numeric, nil] guess initial rate used by XIRR; defaults to Finrb.config.guess
+    # @return [Rate] the effective annual cashflow-equivalent yield
+    # @raise [ArgumentError] if the amortization has no start date
+    # @example
+    #   rate = Rate.new(0.05, :apr, duration: 12)
+    #   loan = Amortization.new(10_000, rate, start_date: Date.new(2025, 1, 15), origination_fee: 250)
+    #   loan.cashflow_yield.apy #=> effective annual borrower cost
+    def cashflow_yield(guess = nil)
+      raise(ArgumentError, 'cashflow_yield requires a start_date.') unless start_date
+
+      transactions = [Transaction.new(net_proceeds, date: start_date)]
+      transactions.concat(schedule.map { |entry| Transaction.new(entry.payment, date: entry.date) })
+      Cashflow.xirr(transactions, guess)
+    end
+
     # amortize the balance of loan with the given interest rate
     # @return none
     # @param [Rate] rate the interest rate to use in the amortization
-    def amortize(rate)
+    def amortize(rate, periods)
       regular_payment = nil
 
-      rate.duration.to_i.times do
+      periods.times do
         # Do this first in case the balance is zero already.
         break if @balance.zero?
 
@@ -182,13 +233,16 @@ module Finrb
         regular_payment ||= build_regular_payment(rate) unless interest_only
 
         # Compute and record interest on the outstanding balance.
-        int = Precision.money(@balance * rate.monthly)
-        interest = Interest.new(int, period: @period)
+        due_date = @payment_dates&.fetch(@period)
+        periodic_rate = due_date ? dated_period_rate(rate, @period) : rate.monthly
+        int = Precision.money(@balance * periodic_rate)
+        interest = Interest.new(int, period: @period, date: due_date)
         @balance += interest.amount
         @transactions << interest.dup
 
-        payment = interest_only ? build_interest_only_payment(int) : regular_payment
+        payment = interest_only ? build_interest_only_payment(int, due_date) : regular_payment
         payment.period = @period
+        payment.date = due_date if due_date
         payment.amount = -@balance if payment.amount.abs > @balance
         @additional_by_period << [-payment.difference, Flt::DecNum(0)].max
         @interest_only_by_period << interest_only
@@ -207,8 +261,8 @@ module Finrb
       @additional_by_period = []
       @interest_only_by_period = []
 
-      @rates.each do |rate|
-        amortize(rate)
+      @rates.each_with_index do |rate, index|
+        amortize(rate, @rate_period_counts.fetch(index))
       end
 
       # Add the residual balloon and any rounding remainder to the last payment.
@@ -230,7 +284,7 @@ module Finrb
 
     private :amortize, :compute
 
-    # @return [Integer] the time required to pay off the loan, in months
+    # @return [Integer] number of payments in the amortization schedule
     # @example In most cases, the duration is equal to the total duration of all rates
     #   rate = Rate.new(0.0375, :apr, :duration => (30 * 12))
     #   amt = Finrb::Amortization.new(300000, rate)
@@ -271,12 +325,66 @@ module Finrb
 
     private
 
+    def validate_calendar_options!(start_date, calendar, convention)
+      if calendar.nil?
+        raise(ArgumentError, 'business_day_convention requires a calendar.') unless convention.nil?
+
+        return
+      end
+
+      raise(ArgumentError, 'calendar must be a Finrb::Calendars::Base instance.') unless calendar.is_a?(Calendars::Base)
+      raise(ArgumentError, 'calendar adjustment requires a start_date.') unless start_date
+      raise(ArgumentError, "business_day_convention must be one of #{Calendars::Base::CONVENTIONS.join(', ')}.") unless Calendars::Base::CONVENTIONS.include?(convention)
+    end
+
+    def validate_day_count!(start_date, day_count)
+      raise(ArgumentError, "day_count must be one of #{DayCount::CONVENTIONS.join(', ')}.") unless DayCount::CONVENTIONS.include?(day_count)
+      raise(ArgumentError, 'a non-default day_count requires a start_date.') if start_date.nil? && day_count != DayCount::DEFAULT
+    end
+
+    def validate_schedule_options!(start_date, frequency, stub)
+      raise(ArgumentError, "frequency must be one of #{FREQUENCY_MONTHS.keys.join(', ')}.") unless FREQUENCY_MONTHS.key?(frequency)
+      raise(ArgumentError, "stub must be one of #{STUB_CONVENTIONS.join(', ')}.") unless STUB_CONVENTIONS.include?(stub)
+      raise(ArgumentError, 'a non-monthly frequency requires a start_date.') if start_date.nil? && frequency != :monthly
+      raise(ArgumentError, 'a non-default stub requires a start_date.') if start_date.nil? && stub != :none
+    end
+
+    def initialize_schedule(start_date, frequency, stub, rates, calendar, business_day_convention)
+      @term_months = rates.sum(&:duration)
+      validate_schedule_options!(start_date, frequency, stub)
+      @frequency = frequency
+      @stub = stub
+      @dated_schedule = start_date && Schedule.from_months(start_date:, term_months: @term_months, frequency:, stub:, calendar:, business_day_convention:)
+      @payment_dates = @dated_schedule&.payment_dates
+      @periods = @payment_dates ? @payment_dates.length : @term_months
+      @rate_period_counts = start_date ? periods_per_rate(rates, frequency, @periods) : rates.map(&:duration)
+    end
+
+    def periods_per_rate(rates, frequency, total_periods)
+      interval = FREQUENCY_MONTHS.fetch(frequency)
+      cumulative_months = 0
+      previous_period_count = 0
+      rates.each_with_index.map do |rate, index|
+        cumulative_months += rate.duration
+        if index == rates.length - 1
+          total_periods - previous_period_count
+        else
+          raise(ArgumentError, 'rate changes must align with a payment date for dated non-monthly schedules.') if (cumulative_months % interval).nonzero?
+
+          period_count = cumulative_months / interval
+          periods_in_segment = period_count - previous_period_count
+          previous_period_count = period_count
+          periods_in_segment
+        end
+      end
+    end
+
     def build_schedule
       opening_balance = @amount_financed
       @transactions.each_slice(2).with_index.map do |(interest, payment), index|
         principal = -(payment.amount + interest.amount)
         closing_balance = opening_balance - principal
-        entry = Entry.new(period: payment.period, opening_balance:, payment: payment.amount, interest: interest.amount, principal:, additional_payment: @additional_by_period.fetch(index), balloon_payment: @balloon_by_period.fetch(index), interest_only: @interest_only_by_period.fetch(index), closing_balance:)
+        entry = Entry.new(period: payment.period, opening_balance:, payment: payment.amount, interest: interest.amount, principal:, additional_payment: @additional_by_period.fetch(index), balloon_payment: @balloon_by_period.fetch(index), interest_only: @interest_only_by_period.fetch(index), closing_balance:, date: payment.date)
         opening_balance = closing_balance
         entry
       end
@@ -284,15 +392,20 @@ module Finrb
 
     def build_regular_payment(rate)
       periods = @periods - @period
-      amount = Amortization.payment(@balance, rate.monthly, periods, balloon: @balloon)
-      Payment.new(amount, period: @period).tap do |payment|
+      amount =
+        if @start_date
+          dated_payment(@balance, rate, @period, @balloon)
+        else
+          Amortization.payment(@balance, rate.monthly, periods, balloon: @balloon)
+        end
+      Payment.new(amount, period: @period, date: @payment_dates && @payment_dates.fetch(@period)).tap do |payment|
         payment.modify(&@block) if @block
         validate_payment!(payment)
       end
     end
 
-    def build_interest_only_payment(interest)
-      Payment.new(-interest, period: @period).tap do |payment|
+    def build_interest_only_payment(interest, date)
+      Payment.new(-interest, period: @period, date:).tap do |payment|
         payment.modify(&@block) if @block
         validate_payment!(payment, allow_zero: true)
       end
@@ -305,5 +418,24 @@ module Finrb
       requirement = allow_zero ? 'must not produce a positive amount' : 'must produce a negative amount'
       raise(ArgumentError, "payment modification #{requirement}.")
     end
+
+    def dated_period_rate(rate, period_index)
+      period = @dated_schedule.periods.fetch(period_index)
+      year_fraction = DayCount.year_fraction(period.accrual_start_date, period.payment_date, convention: @day_count)
+      periodic_rate = Precision.rate(rate.apr * year_fraction)
+      Validation.decimal_greater_than(periodic_rate, minimum: -1, name: 'dated periodic rate')
+    end
+
+    def dated_payment(balance, rate, period_index, balloon)
+      periods = (period_index...@periods).map { |index| dated_period_rate(rate, index) }
+      discount_factors = []
+      growth = Flt::DecNum('1')
+      periods.each do |periodic_rate|
+        growth *= periodic_rate + 1
+        discount_factors << (Flt::DecNum('1') / growth)
+      end
+      balloon_discounted = balloon * discount_factors.last
+      -Precision.money((balance - balloon_discounted) / discount_factors.sum)
+    end
   end
 end

data/lib/finrb/calendars/base.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require 'date'
+
+module Finrb
+  module Calendars
+    # A dated market calendar with explicit business-day adjustment rules.
+    class Base
+      CONVENTIONS = %i[following modified_following preceding modified_preceding half_month_modified_following nearest unadjusted].freeze
+      public_constant :CONVENTIONS
+
+      attr_reader :additional_holidays, :removed_holidays
+
+      def initialize(additional_holidays: [], removed_holidays: [])
+        @additional_holidays = validate_dates(additional_holidays, 'additional_holidays')
+        @removed_holidays = validate_dates(removed_holidays, 'removed_holidays')
+        freeze
+      end
+
+      def business_day?(date)
+        date = normalize_date(date)
+        !weekend?(date) && holiday_names(date).empty?
+      end
+
+      def holiday?(date)
+        !business_day?(date)
+      end
+
+      def holiday_names(date)
+        date = normalize_date(date)
+        names = @removed_holidays.include?(date) ? [] : holidays_for(date)
+        names += ['Additional market holiday'] if @additional_holidays.include?(date)
+        names.uniq.freeze
+      end
+
+      def holidays_between(start_date, end_date, include_weekends: false)
+        start_date = normalize_date(start_date)
+        end_date = normalize_date(end_date)
+        raise(ArgumentError, 'start_date must not be after end_date.') if start_date > end_date
+        raise(ArgumentError, 'include_weekends must be true or false.') unless [true, false].include?(include_weekends)
+
+        holidays =
+          (start_date..end_date).each_with_object({}) do |date, result|
+            names = holiday_names(date)
+            names = ['Weekend'].freeze if include_weekends && weekend?(date) && names.empty?
+            result[date] = names unless names.empty?
+          end
+        holidays.freeze
+      end
+
+      def ==(other)
+        other.instance_of?(self.class) && additional_holidays == other.additional_holidays && removed_holidays == other.removed_holidays
+      end
+      alias eql? ==
+
+      def hash
+        [self.class, additional_holidays, removed_holidays].hash
+      end
+
+      def adjust(date, convention:)
+        date = normalize_date(date)
+        raise(ArgumentError, "business-day convention must be one of #{CONVENTIONS.join(', ')}.") unless CONVENTIONS.include?(convention)
+
+        return date if convention == :unadjusted || business_day?(date)
+
+        case convention
+        when :following
+          seek_business_day(date, 1)
+        when :modified_following
+          following = seek_business_day(date, 1)
+          following.month == date.month ? following : seek_business_day(date, -1)
+        when :preceding
+          seek_business_day(date, -1)
+        when :modified_preceding
+          preceding = seek_business_day(date, -1)
+          preceding.month == date.month ? preceding : seek_business_day(date, 1)
+        when :half_month_modified_following
+          following = seek_business_day(date, 1)
+          crosses_month = following.month != date.month
+          crosses_midmonth = date.day <= 15 && following.day > 15
+          crosses_month || crosses_midmonth ? seek_business_day(date, -1) : following
+        when :nearest
+          nearest_business_day(date)
+        else
+          raise(ArgumentError, "unsupported business-day convention: #{convention}.")
+        end
+      end
+
+      def advance(date, business_days:, convention: :following)
+        date = normalize_date(date)
+        raise(ArgumentError, 'business_days must be an integer.') unless business_days.is_a?(Integer)
+        raise(ArgumentError, "business-day convention must be one of #{CONVENTIONS.join(', ')}.") unless CONVENTIONS.include?(convention)
+        return adjust(date, convention:) if business_days.zero?
+
+        direction = business_days.positive? ? 1 : -1
+        remaining = business_days.abs
+        advanced = date
+        while remaining.positive?
+          advanced += direction
+          remaining -= 1 if business_day?(advanced)
+        end
+        advanced
+      end
+
+      protected
+
+      def weekend?(_date)
+        raise(NotImplementedError, 'calendar subclasses must define their weekend days.')
+      end
+
+      def holidays_for(_date)
+        raise(NotImplementedError, 'calendar subclasses must define their market holidays.')
+      end
+
+      private
+
+      def normalize_date(date)
+        raise(ArgumentError, 'date must be a Date.') unless date.is_a?(Date)
+
+        normalized_date = Date.new(date.year, date.month, date.day, Date::GREGORIAN)
+        supported_dates = self.class::SUPPORTED_DATE_RANGE
+        return normalized_date if supported_dates.cover?(normalized_date)
+
+        raise(RangeError, "#{name} supports dates from #{supported_dates.begin} through #{supported_dates.end}.")
+      end
+
+      def validate_dates(dates, name)
+        raise(ArgumentError, "#{name} must be an array of Dates.") unless dates.is_a?(Array) && dates.all?(Date)
+
+        normalized_dates = []
+        dates.each do |date|
+          normalized_date = normalize_date(date)
+          normalized_dates << normalized_date unless normalized_dates.include?(normalized_date)
+        end
+        normalized_dates.freeze
+      end
+
+      def seek_business_day(date, direction)
+        candidate = date
+        370.times do
+          candidate += direction
+          return candidate if business_day?(candidate)
+        end
+        raise(ArgumentError, 'no business day found within one year of the requested date.')
+      end
+
+      def nearest_business_day(date)
+        distance = 1
+        loop do
+          preceding = date - distance
+          following = date + distance
+          return following if business_day?(following)
+          return preceding if business_day?(preceding)
+
+          distance += 1
+          raise(ArgumentError, 'no business day found within one year of the requested date.') if distance > 370
+        end
+      end
+    end
+  end
+end

data/lib/finrb/calendars/hebrew_calendar.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require 'date'
+
+module Finrb
+  module Calendars
+    # Arithmetic Hebrew calendar dates used for the TASE holiday rules.
+    module HebrewCalendar
+      ANCHOR_HEBREW_YEAR = 5785
+      ANCHOR_ROSH_HASHANAH = Date.new(2024, 10, 3, Date::GREGORIAN)
+      private_constant :ANCHOR_HEBREW_YEAR, :ANCHOR_ROSH_HASHANAH
+
+      module_function
+
+      def leap_year?(year)
+        ((year * 7) + 1) % 19 < 7
+      end
+
+      def date(year, month, day)
+        months = months_in_year(year)
+        raise(ArgumentError, 'invalid Hebrew month.') unless months.include?(month)
+
+        month_length = days_in_month(year, month)
+        raise(ArgumentError, 'invalid Hebrew day.') unless day.between?(1, month_length)
+
+        offset = 0
+        months.each do |candidate_month|
+          break if candidate_month == month
+
+          offset += days_in_month(year, candidate_month)
+        end
+        Date.jd(rosh_hashanah_jd(year) + offset + day - 1, Date::GREGORIAN)
+      end
+
+      def rosh_hashanah_jd(year)
+        ANCHOR_ROSH_HASHANAH.jd + elapsed_days(year) - elapsed_days(ANCHOR_HEBREW_YEAR)
+      end
+
+      def months_in_year(year)
+        after_tishri = (7..(leap_year?(year) ? 13 : 12)).to_a
+        after_tishri + (1..6).to_a
+      end
+
+      def days_in_month(year, month)
+        year_length = elapsed_days(year + 1) - elapsed_days(year)
+        case month
+        when 1, 3, 5, 7, 11
+          30
+        when 2, 4, 6, 10, 13
+          29
+        when 8
+          year_length % 10 == 5 ? 30 : 29
+        when 9
+          year_length % 10 == 3 ? 29 : 30
+        when 12
+          leap_year?(year) ? 30 : 29
+        else
+          raise(ArgumentError, 'invalid Hebrew month.')
+        end
+      end
+
+      def elapsed_days(year)
+        elapsed_months = ((year * 235) - 234) / 19
+        parts_elapsed = ((elapsed_months % 1080) * 793) + 204
+        hours_elapsed = (elapsed_months * 12) + 5 + ((elapsed_months / 1080) * 793) + (parts_elapsed / 1080)
+        day = (elapsed_months * 29) + 1 + (hours_elapsed / 24)
+        parts = ((hours_elapsed % 24) * 1080) + (parts_elapsed % 1080)
+
+        molad_postponement = parts >= 19_440 || ((day % 7) == 2 && parts >= 9_924 && !leap_year?(year)) || ((day % 7) == 1 && parts >= 16_789 && leap_year?(year - 1))
+        day += 1 if molad_postponement
+        day += 1 if [0, 3, 5].include?(day % 7)
+        day
+      end
+      private_class_method :elapsed_days, :days_in_month, :months_in_year, :rosh_hashanah_jd
+    end
+  end
+end