double_entry-reporting 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fb30fb81a5ac9f48c82bb5619f5a1f08ea039c98fe65851ec7faf0bdf7cafabb
+  data.tar.gz: 39922494fa79df8186046675e8cc797d97b7d3a4fcec59c720ae67cd053f62cc
+SHA512:
+  metadata.gz: 8974397dc11de77e803a23f70bc30a9fb3bca382fc3027bc1725d8b193aa0f8e7f56332e9286a56e5679260b4a01e7f4c7e1cc72a0182df80eac9e20e18156d5
+  data.tar.gz: 16a3fd534dcc5b13dabf191a39d9934735ccc1f255b9c09114722478bf7ac28ccea55c217b9930e87c55de3c8800341cc40f24dce079ff48fad17e83933517e9

data/CHANGELOG.md

@@ -0,0 +1,75 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
+and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2019-01-27
+
+### Added
+
+- `DoubleEntry::Reporting` module extracted from the `double_entry` gem. Please see
+  the [Double Entry changelog](https://github.com/envato/double_entry/blob/master/CHANGELOG.md)
+  for changes prior to this release.
+
+- Added support for Ruby 2.3, 2.4, 2.5 and 2.6.
+
+- Added support for Rails 5.0, 5.1 and 5.2
+
+- Allow filtering aggregates by multiple metadata key/value pairs.
+
+### Changed
+
+- These methods now use keyword arguments. This is a breaking change.
+  - `DoubleEntry::Reporting::aggregate`
+  - `DoubleEntry::Reporting::aggregate_array`
+  - `DoubleEntry::Reporting::Aggregate::new`
+  - `DoubleEntry::Reporting::Aggregate::formatted_amount`
+  - `DoubleEntry::Reporting::AggregateArray::new`
+  - `DoubleEntry::Reporting::LineAggregateFilter::new`
+
+- Allow partner account to be specified for aggregates. This changes the DB
+  schema. Apply this change with the migration:
+
+    ```ruby
+    add_column :double_entry_line_aggregates, :partner_account, :string, after: :code
+    remove_index :double_entry_line_aggregates, name: :line_aggregate_idx
+    add_index :double_entry_line_aggregates, %i[function account code partner_account year month week day], name: :line_aggregate_idx
+    ```
+
+- Replaced Machinist with Factory Bot in test suite.
+
+- Changed the `double_entry_line_aggregates.amount` column to be of type `bigint`.
+  Apply this change with the migration:
+
+   ```ruby
+   change_column :double_entry_line_aggregates, :amount, :bigint, null: false
+   ```
+
+- Changed the maximum length of the `account`, `code` and `scope` columns.
+  Apply this change with the migration:
+
+   ```ruby
+   change_column :double_entry_line_aggregates, :account, :string, null: false
+   change_column :double_entry_line_aggregates, :code,    :string, null: true
+   change_column :double_entry_line_aggregates, :scope,   :string, null: true
+   ```
+
+### Removed
+
+- Removed support for Ruby 1.9, 2.0, 2.1 and 2.2.
+
+- Removed support for Rails 3.2, 4.0, and 4.1.
+
+- Removed `DoubleEntry::Reporting.scopes_with_minimum_balance_for_account`
+  method. This is now available on the `DoubleEntry::AccountBalance` class.
+
+### Fixed
+
+- Fixed Ruby warnings.
+
+- Fixed problem of Rails version number not being set in migration template for apps using Rails 5 or higher.
+
+[Unreleased]: https://github.com/envato/double_entry/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/envato/double_entry-reporting/compare/double-entry-v1.0.0...v0.1.0

data/LICENSE.md

@@ -0,0 +1,19 @@
+Copyright © 2014 Envato Pty Ltd
+
+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/README.md

@@ -0,0 +1,71 @@
+# DoubleEntry Reporting
+
+[![License MIT](https://img.shields.io/badge/license-MIT-brightgreen.svg)](https://github.com/envato/double_entry-reporting/blob/master/LICENSE.md)
+[![Gem Version](https://badge.fury.io/rb/double_entry-reporting.svg)](http://badge.fury.io/rb/double_entry-reporting)
+[![Build Status](https://travis-ci.org/envato/double_entry-reporting.svg?branch=master)](https://travis-ci.org/envato/double_entry-reporting)
+
+## Installation
+
+In your application's `Gemfile`, add:
+
+```ruby
+gem 'double_entry-reporting'
+```
+
+Download and install the gem with Bundler:
+
+```sh
+bundle
+```
+
+Generate Rails schema migrations for the required tables:
+
+```sh
+rails generate double_entry:reporting:install
+```
+
+Update the local database:
+
+```sh
+rake db:migrate
+```
+
+## Development Environment Setup
+
+1. Clone this repo.
+
+    ```sh
+    git clone git@github.com:envato/double_entry-reporting.git && cd double_entry-reporting
+    ```
+
+2. Run the included setup script to install the gem dependencies.
+
+    ```sh
+    ./script/setup.sh
+    ```
+
+3. Install MySQL, PostgreSQL and SQLite. We run tests against all three databases.
+4. Create a database in MySQL.
+
+    ```sh
+    mysql -u root -e 'create database double_entry_reporting_test;'
+    ```
+
+5. Create a database in PostgreSQL.
+
+    ```sh
+    psql -c 'create database double_entry_reporting_test;' -U postgres
+    ```
+
+6. Specify how the tests should connect to the database
+
+    ```sh
+    cp spec/support/{database.example.yml,database.yml}
+    vim spec/support/database.yml
+    ```
+
+7. Run the tests
+
+    ```sh
+    bundle exec rake
+    ```

data/lib/double_entry/reporting.rb

@@ -0,0 +1,154 @@
+# encoding: utf-8
+require 'double_entry'
+require 'double_entry/reporting/aggregate'
+require 'double_entry/reporting/aggregate_array'
+require 'double_entry/reporting/time_range'
+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/line_aggregate_filter'
+require 'double_entry/reporting/line_metadata_filter'
+require 'double_entry/reporting/time_range_array'
+
+module DoubleEntry
+  module Reporting
+    include Configurable
+    extend self
+
+    class Configuration
+      attr_accessor :start_of_business, :first_month_of_financial_year
+
+      def initialize #:nodoc:
+        @start_of_business = Time.new(1970, 1, 1)
+        @first_month_of_financial_year = 7
+      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, 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 :specific_transfer_amount, ->(amount) { where(:amount => amount.fractional) }
+    #   end
+    #
+    #   DoubleEntry::Reporting.aggregate(
+    #     :sum,
+    #     :checking,
+    #     :save,
+    #     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
+    # @param [Symbol] account The symbol identifying the account to perform
+    #   the aggregate calculation on. As specified in the account configuration.
+    # @param [Symbol] code The application specific code for the type of
+    #   transfer to perform an aggregate calculation on. As specified in the
+    #   transfer configuration.
+    # @param [DoubleEntry::Reporting::TimeRange] range Only include transfers in
+    #   the given time range in the calculation.
+    # @param [Symbol] partner_account The symbol identifying the partner account
+    #   to perform the aggregate calculatoin on.  As specified in the account
+    #   configuration.
+    # @param [Array<Hash<Symbol,Hash<Symbol,Object>>>] filter
+    #   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, Integer] Returns a Money object for :sum and :average
+    #   calculations, or a Integer for :count calculations.
+    # @raise [Reporting::AggregateFunctionNotSupported] The provided function
+    #   is not supported.
+    #
+    def aggregate(function:, account:, code:, range:, partner_account: nil, filter: nil)
+      Aggregate.formatted_amount(function: function, account: account, code: code, range: range,
+                                 partner_account: partner_account, filter: filter)
+    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::Reporting.aggregate_array(
+    #     :sum,
+    #     :checking,
+    #     :save,
+    #     :range_type => 'month',
+    #     :start      => '2014-01-01',
+    #     :finish     => '2014-12-31',
+    #   )
+    # @param [Symbol] function The function to perform on the set of transfers.
+    #   Valid functions are :sum, :count, and :average
+    # @param [Symbol] account The symbol identifying the account to perform
+    #   the aggregate calculation on. As specified in the account configuration.
+    # @param [Symbol] code The application specific code for the type of
+    #   transfer to perform an aggregate calculation on. As specified in the
+    #   transfer configuration.
+    # @param [Symbol] partner_account The symbol identifying the partner account
+    #   to perform the aggregative calculation on.  As specified in the account
+    #   configuration.
+    # @param [Array<Symbol>, Array<Hash<Symbol, Object>>] filter
+    #   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 [String] range_type 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'
+    # @param [String] start 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'
+    # @param [String] finish 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, Integer>] Returns an array of Money objects for :sum
+    #   and :average calculations, or an array of Integer 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:, partner_account: nil, filter: nil,
+                        range_type: nil, start: nil, finish: nil)
+      AggregateArray.new(function: function, account: account, code: code, partner_account: partner_account,
+                         filter: filter, range_type: range_type, start: start, finish: finish)
+    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/reporting/aggregate.rb

@@ -0,0 +1,130 @@
+# encoding: utf-8
+module DoubleEntry
+  module Reporting
+    class Aggregate
+      attr_reader :function, :account, :partner_account, :code, :range, :filter, :currency
+
+      def self.formatted_amount(function:, account:, code:, range:, partner_account: nil, filter: nil)
+        new(
+          function: function,
+          account: account,
+          code: code,
+          range: range,
+          partner_account: partner_account,
+          filter: filter,
+        ).formatted_amount
+      end
+
+      def initialize(function:, account:, code:, range:, partner_account: nil, filter: nil)
+        @function = function.to_s
+        fail AggregateFunctionNotSupported unless %w(sum count average).include?(@function)
+
+        @account         = account
+        @code            = code.try(:to_s)
+        @range           = range
+        @partner_account = partner_account
+        @filter          = filter
+        @currency        = DoubleEntry::Account.currency(account)
+      end
+
+      def amount(force_recalculation = false)
+        if force_recalculation
+          clear_old_aggregates
+          calculate
+        else
+          retrieve || calculate
+        end
+      end
+
+      def formatted_amount(value = amount)
+        value ||= 0
+        if function == 'count'
+          value
+        else
+          Money.new(value, currency)
+        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 == YearRange
+          aggregate = calculate_yearly_aggregate
+        else
+          aggregate = LineAggregate.aggregate(
+            function: function,
+            account: account,
+            partner_account: partner_account,
+            code: code,
+            range: range,
+            named_scopes: 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
+        if function == 'average'
+          calculate_yearly_average
+        else
+          result = (1..12).inject(formatted_amount(0)) do |total, month|
+            total + Aggregate.new(function: function, account: account, code: code,
+                                  range: MonthRange.new(:year => range.year, :month => month),
+                                  partner_account: partner_account, filter: filter).formatted_amount
+          end
+          result.is_a?(Money) ? result.cents : result
+        end
+      end
+
+      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 = Aggregate.new(function: :sum, account: account, code: code, range: year_range,
+                            partner_account: partner_account, filter: filter).formatted_amount
+        count = Aggregate.new(function: :count, account: account, code: code, range: year_range,
+                              partner_account: partner_account, filter: filter).formatted_amount
+        (count == 0) ? 0 : (sum / count).cents
+      end
+
+      def range_is_complete?
+        Time.now > range.finish
+      end
+
+      def field_hash
+        {
+          :function        => function,
+          :account         => account,
+          :partner_account => partner_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
+end