financial_calculator 2.1.0 → 3.0.0

data/lib/financial_calculator/xnpv.rb

@@ -0,0 +1,91 @@
+module FinancialCalculator
+  # Calculate the net present value of a series of unequally spaced, (potentially) unequal cashflows
+  class Xnpv
+    # @return [Numeric] The rates used for calculating the present value
+    # @api public
+    attr_reader :rate
+
+    # @return [Array<Numeric>] An array of cashflow amounts
+    # @api public
+    attr_reader :cashflows
+
+    # @return [Array<Date>] An array of dates on which the cashflows occur
+    # @api public
+    attr_reader :dates
+
+    # @return [DecNum] Result of the XNPV calculation
+    # @api public
+    attr_reader :result
+
+    # Allows for creating an XNPV calculation with an array of any objects that respond to #amount and #date
+    # @param [Numeric] rate The discount (interest) rate
+    # @param [Array<Transaction>] transaction An array of Transaction objects.
+    # @return [FinancialCalculator::Xnpv]
+    # @api public
+    def self.with_transactions(rate, transactions)
+      raise ArgumentError.new("Argument \"rate\" must be a Numeric. Got #{rate.class} instead") unless rate.is_a? Numeric
+      unless transactions.all? { |t| t.is_a? Transaction }
+        raise ArgumentError.new("Argument \"transactions\" must be an array of Transaction")
+      end
+
+      cashflows  = transactions.map(&:amount)
+      dates      = transactions.map(&:date)
+
+      self.new(rate, cashflows, dates)
+    end
+
+    # Create a new XNPV calculation
+    # @param [Numeric] rate The discount (interest) rate
+    # @param [Array<Numeric>] cashflows An array of cashflows
+    # @param [Array<Date>] dates An array of dates representing when each cashflow occurs
+    # @return [FinancialCalculator::Xnpv]
+    # @raise [ArgumentError] When cashflows and dates are not the same length
+    # @raise [ArgumentError] When dates is not an array of Date
+    # @api public
+    def initialize(rate, cashflows, dates)
+      validate_cashflows_dates_size(cashflows, dates)
+      validate_dates(dates)
+
+      @rate       = Flt::DecNum(rate.to_s)
+      @cashflows  = cashflows.map { |cashflow| Flt::DecNum(cashflow.to_s) }.freeze
+      @dates      = dates.freeze
+      @result     = solve(rate, cashflows, dates)
+    end
+    
+    # @api public
+    def inspect
+      "XNPV(#{result})"
+    end
+
+    private
+
+    # Solve the NPV calcluation.
+    # @note This methods uses a 365 day year regardless of whether or not the 
+    #   year is actually a leap year. This is done in order to maintain 
+    #   consistency with common implementations such as Excel and Google Sheets. 
+    #   In the future it would be nice to have a flag that allows for using 
+    #   the actual number of days in the year
+    def solve(rate, cashflows, dates)
+      start         = dates[0]
+      transactions  = cashflows.zip(dates) 
+      amount_index  = 0
+      date_index    = 1
+      
+      transactions.reduce(0) do |total, transaction|
+        total += transaction[amount_index] / ((1 + @rate) ** (Flt::DecNum(transaction[date_index] - start) / 365)) 
+      end
+    end
+    
+    def validate_dates(dates)
+      unless dates.all? { |date| date.is_a? Date }
+        raise ArgumentError.new("Argument dates must be an array of Date")
+      end
+    end
+
+    def validate_cashflows_dates_size(cashflows, dates)
+      unless dates.length == cashflows.length
+        raise ArgumentError.new("Arguments cashflows and dates must be the same length")
+      end
+    end
+  end
+end

data/spec/irr_spec.rb

@@ -0,0 +1,44 @@
+require_relative 'spec_helper'
+
+describe "Irr" do
+  let(:flows) { [-10, 20, 30, 40] }
+  let(:irr)   { Irr.new(flows) }
+
+  describe '#result' do
+    subject { irr.result }
+
+    it { is_expected.to be_a Flt::DecNum }
+
+    context 'when all values are positive' do
+      let(:flows) { [10, 20, 30, 40] }
+      it_behaves_like 'the values do not converge'
+    end
+
+    context 'when all values are negative' do
+      let(:flows) { [-10, -20, -30, -40] }
+      it_behaves_like 'the values do not converge'
+    end
+
+    context 'when the leading value is zero' do
+      describe 'all other values are positive' do
+        let(:flows) { [0, 10, 20, 30] }
+        it_behaves_like 'the values do not converge'
+      end
+
+      describe 'all other values are negative' do
+        let(:flows) { [0, -10, -20, -30] }
+        it_behaves_like 'the values do not converge'
+      end
+    end
+
+    describe '#inspect' do
+      subject { irr.inspect }
+
+      it { is_expected.to be_a String }
+      it { is_expected.to include 'IRR' }
+      it 'includes the result of the calculation' do
+        expect(subject).to include irr.result.to_s
+      end
+    end
+  end
+end

data/spec/npv_spec.rb

@@ -0,0 +1,39 @@
+require_relative 'spec_helper'
+
+describe "Npv" do
+  let(:rate)      { 0.1 }
+  let(:cashflows) { [10] * 4 }
+  let(:npv)       { Npv.new(rate, cashflows) }
+
+  subject { Npv.new(rate, cashflows) }
+
+  it 'has a rate attribute' do
+    expect(subject).to have_attributes(rate: rate)
+  end
+
+  it 'has an cashflows attribute' do
+    expect(subject).to have_attributes(cashflows: cashflows)
+  end
+
+  it 'has a result attribute' do
+    expect(subject.result).to be_a Numeric
+  end
+
+  context 'when provided a non-numeric rate' do
+    let(:rate) { 'string' }
+
+    it 'raises an ArgumentError' do
+      expect { subject }.to raise_error ArgumentError
+    end
+  end
+
+  describe '#inspect' do
+    subject { npv.inspect }
+
+    it { is_expected.to be_a String }
+    it { is_expected.to include 'NPV' }
+    it 'includes the result of the Npv calculation' do
+      expect(subject).to include npv.result.to_s
+    end
+  end
+end

data/spec/pv_spec.rb

@@ -0,0 +1,127 @@
+require_relative 'spec_helper'
+
+shared_examples_for 'it has invalid present value arguments' do
+  it 'raises an ArgumentError' do
+    expect { subject }.to raise_error ArgumentError
+  end
+end
+
+describe "Pv" do
+  let(:rate)              { 0.1 }
+  let(:num_periods)       { 10 }
+  let(:payment)           { -100 }
+  let(:future_value)      { 0 }
+  let(:pays_at_beginning) { false }
+  let(:present_value)     { Pv.new(rate, num_periods, payment) }
+  
+  subject { present_value }
+
+  it 'has a rate attribute' do
+    expect(subject).to have_attributes(rate: rate)
+  end
+
+  it 'has a num_periods attribute' do
+    expect(subject).to have_attributes(num_periods: num_periods)
+  end
+
+  it 'has a payment attribute' do
+    expect(subject).to have_attributes(payment: payment)
+  end
+
+  it 'has a future_value attribute that defaults to 0' do
+    expect(subject).to have_attributes(future_value: 0)
+  end
+
+  it 'has a pays_at_beginning? attribute that defaults to false' do
+    expect(subject).to have_attributes(pays_at_beginning?: false)
+  end
+
+  it 'has a result attribute whose value is positive' do
+    expect(subject).to have_attributes(result: (a_value > 0))
+  end
+
+  context 'when the payment is positive' do
+    let(:payment) { 100 }
+
+    it 'has a result attribute whose value is negative' do
+      expect(subject).to have_attributes(result: (a_value < 0))
+    end
+  end
+
+  context 'when the payment is 0' do
+    let(:payment) { 0 }
+
+    it 'has a present value of 0' do
+      expect(subject.result).to eql 0
+    end
+  end
+
+  context 'when the number of periods is negative' do
+    let(:num_periods) { -1 }
+    it_behaves_like 'it has invalid present value arguments'
+  end
+
+  context 'when rate is non-numeric' do
+    let(:rate) { 'string' }
+    it_behaves_like 'it has invalid present value arguments'
+  end
+
+  context 'when num_periods is non-numeric' do
+    let(:num_periods) { 'string' }
+    it_behaves_like 'it has invalid present value arguments'
+  end
+
+  context 'when payment is non-numeric' do
+    let(:payment) { 'string' }
+    it_behaves_like 'it has invalid present value arguments'
+  end
+
+  context 'when future_values non-numeric' do
+    let(:future_value) { 'string' }
+    
+    subject { Pv.new(rate, num_periods, payment, future_value) }
+
+    it_behaves_like 'it has invalid present value arguments'
+  end
+
+  context 'when the number of periods is 0' do
+    let(:num_periods) { 0 }
+
+    it 'has a result equal to the future value' do
+      expect(subject.result).to eql future_value
+    end
+  end
+
+  context 'when provided with a future value' do
+    let(:future_value) { 100 }
+
+    subject { Pv.new(rate, num_periods, payment, future_value) }
+
+    it { is_expected.to have_attributes(future_value: future_value) }
+  end
+
+  context 'when payments occur at the beginning of each period' do
+    let(:pays_at_beginning) { true }
+
+    subject { Pv.new(rate, num_periods, payment, 0, pays_at_beginning) }
+
+    it { is_expected.to have_attributes(pays_at_beginning?: true) }
+  end
+
+  describe '#inspect' do
+
+    subject { present_value.inspect }
+
+    it { is_expected.to be_a String }
+    it { is_expected.to include 'PV' }
+    it 'includes the result of the present value calculation' do
+      expect(subject).to include present_value.result.to_s
+    end
+  end
+
+  describe '#result' do
+    subject { present_value.result }
+
+    it {is_expected.to be_a Flt::DecNum }
+  end
+end

data/spec/spec_helper.rb

@@ -1,14 +1,12 @@
 require 'simplecov'
 require 'coveralls'
 
-Coveralls.wear!
+# Coveralls.wear!
 SimpleCov.start do
-  minimum_coverage 99 
+  add_filter "/spec/"
+  minimum_coverage 100
 end
 
-require 'minitest/autorun'
-require 'minitest/spec'
-
 require 'active_support/all'
 
 require 'pry'
@@ -16,8 +14,11 @@ require 'pry'
 require 'flt'
 require 'flt/d'
 
-require_relative '../lib/financial_calculator/amortization.rb'
-require_relative '../lib/financial_calculator/cashflows.rb'
-require_relative '../lib/financial_calculator/rates.rb'
-require_relative '../lib/financial_calculator/transaction.rb'
+require_relative '../lib/financial_calculator'
 include FinancialCalculator
+
+shared_examples_for 'the values do not converge' do
+  it 'should raise an ArgumentError' do
+    expect { subject }.to raise_error ArgumentError
+  end
+end

data/spec/xirr_spec.rb

@@ -0,0 +1,73 @@
+require_relative 'spec_helper'
+
+describe "Xirr" do
+  let(:flows) { [-10, 20, 30, 40] }
+  let(:dates) do
+    [
+      Date.new(2018, 1, 1),
+      Date.new(2018, 6, 1),
+      Date.new(2018, 9, 1),
+      Date.new(2018, 12, 1)
+    ]
+  end
+
+  describe '::with_transactions' do
+    let(:transactions) do 
+      flows.zip(dates).map { |flow_and_date| Transaction.new(flow_and_date[0], date: flow_and_date[1]) }
+    end
+
+    subject { Xirr.with_transactions(transactions) }
+
+    it 'returns an Xirr object' do
+      expect(subject).to be_a Xirr 
+    end
+
+    context 'the array contains objects other than Transaction' do
+      let(:transactions) { flows }
+
+      it 'raises an ArgumentError' do
+        expect { subject }.to raise_error ArgumentError
+      end
+    end
+  end
+
+  describe '#result' do
+    subject { Xirr.new(flows, dates).result }
+
+    it { is_expected.to be_a Flt::DecNum }
+
+    context 'when all values are positive' do
+      let(:flows) { [10, 20, 30, 40] }
+      let(:flows) { [10, 20, 30, 40] }
+      it_behaves_like 'the values do not converge'
+    end
+
+    context 'when all values are negative' do
+      let(:flows) { [-10, -20, -30, -40] }
+      it_behaves_like 'the values do not converge'
+    end
+
+    context 'when the leading value is zero' do
+      describe 'all other values are positive' do
+        let(:flows) { [0, 10, 20, 30] }
+        it_behaves_like 'the values do not converge'
+      end
+
+      describe 'all other values are negative' do
+        let(:flows) { [0, -10, -20, -30] }
+        it_behaves_like 'the values do not converge'
+      end
+    end
+  end
+
+  describe '#inspect' do
+    let(:xirr) { Xirr.new(flows, dates) }
+    subject { xirr.inspect }
+
+    it { is_expected.to be_a String }
+    it { is_expected.to include 'XIRR' }
+    it 'includes the result of the calculation' do
+      expect(subject).to include xirr.result.to_s
+    end
+  end
+end

data/spec/xnpv_spec.rb

@@ -0,0 +1,81 @@
+require_relative 'spec_helper'
+
+describe "Xnpv" do
+  let(:cashflows) { [1000] * 5 }
+  let(:year)      { 2017 }
+  let(:rate)      { 0.02 }
+  let(:xnpv)      { Xnpv.new(rate, cashflows, dates) }
+  let(:dates) do
+    [
+      Date.new(year, 1, 1),
+      Date.new(year, 3, 1),
+      Date.new(year, 6, 1),
+      Date.new(year, 6, 15),
+      Date.new(year, 6, 30)
+    ]
+  end
+
+  subject { xnpv }
+
+  it 'has a cashflows property' do
+    expect(subject).to have_attributes(cashflows: cashflows)
+  end
+  
+  it 'has a rate property' do
+    expect(subject).to have_attributes(rate: rate)
+  end
+
+  it 'has a dates property' do
+    expect(subject).to have_attributes(dates: dates)
+  end
+
+  it 'has a result property' do
+    expect(subject.result).to be_a Flt::DecNum
+  end
+  
+  context 'when dates and cashflows are not the same size' do
+    let(:transactions) { cashflows[1..-1] }
+    
+    subject { Xnpv.new(rate, transactions, dates) }
+
+    it 'raises an ArgumentError' do
+      expect { subject }.to raise_error ArgumentError
+    end
+  end
+
+  context 'when the dates array does not contain only dates' do
+    let(:dates) { [Date.today] * 4 + [1] }
+
+    it 'raises an ArgumentError' do
+      expect { subject }.to raise_error ArgumentError
+    end
+  end
+
+  describe '::with_transactions' do
+    let(:transactions) { dates.map { |date| Transaction.new(1000, date: date) } } 
+
+    subject { Xnpv.with_transactions(rate, transactions) }
+
+    it 'returns an Xnpv object' do
+      expect(subject).to be_a Xnpv
+    end
+
+    context 'the array contains objects other than Transaction' do
+      let(:transactions) { cashflows }
+
+      it 'raises an ArgumentError' do
+        expect { subject }.to raise_error ArgumentError
+      end
+    end
+  end
+
+  describe '#inspect' do
+    subject { xnpv.inspect }
+
+    it { is_expected.to include 'XNPV' }
+
+    it 'includes the result of the calculation' do
+      expect(subject).to include xnpv.result.to_s
+    end
+  end
+end