double_entry 0.0.1.pre → 0.1.0.pre.pre.alpha

data/lib/double_entry.rb

@@ -1,5 +1,270 @@
-require "double_entry/version"
+# encoding: utf-8
 
+require 'active_record'
+require 'active_record/locking_extensions'
+
+require 'active_support/all'
+
+require 'money'
+require 'encapsulate_as_money'
+
+require 'double_entry/version'
+require 'double_entry/configurable'
+require 'double_entry/account'
+require 'double_entry/account_balance'
+require 'double_entry/reporting'
+require 'double_entry/aggregate'
+require 'double_entry/aggregate_array'
+require 'double_entry/time_range'
+require 'double_entry/time_range_array'
+require 'double_entry/day_range'
+require 'double_entry/hour_range'
+require 'double_entry/week_range'
+require 'double_entry/month_range'
+require 'double_entry/year_range'
+require 'double_entry/line'
+require 'double_entry/line_aggregate'
+require 'double_entry/line_check'
+require 'double_entry/locking'
+require 'double_entry/transfer'
+
+# Keep track of all the monies!
+#
+# This module provides the public interfaces for everything to do with
+# transferring money around the system.
 module DoubleEntry
-  # Your code goes here...
+
+  class UnknownAccount < RuntimeError; end
+  class TransferNotAllowed < RuntimeError; end
+  class TransferIsNegative < RuntimeError; end
+  class RequiredMetaMissing < RuntimeError; end
+  class DuplicateAccount < RuntimeError; end
+  class DuplicateTransfer < RuntimeError; end
+  class UserAccountNotLocked < RuntimeError; end
+  class AccountWouldBeSentNegative < RuntimeError; end
+
+  class << self
+    attr_accessor :accounts, :transfers
+
+    # Get the particular account instance with the provided identifier and
+    # scope.
+    #
+    # @example Obtain the 'cash' account for a user
+    #   DoubleEntry.account(:cash, scope: user)
+    # @param identifier [Symbol] The symbol identifying the desired account. As
+    #   specified in the account configuration.
+    # @option options :scope Limit the account to the given scope. As specified
+    #   in the account configuration.
+    # @return [DoubleEntry::Account::Instance]
+    # @raise [DoubleEntry::UnknownAccount] The described account has not been
+    #   configured. It is unknown.
+    #
+    def account(identifier, options = {})
+      account = @accounts.detect do |current_account|
+        current_account.identifier == identifier and
+          (options[:scope] ? current_account.scoped? : !current_account.scoped?)
+      end
+
+      if account
+        DoubleEntry::Account::Instance.new(:account => account, :scope => options[:scope])
+      else
+        raise UnknownAccount.new("account: #{identifier} scope: #{options[:scope]}")
+      end
+    end
+
+    # Transfer money from one account to another.
+    #
+    # Only certain transfers are allowed. Define legal transfers in your
+    # configuration file.
+    #
+    # If you're doing more than one transfer in one hit, or you're doing other
+    # database operations along with your transfer, you'll need to use the
+    # lock_accounts method.
+    #
+    # @example Transfer $20 from a user's checking to savings account
+    #   checking_account = DoubleEntry.account(:checking, scope: user)
+    #   savings_account  = DoubleEntry.account(:savings,  scope: user)
+    #   DoubleEntry.transfer(
+    #     Money.new(20_00),
+    #     from: checking_account,
+    #     to:   savings_account,
+    #     code: :save,
+    #   )
+    # @param amount [Money] The quantity of money to transfer from one account
+    #   to the other.
+    # @option options :from [DoubleEntry::Account::Instance] Transfer money out
+    #   of this account.
+    # @option options :to [DoubleEntry::Account::Instance] Transfer money into
+    #   this account.
+    # @option options :code [Symbol] Your application specific code for this
+    #   type of transfer. As specified in the transfer configuration.
+    # @option options :meta [String] Metadata to associate with this transfer.
+    # @option options :detail [ActiveRecord::Base] ActiveRecord model
+    #   associated (via a polymorphic association) with the transfer.
+    # @raise [DoubleEntry::TransferIsNegative] The amount is less than zero.
+    # @raise [DoubleEntry::TransferNotAllowed] A transfer between these
+    #   accounts with the provided code is not allowed. Check configuration.
+    #
+    def transfer(amount, options = {})
+      raise TransferIsNegative if amount < Money.new(0)
+      from, to, code, meta, detail = options[:from], options[:to], options[:code], options[:meta], options[:detail]
+      transfer = @transfers.find(from, to, code)
+      if transfer
+        transfer.process!(amount, from, to, code, meta, detail)
+      else
+        raise TransferNotAllowed.new([from.identifier, to.identifier, code].inspect)
+      end
+    end
+
+    # Get the current balance of an account, as a Money object.
+    #
+    # @param account [DoubleEntry::Account:Instance, Symbol]
+    # @option options :scope [Symbol]
+    # @option options :from [Time]
+    # @option options :to [Time]
+    # @option options :at [Time]
+    # @option options :code [Symbol]
+    # @option options :codes [Array<Symbol>]
+    # @return [Money]
+    def balance(account, options = {})
+      scope_arg = options[:scope] ? options[:scope].id.to_s : nil
+      scope = (account.is_a?(Symbol) ? scope_arg : account.scope_identity)
+      account = (account.is_a?(Symbol) ? account : account.identifier).to_s
+      from, to, at = options[:from], options[:to], options[:at]
+      code, codes = options[:code], options[:codes]
+
+      # time based scoping
+      conditions = if at
+        # lookup method could use running balance, with a order by limit one clause
+        # (unless it's a reporting call, i.e. account == symbol and not an instance)
+        ['account = ? and created_at <= ?', account, at] # index this??
+      elsif from and to
+        ['account = ? and created_at >= ? and created_at <= ?', account, from, to] # index this??
+      else
+        # lookup method could use running balance, with a order by limit one clause
+        # (unless it's a reporting call, i.e. account == symbol and not an instance)
+        ['account = ?', account]
+      end
+
+      # code based scoping
+      if code
+        conditions[0] << ' and code = ?' # index this??
+        conditions << code.to_s
+      elsif codes
+        conditions[0] << ' and code in (?)' # index this??
+        conditions << codes.collect { |c| c.to_s }
+      end
+
+      # account based scoping
+      if scope
+        conditions[0] << ' and scope = ?'
+        conditions << scope
+
+        # This is to work around a MySQL 5.1 query optimiser bug that causes the ORDER BY
+        # on the query to fail in some circumstances, resulting in an old balance being
+        # returned. This was biting us intermittently in spec runs.
+        # See http://bugs.mysql.com/bug.php?id=51431
+        if Line.connection.adapter_name.match /mysql/i
+          use_index = "USE INDEX (lines_scope_account_id_idx)"
+        end
+      end
+
+      if (from and to) or (code or codes)
+        # from and to or code lookups have to be done via sum
+        Money.new(Line.where(conditions).sum(:amount))
+      else
+        # all other lookups can be performed with running balances
+        line = Line.select("id, balance").from("#{Line.quoted_table_name} #{use_index}").where(conditions).order('id desc').first
+        line ? line.balance : Money.empty
+      end
+    end
+
+    # Identify the scopes with the given account identifier holding at least
+    # the provided minimum balance.
+    #
+    # @example Find users with at lease $1,000,000 in their savings accounts
+    #   DoubleEntry.scopes_with_minimum_balance_for_account(
+    #     Money.new(1_000_000_00),
+    #     :savings
+    #   ) # might return user ids: [ 1423, 12232, 34729 ]
+    # @param minimum_balance [Money] Minimum account balance a scope must have
+    #   to be included in the result set.
+    # @param account_identifier [Symbol]
+    # @return [Array<Fixnum>] Scopes
+    def scopes_with_minimum_balance_for_account(minimum_balance, account_identifier)
+      select_values(sanitize_sql_array([<<-SQL, account_identifier, minimum_balance.cents])).map {|scope| scope.to_i }
+        SELECT scope
+          FROM #{AccountBalance.table_name}
+         WHERE account = ?
+           AND balance >= ?
+      SQL
+    end
+
+    # Lock accounts in preparation for transfers.
+    #
+    # This creates a transaction, and uses database-level locking to ensure
+    # that we're the only ones who can transfer to or from the given accounts
+    # for the duration of the transaction.
+    #
+    # @example Lock the savings and checking accounts for a user
+    #   checking_account = DoubleEntry.account(:checking, scope: user)
+    #   savings_account  = DoubleEntry.account(:savings,  scope: user)
+    #   DoubleEntry.lock_accounts(checking_account, savings_account) do
+    #     # ...
+    #   end
+    # @yield Hold the locks while the provided block is processed.
+    # @raise [DoubleEntry::Locking::LockMustBeOutermostTransaction]
+    #   The transaction must be the outermost database transaction
+    #
+    def lock_accounts(*accounts, &block)
+      DoubleEntry::Locking.lock_accounts(*accounts, &block)
+    end
+
+    # @api private
+    def describe(line)
+      # make sure we have a test for this refactoring, the test
+      # conditions are: i forget... but it's important!
+      if line.credit?
+        @transfers.find(line.account, line.partner_account, line.code)
+      else
+        @transfers.find(line.partner_account, line.account, line.code)
+      end.description.call(line)
+    end
+
+    def aggregate(function, account, code, options = {})
+      DoubleEntry::Aggregate.new(function, account, code, options).formatted_amount
+    end
+
+    def aggregate_array(function, account, code, options = {})
+      DoubleEntry::AggregateArray.new(function, account, code, options)
+    end
+
+    # This is used by the concurrency test script.
+    #
+    # @api private
+    # @return [Boolean] true if all the amounts for an account add up to the final balance,
+    #   which they always should.
+    def reconciled?(account)
+      scoped_lines = Line.where(:account => "#{account.identifier}", :scope => "#{account.scope}")
+      sum_of_amounts = scoped_lines.sum(:amount)
+      final_balance  = scoped_lines.order(:id).last[:balance]
+      cached_balance = AccountBalance.find_by_account(account)[:balance]
+      final_balance == sum_of_amounts && final_balance == cached_balance
+    end
+
+    def table_name_prefix
+      'double_entry_'
+    end
+
+  private
+
+    delegate :connection, :to => ActiveRecord::Base
+    delegate :select_values, :to => :connection
+
+    def sanitize_sql_array(sql_array)
+      ActiveRecord::Base.send(:sanitize_sql_array, sql_array)
+    end
+
+  end
+
 end

data/lib/double_entry/account.rb

@@ -0,0 +1,82 @@
+# encoding: utf-8
+module DoubleEntry
+  class Account
+    class Set < Array
+      def <<(account)
+        if detect { |a| a.identifier == account.identifier }
+          raise DuplicateAccount.new
+        else
+          super(account)
+        end
+      end
+    end
+
+    class Instance
+      attr_accessor :account, :scope
+
+      def initialize(attributes)
+        attributes.each { |name, value| send("#{name}=", value) }
+      end
+
+      def method_missing(method, *args)
+        if block_given?
+          account.send(method, *args, &Proc.new)
+        else
+          account.send(method, *args)
+        end
+      end
+
+      def scope_identity
+        scope_identifier.call(scope).to_s if scoped?
+      end
+
+      def balance(args = {})
+        DoubleEntry.balance(self, args)
+      end
+
+      include Comparable
+
+      def ==(other)
+        other.is_a?(self.class) && identifier == other.identifier && scope_identity == other.scope_identity
+      end
+
+      def eql?(other)
+        self == other
+      end
+
+      def <=>(account)
+        if scoped?
+          [scope_identity, identifier.to_s] <=> [account.scope_identity, account.identifier.to_s]
+        else
+          identifier.to_s <=> account.identifier.to_s
+        end
+      end
+
+      def hash
+        if scoped?
+          "#{scope_identity}:#{identifier}".hash
+        else
+          identifier.hash
+        end
+      end
+
+      def to_s
+        "\#{Account account: #{identifier} scope: #{scope}}"
+      end
+
+      def inspect
+        to_s
+      end
+    end
+
+    attr_accessor :identifier, :scope_identifier, :positive_only
+
+    def initialize(attributes)
+      attributes.each { |name, value| send("#{name}=", value) }
+    end
+
+    def scoped?
+      !!scope_identifier
+    end
+  end
+end

data/lib/double_entry/account_balance.rb

@@ -0,0 +1,31 @@
+# encoding: utf-8
+module DoubleEntry
+
+  # Account balance records cache the current balance for each account. They
+  # also provide a database representation of an account that we can use to do
+  # DB level locking.
+  #
+  # See DoubleEntry::Locking for more info on locking.
+  #
+  # Account balances are created on demand when transfers occur.
+  class AccountBalance < ActiveRecord::Base
+    extend EncapsulateAsMoney
+
+    encapsulate_as_money :balance
+
+    def account=(account)
+      self[:account] = account.identifier.to_s
+      self[:scope] = account.scope_identity
+      account
+    end
+
+    def self.find_by_account(account, options = {})
+      scope = where(:scope => account.scope_identity, :account => account.identifier.to_s)
+      scope = scope.lock(true) if options[:lock]
+      scope.first
+    end
+
+  end
+
+end
+

data/lib/double_entry/aggregate.rb

@@ -0,0 +1,118 @@
+# encoding: utf-8
+module DoubleEntry
+  class Aggregate
+    attr_reader :function, :account, :code, :scope, :range, :options, :filter
+
+    def initialize(function, account, code, options)
+      @function = function.to_s
+      raise "Function not supported" unless %w[sum count average].include?(@function)
+
+      @account = account.to_s
+      @code = code ? code.to_s : nil
+      @options = options
+      @scope = options[:scope]
+      @range = options[:range]
+      @filter = options[:filter]
+    end
+
+    def amount(force_recalculation = false)
+      if force_recalculation
+        clear_old_aggregates
+        calculate
+      else
+        retrieve || calculate
+      end
+    end
+
+    def formatted_amount
+      Aggregate.formatted_amount(function, amount)
+    end
+
+    def self.formatted_amount(function, amount)
+      safe_amount = amount || 0
+
+      case function.to_s
+      when 'count'
+        safe_amount
+      else
+        Money.new(safe_amount)
+      end
+    end
+
+    private
+
+    def retrieve
+      aggregate = LineAggregate.where(field_hash).first
+      aggregate.amount if aggregate
+    end
+
+    def clear_old_aggregates
+      LineAggregate.delete_all(field_hash)
+    end
+
+    def calculate
+      if range.class == DoubleEntry::YearRange
+        aggregate = calculate_yearly_aggregate
+      else
+        aggregate = LineAggregate.aggregate(function, account, code, nil, range, filter)
+      end
+
+      if range_is_complete?
+        fields = field_hash
+        fields[:amount] = aggregate || 0
+        LineAggregate.create! fields
+      end
+
+      aggregate
+    end
+
+    def calculate_yearly_aggregate
+      # We calculate yearly aggregates by combining monthly aggregates
+      # otherwise they will get excruciatingly slow to calculate
+      # as the year progresses.  (I am thinking mainly of the 'current' year.)
+      # Combining monthly aggregates will mean that the figure will be partially memoized
+      case function.to_s
+      when 'average'
+        calculate_yearly_average
+      else
+        zero = Aggregate.formatted_amount(function, 0)
+
+        result = (1..12).inject(zero) do |total, month|
+          total += DoubleEntry.aggregate(function, account, code,
+                                      :range => DoubleEntry::MonthRange.new(:year => range.year, :month => month), :filter => filter)
+        end
+
+        result = result.cents if result.class == Money
+        result
+      end
+    end
+
+    def calculate_yearly_average
+      # need this seperate function, because an average of averages is not the correct average
+      sum = DoubleEntry.aggregate(:sum, account, code,
+                               :range => DoubleEntry::YearRange.new(:year => range.year), :filter => filter)
+      count = DoubleEntry.aggregate(:count, account, code,
+                                 :range => DoubleEntry::YearRange.new(:year => range.year), :filter => filter)
+      (count == 0) ? 0 : (sum / count).cents
+    end
+
+    def range_is_complete?
+      Time.now > range.finish
+    end
+
+    def field_hash
+      {
+        :function => function,
+        :account => account,
+        :code => code,
+        :year => range.year,
+        :month => range.month,
+        :week => range.week,
+        :day => range.day,
+        :hour => range.hour,
+        :filter => filter.inspect,
+        :range_type => range.range_type.to_s
+      }
+    end
+  end
+end