double_entry 0.10.3 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 54feac773a636f4df4556412c09a80698172e6ca
-  data.tar.gz: 7373d84edcb61edab5d4bedc3da3792a6d3ef01e
+  metadata.gz: 2de3c5bcd2513815b3240072a87abed07c054176
+  data.tar.gz: 441671942df5faff21b7db426075a8dd26822fbc
 SHA512:
-  metadata.gz: 2d62479172ef59645acda32f45231bc074bc2b46b9688932d3fc7aba336ea7aeb26fe71dfcd3f3e74a0015c30a3f6881f998374ab474214b7e284e87cef0b5a4
-  data.tar.gz: 8cb7508387deacfcfb836a54fd16986ff6b47efee669082a8be40031e5c12eb3552c7795c11faea3d324debbcaae6ba3b0195992b3ddd5ce6f472d6e552eaf4e
+  metadata.gz: 88e504ea0d5504c1ce05e63a01ad5697b1cc045298c51a02b52b8bfafb969e5facf0235e727ba600f83b317483b72c9ce284d3dd6e5ac1227aefb40d339696f9
+  data.tar.gz: a669b5f44cc5e955f9c942301748bac1622f58e34082f892b9c12f38dd76aa8d16a85533d8e8e08ab0d2a6440498eba81b93c4cc2311a67538cc8fd5607cd3ae

data/.gitignore

@@ -9,6 +9,9 @@
 /test/version_tmp/
 /tmp/
 
+## Performance profiling
+/profiles/
+
 ## Documentation cache and generated files:
 /.yardoc/
 /_yardoc/

data/.rubocop.yml

@@ -42,6 +42,9 @@ Style/ModuleFunction:
 Style/ParallelAssignment:
   Enabled: false
 
+Style/SingleLineBlockParams:
+  Enabled: false
+
 Metrics/AbcSize:
   Max: 47 #15
 
@@ -55,7 +58,8 @@ Metrics/MethodLength:
   Max: 30 # 10
 
 Metrics/ModuleLength:
-  Max: 221 #100
+  Exclude:
+    - spec/**/*
 
 Metrics/PerceivedComplexity:
   Max: 13 #7

data/README.md

@@ -124,6 +124,19 @@ The possible transfers, and their codes, should be defined in the configuration.
 
 See **DoubleEntry::Transfer** for more info.
 
+### Metadata
+
+You may associate arbitrary metadata with transfers, for example:
+
+```ruby
+DoubleEntry.transfer(
+  Money.new(20_00),
+  :from => one_account,
+  :to   => another_account,
+  :code => :a_business_code_for_this_type_of_transfer,
+  :metadata => {:key1 => 'value 1', :key2 => 'value 2'},
+)
+```
 
 ### Locking
 
@@ -160,6 +173,9 @@ See **DoubleEntry::Line** for more info.
 AccountBalance records cache the current balance for each Account, and are used
 to perform database level locking.
 
+Transfer metadata is stored as key/value pairs associated with both the source and destination lines of the transfer.
+See **DoubleEntry::LineMetadata** for more info.
+
 ## Configuration
 
 A configuration file should be used to define a set of accounts, optional scopes on

data/double_entry.gemspec

@@ -17,6 +17,34 @@ Gem::Specification.new do |gem|
   gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
   gem.require_paths = ['lib']
 
+  gem.post_install_message = <<-'POSTINSTALLMESSAGE'
+Please note the following changes in DoubleEntry:
+ - New table `double_entry_line_metadata` has been introduced and is *required* for
+   aggregate reporting filtering to work. Existing applications must manually manage
+   this change via a migration similar to the following:
+
+    class CreateDoubleEntryLineMetadata < ActiveRecord::Migration
+      def self.up
+        create_table "#{DoubleEntry.table_name_prefix}line_metadata", :force => true do |t|
+          t.integer    "line_id",               :null => false
+          t.string     "key",     :limit => 48, :null => false
+          t.string     "value",   :limit => 64, :null => false
+          t.timestamps                          :null => false
+        end
+
+        add_index "#{DoubleEntry.table_name_prefix}line_metadata",
+                  ["line_id", "key", "value"],
+                  :name => "lines_meta_line_id_key_value_idx"
+      end
+
+      def self.down
+        drop_table "#{DoubleEntry.table_name_prefix}line_metadata"
+      end
+    end
+
+  Please ensure that you update your database accordingly.
+POSTINSTALLMESSAGE
+
   gem.add_dependency 'money',                 '>= 6.0.0'
   gem.add_dependency 'activerecord',          '>= 3.2.0'
   gem.add_dependency 'activesupport',         '>= 3.2.0'
@@ -35,4 +63,11 @@ Gem::Specification.new do |gem|
   gem.add_development_dependency 'machinist'
   gem.add_development_dependency 'timecop'
   gem.add_development_dependency 'rubocop', '~> 0.32.0'
+
+  gem.add_development_dependency 'pry'
+  gem.add_development_dependency 'pry-doc'
+  gem.add_development_dependency 'pry-byebug'         if RUBY_VERSION >= '2.0.0'
+  gem.add_development_dependency 'pry-stack_explorer'
+  gem.add_development_dependency 'awesome_print'
+  gem.add_development_dependency 'ruby-prof'
 end

data/lib/double_entry.rb

@@ -15,6 +15,7 @@ require 'double_entry/balance_calculator'
 require 'double_entry/locking'
 require 'double_entry/transfer'
 require 'double_entry/line'
+require 'double_entry/line_metadata'
 require 'double_entry/reporting'
 require 'double_entry/validation'
 

data/lib/double_entry/line.rb

@@ -56,6 +56,7 @@ module DoubleEntry
   #
   class Line < ActiveRecord::Base
     belongs_to :detail, :polymorphic => true
+    has_many :metadata, :class_name => 'DoubleEntry::LineMetadata'
 
     def amount
       self[:amount] && Money.new(self[:amount], currency)

data/lib/double_entry/line_metadata.rb

@@ -0,0 +1,18 @@
+module DoubleEntry
+  class LineMetadata < ActiveRecord::Base
+    class SymbolWrapper
+      def self.load(string)
+        return unless string
+        string.to_sym
+      end
+
+      def self.dump(symbol)
+        return unless symbol
+        symbol.to_s
+      end
+    end
+
+    belongs_to :line
+    serialize :key, SymbolWrapper
+  end
+end

data/lib/double_entry/locking.rb

@@ -41,6 +41,13 @@ module DoubleEntry
       else
         lock.perform_lock(&Proc.new)
       end
+
+    rescue ActiveRecord::StatementInvalid => exception
+      if exception.message =~ /lock wait timeout/i
+        raise LockWaitTimeout
+      else
+        raise
+      end
     end
 
     # Return the account balance record for the given account name if there's a
@@ -177,5 +184,9 @@ module DoubleEntry
     # Raised if things go horribly, horribly wrong. This should never happen.
     class LockDisaster < RuntimeError
     end
+
+    # Raised if waiting for locks times out.
+    class LockWaitTimeout < RuntimeError
+    end
   end
 end

data/lib/double_entry/reporting.rb

@@ -8,6 +8,7 @@ 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/line_aggregate_filter'
 require 'double_entry/reporting/time_range_array'
 
 module DoubleEntry
@@ -32,19 +33,27 @@ module DoubleEntry
     # 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).
+    # @example Find the sum for all $10 :save transfers in all :checking accounts in the current month, made by Australian users (assume the date is January 30, 2014).
     #   time_range = DoubleEntry::Reporting::TimeRange.make(2014, 1)
     #
     #   DoubleEntry::Line.class_eval do
-    #     scope :ten_dollar_transfers, -> { where(:amount => 10_00) }
+    #     scope :specific_transfer_amount, ->(amount) { where(:amount => amount.fractional) }
     #   end
     #
     #   DoubleEntry::Reporting.aggregate(
     #     :sum,
     #     :checking,
     #     :save,
-    #     :range  => time_range,
-    #     :filter => [ :ten_dollar_transfers ],
+    #     time_range,
+    #     :filter => [
+    #       :scope    => {
+    #         :name      => :specific_transfer_amount,
+    #         :arguments => [Money.new(10_00)]
+    #       },
+    #       :metadata => {
+    #         :user_location => 'AU'
+    #       },
+    #     ]
     #   )
     # @param [Symbol] function The function to perform on the set of transfers.
     #   Valid functions are :sum, :count, and :average
@@ -53,21 +62,24 @@ module DoubleEntry
     # @param [Symbol] code 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::Reporting::TimeRange] Only include
-    #   transfers in the given time range in the calculation.
-    # @option options :filter [Array<Symbol>, Array<Hash<Symbol, Object>>]
-    #   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.
+    # @param [DoubleEntry::Reporting::TimeRange] Only include transfers in the
+    #   given time range in the calculation.
+    # @option options :filter [Array<Hash<Symbol,Hash<Symbol,Object>>>]
+    #   An array of custom filter to apply before performing the aggregate
+    #   calculation. Filters can be either scope filters, where the name must be
+    #   specified, or they can be metadata filters, where the key/value pair to
+    #   match on must be specified.
+    #   Scope filters must be monkey patched as scopes into the DoubleEntry::Line
+    #   class, as the example above shows. Scope filters may also take a list of
+    #   arguments to pass into the monkey patched scope, and, if provided, must
+    #   be contained within an array.
     # @return [Money, Fixnum] 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
+    def aggregate(function, account, code, range, options = {})
+      Aggregate.formatted_amount(function, account, code, range, options)
     end
 
     # Perform an aggregate calculation on a set of transfers for an account

data/lib/double_entry/reporting/aggregate.rb

@@ -2,16 +2,19 @@
 module DoubleEntry
   module Reporting
     class Aggregate
-      attr_reader :function, :account, :code, :range, :options, :filter, :currency
+      attr_reader :function, :account, :code, :range, :filter, :currency
 
-      def initialize(function, account, code, options)
+      def self.formatted_amount(function, account, code, range, options = {})
+        new(function, account, code, range, options).formatted_amount
+      end
+
+      def initialize(function, account, code, range, options = {})
         @function = function.to_s
         fail AggregateFunctionNotSupported unless %w(sum count average).include?(@function)
 
         @account = account
         @code = code ? code.to_s : nil
-        @options = options
-        @range = options[:range]
+        @range = range
         @filter = options[:filter]
         @currency = DoubleEntry::Account.currency(account)
       end
@@ -69,15 +72,8 @@ module DoubleEntry
         if function == 'average'
           calculate_yearly_average
         else
-          zero = formatted_amount(0)
-          result = (1..12).inject(zero) do |total, month|
-            total + Reporting.aggregate(
-              function,
-              account,
-              code,
-              :range => MonthRange.new(:year => range.year, :month => month),
-              :filter => filter,
-            )
+          result = (1..12).inject(formatted_amount(0)) do |total, month|
+            total + Aggregate.new(function, account, code, MonthRange.new(:year => range.year, :month => month), :filter => filter).formatted_amount
           end
           result.is_a?(Money) ? result.cents : result
         end
@@ -86,8 +82,8 @@ module DoubleEntry
       def calculate_yearly_average
         # need this seperate function, because an average of averages is not the correct average
         year_range = YearRange.new(:year => range.year)
-        sum = Reporting.aggregate(:sum, account, code, :range => year_range, :filter => filter)
-        count = Reporting.aggregate(:count, account, code, :range => year_range, :filter => filter)
+        sum = Aggregate.new(:sum, account, code, year_range, :filter => filter).formatted_amount
+        count = Aggregate.new(:count, account, code, year_range, :filter => filter).formatted_amount
         (count == 0) ? 0 : (sum / count).cents
       end
 

data/lib/double_entry/reporting/aggregate_array.rb

@@ -39,7 +39,7 @@ module DoubleEntry
         # (this includes aggregates for the still-running period)
         all_periods.each do |period|
           unless @aggregates[period.key]
-            @aggregates[period.key] = Reporting.aggregate(function, account, code, :filter => filter, :range => period)
+            @aggregates[period.key] = Aggregate.formatted_amount(function, account, code, period, :filter => filter)
           end
         end
       end

data/lib/double_entry/reporting/line_aggregate.rb

@@ -3,32 +3,11 @@ module DoubleEntry
   module Reporting
     class LineAggregate < ActiveRecord::Base
       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)
-        collection = collection.where(:code => code) if code
+        collection_filter = LineAggregateFilter.new(account, code, range, named_scopes)
+        collection = collection_filter.filter
         collection.send(function, :amount)
       end
 
-      # a lot of the trickier reports will use filters defined
-      # in named_scopes to bring in data from other tables.
-      def self.aggregate_collection(named_scopes)
-        if named_scopes
-          collection = DoubleEntry::Line
-          named_scopes.each do |named_scope|
-            if named_scope.is_a?(Hash)
-              method_name = named_scope.keys[0]
-              collection = collection.send(method_name, named_scope[method_name])
-            else
-              collection = collection.send(named_scope)
-            end
-          end
-          collection
-        else
-          DoubleEntry::Line
-        end
-      end
-
       def key
         "#{year}:#{month}:#{week}:#{day}:#{hour}"
       end

data/lib/double_entry/reporting/line_aggregate_filter.rb

@@ -0,0 +1,81 @@
+# encoding: utf-8
+module DoubleEntry
+  module Reporting
+    class LineAggregateFilter
+      def initialize(account, code, range, filter_criteria)
+        @account         = account
+        @code            = code
+        @range           = range
+        @filter_criteria = filter_criteria || []
+      end
+
+      def filter
+        @collection ||= apply_filters
+      end
+
+    private
+
+      attr_reader :account, :code, :range, :filter_criteria
+
+      def apply_filters
+        collection = apply_filter_criteria.
+                     where(:account => account).
+                     where(:created_at => range.start..range.finish)
+        collection = collection.where(:code => code) if code
+
+        collection
+      end
+
+      # a lot of the trickier reports will use filters defined
+      # in filter_criteria to bring in data from other tables.
+      # For example:
+      #
+      #   filter_criteria = [
+      #     # an example of calling a named scope called with arguments
+      #     {
+      #       :scope => {
+      #         :name => :ten_dollar_purchases_by_category,
+      #         :arguments => [:cat_videos, :cat_pictures]
+      #       }
+      #     },
+      #     # an example of calling a named scope with no arguments
+      #     {
+      #       :scope => {
+      #         :name => :ten_dollar_purchases
+      #       }
+      #     },
+      #     # an example of providing a single metadatum criteria to filter on
+      #     {
+      #       :metadata => {
+      #         :meme => :business_cat
+      #       }
+      #     }
+      #   ]
+      def apply_filter_criteria
+        filter_criteria.reduce(DoubleEntry::Line) do |collection, filter|
+          if filter[:scope].present?
+            filter_by_scope(collection, filter[:scope])
+          elsif filter[:metadata].present?
+            filter_by_metadata(collection, filter[:metadata])
+          else
+            collection
+          end
+        end
+      end
+
+      def filter_by_scope(collection, scope)
+        collection.public_send(scope[:name], *scope[:arguments])
+      end
+
+      def filter_by_metadata(collection, metadata)
+        metadata.reduce(collection.joins(:metadata)) do |filtered_collection, (key, value)|
+          filtered_collection.where(metadata_table => { :key => key, :value => value })
+        end
+      end
+
+      def metadata_table
+        DoubleEntry::LineMetadata.table_name.to_sym
+      end
+    end
+  end
+end

data/lib/double_entry/transfer.rb

@@ -17,11 +17,10 @@ module DoubleEntry
       # @api private
       def transfer(amount, options = {})
         fail TransferIsNegative if amount < Money.zero
-        from = options[:from]
-        to = options[:to]
+        from_account = options[:from]
+        to_account = options[:to]
         code = options[:code]
-        detail = options[:detail]
-        transfers.find!(from, to, code).process(amount, from, to, code, detail)
+        transfers.find!(from_account, to_account, code).process(amount, options)
       end
     end
 
@@ -72,34 +71,52 @@ module DoubleEntry
       end
     end
 
-    def process(amount, from, to, code, detail)
-      if from.scope_identity == to.scope_identity && from.identifier == to.identifier
-        fail TransferNotAllowed, 'from and to are identical'
+    def process(amount, options)
+      from_account = options[:from]
+      to_account = options[:to]
+      code = options[:code]
+      detail = options[:detail]
+      metadata = options[:metadata]
+      if from_account.scope_identity == to_account.scope_identity && from_account.identifier == to_account.identifier
+        fail TransferNotAllowed, 'from account and to account are identical'
       end
-      if to.currency != from.currency
-        fail MismatchedCurrencies, "Missmatched currency (#{to.currency} <> #{from.currency})"
+      if to_account.currency != from_account.currency
+        fail MismatchedCurrencies, "Mismatched currency (#{to_account.currency} <> #{from_account.currency})"
       end
-      Locking.lock_accounts(from, to) do
-        credit, debit = Line.new, Line.new
+      Locking.lock_accounts(from_account, to_account) do
+        credit, debit = create_lines(amount, code, detail, from_account, to_account)
+        create_line_metadata(credit, debit, metadata) if metadata
+      end
+    end
+
+    def create_lines(amount, code, detail, from_account, to_account)
+      credit, debit = Line.new, Line.new
 
-        credit_balance = Locking.balance_for_locked_account(from)
-        debit_balance  = Locking.balance_for_locked_account(to)
+      credit_balance = Locking.balance_for_locked_account(from_account)
+      debit_balance  = Locking.balance_for_locked_account(to_account)
 
-        credit_balance.update_attribute :balance, credit_balance.balance - amount
-        debit_balance.update_attribute :balance, debit_balance.balance + amount
+      credit_balance.update_attribute :balance, credit_balance.balance - amount
+      debit_balance.update_attribute :balance, debit_balance.balance + amount
 
-        credit.amount,  debit.amount  = -amount, amount
-        credit.account, debit.account = from, to
-        credit.code,    debit.code    = code, code
-        credit.detail,  debit.detail  = detail, detail
-        credit.balance, debit.balance = credit_balance.balance, debit_balance.balance
+      credit.amount, debit.amount   = -amount, amount
+      credit.account, debit.account = from_account, to_account
+      credit.code, debit.code       = code, code
+      credit.detail, debit.detail   = detail, detail
+      credit.balance, debit.balance = credit_balance.balance, debit_balance.balance
 
-        credit.partner_account, debit.partner_account = to, from
+      credit.partner_account, debit.partner_account = to_account, from_account
+
+      credit.save!
+      debit.partner_id = credit.id
+      debit.save!
+      credit.update_attribute :partner_id, debit.id
+      [credit, debit]
+    end
 
-        credit.save!
-        debit.partner_id = credit.id
-        debit.save!
-        credit.update_attribute :partner_id, debit.id
+    def create_line_metadata(credit, debit, metadata)
+      metadata.each_pair do |key, value|
+        LineMetadata.create!(:line => credit, :key => key, :value => value)
+        LineMetadata.create!(:line => debit, :key => key, :value => value)
       end
     end
   end