loan_creator 0.2.3 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 05b6daa216ea6263c492b90400a5885c6da2cf11
-  data.tar.gz: 5f583406fd970409e5e0c5c471006600a3f019dd
+  metadata.gz: ce94717f0c667263653597ea2037844157e6cebe
+  data.tar.gz: e498fe9069ca0ff9c3d765083a182f28ddc3ca22
 SHA512:
-  metadata.gz: bd2304c39a20bcc147c29f816be628f9cca6979763acb99287c49b526cf0ddb9120856ddec0f8e4ba3b16f431629e7749552a00997c3afeafd8f43e01a4a2cd9
-  data.tar.gz: a03687f04b2a9718c84027aae35b30d0d37e7a11a189d7e64a05b9d9c5f8251c1987e7e80c49250e91f0e3ef73712c842a674975be960aac286f124836677832
+  metadata.gz: da8108111a04280719eba3143444bd2ceac35abaade6521c2e9a5a3297266037c7d8e194156c3a373602fe766bbce49c23ebe515a2db1b64e1a35ac67a4aff06
+  data.tar.gz: 5e49dd7114a25fc67e9230ea0d6120b7a12bb83b6b6c50d28eecbfb7c92cc7bbd68da4ca26d0bf7dffe0b7b1fc2a7ec9acbbbb9369bf2cdfb1eb6837625dd2be

data/README.md

@@ -46,6 +46,7 @@ Each instance of one of the previous classes has the following attributes:
     :starts_at
     :duration_in_periods
     :deferred_in_periods (default to zero)
+    :interests_start_date (optional)
 ```
 
 There is also a `LoanCreator::Timetable` class dedicated to record the data of the loans' terms. Each instance of `LoanCreator::Timetable` represents an array of `LoanCreator::Term` records, each having the following attributes:
@@ -55,7 +56,7 @@ There is also a `LoanCreator::Timetable` class dedicated to record the data of t
       :index
 
       # Term date
-      :date
+      :due_on
 
       # Remaining due capital at the beginning of the term
       :crd_beginning_of_period
@@ -99,8 +100,29 @@ support all those differences.
 `.borrower_timetable(*lenders_timetables)` (class method) intends to sum each attribute of each provided `lender_timetable` on each term and thus to provide an ascending order array of `LoanCreator::Term`. It should be used for the borrower of a loan, once all lenders and their lending amounts
 are known. It makes the borrower support all financial rounding differences.
 
+## Example
+
+```ruby
+loan_creator = LoanCreator::Standard.new(
+  period: :year,
+  amount: 42_000,
+  annual_interests_rate: 4,
+  starts_on: '2019-03-01',
+  duration_in_periods: 5,
+  deferred_in_periods: 1,
+  interests_start_date: '2019-02-10'
+)
+loan_creator.lender_timetable
+# => #<LoanCreator::Timetable:0x0000000003198bd0 @terms=[...] ...>
+loan_creator.lender_timetable.terms.first
+# => #<LoanCreator::Term:0x00000000030f1a88 @crd_beginning_of_period=0.42e5,
+# [...] @period_amount_to_pay=0.8745e2, @index=0, @due_on=Sun, 10 Feb 2019>
+````
+
 ## Explanation
 
+### Classes
+
 `Standard` loan generates terms with constant payments.
 
 `Linear` loan generates terms with constant capital share payment.
@@ -117,6 +139,26 @@ Capital share shall be repaid in full and all interests paid at loan's end.
 
 There is no deferred time for `InFine` and `Bullet` loans as it would be equivalent to increasing loan's duration.
 
+### Attributes
+
+`period`: A `Symbol`. `:month`, `:quarter`, `:semester` or `:year`.
+
+`duration_in_periods`: An `Integer`.
+
+`amount`: Any number that can be converted to `BigDecimal`.
+
+`annual_interests_rate`: In percentage. Any number that can be converted to `BigDecimal`.
+
+`starts_at`: A `Date`, or a `String` that can be parsed.
+
+`deferred_in_periods`: Optional. An `Integer`, smaller than `duration_in_periods`. Number of periods during which no
+capital is refunded, only interest. Only relevant for `Standard` and `Linear` loans.
+
+`interests_start_date`: Optional. To be used when the loan starts before the first full term date. This then compute an
+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.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rspec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/loan_creator/bullet.rb

@@ -2,6 +2,7 @@ module LoanCreator
   class Bullet < LoanCreator::Common
     def lender_timetable
       raise ArgumentError.new(:deferred_in_periods) unless deferred_in_periods == 0
+      raise ArgumentError.new(:interests_start_date) unless interests_start_date.nil?
       timetable = new_timetable
       reset_current_term
       @crd_beginning_of_period = amount

data/lib/loan_creator/common.rb

@@ -19,7 +19,8 @@ module LoanCreator
 
     OPTIONAL_ATTRIBUTES = {
       # attribute: default_value
-      deferred_in_periods: 0
+      deferred_in_periods: 0,
+      interests_start_date: nil,
     }.freeze
 
     attr_reader *REQUIRED_ATTRIBUTES
@@ -48,7 +49,7 @@ module LoanCreator
     end
 
     def self.bigd(value)
-      BigDecimal.new(value, BIG_DECIMAL_DIGITS)
+      BigDecimal(value, BIG_DECIMAL_DIGITS)
     end
 
     def bigd(value)
@@ -65,7 +66,8 @@ module LoanCreator
       @options[:period] = @options[:period].to_sym
       @options[:amount] = bigd(@options[:amount])
       @options[:annual_interests_rate] = bigd(@options[:annual_interests_rate])
-      @options[:starts_on] = @options[:starts_on].strftime('%Y-%m-%d') if Date === @options[:starts_on]
+      @options[:starts_on] = Date.parse(@options[:starts_on]) if @options[:starts_on].is_a?(String)
+      @options[:interests_start_date] = Date.parse(@options[:interests_start_date]) if @options[:interests_start_date].is_a?(String)
     end
 
     def set_attributes
@@ -83,7 +85,7 @@ module LoanCreator
       validate(:period) { |v| PERIODS_IN_MONTHS.keys.include?(v) }
       validate(:amount) { |v| v.is_a?(BigDecimal) && v > 0 }
       validate(:annual_interests_rate) { |v| v.is_a?(BigDecimal) && v >= 0 }
-      validate(:starts_on) { |v| !!Date.parse(v) }
+      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 }
     end
@@ -100,6 +102,8 @@ module LoanCreator
       @total_paid_capital_end_of_period = bigd('0')
       @total_paid_interests_end_of_period = bigd('0')
       @period_amount_to_pay = bigd('0')
+      @due_on = nil
+      @index = nil
     end
 
     def current_term
@@ -114,12 +118,46 @@ module LoanCreator
         period_capital: @period_capital,
         total_paid_capital_end_of_period: @total_paid_capital_end_of_period,
         total_paid_interests_end_of_period: @total_paid_interests_end_of_period,
-        period_amount_to_pay: @period_amount_to_pay
+        period_amount_to_pay: @period_amount_to_pay,
+        due_on: @due_on,
+        index: @index
       )
     end
 
     def new_timetable
-      LoanCreator::Timetable.new(starts_on: starts_on, period: period)
+      LoanCreator::Timetable.new(starts_on: starts_on, period: period, interests_start_date: interests_start_date)
+    end
+
+    def compute_term_zero
+      @crd_beginning_of_period = @crd_end_of_period
+      @period_theoric_interests = term_zero_interests
+      @delta_interests = @period_theoric_interests - @period_theoric_interests.round(2)
+      @accrued_delta_interests += @delta_interests
+      @period_interests = @period_theoric_interests.round(2)
+      @total_paid_interests_end_of_period += @period_interests
+      @period_amount_to_pay = @period_interests
+      @index = 0
+    end
+
+    def term_zero_interests
+      @crd_beginning_of_period * term_zero_interests_rate
+    end
+
+    def term_zero_interests_rate
+      term_zero_interests_rate_percentage = (annual_interests_rate * term_zero_duration).div(365, BIG_DECIMAL_DIGITS)
+      term_zero_interests_rate_percentage.div(100, BIG_DECIMAL_DIGITS)
+    end
+
+    def term_zero_duration
+      (term_zero_date - interests_start_date).to_i
+    end
+
+    def term_zero_date
+      starts_on.advance(months: -PERIODS_IN_MONTHS.fetch(@period))
+    end
+
+    def term_zero?
+      interests_start_date && interests_start_date < term_zero_date
     end
   end
 end

data/lib/loan_creator/excel_formulas.rb

@@ -1,12 +1,16 @@
 # Source: https://gist.github.com/mattetti/1015948
 
 module LoanCreator::ExcelFormulas
+  # Returns the interest payment
+  # for a given period for an investment based on periodic, constant payments and a constant interest rate.
   def ipmt(rate, per, nper, pv, fv=0, type=0)
     p = _pmt(rate, nper, pv, fv, 0);
     ip = -(pv * _pow1p(rate, per - 1) * rate + p * _pow1pm1(rate, per - 1))
     (type == 0) ? ip : ip / (1 + rate)
   end
 
+  # Returns the payment on the principal
+  # for a given period for an investment based on periodic, constant payments and a constant interest rate.
   def ppmt(rate, per, nper, pv, fv=0, type=0)
     p = _pmt(rate, nper, pv, fv, type)
     ip = ipmt(rate, per, nper, pv, fv, type)

data/lib/loan_creator/in_fine.rb

@@ -3,9 +3,7 @@ module LoanCreator
     # InFine is the same as a Linear loan with (duration - 1) deferred periods.
     # Thus we're generating a Linear loan instead of rewriting already existing code.
     def lender_timetable
-      raise ArgumentError.new(:deferred_in_periods) unless deferred_in_periods == 0
-      options = { deferred_in_periods: duration_in_periods - 1 }
-      options = REQUIRED_ATTRIBUTES.each_with_object(options) { |k,h| h[k] = send(k) }
+      options = @options.merge(deferred_in_periods: duration_in_periods - 1)
       LoanCreator::Linear.new(options).lender_timetable
     end
   end

data/lib/loan_creator/linear.rb

@@ -5,10 +5,16 @@ module LoanCreator
       timetable = new_timetable
       reset_current_term
       @crd_end_of_period = amount
+
+      if term_zero?
+        compute_term_zero
+        timetable << current_term
+      end
+
       duration_in_periods.times do |idx|
         @last_period = last_period?(idx)
         @deferred_period = idx < deferred_in_periods
-        compute_current_term
+        compute_current_term(idx)
         timetable << current_term
       end
       timetable
@@ -20,7 +26,7 @@ module LoanCreator
       idx == (duration_in_periods - 1)
     end
 
-    def compute_current_term
+    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
@@ -42,6 +48,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
     end
 
     def period_capital

data/lib/loan_creator/standard.rb

@@ -6,6 +6,12 @@ module LoanCreator
       timetable = new_timetable
       reset_current_term
       @crd_end_of_period = amount
+
+      if term_zero?
+        compute_term_zero
+        timetable << current_term
+      end
+
       duration_in_periods.times do |idx|
         @last_period = last_period?(idx)
         @deferred_period = idx < deferred_in_periods
@@ -42,6 +48,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
     end
 
     def period_theoric_interests(idx)

data/lib/loan_creator/term.rb

@@ -36,7 +36,7 @@ module LoanCreator
       :period_amount_to_pay
     ].freeze
 
-    ATTRIBUTES = [
+    OPTIONAL_ARGUMENTS = [
       # Term number (starts at 1)
       # This value is to be set by Timetable
       :index,
@@ -44,15 +44,15 @@ module LoanCreator
       # Term date
       # This value is to be set by Timetable
       :due_on,
+    ]
 
-      # These values are to be specified during Term's initialization
-      *ARGUMENTS
-    ].freeze
+    ATTRIBUTES = (ARGUMENTS + OPTIONAL_ARGUMENTS).freeze
 
     attr_accessor *ATTRIBUTES
 
     def initialize(**options)
       ARGUMENTS.each { |k| instance_variable_set(:"@#{k}", options.fetch(k)) }
+      OPTIONAL_ARGUMENTS.each { |k| instance_variable_set(:"@#{k}", options.fetch(k, nil)) }
     end
 
     def to_csv

data/lib/loan_creator/timetable.rb

@@ -3,39 +3,34 @@ 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 }
+      month:    {months: 1},
+      quarter:  {months: 3},
+      semester: {months: 6},
+      year:     {years: 1}
     }
 
-    attr_reader :terms, :starts_on, :period
+    attr_reader :terms, :starts_on, :period #, :interests_start_date
 
-    def initialize(starts_on:, period:)
-      @terms = []
-      @starts_on = (Date === starts_on ? starts_on : Date.parse(starts_on))
+    def initialize(starts_on:, period:, interests_start_date: nil)
       raise ArgumentError.new(:period) unless PERIODS.keys.include?(period)
-      @period = period
+
+      @terms     = []
+      @starts_on = (starts_on.is_a?(Date) ? starts_on : Date.parse(starts_on))
+      @period    = period
+
+      if interests_start_date
+        @interests_start_date = (interests_start_date.is_a?(Date) ? interests_start_date : Date.parse(interests_start_date))
+      end
     end
 
     def <<(term)
-      raise ArgumentError.new('LoanCreator::Term expected') unless LoanCreator::Term === term
-      term.index = autoincrement_index
-      term.due_on = autoincrement_date
+      raise ArgumentError.new('LoanCreator::Term expected') unless term.is_a?(LoanCreator::Term)
+      term.index  ||= autoincrement_index
+      term.due_on ||= date_for(term.index)
       @terms << term
       self
     end
 
-    def reset_indexes_and_due_on_dates
-      @autoincrement_index = 0
-      @autoincrement_date = @starts_on
-      @terms.each do |term|
-        term[:index] = autoincrement_index
-        term[:due_on] = autoincrement_date
-      end
-      self
-    end
-
     def to_csv(header: true)
       output = []
       output << terms.first.to_h.keys.join(',') if header
@@ -43,20 +38,33 @@ module LoanCreator
       output
     end
 
+    def term(index)
+      @terms.find { |term| term.index == index }
+    end
+
     private
 
-    # First term index of a timetable term is 1
     def autoincrement_index
-      @autoincrement_index ||= 0
-      @autoincrement_index += 1
+      @current_index = @current_index.nil? ? 1 : @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
 
-    # First term due_on date of timetable term is the starts_on given date
-    def autoincrement_date
-      @autoincrement_date ||= @starts_on
-      date = @autoincrement_date
-      @autoincrement_date = @autoincrement_date.advance(PERIODS.fetch(@period))
-      date
+    def reset_dates
+      @_dates = nil
     end
   end
 end

data/lib/loan_creator/version.rb

@@ -1,3 +1,3 @@
 module LoanCreator
-  VERSION = '0.2.3'.freeze
+  VERSION = '0.5.0'.freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: loan_creator
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.5.0
 platform: ruby
 authors:
 - thibaulth
@@ -126,6 +126,7 @@ files:
 - ".ruby-gemset"
 - ".ruby-version"
 - ".travis.yml"
+- CapSens_Loan.xlsx
 - Gemfile
 - LICENSE.txt
 - README.md