PaymentSchedule

PaymentSchedule is a Ruby gem for describing and calculating payment schedules. Its goal is to make implementation and modification of payment schedule algorithms fast and easy to understand.

Requires Ruby 2.4.0 or higher.

Introduction

Easy to use

Simple to keep the algorithm similar to payment schedule's tabular nature. This enables faster changes in the code when the specification changes. At the same time code is clear and readable, even for a person who hasn't got much experience with such algorithms.

Fast

It has good memory and is very lazy — that's why it calculates as little as needed and is very fast.

Example

Take a look at the example, which demostrates the simplicity of the gem.

Example specification (spreadsheet)

Algorithm implemented using a spreadsheet software: amortization_schedule.xlsx

Screenshot:

Example implementation in Ruby

Algorithm implementation in Ruby, based on the spreadsheet: amortization_schedule.rb

Screenshot:

Getting Started

Add this line to your application's Gemfile:
```
gem 'payment_schedule'
```
In project directory, execute:
```
bundle
```

Create a class which describes the algorithm:

# Description of My Awesome Payment Schedule algorithm.
# References spreadsheet examples/amortization_schedule.xlsx

MyAwesomeSchedule = PaymentSchedule.new do
  require_input(
    :loan_amount,        # Cell: C5
    :loan_term,          # Cell: C6
    :interest_rate_year  # Cell: C7
  )

  # Helper required by algorithm for output and summation
  helper(:first_row_number) do
    0
  end

  # Helper required by algorithm for output and summation
  helper(:last_row_number) do
    self[:loan_term]
  end

  # Cell: C8
  helper(:interest_rate_month) do
    (1 + self[:interest_rate_year].to_d) ** (1 / 12.to_d) - 1
  end

  # Column: G
  # Note: modified for simplified example
  component(:balance) do
    # Cells: G6-G7
    rows(0..1) { self[:loan_amount] }

    default do |n|
      self[:balance, n - 1] - n * 5
    end
  end

  # Column: I
  component(:interest) do
    # Cell: I6
    row(0) { 0 }

    default do |n|
      (self[:interest_rate_month] * self[:balance, n]).round(2)
    end
  end
end

Try it out in REPL:

schedule = MyAwesomeSchedule.new(
  loan_amount:        1000,
  loan_term:          12,
  interest_rate_year: 0.1
)

schedule[:balance, 12]
# => 615

schedule[:interest_rate_month]
# => 0.00797414042890374

puts schedule
+----+---------+----------+
|    MyAwesomeSchedule    |
+----+---------+----------+
| No | Balance | Interest |
+----+---------+----------+
| 0  | 1000    | 0        |
| 1  | 1000    | 7.97     |
| 2  | 990     | 7.89     |
| 3  | 975     | 7.77     |
| 4  | 955     | 7.62     |
| 5  | 930     | 7.42     |
| 6  | 900     | 7.18     |
| 7  | 865     | 6.9      |
| 8  | 825     | 6.58     |
| 9  | 780     | 6.22     |
| 10 | 730     | 5.82     |
| 11 | 675     | 5.38     |
| 12 | 615     | 4.9      |
+----+---------+----------+
# => nil

Plug it in to your app
Share it with customers
Profit! 😎

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/Murdho/payment_schedule. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

Wishlist

Things that would make it even nicer to use.

Add proper documentation (preferably TomDoc) for lowering the barriers of entry
Replace MyClassName = PaymentSchedule.new(&block) with class MyClassName < PaymentSchedule::Schedule (or similar) to enable inheritance for schedule definitions. Definitely needs modifications to instruction finding as well
Algorithm for generating the schedule Ruby code automatically based on spreadsheet file
Add more commented examples for demonstrating flexibility, readbility and power!

License

The gem is available as open source under the terms of the MIT License.

murdho/payment_schedule