double_entry 0.2.0 → 0.3.0

data/README.md

@@ -66,7 +66,9 @@ than scoped accounts due to lock contention.
 
 To get a particular account:
 
-    account = DoubleEntry.account(:spending, :scope => user)
+```ruby
+account = DoubleEntry.account(:spending, :scope => user)
+```
 
 (This actually returns an Account::Instance object.)
 
@@ -77,7 +79,9 @@ See **DoubleEntry::Account** for more info.
 
 Calling:
 
-    account.balance
+```ruby
+account.balance
+```
 
 will return the current balance for an account as a Money object.
 
@@ -86,7 +90,9 @@ will return the current balance for an account as a Money object.
 
 To transfer money between accounts:
 
-    DoubleEntry.transfer(20.dollars, :from => account_a, :to => account_b, :code => :purchase)
+```ruby
+DoubleEntry.transfer(20.dollars, :from => account_a, :to => account_b, :code => :purchase)
+```
 
 The possible transfers, and their codes, should be defined in the configuration.
 
@@ -99,10 +105,12 @@ If you're doing more than one transfer in a single financial transaction, or
 you're doing other database operations along with the transfer, you'll need to
 manually lock the accounts you're using:
 
-    DoubleEntry.lock_accounts(account_a, account_b) do
-      # Do some other stuff in here...
-      DoubleEntry.transfer(20.dollars, :from => account_a, :to => account_b, :code => :purchase)
-    end
+```ruby
+DoubleEntry.lock_accounts(account_a, account_b) do
+  # Do some other stuff in here...
+  DoubleEntry.transfer(20.dollars, :from => account_a, :to => account_b, :code => :purchase)
+end
+```
 
 The lock_accounts call generates a database transaction, which must be the
 outermost transaction.
@@ -152,13 +160,13 @@ DoubleEntry.configure do |config|
       end
     end
 
-    accounts.define(identifier: :savings,  scope_identifier: user_scope, positive_only: true)
-    accounts.define(identifier: :checking, scope_identifier: user_scope)
+    accounts.define(:identifier => :savings,  :scope_identifier => user_scope, :positive_only => true)
+    accounts.define(:identifier => :checking, :scope_identifier => user_scope)
   end
 
   config.define_transfers do |transfers|
-    transfers.define(from: :checking, to: :savings,  code: :deposit)
-    transfers.define(from: :savings,  to: :checking, code: :withdraw)
+    transfers.define(:from => :checking, :to => :savings,  :code => :deposit)
+    transfers.define(:from => :savings,  :to => :checking, :code => :withdraw)
   end
 end
 ```

data/lib/double_entry.rb

@@ -6,10 +6,12 @@ require 'money'
 require 'encapsulate_as_money'
 
 require 'double_entry/version'
+require 'double_entry/errors'
 require 'double_entry/configurable'
 require 'double_entry/configuration'
 require 'double_entry/account'
 require 'double_entry/account_balance'
+require 'double_entry/balance_calculator'
 require 'double_entry/locking'
 require 'double_entry/transfer'
 require 'double_entry/line'
@@ -22,15 +24,6 @@ require 'double_entry/validation'
 # transferring money around the system.
 module DoubleEntry
 
-  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
 
     # Get the particular account instance with the provided identifier and
@@ -47,16 +40,7 @@ module DoubleEntry
     #   configured. It is unknown.
     #
     def account(identifier, options = {})
-      account = configuration.accounts.detect do |current_account|
-        current_account.identifier == identifier &&
-          (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
+      Account.account(configuration.accounts, identifier, options)
     end
 
     # Transfer money from one account to another.
@@ -83,7 +67,7 @@ module DoubleEntry
     #   of this account.
     # @option options :to [DoubleEntry::Account::Instance] Transfer money into
     #   this account.
-    # @option options :code [Symbol] Your application specific code for this
+    # @option options :code [Symbol] The 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
@@ -93,20 +77,13 @@ module DoubleEntry
     #   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 = configuration.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
+      Transfer.transfer(configuration.transfers, amount, options)
     end
 
-    # Get the current balance of an account, as a Money object.
+    # Get the current or historic balance of an account.
     #
     # @param account [DoubleEntry::Account:Instance, Symbol]
-    # @option options :scope [Symbol]
+    # @option options :scope [Object, String]
     # @option options :from [Time]
     # @option options :to [Time]
     # @option options :at [Time]
@@ -114,56 +91,7 @@ module DoubleEntry
     # @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
+      BalanceCalculator.calculate(account, options)
     end
 
     # Lock accounts in preparation for transfers.
@@ -183,33 +111,10 @@ module DoubleEntry
     #   The transaction must be the outermost database transaction
     #
     def lock_accounts(*accounts, &block)
-      DoubleEntry::Locking.lock_accounts(*accounts, &block)
+      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?
-        configuration.transfers.find(line.account, line.partner_account, line.code)
-      else
-        configuration.transfers.find(line.partner_account, line.account, line.code)
-      end.description.call(line)
-    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

data/lib/double_entry/account.rb

@@ -1,11 +1,27 @@
 # encoding: utf-8
 module DoubleEntry
   class Account
+
+    # @api private
+    def self.account(defined_accounts, identifier, options = {})
+      account = defined_accounts.find(identifier, options[:scope].present?)
+      DoubleEntry::Account::Instance.new(:account => account, :scope => options[:scope])
+    end
+
+    # @api private
     class Set < Array
       def define(attributes)
         self << Account.new(attributes)
       end
 
+      def find(identifier, scoped)
+        account = detect do |account|
+          account.identifier == identifier && account.scoped? == scoped
+        end
+        raise UnknownAccount.new("account: #{identifier} scoped?: #{scoped}") unless account
+        return account
+      end
+
       def <<(account)
         if any? { |a| a.identifier == account.identifier }
           raise DuplicateAccount.new
@@ -34,8 +50,17 @@ module DoubleEntry
         scope_identifier.call(scope).to_s if scoped?
       end
 
-      def balance(args = {})
-        DoubleEntry.balance(self, args)
+      # Get the current or historic balance of this account.
+      #
+      # @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(options = {})
+        BalanceCalculator.calculate(self, options)
       end
 
       include Comparable

data/lib/double_entry/balance_calculator.rb

@@ -0,0 +1,105 @@
+# encoding: utf-8
+module DoubleEntry
+  module BalanceCalculator
+    extend self
+
+    # Get the current or historic balance of an account.
+    #
+    # @param account [DoubleEntry::Account:Instance, Symbol]
+    # @option args :scope [Object, String]
+    # @option args :from [Time]
+    # @option args :to [Time]
+    # @option args :at [Time]
+    # @option args :code [Symbol]
+    # @option args :codes [Array<Symbol>]
+    # @return [Money]
+    #
+    def calculate(account, args = {})
+      options = Options.new(account, args)
+      relations = RelationBuilder.new(options)
+      lines = relations.build
+
+      if options.between? || options.code?
+        # from and to or code lookups have to be done via sum
+        Money.new(lines.sum(:amount))
+      else
+        # all other lookups can be performed with running balances
+        result = lines.
+          from(lines_table_name(options)).
+          order('id DESC').
+          limit(1).
+          pluck(:balance)
+        result.empty? ? Money.empty : Money.new(result.first)
+      end
+    end
+
+  private
+
+    def lines_table_name(options)
+      "#{Line.quoted_table_name}#{' USE INDEX (lines_scope_account_id_idx)' if force_index?(options)}"
+    end
+
+    def force_index?(options)
+      # 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
+      options.scope? && Line.connection.adapter_name.match(/mysql/i)
+    end
+
+    # @api private
+    class Options
+      attr_reader :account, :scope, :from, :to, :at, :codes
+
+      def initialize(account, args = {})
+        if account.is_a? Symbol
+          @account = account.to_s
+          @scope = args[:scope].present? ? args[:scope].id.to_s : nil
+        else
+          @account = account.identifier.to_s
+          @scope = account.scope_identity
+        end
+        @codes = (args[:codes].to_a << args[:code]).compact
+        @from = args[:from]
+        @to = args[:to]
+        @at = args[:at]
+      end
+
+      def at?
+        !!at
+      end
+
+      def between?
+        !!(from && to && !at?)
+      end
+
+      def code?
+        codes.present?
+      end
+
+      def scope?
+        !!scope
+      end
+    end
+
+    # @api private
+    class RelationBuilder
+      attr_reader :options
+      delegate :account, :scope, :scope?, :from, :to, :between?, :at, :at?, :codes, :code?, :to => :options
+
+      def initialize(options)
+        @options = options
+      end
+
+      def build
+        lines = Line.where(:account => account)
+        lines = lines.where('created_at <= ?', at) if at?
+        lines = lines.where(:created_at => from..to) if between?
+        lines = lines.where(:code => codes) if code?
+        lines = lines.where(:scope => scope) if scope?
+        lines
+      end
+    end
+
+  end
+end

data/lib/double_entry/errors.rb

@@ -0,0 +1,13 @@
+# encoding: utf-8
+module DoubleEntry
+
+  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
+
+end

data/lib/double_entry/line.rb

@@ -122,10 +122,6 @@ module DoubleEntry
       amount > Money.empty
     end
 
-    def description
-     DoubleEntry.describe(self)
-    end
-
     # Query out just the id and created_at fields for lines, without
     # instantiating any ActiveRecord objects.
     def self.find_id_and_created_at(options)

data/lib/double_entry/reporting.rb

@@ -2,13 +2,13 @@
 require 'double_entry/reporting/aggregate'
 require 'double_entry/reporting/aggregate_array'
 require 'double_entry/reporting/time_range'
-require 'double_entry/reporting/time_range_array'
 require 'double_entry/reporting/day_range'
 require 'double_entry/reporting/hour_range'
 require 'double_entry/reporting/week_range'
 require 'double_entry/reporting/month_range'
 require 'double_entry/reporting/year_range'
 require 'double_entry/reporting/line_aggregate'
+require 'double_entry/reporting/time_range_array'
 
 module DoubleEntry
 
@@ -26,10 +26,82 @@ module DoubleEntry
       end
     end
 
+    class AggregateFunctionNotSupported < RuntimeError; end
+
+    # Perform an aggregate calculation on a set of transfers for an account.
+    #
+    # The transfers included in the calculation can be limited by time range
+    # and provided custom filters.
+    #
+    # @example Find the sum for all $10 :save transfers in all :checking accounts in the current month (assume the date is January 30, 2014).
+    #   time_range = DoubleEntry::TimeRange.make(2014, 1)
+    #   class ::DoubleEntry::Line
+    #     scope :ten_dollar_transfers, -> { where(:amount => 10_00) }
+    #   end
+    #   DoubleEntry.aggregate(:sum, :checking, :save, range: time_range, filter: [:ten_dollar_transfers])
+    # @param function [Symbol] The function to perform on the set of transfers.
+    #   Valid functions are :sum, :count, and :average
+    # @param account [Symbol] The symbol identifying the account to perform
+    #   the aggregate calculation on. As specified in the account configuration.
+    # @param code [Symbol] The application specific code for the type of
+    #   transfer to perform an aggregate calculation on. As specified in the
+    #   transfer configuration.
+    # @option options :range [DoubleEntry::TimeRange] Only include transfers
+    #   in the given time range in the calculation.
+    # @option options :filter [Array[Symbol], or Array[Hash<Symbol,Parameter>]]
+    #   A custom filter to apply before performing the aggregate calculation.
+    #   Currently, filters must be monkey patched as scopes into the DoubleEntry::Line
+    #   class in order to be used as filters, as the example shows.
+    #   If the filter requires a parameter, it must be given in a Hash, otherwise
+    #   pass an array with the symbol names for the defined scopes.
+    # @return Returns a Money object for :sum and :average calculations, or a
+    #   Fixnum for :count calculations.
+    # @raise [Reporting::AggregateFunctionNotSupported] The provided function
+    #   is not supported.
+    #
     def aggregate(function, account, code, options = {})
       Aggregate.new(function, account, code, options).formatted_amount
     end
 
+    # Perform an aggregate calculation on a set of transfers for an account
+    # and return the results in an array partitioned by a time range type.
+    #
+    # The transfers included in the calculation can be limited by a time range
+    # and provided custom filters.
+    #
+    # @example Find the number of all $10 :save transfers in all :checking accounts per month for the entire year (Assume the year is 2014).
+    #   DoubleEntry.aggregate_array(:sum, :checking, :save, range_type: 'month', start: '2014-01-01', finish: '2014-12-31')
+    # @param function [Symbol] The function to perform on the set of transfers.
+    #   Valid functions are :sum, :count, and :average
+    # @param account [Symbol] The symbol identifying the account to perform
+    #   the aggregate calculation on. As specified in the account configuration.
+    # @param code [Symbol] The application specific code for the type of
+    #   transfer to perform an aggregate calculation on. As specified in the
+    #   transfer configuration.
+    # @option options :filter [Array[Symbol], or Array[Hash<Symbol,Parameter>]]
+    #   A custom filter to apply before performing the aggregate calculation.
+    #   Currently, filters must be monkey patched as scopes into the DoubleEntry::Line
+    #   class in order to be used as filters, as the example shows.
+    #   If the filter requires a parameter, it must be given in a Hash, otherwise
+    #   pass an array with the symbol names for the defined scopes.
+    # @option options :range_type [String] The type of time range to return data
+    #   for.  For example, specifying 'month' will return an array of the resulting
+    #   aggregate calculation for each month.
+    #   Valid range_types are 'hour', 'day', 'week', 'month', and 'year'
+    # @option options :start [String] The start date for the time range to perform
+    #   calculations in.  The default start date is the start_of_business (can
+    #   be specified in configuration).
+    #   The format of the string must be as follows: 'YYYY-mm-dd'
+    # @option options :finish [String] The finish (or end) date for the time range
+    #   to perform calculations in.  The default finish date is the current date.
+    #   The format of the string must be as follows: 'YYYY-mm-dd'
+    # @return [Array[Money/Fixnum]] Returns an array of Money objects for :sum
+    #   and :average calculations, or an array of Fixnum for :count calculations.
+    #   The array is indexed by the range_type.  For example, if range_type is
+    #   specified as 'month', each index in the array will represent a month.
+    # @raise [Reporting::AggregateFunctionNotSupported] The provided function
+    #   is not supported.
+    #
     def aggregate_array(function, account, code, options = {})
       AggregateArray.new(function, account, code, options)
     end
@@ -55,6 +127,19 @@ module DoubleEntry
       SQL
     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
+
   private
 
     delegate :connection, :to => ActiveRecord::Base

data/lib/double_entry/reporting/aggregate.rb

@@ -2,16 +2,15 @@
 module DoubleEntry
  module Reporting
   class Aggregate
-    attr_reader :function, :account, :code, :scope, :range, :options, :filter
+    attr_reader :function, :account, :code, :range, :options, :filter
 
     def initialize(function, account, code, options)
       @function = function.to_s
-      raise "Function not supported" unless %w[sum count average].include?(@function)
+      raise AggregateFunctionNotSupported 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
@@ -55,7 +54,7 @@ module DoubleEntry
       if range.class == YearRange
         aggregate = calculate_yearly_aggregate
       else
-        aggregate = LineAggregate.aggregate(function, account, code, nil, range, filter)
+        aggregate = LineAggregate.aggregate(function, account, code, range, filter)
       end
 
       if range_is_complete?

data/lib/double_entry/reporting/line_aggregate.rb

@@ -4,7 +4,7 @@ module DoubleEntry
   class LineAggregate < ActiveRecord::Base
     extend EncapsulateAsMoney
 
-    def self.aggregate(function, account, code, scope, range, named_scopes)
+    def self.aggregate(function, account, code, range, named_scopes)
       collection = aggregate_collection(named_scopes)
       collection = collection.where(:account => account)
       collection = collection.where(:created_at => range.start..range.finish)

data/lib/double_entry/reporting/time_range_array.rb

@@ -1,45 +1,42 @@
 # encoding: utf-8
 module DoubleEntry
- module Reporting
-  class TimeRangeArray
-    class << self
+  module Reporting
+    class TimeRangeArray
 
-      def make(range_type, start, finish = nil)
-        raise "Must specify range for #{range_type}-by-#{range_type} reports" if start == nil
+      attr_reader :type, :require_start
+      alias_method :require_start?, :require_start
 
-        case range_type
-        when 'hour'
-          make_array HourRange, start, finish
-        when 'day'
-          make_array DayRange, start, finish
-        when 'week'
-          make_array WeekRange, start, finish
-        when 'month'
-          make_array MonthRange, start, finish
-        when 'year'
-          make_array YearRange, start
-        else
-          raise ArgumentError.new("Invalid range type '#{range_type}'")
-        end
+      def initialize(options = {})
+        @type = options[:type]
+        @require_start = options[:require_start]
       end
 
-      private
-
-      def make_array(type, start, finish = nil)
-        start = type.from_time(Time.parse(start))
-        finish = type.from_time(Time.parse(finish)) if finish
-
-        loop = start
-        last = finish || type.current
-        results = [loop]
-        while(loop != last) do
-          loop = loop.next
-          results << loop
+      def make(start = nil, finish = nil)
+        raise "Must specify start of range" if start == nil && require_start?
+        start = type.from_time(Time.parse(start || Reporting.configuration.start_of_business))
+        finish = finish ? type.from_time(Time.parse(finish)) : type.current
+        [ start ].tap do |array|
+          while start != finish
+            start = start.next
+            array << start
+          end
         end
+      end
+
+      FACTORIES = {
+        'hour'  => new(:type => HourRange,  :require_start => true),
+        'day'   => new(:type => DayRange,   :require_start => true),
+        'week'  => new(:type => WeekRange,  :require_start => true),
+        'month' => new(:type => MonthRange, :require_start => false),
+        'year'  => new(:type => YearRange,  :require_start => false),
+      }
 
-        results
+      def self.make(range_type, start = nil, finish = nil)
+        factory = FACTORIES[range_type]
+        raise ArgumentError.new("Invalid range type '#{range_type}'") unless factory
+        factory.make(start, finish)
       end
+
     end
   end
- end
 end

data/lib/double_entry/transfer.rb

@@ -1,6 +1,17 @@
 # encoding: utf-8
 module DoubleEntry
   class Transfer
+
+    # @api private
+    def self.transfer(defined_transfers, amount, options = {})
+      raise TransferIsNegative if amount < Money.empty
+      from, to, code, meta, detail = options[:from], options[:to], options[:code],  options[:meta],  options[:detail]
+      defined_transfers.
+        find!(from, to, code).
+        process!(amount, from, to, code, meta, detail)
+    end
+
+    # @api private
     class Set < Array
       def define(attributes)
         self << Transfer.new(attributes)
@@ -10,6 +21,12 @@ module DoubleEntry
         _find(from.identifier, to.identifier, code)
       end
 
+      def find!(from, to, code)
+        transfer = find(from, to, code)
+        raise TransferNotAllowed.new([from.identifier, to.identifier, code].inspect) unless transfer
+        return transfer
+      end
+
       def <<(transfer)
         if _find(transfer.from, transfer.to, transfer.code)
           raise DuplicateTransfer.new

data/lib/double_entry/version.rb

@@ -1,5 +1,5 @@
 # encoding: utf-8
 
 module DoubleEntry
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/script/jack_hammer

@@ -156,11 +156,11 @@ def reconcile
     error_count += 1
   end
 
-  if $accounts.all? {|account| DoubleEntry.reconciled?(account) }
+  if $accounts.all? {|account| DoubleEntry::Reporting.reconciled?(account) }
     puts "All accounts reconciled, FTW!"
   else
     $accounts.each do |account|
-      if !DoubleEntry.reconciled?(account)
+      if !DoubleEntry::Reporting.reconciled?(account)
         puts "Account #{account.identifier} failed to reconcile. :("
 
         # See http://bugs.mysql.com/bug.php?id=51431

data/spec/double_entry/balance_calculator_spec.rb

@@ -0,0 +1,131 @@
+# encoding: utf-8
+require 'spec_helper'
+
+describe DoubleEntry::BalanceCalculator do
+
+  describe '#calculate' do
+    let(:account) { double.as_null_object }
+    let(:scope) { nil }
+    let(:from) { nil }
+    let(:to) { nil }
+    let(:at) { nil }
+    let(:code) { nil }
+    let(:codes) { nil }
+    let(:relation) { double.as_null_object }
+
+    before do
+      allow(DoubleEntry::Line).to receive(:where).and_return(relation)
+      DoubleEntry::BalanceCalculator.calculate(
+        account,
+        :scope => scope,
+        :from => from,
+        :to => to,
+        :at => at,
+        :code => code,
+        :codes => codes,
+      )
+    end
+
+    describe 'what happens with different accounts' do
+      context 'when the given account is a symbol' do
+        let(:account) { :account }
+
+        it 'scopes the lines summed by the account symbol' do
+          expect(DoubleEntry::Line).to have_received(:where).with(:account => 'account')
+        end
+
+        context 'with a scopeable entity provided' do
+          let(:scope) { double(:id => 'scope') }
+
+          it 'scopes the lines summed by the scope of the scopeable entity...scope' do
+            expect(relation).to have_received(:where).with(:scope => 'scope')
+          end
+        end
+
+        context 'with no scope provided' do
+          it 'does not scope the lines summed by the given scope' do
+            expect(relation).to_not have_received(:where).with(:scope => 'scope')
+          end
+        end
+      end
+
+      context 'when the given account is DoubleEntry::Account-like' do
+        let(:account) do
+          DoubleEntry::Account::Instance.new(
+            :account => DoubleEntry::Account.new(
+                          :identifier => 'account_identity',
+                          :scope_identifier => lambda { |scope_id| scope_id },
+                        ),
+            :scope   => 'account_scope_identity'
+          )
+        end
+
+        it 'scopes the lines summed by the accounts identifier and its scope identity' do
+          expect(DoubleEntry::Line).to have_received(:where).with(:account => 'account_identity')
+          expect(relation).to have_received(:where).with(:scope => 'account_scope_identity')
+        end
+      end
+    end
+
+    describe 'what happens with different times' do
+      context 'when we want to sum the lines before a given created_at date' do
+        let(:at) { Time.parse('2014-06-19 15:09:18 +1000') }
+
+        it 'scopes the lines summed to times before (or at) the given time' do
+          expect(relation).to have_received(:where).with(
+            'created_at <= ?', Time.parse('2014-06-19 15:09:18 +1000')
+          )
+        end
+
+        context 'when a time range is also specified' do
+          let(:from) { Time.parse('2014-06-19 10:09:18 +1000') }
+          let(:to) { Time.parse('2014-06-19 20:09:18 +1000') }
+
+          it 'ignores the time range when summing the lines' do
+            expect(relation).to_not have_received(:where).with(
+              :created_at => Time.parse('2014-06-19 10:09:18 +1000')..Time.parse('2014-06-19 20:09:18 +1000')
+            )
+            expect(relation).to_not have_received(:sum)
+          end
+        end
+      end
+
+      context 'when we want to sum the lines between a given range' do
+        let(:from) { Time.parse('2014-06-19 10:09:18 +1000') }
+        let(:to) { Time.parse('2014-06-19 20:09:18 +1000') }
+
+        it 'scopes the lines summed to times within the given range' do
+          expect(relation).to have_received(:where).with(
+            :created_at => Time.parse('2014-06-19 10:09:18 +1000')..Time.parse('2014-06-19 20:09:18 +1000')
+          )
+          expect(relation).to have_received(:sum).with(:amount)
+        end
+      end
+    end
+
+    context 'when a single code is provided' do
+      let(:code) { 'code1' }
+
+      it 'scopes the lines summed by the given code' do
+        expect(relation).to have_received(:where).with(:code => ['code1'])
+        expect(relation).to have_received(:sum).with(:amount)
+      end
+    end
+
+    context 'when a list of codes is provided' do
+      let(:codes) { ['code1', 'code2'] }
+
+      it 'scopes the lines summed by the given codes' do
+        expect(relation).to have_received(:where).with(:code => ['code1', 'code2'])
+        expect(relation).to have_received(:sum).with(:amount)
+      end
+    end
+
+    context 'when no codes are provided' do
+      it 'does not scope the lines summed by any code' do
+        expect(relation).to_not have_received(:where).with(:code => anything)
+        expect(relation).to_not have_received(:sum).with(:amount)
+      end
+    end
+  end
+end

data/spec/double_entry/reporting/aggregate_array_spec.rb

@@ -1,75 +1,89 @@
 require 'spec_helper'
-describe DoubleEntry::Reporting::AggregateArray do
+module DoubleEntry
+  module Reporting
+    describe AggregateArray do
 
-  let(:user) { User.make! }
-  let(:start) { nil }
-  let(:finish) { nil }
-  let(:range_type) { 'year' }
+      let(:user) { User.make! }
+      let(:start) { nil }
+      let(:finish) { nil }
+      let(:range_type) { 'year' }
+      let(:function) { :sum }
 
-  subject(:aggregate_array) {
-    DoubleEntry::Reporting.aggregate_array(
-      :sum,
-      :savings,
-      :bonus,
-      :range_type => range_type,
-      :start => start,
-      :finish => finish,
-    )
-  }
+      subject(:aggregate_array) {
+        Reporting.aggregate_array(
+          function,
+          :savings,
+          :bonus,
+          :range_type => range_type,
+          :start => start,
+          :finish => finish,
+        )
+      }
 
-  context 'given a deposit was made in 2007 and 2008' do
-    before do
-      Timecop.travel(Time.local(2007)) do
-        perform_deposit user, 10_00
-      end
-      Timecop.travel(Time.local(2008)) do
-        perform_deposit user, 20_00
-      end
-    end
+      context 'given a deposit was made in 2007 and 2008' do
+        before do
+          Timecop.travel(Time.local(2007)) do
+            perform_deposit user, 10_00
+          end
+          Timecop.travel(Time.local(2008)) do
+            perform_deposit user, 20_00
+          end
+        end
 
-    context 'given the date is 2009-03-19' do
-      before { Timecop.travel(Time.local(2009, 3, 19)) }
+        context 'given the date is 2009-03-19' do
+          before { Timecop.travel(Time.local(2009, 3, 19)) }
 
-      context 'when called with range type of "year"' do
-        let(:range_type) { 'year' }
-        let(:start) { '2006-08-03' }
-        it { should eq [ Money.new(0), Money.new(10_00), Money.new(20_00), Money.new(0) ] }
+          context 'when called with range type of "year"' do
+            let(:range_type) { 'year' }
+            let(:start) { '2006-08-03' }
+            it { should eq [ Money.new(0), Money.new(10_00), Money.new(20_00), Money.new(0) ] }
+          end
+        end
       end
-    end
-  end
 
-  context 'given a deposit was made in October and December 2006' do
-    before do
-      Timecop.travel(Time.local(2006, 10)) do
-        perform_deposit user, 10_00
-      end
-      Timecop.travel(Time.local(2006, 12)) do
-        perform_deposit user, 20_00
-      end
-    end
+      context 'given a deposit was made in October and December 2006' do
+        before do
+          Timecop.travel(Time.local(2006, 10)) do
+            perform_deposit user, 10_00
+          end
+          Timecop.travel(Time.local(2006, 12)) do
+            perform_deposit user, 20_00
+          end
+        end
 
-    context 'when called with range type of "month", a start of "2006-09-01", and finish of "2007-01-02"' do
-      let(:range_type) { 'month' }
-      let(:start) { '2006-09-01' }
-      let(:finish) { '2007-01-02' }
-      it { should eq [ Money.new(0), Money.new(10_00), Money.new(0), Money.new(20_00), Money.new(0), ] }
-    end
+        context 'when called with range type of "month", a start of "2006-09-01", and finish of "2007-01-02"' do
+          let(:range_type) { 'month' }
+          let(:start) { '2006-09-01' }
+          let(:finish) { '2007-01-02' }
+          it { should eq [ Money.new(0), Money.new(10_00), Money.new(0), Money.new(20_00), Money.new(0), ] }
+        end
+
+        context 'given the date is 2007-02-02' do
+          before { Timecop.travel(Time.local(2007, 2, 2)) }
+
+          context 'when called with range type of "month"' do
+            let(:range_type) { 'month' }
+            let(:start) { '2006-08-03' }
+            it { should eq [ Money.new(0), Money.new(0), Money.new(10_00), Money.new(0), Money.new(20_00), Money.new(0), Money.new(0) ] }
+          end
+        end
+      end
 
-    context 'given the date is 2007-02-02' do
-      before { Timecop.travel(Time.local(2007, 2, 2)) }
+      context 'when called with range type of "invalid_and_should_not_work"' do
+        let(:range_type) { 'invalid_and_should_not_work' }
+        it 'raises an argument error' do
+          expect { aggregate_array }.to raise_error ArgumentError, "Invalid range type 'invalid_and_should_not_work'"
+        end
+      end
 
-      context 'when called with range type of "month"' do
+      context 'when an invalid function is provided' do
         let(:range_type) { 'month' }
         let(:start) { '2006-08-03' }
-        it { should eq [ Money.new(0), Money.new(0), Money.new(10_00), Money.new(0), Money.new(20_00), Money.new(0), Money.new(0) ] }
+        let(:function) { :invalid_function }
+        it 'raises an AggregateFunctionNotSupported error' do
+          expect{ aggregate_array }.to raise_error AggregateFunctionNotSupported
+        end
       end
     end
   end
-
-  context 'when called with range type of "invalid_and_should_not_work"' do
-    let(:range_type) { 'invalid_and_should_not_work' }
-    it 'should raise an argument error' do
-      expect { aggregate_array }.to raise_error ArgumentError, "Invalid range type 'invalid_and_should_not_work'"
-    end
-  end
 end

data/spec/double_entry/reporting/aggregate_spec.rb

@@ -5,6 +5,12 @@ module DoubleEntry
     describe Aggregate do
 
       let(:user) { User.make! }
+      let(:expected_weekly_average) do
+        (Money.new(20_00) + Money.new(40_00) + Money.new(50_00)) / 3
+      end
+      let(:expected_monthly_average) do
+        (Money.new(20_00) + Money.new(40_00) + Money.new(50_00) + Money.new(40_00) + Money.new(50_00)) / 5
+      end
 
       before do
         # Thursday
@@ -107,12 +113,42 @@ module DoubleEntry
         ).to eq Money.new(200_00)
       end
 
+      it 'calculates the average monthly all_time ranges correctly' do
+        expect(
+          Reporting.aggregate(:average, :savings, :bonus, :range => TimeRange.make(:year => 2009, :month => 12, :range_type => :all_time))
+        ).to eq expected_monthly_average
+      end
+
+      it 'returns the correct count for weekly all_time ranges correctly' do
+        expect(
+          Reporting.aggregate(:count, :savings, :bonus, :range => TimeRange.make(:year => 2009, :month => 12, :range_type => :all_time))
+        ).to eq 5
+      end
+
       it 'should calculate weekly all_time ranges correctly' do
         expect(
           Reporting.aggregate(:sum, :savings, :bonus, :range => TimeRange.make(:year => 2009, :week => 43, :range_type => :all_time))
         ).to eq Money.new(110_00)
       end
 
+      it 'calculates the average weekly all_time ranges correctly' do
+        expect(
+          Reporting.aggregate(:average, :savings, :bonus, :range => TimeRange.make(:year => 2009, :week => 43, :range_type => :all_time))
+        ).to eq expected_weekly_average
+      end
+
+      it 'returns the correct count for weekly all_time ranges correctly' do
+        expect(
+          Reporting.aggregate(:count, :savings, :bonus, :range => TimeRange.make(:year => 2009, :week => 43, :range_type => :all_time))
+        ).to eq 3
+      end
+
+      it "raises an AggregateFunctionNotSupported exception" do
+        expect{
+          Reporting.aggregate(:not_supported_calculation, :savings, :bonus, :range => TimeRange.make(:year => 2009, :week => 43, :range_type => :all_time))
+        }.to raise_error(AggregateFunctionNotSupported)
+      end
+
       context 'filters' do
 
         let(:range) { TimeRange.make(:year => 2011, :month => 10) }

data/spec/double_entry/reporting/time_range_array_spec.rb

@@ -21,7 +21,7 @@ module DoubleEntry::Reporting
       context 'given start and finish are nil' do
         it 'should raise an error' do
           expect { TimeRangeArray.make(range_type, nil, nil) }.
-            to raise_error 'Must specify range for hour-by-hour reports'
+            to raise_error 'Must specify start of range'
         end
       end
     end
@@ -44,7 +44,7 @@ module DoubleEntry::Reporting
       context 'given start and finish are nil' do
         it 'should raise an error' do
           expect { TimeRangeArray.make(range_type, nil, nil) }.
-            to raise_error 'Must specify range for day-by-day reports'
+            to raise_error 'Must specify start of range'
         end
       end
     end
@@ -66,7 +66,7 @@ module DoubleEntry::Reporting
       context 'given start and finish are nil' do
         it 'should raise an error' do
           expect { TimeRangeArray.make(range_type, nil, nil) }.
-            to raise_error 'Must specify range for week-by-week reports'
+            to raise_error 'Must specify start of range'
         end
       end
     end
@@ -117,11 +117,10 @@ module DoubleEntry::Reporting
         context 'and the date is "2009-11-23"' do
           before { Timecop.freeze(Time.new(2009, 11, 23)) }
 
-          it 'takes no notice of start and finish' do
+          it 'takes notice of start and finish' do
             should eq [
               YearRange.from_time(Time.new(2007)),
               YearRange.from_time(Time.new(2008)),
-              YearRange.from_time(Time.new(2009)),
             ]
           end
 

data/spec/double_entry_spec.rb

@@ -215,11 +215,6 @@ describe DoubleEntry do
       expect(debit_line).to_not be_credit
     end
 
-    it 'can describe itself' do
-      expect(credit_line.description).to eq 'Money goes out: $-10.00'
-      expect(debit_line.description).to eq 'Money goes in: $10.00'
-    end
-
     it 'can reference its partner' do
       expect(credit_line.partner).to eq debit_line
       expect(debit_line.partner).to eq credit_line

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: double_entry
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
   prerelease: 
 platform: ruby
 authors:
@@ -16,7 +16,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-06-28 00:00:00.000000000 Z
+date: 2014-07-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: money
@@ -272,8 +272,10 @@ files:
 - lib/double_entry.rb
 - lib/double_entry/account.rb
 - lib/double_entry/account_balance.rb
+- lib/double_entry/balance_calculator.rb
 - lib/double_entry/configurable.rb
 - lib/double_entry/configuration.rb
+- lib/double_entry/errors.rb
 - lib/double_entry/line.rb
 - lib/double_entry/locking.rb
 - lib/double_entry/reporting.rb
@@ -298,6 +300,7 @@ files:
 - spec/active_record/locking_extensions_spec.rb
 - spec/double_entry/account_balance_spec.rb
 - spec/double_entry/account_spec.rb
+- spec/double_entry/balance_calculator_spec.rb
 - spec/double_entry/configuration_spec.rb
 - spec/double_entry/line_spec.rb
 - spec/double_entry/locking_spec.rb
@@ -349,6 +352,7 @@ test_files:
 - spec/active_record/locking_extensions_spec.rb
 - spec/double_entry/account_balance_spec.rb
 - spec/double_entry/account_spec.rb
+- spec/double_entry/balance_calculator_spec.rb
 - spec/double_entry/configuration_spec.rb
 - spec/double_entry/line_spec.rb
 - spec/double_entry/locking_spec.rb