finrb 1.2.0 → 1.3.0

data/lib/finrb/schedule.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require_relative 'calendars'
+require 'date'
+
+module Finrb
+  # Immutable date schedule for recurring financial payments.
+  class Schedule
+    FREQUENCY_MONTHS = { monthly: 1, quarterly: 3, semiannual: 6, annual: 12 }.freeze
+    STUB_CONVENTIONS = %i[none short_final].freeze
+    public_constant :FREQUENCY_MONTHS, :STUB_CONVENTIONS
+
+    # Shared date rules used by both the class constructor and period builder.
+    module DateRules
+      module_function
+
+      def normalize(date, name)
+        raise(ArgumentError, "#{name} must be a Date.") unless date.instance_of?(Date)
+
+        Date.new(date.year, date.month, date.day, Date::GREGORIAN)
+      end
+
+      def anchored_date(anchor, month_offset)
+        month_start = Date.new(anchor.year, anchor.month, 1, Date::GREGORIAN) >> month_offset
+        next_month_start = month_start >> 1
+        month_end = next_month_start - 1
+        anchor_month_end = (Date.new(anchor.year, anchor.month, 1, Date::GREGORIAN) >> 1) - 1
+        day = anchor.day == anchor_month_end.day ? month_end.day : [anchor.day, month_end.day].min
+        Date.new(month_start.year, month_start.month, day, Date::GREGORIAN)
+      end
+    end
+    private_constant :DateRules
+
+    # Immutable dates and index for one accrual/payment period.
+    class Period
+      attr_reader :index, :accrual_start_date, :unadjusted_payment_date, :payment_date, :stub
+
+      def initialize(index:, accrual_start_date:, unadjusted_payment_date:, payment_date:, stub: nil)
+        @index = index
+        @accrual_start_date = accrual_start_date
+        @unadjusted_payment_date = unadjusted_payment_date
+        @payment_date = payment_date
+        @stub = stub
+        freeze
+      end
+
+      def short_final_stub?
+        stub == :short_final
+      end
+    end
+
+    attr_reader :start_date, :maturity_date, :frequency, :stub, :calendar, :business_day_convention, :periods, :payment_dates, :unadjusted_payment_dates
+
+    def self.from_months(start_date:, term_months:, frequency: :monthly, stub: :none, calendar: nil, business_day_convention: nil)
+      raise(ArgumentError, 'term_months must be a positive integer.') unless term_months.is_a?(Integer) && term_months.positive?
+
+      start_date = DateRules.normalize(start_date, 'start_date')
+      maturity_date = DateRules.anchored_date(start_date, term_months)
+      new(start_date:, maturity_date:, frequency:, stub:, calendar:, business_day_convention:)
+    end
+
+    def initialize(start_date:, maturity_date:, frequency: :monthly, stub: :none, calendar: nil, business_day_convention: nil)
+      @start_date = DateRules.normalize(start_date, 'start_date')
+      @maturity_date = DateRules.normalize(maturity_date, 'maturity_date')
+      raise(ArgumentError, 'maturity_date must be after start_date.') if @maturity_date <= @start_date
+      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)
+
+      validate_calendar_options!(calendar, business_day_convention)
+      @frequency = frequency
+      @stub = stub
+      @calendar = calendar
+      @business_day_convention = business_day_convention
+      @unadjusted_payment_dates = build_unadjusted_payment_dates.freeze
+      @periods = build_periods.freeze
+      @payment_dates = @periods.map(&:payment_date).freeze
+      freeze
+    end
+
+    private
+
+    def validate_calendar_options!(calendar, convention)
+      raise(ArgumentError, 'business_day_convention requires a calendar.') if calendar.nil? && !convention.nil?
+      return if calendar.nil?
+
+      raise(ArgumentError, 'calendar must be a Finrb::Calendars::Base instance.') unless calendar.is_a?(Calendars::Base)
+      raise(ArgumentError, "business_day_convention must be one of #{Calendars::Base::CONVENTIONS.join(', ')}.") unless Calendars::Base::CONVENTIONS.include?(convention)
+    end
+
+    def build_unadjusted_payment_dates
+      interval = FREQUENCY_MONTHS.fetch(frequency)
+      dates = []
+      month_offset = interval
+      loop do
+        regular_date = DateRules.anchored_date(start_date, month_offset)
+        if regular_date < maturity_date
+          dates << regular_date
+          month_offset += interval
+        elsif regular_date == maturity_date
+          dates << regular_date
+          break
+        else
+          raise(ArgumentError, 'maturity_date does not align with frequency; pass stub: :short_final to allow a short final period.') unless stub == :short_final
+
+          dates << maturity_date
+          break
+        end
+      end
+      dates
+    end
+
+    def build_periods
+      previous_payment_date = start_date
+      unadjusted_payment_dates.each_with_index.map do |unadjusted_date, index|
+        regular_date = DateRules.anchored_date(start_date, FREQUENCY_MONTHS.fetch(frequency) * (index + 1))
+        period_stub = :short_final if index == unadjusted_payment_dates.length - 1 && regular_date != unadjusted_date
+        payment_date = calendar ? calendar.adjust(unadjusted_date, convention: business_day_convention) : unadjusted_date
+        raise(ArgumentError, 'calendar adjustment must produce dates strictly after the prior payment date.') if payment_date <= previous_payment_date
+
+        period = Period.new(index:, accrual_start_date: previous_payment_date, unadjusted_payment_date: unadjusted_date, payment_date:, stub: period_stub)
+        previous_payment_date = payment_date
+        period
+      end
+    end
+  end
+end

data/lib/finrb/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module Finrb
-  VERSION = '1.2.0'
+  VERSION = '1.3.0'
   public_constant :VERSION
 end

data/lib/finrb.rb

@@ -1,13 +1,16 @@
 # frozen_string_literal: true
 
 require 'finrb/accounting'
+require 'finrb/calendars'
 require 'finrb/cashflows'
 require 'finrb/config'
+require 'finrb/day_count'
 require 'finrb/decimal'
 require 'finrb/errors'
 require 'finrb/precision'
 require 'finrb/ratios'
 require 'finrb/returns'
+require 'finrb/schedule'
 require 'finrb/tvm'
 require 'finrb/version'
 require 'finrb/yields'
@@ -23,6 +26,7 @@ FinrbError = Finrb::Error
 #  * *rate* represents the interest rate _per period_.
 module Finrb
   autoload :Amortization, 'finrb/amortization'
+  autoload :FixedRateBond, 'finrb/fixed_rate_bond'
   autoload :Rate,         'finrb/rates'
   autoload :Transaction,  'finrb/transaction'
 end

data/sig/finrb.rbs

@@ -42,9 +42,104 @@ module Finrb
   class DomainError < Error
   end
 
+  module Calendars
+    type convention = :following | :modified_following | :preceding | :modified_preceding | :half_month_modified_following | :nearest | :unadjusted
+
+    class Base
+      CONVENTIONS: Array[Symbol]
+
+      def initialize: (?additional_holidays: Array[Date], ?removed_holidays: Array[Date]) -> void
+      def additional_holidays: () -> Array[Date]
+      def removed_holidays: () -> Array[Date]
+      def business_day?: (Date) -> bool
+      def holiday?: (Date) -> bool
+      def holiday_names: (Date) -> Array[String]
+      def holidays_between: (Date, Date, ?include_weekends: bool) -> Hash[Date, Array[String]]
+      def adjust: (Date, convention: convention) -> Date
+      def advance: (Date, business_days: Integer, ?convention: convention) -> Date
+      def ==: (untyped) -> bool
+      def eql?: (untyped) -> bool
+      def hash: () -> Integer
+    end
+
+    class USFederalReserve < Base
+      SUPPORTED_START_DATE: Date
+      SUPPORTED_END_DATE: Date
+      SUPPORTED_DATE_RANGE: Range[Date]
+      def name: () -> String
+    end
+
+    class IsraelTase < Base
+      SUPPORTED_START_DATE: Date
+      SUPPORTED_END_DATE: Date
+      SUPPORTED_DATE_RANGE: Range[Date]
+      TRADING_WEEK_CHANGE: Date
+      def name: () -> String
+    end
+  end
+
+  module DayCount
+    type convention = :actual_365_fixed | :actual_360 | :actual_actual_icma
+    CONVENTIONS: Array[convention]
+    DEFAULT: convention
+
+    def self.year_fraction: (Date, Date, ?convention: convention, ?reference_period_start: Date?, ?reference_period_end: Date?, ?frequency: Integer?) -> decimal
+  end
+
+  class Schedule
+    type frequency = :monthly | :quarterly | :semiannual | :annual
+    type stub = :none | :short_final
+
+    FREQUENCY_MONTHS: Hash[frequency, Integer]
+    STUB_CONVENTIONS: Array[stub]
+
+    class Period
+      def initialize: (index: Integer, accrual_start_date: Date, unadjusted_payment_date: Date, payment_date: Date, ?stub: stub?) -> void
+      def index: () -> Integer
+      def accrual_start_date: () -> Date
+      def unadjusted_payment_date: () -> Date
+      def payment_date: () -> Date
+      def stub: () -> stub?
+      def short_final_stub?: () -> bool
+    end
+
+    def self.from_months: (start_date: Date, term_months: Integer, ?frequency: frequency, ?stub: stub, ?calendar: Calendars::Base?, ?business_day_convention: Calendars::convention?) -> Schedule
+    def initialize: (start_date: Date, maturity_date: Date, ?frequency: frequency, ?stub: stub, ?calendar: Calendars::Base?, ?business_day_convention: Calendars::convention?) -> void
+    def start_date: () -> Date
+    def maturity_date: () -> Date
+    def frequency: () -> frequency
+    def stub: () -> stub
+    def calendar: () -> Calendars::Base?
+    def business_day_convention: () -> Calendars::convention?
+    def periods: () -> Array[Period]
+    def payment_dates: () -> Array[Date]
+    def unadjusted_payment_dates: () -> Array[Date]
+  end
+
   class InvalidCashflowError < Error
   end
 
+  class FixedRateBond
+    type price_type = :clean | :dirty
+    PRICE_TYPES: Array[price_type]
+
+    def initialize: (face_value: number, coupon_rate: number, issue_date: Date, maturity_date: Date, ?frequency: Schedule::frequency, ?calendar: Calendars::Base?, ?business_day_convention: Calendars::convention?) -> void
+    def face_value: () -> decimal
+    def coupon_rate: () -> decimal
+    def issue_date: () -> Date
+    def maturity_date: () -> Date
+    def frequency: () -> Schedule::frequency
+    def schedule: () -> Schedule
+    def calendar: () -> Calendars::Base?
+    def business_day_convention: () -> Calendars::convention?
+    def day_count: () -> :actual_actual_icma
+    def cashflows: (settlement_date: Date) -> Array[Transaction]
+    def accrued_interest: (settlement_date: Date) -> decimal
+    def dirty_price: (settlement_date: Date, yield_rate: number) -> decimal
+    def clean_price: (settlement_date: Date, yield_rate: number) -> decimal
+    def yield_to_maturity: (settlement_date: Date, price: number, ?price_type: price_type, ?guess: number) -> decimal
+  end
+
   module Precision
     def self.money: (number) -> decimal
     def self.rate: (number) -> decimal
@@ -94,8 +189,14 @@ module Finrb
   end
 
   class Amortization
+    type frequency = :monthly | :quarterly | :semiannual | :annual
+    type stub = :none | :short_final
+
+    FREQUENCY_MONTHS: Hash[frequency, Integer]
+    STUB_CONVENTIONS: Array[stub]
+
     class Entry
-      def initialize: (period: Integer, opening_balance: number, payment: number, interest: number, principal: number, additional_payment: number, balloon_payment: number, interest_only: bool, closing_balance: number) -> void
+      def initialize: (period: Integer, opening_balance: number, payment: number, interest: number, principal: number, additional_payment: number, balloon_payment: number, interest_only: bool, closing_balance: number, ?date: Date?) -> void
       def period: () -> Integer
       def opening_balance: () -> decimal
       def payment: () -> decimal
@@ -106,15 +207,16 @@ module Finrb
       def interest_only: () -> bool
       def interest_only?: () -> bool
       def closing_balance: () -> decimal
+      def date: () -> Date?
       def ==: (untyped) -> bool
       def eql?: (untyped) -> bool
       def hash: () -> Integer
-      def to_h: () -> Hash[Symbol, Integer | decimal]
+      def to_h: () -> Hash[Symbol, Integer | decimal | bool | Date]
     end
 
     def self.payment: (number, number, Integer, ?balloon: number) -> decimal
 
-    def initialize: (number, *Rate, ?balloon: number, ?interest_only_periods: Integer, ?origination_fee: number, ?finance_origination_fee: bool) ?{ (Transaction) -> number } -> void
+    def initialize: (number, *Rate, ?balloon: number, ?interest_only_periods: Integer, ?origination_fee: number, ?finance_origination_fee: bool, ?start_date: Date?, ?calendar: Calendars::Base?, ?business_day_convention: Calendars::convention?, ?day_count: DayCount::convention, ?frequency: frequency, ?stub: stub) ?{ (Transaction) -> number } -> void
     def ==: (untyped) -> bool
     def balance: () -> decimal
     def balloon: () -> decimal
@@ -128,7 +230,14 @@ module Finrb
     def principal: () -> decimal
     def rates: () -> Array[Rate]
     def schedule: () -> Array[Entry]
+    def start_date: () -> Date?
+    def calendar: () -> Calendars::Base?
+    def business_day_convention: () -> Calendars::convention?
+    def day_count: () -> DayCount::convention
+    def frequency: () -> frequency
+    def stub: () -> stub
     def additional_payments: () -> Array[decimal]
+    def cashflow_yield: (?number) -> Rate
     def duration: () -> Integer
     def inspect: () -> String
     def interest: () -> Array[decimal]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: finrb
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Nadir Cohen
@@ -271,19 +271,27 @@ files:
 - lib/finrb.rb
 - lib/finrb/accounting.rb
 - lib/finrb/amortization.rb
+- lib/finrb/calendars.rb
+- lib/finrb/calendars/base.rb
+- lib/finrb/calendars/hebrew_calendar.rb
+- lib/finrb/calendars/israel_tase.rb
+- lib/finrb/calendars/us_federal_reserve.rb
 - lib/finrb/cashflows.rb
 - lib/finrb/config.rb
 - lib/finrb/core_ext.rb
 - lib/finrb/core_ext/array.rb
 - lib/finrb/core_ext/numeric.rb
+- lib/finrb/day_count.rb
 - lib/finrb/decimal.rb
 - lib/finrb/errors.rb
+- lib/finrb/fixed_rate_bond.rb
 - lib/finrb/numerical/brent.rb
 - lib/finrb/numerical/rate_search.rb
 - lib/finrb/precision.rb
 - lib/finrb/rates.rb
 - lib/finrb/ratios.rb
 - lib/finrb/returns.rb
+- lib/finrb/schedule.rb
 - lib/finrb/transaction.rb
 - lib/finrb/tvm.rb
 - lib/finrb/validation.rb
@@ -313,7 +321,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.19
+rubygems_version: 4.0.22
 specification_version: 4
 summary: Precision-first financial mathematics for Ruby
 test_files: []