aloe 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: f4a87bfd19ba538180dce803adff1c2f305f16da
+  data.tar.gz: bb678013f56e69ba1c22f96ed892ff355978545e
+SHA512:
+  metadata.gz: a150a76f4770ca11ebb642ad73a6f00b063535cf450ae903ffc9fc8fd4fe23c5672459407fe89925860b494bac524bbb6e0e10d7fc609773e55a601f525ae916
+  data.tar.gz: 63166ea20295695082ba9d6f2e43ea905226bfcc23f3fb60ecf32870ee0730f60d2632d8f9491c72a89dbdadd89b3571f14b2b4f9ed09473c3b35de87655d9f0

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright 2013 YOURNAME
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,26 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Aloe'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+APP_RAKEFILE = File.expand_path("../spec/dummy/Rakefile", __FILE__)
+load 'rails/tasks/engine.rake'
+
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec
+

data/lib/aloe.rb

@@ -0,0 +1,14 @@
+require 'aloe/ledger'
+require 'aloe/engine'
+require 'aloe/reports/account_history'
+require 'aloe/reports/accounts_list'
+
+module Aloe
+
+  ROLLBACK_TRANSACTION = 'rollback'.freeze
+
+  def self.table_name_prefix
+    'aloe_'
+  end
+
+end

data/lib/aloe/account.rb

@@ -0,0 +1,176 @@
+require 'aloe/account_repository'
+require 'aloe/account_configuration'
+require 'aloe/entry'
+require 'active_record'
+require 'money'
+require 'state_machine'
+require 'active_support/core_ext/object/with_options'
+
+module Aloe
+  class Account < ActiveRecord::Base
+
+    extend Aloe::AccountRepository
+
+    # Associations
+
+    belongs_to :owner, polymorphic: true
+    has_many :entries, class_name: "Aloe::Entry", include: :account
+    has_many :debit_transactions, through: :entries
+    has_many :credit_transactions, through: :entries
+
+    # Validations
+
+    validates :currency, presence: true
+    with_options scope: :currency do |opts|
+      opts.validates_uniqueness_of :name, if: ->{ name? }
+    end
+    validate :uniqueness_of_owner
+
+    # State machine
+
+    # An account can have following states:
+    #   * open - can be manipulated
+    #   * suspended - cannot be manipulated, needs to be unsuspended first
+    #   * closed - cannot be manipulated, only with 0 balance
+    state_machine :state, initial: :open do
+      event :close do
+        transition all => :closed, if: :closeable?
+      end
+
+      event :reopen do
+        transition :closed => :open
+      end
+
+      event :suspend do
+        transition all => :suspended
+      end
+
+      event :unsuspend do
+        transition :suspended => :open
+      end
+    end
+
+    # Instance methods
+
+    serialize :configuration, Aloe::AccountConfiguration
+
+    delegate :allow_negative_balance, to: :configuration
+
+    # Return the balance of account
+    #
+    # @return [Money] The balance
+    def balance
+      Money.new read_attribute(:balance), currency
+    end
+
+    # Computes the balance of the account at the requested date and time.
+    # Returns nil if the account did not exist at that time.
+    #
+    # @param [Time] the date and time
+    # @return [Money] the past balance
+    def balance_at(time)
+      return nil unless created_at <= time
+      amount = entries.where('created_at >= ?', time).sum(&:amount)
+      offset = amount == 0 ? Money.new(0, currency) : amount
+      balance - offset
+    end
+
+    # Does account have minimum given balance?
+    #
+    # @param [Money, Fixnum] amount Amount in question in cents
+    # @param [NilClass, Symbol] option Option
+    # @return [true, false]
+    def balance_of?(amount, option = nil)
+      reload if option == :reload
+      cents_amount = amount.respond_to?(:cents) ? amount.cents : amount
+      read_attribute(:balance) >= cents_amount
+    end
+
+    # Can the account be closed?
+    #
+    # An account can be closed only if the balance is 0.
+    #
+    # @return [true, false]
+    def closeable?
+      balance.zero?
+    end
+
+    # Creates entry in the account.
+    #
+    # Creates new entry and modified the balance.
+    #
+    # @param [Fixnum] cents_amount Amount in cents
+    # @return [Aloe::Entry] Created entry
+    def create_entry(cents_amount)
+      with_lock(true) do
+        if cents_amount < 0 && !debit_possible?(-cents_amount)
+          raise Aloe::InsufficientBalanceError.new(self, -cents_amount)
+        end
+        entry = entries.create! amount: cents_amount
+        increment! :balance, cents_amount
+        entry
+      end
+    end
+
+    # Is account in given currency?
+    #
+    # @param [Currency, Symbol, String] currency_in_question
+    # @return [true, false]
+    def currency?(currency_in_question)
+      currency.to_s == currency_in_question.to_s
+    end
+
+    # Is the debit of given amount possible?
+    #
+    # @param [Money, Fixnum] amount Amount in question in cents
+    # @return [true, false]
+    def debit_possible?(amount)
+      allow_negative_balance ? true : balance_of?(amount, :reload)
+    end
+
+    # Rolls back all transactions on this account.
+    def rollback_all
+      transactions = entries.map &:transaction
+      transactions.map &:rollback
+    end
+
+    # Return string representation of account.
+    #
+    # @return [String]
+    def to_s
+      name? ? name : owner_type_and_id
+    end
+
+    # Return account turnover over given period of time.
+    #
+    # @param [Range] period
+    # @return [Money]
+    def turnover(period)
+      turnover = entries.where(created_at: period).sum &:amount
+      turnover == 0 ? Money.new(0, currency) : turnover
+    end
+
+    # Return account owner type and it's ID.
+    #
+    # @return [String]
+    def owner_type_and_id
+      "#{owner_type} #{owner_id}" if owner.present?
+    end
+
+    protected
+
+    def uniqueness_of_owner
+      if has_conflicting_account_for_owner?
+        message = I18n.t('aloe.accounts.errors.owner_already_has_account')
+        errors.add(:owner, message)
+      end
+    end
+
+    def has_conflicting_account_for_owner?
+      new_record? && owner.present? &&
+        self.class.owner(owner).currency(currency).where(name: name).exists?
+    end
+
+  end
+end
+

data/lib/aloe/account_configuration.rb

@@ -0,0 +1,21 @@
+module Aloe
+  class AccountConfiguration
+
+    attr_writer :allow_negative_balance
+
+    def initialize(attrs = {})
+      attrs.each do |k ,v|
+        public_send :"#{k}=", v
+      end
+    end
+
+    # Does the account allow negative balance?
+    # Defaults to true if no values is provided
+    #
+    # @return [true, false]
+    def allow_negative_balance
+      @allow_negative_balance == false ? false : true
+    end
+
+  end
+end

data/lib/aloe/account_repository.rb

@@ -0,0 +1,45 @@
+module Aloe
+  module AccountRepository
+
+    # Scope by currency.
+    #
+    # @param [String, Symbol] currency Currency symbol
+    # @return [ActiveRecord::Relation]
+    def currency(currency)
+      where(currency: currency)
+    end
+
+    # Default scope excludes closed accounts.
+    def default_scope
+      where('state != ?', 'closed')
+    end
+
+    # Scope to closed accounts.
+    #
+    # @return [ActiveRecord::Relation]
+    def closed
+      unscoped.with_state('closed')
+    end
+
+    # Scope by owner.
+    #
+    # @param [ActiveRecord::Base] owner
+    # @return [ActiveRecord::Relation]
+    def owner(owner)
+      where(owner_type: owner.class.model_name.to_s, owner_id: owner.id)
+    end
+
+    # Return the trial balance.
+    #
+    # Trial balance is balance of all accounts in the system
+    # combined. It should at all times be 0. If it's not, there
+    # is an error in accounts somewhere.
+    #
+    # @param [String, Symbol] currency Currency symbol
+    # @return [Fixnum] Zero if everything's fine
+    def trial_balance(currency)
+      currency(currency).sum :balance
+    end
+
+  end
+end

data/lib/aloe/engine.rb

@@ -0,0 +1,6 @@
+module Aloe
+
+  class Engine < Rails::Engine
+  end
+
+end

data/lib/aloe/entry.rb

@@ -0,0 +1,59 @@
+require 'aloe/account'
+require 'aloe/transaction'
+require 'active_record'
+require 'money'
+
+module Aloe
+  class Entry < ActiveRecord::Base
+
+    # Scopes
+
+    default_scope do
+      order('aloe_entries.created_at DESC')
+    end
+
+    scope :withdrawals, -> { where('amount < 0') }
+    scope :deposits,    -> { where('amount > 0') }
+
+    # Associations
+
+    belongs_to :account, class_name: "Aloe::Account"
+    has_one :credit_transaction, class_name: "Aloe::Transaction",
+                                 foreign_key: "credit_entry_id"
+    has_one :debit_transaction, class_name: "Aloe::Transaction",
+                                foreign_key: "debit_entry_id"
+
+    # Instance methods
+
+    delegate :currency, to: :account
+
+    # Return the amount of entry
+    #
+    # @return [Money] The amount
+    def amount
+      Money.new read_attribute(:amount), currency
+    end
+    #
+    # Return the related transaction.
+    #
+    # @return [Aloe::Transaction]
+    def transaction
+      credit_transaction || debit_transaction
+    end
+
+    # Is the entry deposit of funds?
+    #
+    # @return [true, false]
+    def deposit?
+      !withdrawal?
+    end
+
+    # Is the entry withdrawal of funds?
+    #
+    # @return [true, false]
+    def withdrawal?
+      amount.negative?
+    end
+
+  end
+end

data/lib/aloe/inoperable_account_error.rb

@@ -0,0 +1,11 @@
+module Aloe
+  class InoperableAccountError < StandardError
+    def initialize(account)
+      @account = account
+    end
+
+    def to_s
+      "Account #{@account} is inoperable! (account state: #{@account.state})"
+    end
+  end
+end

data/lib/aloe/insufficient_balance_error.rb

@@ -0,0 +1,14 @@
+module Aloe
+  class InsufficientBalanceError < StandardError
+
+    def initialize(account, expected_balance)
+      @account, @expected_balance = account, expected_balance
+    end
+
+    def to_s
+      "Account #{@account} has not enough balance" +
+        " - required at least #{@expected_balance}!"
+    end
+
+  end
+end

data/lib/aloe/invalid_amount_error.rb

@@ -0,0 +1,3 @@
+module Aloe
+  class InvalidAmountError < StandardError; end
+end

data/lib/aloe/invalid_currency_error.rb

@@ -0,0 +1,16 @@
+module Aloe
+  class InvalidCurrencyError < StandardError
+
+    def initialize(credit_account, debit_account, currency)
+      @credit_account = credit_account
+      @debit_account = debit_account
+      @currency = currency
+    end
+
+    def to_s
+      "Different currencies on accounts #{@credit_account}, #{@debit_account}" +
+        " - expected #{@currency}."
+    end
+
+  end
+end

data/lib/aloe/ledger.rb

@@ -0,0 +1,83 @@
+require 'aloe/account'
+require 'aloe/transaction'
+require 'aloe/ledger_entry'
+require 'money'
+
+module Aloe
+  # Ledger is the façade interface to the account. When manipulating accounts
+  # (eg. creating transactions between accounts) you should use the Ledger and
+  # not the underlying models.
+  module Ledger
+
+    extend self
+
+    attr_writer :account_scope
+
+    # Returns an account for given owner.
+    #
+    # @param [Object, Symbol] owner Account owner or account name
+    # @param [String, Symbol] currency Currency symbol
+    # @return [Aloe::Account, nil] Account which belongs to given object
+    #   or nil
+    def find_account(owner, currency = default_currency)
+      scope_for_owner(owner).currency(currency.to_s).first
+    end
+
+    # Returns accounts for a given owner.
+    #
+    # @param [Object, Symbol] owner Account owner or account name
+    # @param [String, Symbol] currency Currency symbol
+    # @return [Aloe::Account, nil] Array of accounts which belongs to
+    #   given object
+    def find_accounts(owner, currency = nil)
+      scope = scope_for_owner(owner)
+      currency ? scope.currency(currency) : scope
+    end
+
+    # Creates entry in the ledger.
+    #
+    # Creates entries in both credit and debit account and linking
+    # transaction between those two entries. Credit and debit accounts
+    # and given amount have to be in the same currency otherwise an
+    # exception is raised.
+    #
+    # @param [Money] amount The amount of money
+    # @param [Hash] options Options
+    # @option options [Aloe::Account] :from Account which to debit
+    # @option options [Aloe::Account] :to Account which to credit
+    # @option options [Fixnum] :type Type of transaction
+    # @return [Aloe::Transaction]
+    def create_entry(amount, options)
+      Aloe::LedgerEntry.new(amount, options).create!
+    end
+
+    # Return the default currency that gets used when no currency is specified.
+    #
+    # @return [String]
+    def default_currency
+      Money.default_currency.to_s
+    end
+
+    protected
+
+    # Return the scope for account with given owner.
+    #
+    # @param [Object]
+    # @return [ActiveRecord::Relation]
+    def scope_for_owner(owner)
+      if owner.class.respond_to?(:model_name)
+        account_scope.owner(owner)
+      else
+        account_scope.where(name: owner.to_s.titleize)
+      end
+    end
+
+    # Return the scope for Accounts repository.
+    #
+    # @return [ActiveRecord::Relation]
+    def account_scope
+      @account_scope ||= Aloe::Account.unscoped
+    end
+
+  end
+end