loan_creator 0.8.0 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c39773817a99d44a421aac19ea019f43ba24bba4359f8f61630b480f47662c65
-  data.tar.gz: b645544fb96db2d5bf60c8b8e811e8b08e54d49d7c5fb62f2af4d54e4619d64d
+  metadata.gz: 4dcaafbce29a00ebcdea57133619e566cc210be6ed613003af14e0a199cc126a
+  data.tar.gz: 2da6fe223cfc40fd8455a5c1ec0d8ef857bfd48effb22b285f46da7c3800a81b
 SHA512:
-  metadata.gz: e24e2f465c85252f8654a62fc252f0f82f75ffd0690b90ee586517769ad7055d24cecd4e7694f73dc6e54f2260969bffff01f65864e161e2cd89e5bb817477ac
-  data.tar.gz: 7428313e7ca37b6f10b5f20375c007ea1af3d00a1dc7ed95f0d82a56543267a7c37f7604a931f541c2a93ca1bb953d15d774fa7cad064ef08c846c40adfa8ca0
+  metadata.gz: 215f9a9b34c5ac6f9eef09f8658bbcd7c322e1964f0d4a0c9f55d3f97c99d1c9fc804c9e69f2c5509085bca9ec6ed848e92561ce456d6348d7b5ea343e38ada6
+  data.tar.gz: 98b6cf146fd802777c156266cd9378d8816ef00d4c4ab8aafdc092f4b52b001e2b8862d61a260502803f888f3b7f0f1b34bea5e29ea4a5843f8b01b5d99ce729

data/CHANGELOG.md

@@ -1,14 +1,18 @@
+v0.8.1
+-------------------------
+- add `realistic_durations` option
+
 v0.8.0
 -------------------------
 
-### FEATURE
+#### Feature
 - due interests to date are now store into `due_interests_` columns for `LoanCreator::UncapitalizedBullet`
 
-### BUGFIX
+#### Bugfix
 - fix `initial_values` not taking `paid_capital` and `paid_interests` into account for `LoanCreator::UncapitalizedBullet`
   and `LoanCreator::Bullet`
 
-### BREAKING CHANGES
+#### Breaking changes
 - rename columns `capitalized_interests_beginning_of_period` and `capitalized_interests_end_of_period` for
   `due_interests_beginning_of_period` and `due_interests_end_of_period`
 - rename `capitalized_interests` option in `:inital_values` into `due_interests`

data/README.md

@@ -44,9 +44,10 @@ Each instance of one of the previous classes has the following attributes:
     :annual_interests_rate
     :starts_at
     :duration_in_periods
-    :deferred_in_periods (default to zero)
+    :deferred_in_periods (defaults to zero)
     :interests_start_date (optional)
     :initial_values (to generate a timetable from a previous term or at a given state)
+    :realistic_durations (optional, defaults to false)
 ```
 
 Initial values must be a hash with specific keys, like so:
@@ -102,6 +103,9 @@ There is also a `LoanCreator::Timetable` class dedicated to record the data of t
 
       # Amount to pay this term
       :period_amount_to_pay
+
+      # Whether or not to use the real number of days in each month
+      :realistic_durations
 ```
 
 `#periodic_interests_rate` renders a precise calculation of the loan's periodic interests rate based on two inputs: `#annual_interests_rate` and `#period`.
@@ -176,6 +180,9 @@ additional term with only interests for the time difference.
 For example, with a `start_at` in january 2020 and a `interests_start_date` in october 2019, the timetable will include a
 first term corresponding to 3 months of interests.
 
+`realistic_durations`: Optional. A boolean tha specifies whether or not to use the real number of days in each month when calculating the periodic interests rate. Note that leap years are taken into account. Default: `false`.
+The default behaviour is to use the `period` in relation to the number of months in a year (ie: 12)
+
 ## Calculation
 
 An excel simulator for standard case can be found [here](CapSens_Loan.xlsx).

data/lib/loan_creator/borrower_timetable.rb

@@ -21,8 +21,7 @@ module LoanCreator
 
       borrower_timetable = LoanCreator::Timetable.new(
         starting_index: lenders_timetables.first.starting_index,
-        starts_on: lenders_timetables.first.starts_on,
-        period: lenders_timetables.first.period
+        loan: lenders_timetables.first.loan
       )
 
       # Borrower timetable is not concerned with computation-related value (delta, etc.),

data/lib/loan_creator/bullet.rb

@@ -7,18 +7,24 @@ module LoanCreator
       reset_current_term
       @crd_beginning_of_period = amount
       @crd_end_of_period = amount
-      (duration_in_periods - 1).times { |period| compute_term(timetable) }
-      compute_last_term
-      timetable << current_term
+
+      duration_in_periods.times { |idx| timetable << compute_current_term(idx, timetable) }
+
       timetable
     end
 
     private
 
-    def compute_last_term
+    def compute_current_term(idx, timetable)
+      @due_on = timetable_term_dates[timetable.next_index]
+      last_period?(idx) ? compute_last_term(timetable) : compute_term(timetable)
+      current_term
+    end
+
+    def compute_last_term(timetable)
       @crd_end_of_period                  = bigd('0')
       @due_interests_beginning_of_period  = @due_interests_end_of_period
-      @period_interests                   = @due_interests_end_of_period + compute_capitalized_interests
+      @period_interests                   = @due_interests_end_of_period + compute_capitalized_interests(@due_on, timetable)
       @due_interests_end_of_period        = 0
       @period_capital                     = @crd_beginning_of_period
       @total_paid_capital_end_of_period   += @period_capital
@@ -26,14 +32,14 @@ module LoanCreator
       @period_amount_to_pay               = @period_capital + @period_interests
     end
 
-    def compute_capitalized_interests
-      (amount + @due_interests_beginning_of_period).mult(periodic_interests_rate, BIG_DECIMAL_DIGITS)
+    def compute_capitalized_interests(due_date, timetable)
+      computed_periodic_interests_rate = periodic_interests_rate(due_date, relative_to_date: timetable_term_dates[timetable.next_index - 1])
+      (amount + @due_interests_beginning_of_period).mult(computed_periodic_interests_rate, BIG_DECIMAL_DIGITS)
     end
 
     def compute_term(timetable)
       @due_interests_beginning_of_period = @due_interests_end_of_period
-      @due_interests_end_of_period += compute_capitalized_interests
-      timetable << current_term
+      @due_interests_end_of_period += compute_capitalized_interests(@due_on, timetable)
     end
   end
 end

data/lib/loan_creator/common.rb

@@ -21,7 +21,8 @@ module LoanCreator
       # attribute: default_value
       deferred_in_periods: 0,
       interests_start_date: nil,
-      initial_values: {}
+      initial_values: {},
+      realistic_durations: false
     }.freeze
 
     attr_reader *REQUIRED_ATTRIBUTES
@@ -37,14 +38,26 @@ module LoanCreator
       validate_initial_values
     end
 
-    def periodic_interests_rate_percentage
-      @periodic_interests_rate_percentage ||=
-        annual_interests_rate.div(12 / PERIODS_IN_MONTHS[period], BIG_DECIMAL_DIGITS)
+    def periodic_interests_rate(date = nil, relative_to_date: nil)
+      if realistic_durations?
+        compute_realistic_periodic_interests_rate_percentage_for(date, relative_to_date: relative_to_date).div(100, BIG_DECIMAL_DIGITS)
+      else
+        @periodic_interests_rate ||=
+          annual_interests_rate.div(12 / PERIODS_IN_MONTHS[period], BIG_DECIMAL_DIGITS).div(100, BIG_DECIMAL_DIGITS)
+      end
     end
 
-    def periodic_interests_rate
-      @periodic_interests_rate ||=
-        periodic_interests_rate_percentage.div(100, BIG_DECIMAL_DIGITS)
+    def timetable_term_dates
+      @_timetable_term_dates ||= Hash.new do |dates, index|
+        dates[index] =
+          if index < 1
+            dates[index + 1].advance(months: -PERIODS_IN_MONTHS.fetch(period))
+          elsif index == 1
+            starts_on
+          else
+            starts_on.advance(months: PERIODS_IN_MONTHS.fetch(period) * (index - 1))
+          end
+      end
     end
 
     def lender_timetable
@@ -152,8 +165,7 @@ module LoanCreator
 
     def new_timetable
       LoanCreator::Timetable.new(
-        starts_on: starts_on,
-        period: period,
+        loan: self,
         interests_start_date: interests_start_date,
         starting_index: @starting_index
       )
@@ -163,6 +175,10 @@ module LoanCreator
       @index ? (@starting_index + @index - 1) : nil
     end
 
+    def last_period?(idx)
+      idx == (duration_in_periods - 1)
+    end
+
     def compute_term_zero
       @crd_beginning_of_period              = @crd_end_of_period
       @period_theoric_interests             = term_zero_interests
@@ -172,6 +188,7 @@ module LoanCreator
       @total_paid_interests_end_of_period  += @period_interests
       @period_amount_to_pay                 = @period_interests
       @index                                = 0
+      @due_on                               = timetable_term_dates[0]
     end
 
     def term_zero_interests
@@ -194,5 +211,17 @@ module LoanCreator
     def term_zero?
       interests_start_date && interests_start_date < term_zero_date
     end
+
+    def compute_realistic_periodic_interests_rate_percentage_for(date, relative_to_date:)
+      realistic_days = 365
+      realistic_days += 1 if date.leap?
+      realistic_days_in_period = (date - relative_to_date).to_i
+
+      annual_interests_rate.div(bigd(realistic_days) / bigd(realistic_days_in_period), BIG_DECIMAL_DIGITS)
+    end
+
+    def realistic_durations?
+      !!@realistic_durations
+    end
   end
 end

data/lib/loan_creator/linear.rb

@@ -11,26 +11,23 @@ module LoanCreator
         timetable << current_term
       end
 
-      duration_in_periods.times do |idx|
-        @last_period = last_period?(idx)
-        @deferred_period = idx < deferred_in_periods
-        compute_current_term(idx)
-        timetable << current_term
-      end
+      duration_in_periods.times { |idx| timetable << compute_current_term(idx, timetable) }
 
       timetable
     end
 
     private
 
-    def last_period?(idx)
-      idx == (duration_in_periods - 1)
-    end
+    def compute_current_term(idx, timetable)
+      @index = idx + 1
+      @last_period = last_period?(idx)
+      @deferred_period = @index <= deferred_in_periods
+      @due_on = timetable_term_dates[timetable.next_index]
+      computed_periodic_interests_rate = periodic_interests_rate(@due_on, relative_to_date: timetable_term_dates[timetable.next_index - 1])
 
-    def compute_current_term(idx)
       # Reminder: CRD beginning of period = CRD end of period **of previous period**
       @crd_beginning_of_period = @crd_end_of_period
-      @period_theoric_interests = @crd_beginning_of_period * periodic_interests_rate
+      @period_theoric_interests = @crd_beginning_of_period * computed_periodic_interests_rate
       @delta_interests = @period_theoric_interests - @period_theoric_interests.round(2)
       @accrued_delta_interests += @delta_interests
       @amount_to_add = bigd(
@@ -49,8 +46,8 @@ module LoanCreator
       @total_paid_interests_end_of_period += @period_interests
       @period_amount_to_pay = @period_interests + @period_capital
       @crd_end_of_period -= @period_capital
-      @due_on = nil
-      @index = idx + 1
+
+      current_term
     end
 
     def period_capital

data/lib/loan_creator/standard.rb

@@ -12,24 +12,22 @@ module LoanCreator
         timetable << current_term
       end
 
-      duration_in_periods.times do |idx|
-        @last_period = last_period?(idx)
-        @deferred_period = idx < deferred_in_periods
-        compute_current_term(idx)
-        timetable << current_term
-      end
+      duration_in_periods.times { |idx| timetable << compute_current_term(idx, timetable) }
+
       timetable
     end
 
     private
 
-    def last_period?(idx)
-      idx == (duration_in_periods - 1)
-    end
+    def compute_current_term(idx, timetable)
+      @index = idx + 1
+      @last_period = last_period?(idx)
+      @deferred_period = @index <= deferred_in_periods
+      @due_on = timetable_term_dates[timetable.next_index]
+      computed_periodic_interests_rate = periodic_interests_rate(@due_on, relative_to_date: timetable_term_dates[timetable.next_index - 1])
 
-    def compute_current_term(idx)
       @crd_beginning_of_period = @crd_end_of_period
-      @period_theoric_interests = period_theoric_interests(idx)
+      @period_theoric_interests = period_theoric_interests(@index, computed_periodic_interests_rate)
       @delta_interests = @period_theoric_interests - @period_theoric_interests.round(2)
       @accrued_delta_interests += @delta_interests
       @amount_to_add = bigd(
@@ -43,37 +41,37 @@ module LoanCreator
       )
       @accrued_delta_interests -= @amount_to_add
       @period_interests = @period_theoric_interests.round(2) + @amount_to_add
-      @period_capital = period_capital(idx)
+      @period_capital = period_capital(@index, computed_periodic_interests_rate)
       @total_paid_capital_end_of_period += @period_capital
       @total_paid_interests_end_of_period += @period_interests
       @period_amount_to_pay = @period_interests + @period_capital
       @crd_end_of_period -= @period_capital
-      @due_on = nil
-      @index = idx + 1
+
+      current_term
     end
 
-    def period_theoric_interests(idx)
+    def period_theoric_interests(idx, computed_periodic_interests_rate)
       if @deferred_period
-        @crd_beginning_of_period * periodic_interests_rate
+        @crd_beginning_of_period * computed_periodic_interests_rate
       else
         -ipmt(
-          periodic_interests_rate,
-          (idx + 1) - deferred_in_periods,
+          computed_periodic_interests_rate,
+          idx - deferred_in_periods,
           duration_in_periods - deferred_in_periods,
           amount
         )
       end
     end
 
-    def period_capital(idx)
+    def period_capital(idx, computed_periodic_interests_rate)
       if @last_period
         @crd_beginning_of_period
       elsif @deferred_period
         bigd(0)
       else
         -ppmt(
-          periodic_interests_rate,
-          (idx + 1) - deferred_in_periods,
+          computed_periodic_interests_rate,
+          idx - deferred_in_periods,
           duration_in_periods - deferred_in_periods,
           amount
         ).round(2)

data/lib/loan_creator/timetable.rb

@@ -1,22 +1,13 @@
 # coding: utf-8
 module LoanCreator
   class Timetable
-    # Used to calculate next term's date (see ActiveSupport#advance)
-    PERIODS = {
-      month:    {months: 1},
-      quarter:  {months: 3},
-      semester: {months: 6},
-      year:     {years: 1}
-    }
+    attr_reader :loan, :terms, :starting_index #, :interests_start_date
 
-    attr_reader :terms, :starts_on, :period, :starting_index #, :interests_start_date
-
-    def initialize(starts_on:, period:, interests_start_date: nil, starting_index: 1)
-      raise ArgumentError.new(:period) unless PERIODS.keys.include?(period)
+    delegate :starts_on, :period, to: :loan
 
+    def initialize(loan:, interests_start_date: nil, starting_index: 1)
       @terms          = []
-      @starts_on      = (starts_on.is_a?(Date) ? starts_on : Date.parse(starts_on))
-      @period         = period
+      @loan           = loan
       @starting_index = starting_index
 
       if interests_start_date
@@ -26,8 +17,11 @@ module LoanCreator
 
     def <<(term)
       raise ArgumentError.new('LoanCreator::Term expected') unless term.is_a?(LoanCreator::Term)
-      term.index  ||= autoincrement_index
-      term.due_on ||= date_for(term.index)
+
+      @current_index = term.index || next_index
+
+      term.index    = @current_index
+      term.due_on ||= loan.timetable_term_dates[term.index]
       @terms << term
       self
     end
@@ -43,29 +37,8 @@ module LoanCreator
       @terms.find { |term| term.index == index }
     end
 
-    private
-
-    def autoincrement_index
-      @current_index = (@current_index.nil? ? @starting_index : @current_index + 1)
-    end
-
-    def date_for(index)
-      @_dates ||= Hash.new do |dates, index|
-        dates[index] =
-          if index < 1
-            dates[index + 1].advance(PERIODS.fetch(period).transform_values {|n| -n})
-          elsif index == 1
-            starts_on
-          else
-            dates[index - 1].advance(PERIODS.fetch(period))
-          end
-      end
-
-      @_dates[index]
-    end
-
-    def reset_dates
-      @_dates = nil
+    def next_index
+      @current_index.nil? ? @starting_index : @current_index + 1
     end
   end
 end

data/lib/loan_creator/uncapitalized_bullet.rb

@@ -7,18 +7,24 @@ module LoanCreator
       reset_current_term
       @crd_beginning_of_period = amount
       @crd_end_of_period = amount
-      (duration_in_periods - 1).times { |period| compute_term(timetable) }
-      compute_last_term
-      timetable << current_term
+
+      duration_in_periods.times { |idx| timetable << compute_current_term(idx, timetable) }
+
       timetable
     end
 
     private
 
-    def compute_last_term
+    def compute_current_term(idx, timetable)
+      @due_on = timetable_term_dates[timetable.next_index]
+      last_period?(idx) ? compute_last_term(timetable) : compute_term(timetable)
+      current_term
+    end
+
+    def compute_last_term(timetable)
       @crd_end_of_period                  =  bigd('0')
       @due_interests_beginning_of_period  =  @due_interests_end_of_period
-      @period_interests                   =  @due_interests_end_of_period + compute_interests
+      @period_interests                   =  @due_interests_end_of_period + compute_interests(@due_on, timetable)
       @due_interests_end_of_period        =  0
       @period_capital                     =  @crd_beginning_of_period
       @total_paid_capital_end_of_period   += @period_capital
@@ -26,14 +32,14 @@ module LoanCreator
       @period_amount_to_pay               =  @period_capital + @period_interests
     end
 
-    def compute_interests
-      amount.mult(bigd(periodic_interests_rate), BIG_DECIMAL_DIGITS)
+    def compute_interests(due_date, timetable)
+      computed_periodic_interests_rate = periodic_interests_rate(due_date, relative_to_date: timetable_term_dates[timetable.next_index - 1])
+      amount.mult(bigd(computed_periodic_interests_rate), BIG_DECIMAL_DIGITS)
     end
 
     def compute_term(timetable)
       @due_interests_beginning_of_period = @due_interests_end_of_period
-      @due_interests_end_of_period += compute_interests
-      timetable << current_term
+      @due_interests_end_of_period += compute_interests(@due_on, timetable)
     end
   end
 end

data/lib/loan_creator/version.rb

@@ -1,3 +1,3 @@
 module LoanCreator
-  VERSION = '0.8.0'.freeze
+  VERSION = '0.8.1'.freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: loan_creator
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.8.1
 platform: ruby
 authors:
 - thibaulth
@@ -12,7 +12,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-02-23 00:00:00.000000000 Z
+date: 2021-04-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler