loan_creator 0.9.1 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e207b2a1a30e9f07b773f9d3071c8df1cb815e17602661efb72d4315ead65dba
-  data.tar.gz: c6760d02448a8a9bd6f40fa992aa09f1d716a06b94e2ce5afa8b54eddfeeddf6
+  metadata.gz: 9a85f9d61c45df0f972e329a33a1beedbedc1e0090d481613e93ad90d66dea98
+  data.tar.gz: 7dab891b9a5d3acefb8d6cd43eef0bdb5cfe511631f5674ae655046cda11ca25
 SHA512:
-  metadata.gz: 75d786838e61c1f342da8a3ebf3e0264e42f0e80909bc22ffe63f5c76acf4a1c36e1130ebcbcb4f8c72d87f7a99735c8e3d70f634889935dd57849f92bcdf98d
-  data.tar.gz: 768182d707c17e9f5b1f8f748f6dcaf1277e1a1bf0b68c33ed28a178464117272e8dfe294585baeac3fa1d9fb3f28945e1224b7e158fffea66bda89c5cb25dff
+  metadata.gz: f92cd167e57a06b93169011fe8c178e7e3f434dc4c99c4a9458fb29501dd643d6011da2b8af7adfd94dd7412e7e0cd9566f281c5ff3331815daa2aa39bc27d58
+  data.tar.gz: c21997ee861f81b7ad4a28b334f2f1d4258e2df54eb01865de79e0b30dae5abba1d4a6771055564a6e349d16ad07ea82e6aac57a3f35ef70fee07c9ba8f94f6a

data/CHANGELOG.md

@@ -1,3 +1,15 @@
+v0.12.0
+-------------------------
+- improve argument error management and allow amount equal to zero.
+
+v0.11.0
+-------------------------
+- add `multi_part_interests_calculation` option.
+
+v0.10.0
+-------------------------
+- fix `term_dates` options, notably with `starts_on`.
+
 v0.9.1
 -------------------------
 - add spec importer `scripts/convert_export_to_spec.rb {csv_url}`

data/README.md

@@ -187,7 +187,7 @@ Default: `false`.
 The default behaviour is to use the `period` in relation to the number of months in a year (ie: for a monthly timetable annual_interests_rate * 1/12, for quarter annual_interests_rate * 3/12, etc.)
 
 
-`term_dates`: Optional. Implemented for `LoanCreator::Bullet`, `LoanCreator::InFine` and `LoanCreator::Linear`. Can be used if you want to implement custom due dates for terms. Terms will be compute from date to date. Must be an array with following dates.
+`term_dates`: Optional. Implemented for `LoanCreator::Bullet`, `LoanCreator::InFine` and `LoanCreator::Linear`. Can be used if you want to implement custom due dates for terms. Terms will be computed from date to date. Must be an array with following dates. Must contain duration + 1 dates. The first element of the array is the first period start_date and last is the last period pay day.
 
 ## Calculation
 

data/lib/loan_creator/bullet.rb

@@ -24,7 +24,7 @@ module LoanCreator
     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(@due_on, timetable)
+      @period_interests                   = @due_interests_end_of_period + compute_capitalized_interests(timetable)
       @due_interests_end_of_period        = 0
       @period_capital                     = @crd_beginning_of_period
       @total_paid_capital_end_of_period   += @period_capital
@@ -32,14 +32,22 @@ module LoanCreator
       @period_amount_to_pay               = @period_capital + @period_interests
     end
 
-    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)
+    def compute_capitalized_interests(timetable)
+      if multi_part_interests_calculation && term_dates? && (timetable_term_dates[timetable.current_index] + 1.year) < @due_on
+        multi_part_interests(
+          timetable_term_dates[timetable.current_index],
+          @due_on,
+          annual_interests_rate,
+          amount_to_capitalize
+        )
+      else
+        compute_period_generated_interests(periodic_interests_rate(timetable_term_dates[timetable.current_index], @due_on))
+      end
     end
 
     def compute_term(timetable)
       @due_interests_beginning_of_period = @due_interests_end_of_period
-      @due_interests_end_of_period += compute_capitalized_interests(@due_on, timetable)
+      @due_interests_end_of_period += compute_capitalized_interests(timetable)
     end
   end
 end

data/lib/loan_creator/common.rb

@@ -1,6 +1,7 @@
 module LoanCreator
   class Common
     extend BorrowerTimetable
+    include TimeHelper
 
     PERIODS_IN_MONTHS = {
       month: 1,
@@ -30,9 +31,11 @@ module LoanCreator
       deferred_in_periods: 0,
       interests_start_date: nil,
       initial_values: {},
-      realistic_durations: false
+      realistic_durations: false,
+      multi_part_interests_calculation: true
     }.freeze
 
+
     attr_reader *REQUIRED_ATTRIBUTES
     attr_reader *OPTIONAL_ATTRIBUTES.keys
 
@@ -47,9 +50,9 @@ module LoanCreator
       prepare_custom_term_dates if term_dates?
     end
 
-    def periodic_interests_rate(date = nil, relative_to_date: nil)
+    def periodic_interests_rate(start_date, end_date)
       if realistic_durations?
-        compute_realistic_periodic_interests_rate_percentage_for(date, relative_to_date: relative_to_date).div(100, BIG_DECIMAL_DIGITS)
+        compute_realistic_periodic_interests_rate(start_date, end_date, annual_interests_rate)
       else
         @periodic_interests_rate ||=
           annual_interests_rate.div(12 / PERIODS_IN_MONTHS[period], BIG_DECIMAL_DIGITS).div(100, BIG_DECIMAL_DIGITS)
@@ -101,23 +104,37 @@ module LoanCreator
 
     def set_attributes
       required_attributes.each { |k| instance_variable_set(:"@#{k}", @options.fetch(k)) }
-      OPTIONAL_ATTRIBUTES.each { |k,v| instance_variable_set(:"@#{k}", @options.fetch(k, v)) }
+      OPTIONAL_ATTRIBUTES.each { |k, v| instance_variable_set(:"@#{k}", @options.fetch(k, v)) }
     end
 
-    def validate(key, &block)
-      raise unless block.call(instance_variable_get(:"@#{key}"))
-    rescue => e
-      raise ArgumentError.new([key, e.message].join(': '))
+    def validate(message, &block)
+      raise ArgumentError.new(message) unless block.call
     end
 
     def validate_attributes
-      validate(:period) { |v| PERIODS_IN_MONTHS.keys.include?(v) } unless term_dates?
-      validate(:amount) { |v| v.is_a?(BigDecimal) && v > 0 }
-      validate(:annual_interests_rate) { |v| v.is_a?(BigDecimal) && v >= 0 }
-      validate(:starts_on) { |v| v.is_a?(Date) }
-      validate(:duration_in_periods) { |v| v.is_a?(Integer) && v > 0 }
-      validate(:deferred_in_periods) { |v| v.is_a?(Integer) && v >= 0 && v < duration_in_periods }
-      validate_term_dates if term_dates?
+      validate("amount #{@amount} must be positive") do
+        @amount.is_a?(BigDecimal) && @amount >= 0
+      end
+      validate("annual_interests_rate #{@annual_interests_rate} must be positive") do
+        @annual_interests_rate.is_a?(BigDecimal) && @annual_interests_rate >= 0
+      end
+      validate("starts_on #{@starts_on} must be a date but is a #{@starts_on.class}") do
+        @starts_on.is_a?(Date)
+      end
+      validate("duration_in_periods #{@duration_in_periods} must be positive") do
+        @duration_in_periods.is_a?(Integer) && @duration_in_periods > 0
+      end
+      validate("deferred_in_periods #{@deferred_in_periods} must be positive and less than duration_in_periods #{@duration_in_periods}") do
+        @deferred_in_periods.is_a?(Integer) && @deferred_in_periods >= 0 && @deferred_in_periods < duration_in_periods
+      end
+      if term_dates?
+        validate_term_dates
+      else
+        validate("period #{@period} must be in #{PERIODS_IN_MONTHS}") do
+          PERIODS_IN_MONTHS.keys.include?(@period)
+        end
+      end
+
     end
 
     def validate_term_dates
@@ -132,10 +149,18 @@ module LoanCreator
     def validate_initial_values
       return if initial_values.blank?
 
-      validate(:total_paid_capital_end_of_period) { |v| v.is_a?(BigDecimal) && v >= 0 }
-      validate(:total_paid_interests_end_of_period) { |v| v.is_a?(BigDecimal) && v >= 0 }
-      validate(:accrued_delta_interests) { |v| v.is_a?(BigDecimal) }
-      validate(:starting_index) { |v| v.is_a?(Integer) && v >= 0 }
+      validate("total_paid_capital_end_of_period #{@total_paid_capital_end_of_period} must be positive") do
+        @total_paid_capital_end_of_period.is_a?(BigDecimal) && @total_paid_capital_end_of_period >= 0
+      end
+      validate("total_paid_interests_end_of_period #{@total_paid_interests_end_of_period} must be positive") do
+        @total_paid_interests_end_of_period.is_a?(BigDecimal) && @total_paid_interests_end_of_period >= 0
+      end
+      validate("accrued_delta_interests must be a BigDecimal but is a #{@accrued_delta_interests.class}") do
+        @accrued_delta_interests.is_a?(BigDecimal)
+      end
+      validate("starting_index #{@starting_index} must be positive") do
+        @starting_index.is_a?(Integer) && @starting_index >= 0
+      end
     end
 
     def set_initial_values
@@ -236,43 +261,6 @@ module LoanCreator
       (interests_start_date && interests_start_date < term_zero_date) && !term_dates?
     end
 
-    def leap_days_count(date, relative_to_date:)
-      start_year = relative_to_date.year
-      end_year = date.year
-
-      (start_year..end_year).sum do |year|
-        next 0 unless Date.gregorian_leap?(year)
-
-        start_date =
-          if start_year == year
-            relative_to_date
-          else
-            Date.new(year - 1, 12, 31)
-          end
-
-        end_date =
-          if end_year == year
-            date
-          else
-            Date.new(year, 12, 31)
-          end
-
-        end_date - start_date
-      end
-    end
-
-    def compute_realistic_periodic_interests_rate_percentage_for(date, relative_to_date:)
-      total_days = date - relative_to_date
-      leap_days = bigd(leap_days_count(date, relative_to_date: relative_to_date))
-      non_leap_days = bigd(total_days - leap_days)
-
-      annual_interests_rate.mult(
-        leap_days.div(366, BIG_DECIMAL_DIGITS) +
-        non_leap_days.div(365, BIG_DECIMAL_DIGITS),
-        BIG_DECIMAL_DIGITS
-      )
-    end
-
     def realistic_durations?
       term_dates? || @realistic_durations.present?
     end
@@ -291,16 +279,21 @@ module LoanCreator
 
     def prepare_custom_term_dates
       term_dates = @options[:term_dates].each_with_index.with_object({}) do |(term_date, index), obj|
-        obj[index + 1] = term_date
+        obj[index + @starting_index - 1] = term_date
       end
 
-      term_dates[0] = starts_on
+      # if starting_index > 1 term_dates[0] is not set
+      term_dates[0] ||= starts_on
       @_timetable_term_dates = term_dates
       @realistic_durations = true
     end
 
     def compute_period_generated_interests(interests_rate)
-      (@crd_beginning_of_period + @due_interests_beginning_of_period).mult(interests_rate, BIG_DECIMAL_DIGITS)
+      amount_to_capitalize.mult(interests_rate, BIG_DECIMAL_DIGITS)
+    end
+
+    def amount_to_capitalize
+      @crd_beginning_of_period + @due_interests_beginning_of_period
     end
   end
 end

data/lib/loan_creator/linear.rb

@@ -23,12 +23,25 @@ module LoanCreator
       @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])
 
       # Reminder: CRD beginning of period = CRD end of period **of previous period**
       @crd_beginning_of_period = @crd_end_of_period
       @due_interests_beginning_of_period = @due_interests_end_of_period
-      @period_theoric_interests = period_theoric_interests(computed_periodic_interests_rate)
+
+      @period_theoric_interests = (
+        # if period is more than a year
+        if multi_part_interests_calculation && term_dates? && (timetable_term_dates[timetable.current_index] + 1.year) < @due_on
+          multi_part_interests(
+            timetable_term_dates[timetable.current_index],
+            @due_on,
+            annual_interests_rate,
+            amount_to_capitalize
+          )
+        else
+          period_theoric_interests(periodic_interests_rate(timetable_term_dates[timetable.current_index], @due_on))
+        end
+      )
+
       @delta_interests = @period_theoric_interests - @period_theoric_interests.round(2)
       @accrued_delta_interests += @delta_interests
       @amount_to_add = bigd(

data/lib/loan_creator/standard.rb

@@ -24,7 +24,7 @@ module LoanCreator
       @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])
+      computed_periodic_interests_rate = periodic_interests_rate(timetable_term_dates[timetable.current_index], @due_on)
 
       @crd_beginning_of_period = @crd_end_of_period
       @period_theoric_interests = period_theoric_interests(@index, computed_periodic_interests_rate)

data/lib/loan_creator/term_dates_validator.rb

@@ -17,8 +17,10 @@ module LoanCreator
     end
 
     def self.matches_duration(term_dates, duration_in_periods)
-      unless term_dates.size == duration_in_periods
-        raise ArgumentError, "the size of :term_dates (#{term_dates.size}) do not match the :duration_in_periods (#{duration_in_periods})"
+      unless term_dates.size == duration_in_periods + 1
+        error_message = "the size of :term_dates (#{term_dates.size}) do not match the :duration_in_periods (#{duration_in_periods})."
+        advice = "You must pass the previous term date (or start_on if starting_index == 1) as the first term date"
+        raise ArgumentError, "#{error_message} #{advice}"
       end
     end
 
@@ -64,7 +66,7 @@ module LoanCreator
           raise ArgumentError, "term dates can't be more than 1 year apart. #{error_description}"
         end
       end
-    end      
+    end
 
     def self.bullet?(loan_class)
       loan_class == "LoanCreator::Bullet"

data/lib/loan_creator/time_helper.rb

@@ -0,0 +1,62 @@
+module LoanCreator
+  module TimeHelper
+    extend ActiveSupport::Concern
+
+    included do
+      def leap_days_count(start_date, end_date)
+        start_year = start_date.year
+        # mostly no op but allows to skip one iteration if end date is january 1st
+        end_year = (end_date - 1.day).year
+
+        (start_year..end_year).sum do |year|
+          next 0 unless Date.gregorian_leap?(year)
+
+          current_start_date =
+            if start_year == year
+              start_date
+            else
+              Date.new(year, 1, 1)
+            end
+
+          current_end_date =
+            if end_year == year
+              end_date
+            else
+              Date.new(year + 1, 1, 1)
+            end
+
+          current_end_date - current_start_date
+        end
+      end
+
+      def compute_realistic_periodic_interests_rate(start_date, end_date, annual_interests_rate)
+        total_days = end_date - start_date
+        leap_days = bigd(leap_days_count(start_date, end_date))
+        non_leap_days = bigd(total_days - leap_days)
+
+        annual_interests_rate.mult(
+          leap_days.div(366, BIG_DECIMAL_DIGITS) +
+          non_leap_days.div(365, BIG_DECIMAL_DIGITS),
+          BIG_DECIMAL_DIGITS
+        ).div(100, BIG_DECIMAL_DIGITS)
+      end
+
+      # for terms spanning more than a year,
+      # we capitalize each years until the last one which behaves normally
+      def multi_part_interests(start_date, end_date, annual_interests_rate, amount_to_capitalize)
+        duration_in_days = end_date - start_date
+        leap_days = bigd(leap_days_count(start_date, end_date))
+        non_leap_days = bigd(duration_in_days - leap_days)
+
+        ratio = non_leap_days.div(365, BIG_DECIMAL_DIGITS) + leap_days.div(366, BIG_DECIMAL_DIGITS)
+        full_years, year_part = ratio.divmod(1)
+        rate = annual_interests_rate.div(100, BIG_DECIMAL_DIGITS)
+
+        total = amount_to_capitalize.mult((1 + rate)**full_years, BIG_DECIMAL_DIGITS)
+                                    .mult(1 + rate * year_part, BIG_DECIMAL_DIGITS)
+
+        total - amount_to_capitalize
+      end
+    end
+  end
+end

data/lib/loan_creator/timetable.rb

@@ -40,5 +40,9 @@ module LoanCreator
     def next_index
       @current_index.nil? ? @starting_index : @current_index + 1
     end
+
+    def current_index
+      @current_index.nil? ? @starting_index - 1 : @current_index
+    end
   end
 end

data/lib/loan_creator/uncapitalized_bullet.rb

@@ -33,7 +33,7 @@ module LoanCreator
     end
 
     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])
+      computed_periodic_interests_rate = periodic_interests_rate(timetable_term_dates[timetable.current_index], due_date)
       amount.mult(bigd(computed_periodic_interests_rate), BIG_DECIMAL_DIGITS)
     end
 

data/lib/loan_creator/version.rb

@@ -1,3 +1,3 @@
 module LoanCreator
-  VERSION = '0.9.1'.freeze
+  VERSION = '0.12.0'.freeze
 end

data/lib/loan_creator.rb

@@ -8,6 +8,7 @@ module LoanCreator
   BIG_DECIMAL_DIGITS = 14
 
   autoload :ExcelFormulas,            'loan_creator/excel_formulas'
+  autoload :TimeHelper,               'loan_creator/time_helper'
   autoload :BorrowerTimetable,        'loan_creator/borrower_timetable'
   autoload :Common,                   'loan_creator/common'
   autoload :Standard,                 'loan_creator/standard'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: loan_creator
 version: !ruby/object:Gem::Version
-  version: 0.9.1
+  version: 0.12.0
 platform: ruby
 authors:
 - thibaulth
@@ -12,7 +12,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-05-11 00:00:00.000000000 Z
+date: 2022-07-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -178,6 +178,7 @@ files:
 - lib/loan_creator/standard.rb
 - lib/loan_creator/term.rb
 - lib/loan_creator/term_dates_validator.rb
+- lib/loan_creator/time_helper.rb
 - lib/loan_creator/timetable.rb
 - lib/loan_creator/uncapitalized_bullet.rb
 - lib/loan_creator/version.rb