double_entry 1.0.1 → 2.0.0.beta5

data/README.md

@@ -3,8 +3,8 @@
 
 [![License MIT](https://img.shields.io/badge/license-MIT-brightgreen.svg)](https://github.com/envato/double_entry/blob/master/LICENSE.md)
 [![Gem Version](https://badge.fury.io/rb/double_entry.svg)](http://badge.fury.io/rb/double_entry)
-[![Build Status](https://travis-ci.org/envato/double_entry.svg?branch=1-stable)](https://travis-ci.org/envato/double_entry)
-[![Code Climate](https://codeclimate.com/github/envato/double_entry.png)](https://codeclimate.com/github/envato/double_entry)
+[![Build Status](https://travis-ci.org/envato/double_entry.svg?branch=master)](https://travis-ci.org/envato/double_entry)
+[![Code Climate](https://codeclimate.com/github/envato/double_entry/badges/gpa.svg)](https://codeclimate.com/github/envato/double_entry)
 
 ![Show me the Money](http://24.media.tumblr.com/tumblr_m3bwbqNJIG1rrgbmqo1_500.gif)
 
@@ -22,15 +22,18 @@ DoubleEntry uses the [Money gem](https://github.com/RubyMoney/money) to encapsul
 DoubleEntry is tested against:
 
 Ruby
- * 2.1.x
- * 2.2.x
  * 2.3.x
+ * 2.4.x
+ * 2.5.x
+ * 2.6.x
+ * 2.7.x
 
 Rails
- * 3.2.x
- * 4.1.x
  * 4.2.x
  * 5.0.x
+ * 5.1.x
+ * 5.2.x
+ * 6.0.x
 
 Databases
  * MySQL
@@ -53,6 +56,8 @@ bundle
 
 Generate Rails schema migrations for the required tables:
 
+> The default behavior is to store metadata in a json(b) column rather than a separate `double_entry_line_metadata` table. If you would like the old (1.x) behavior, you can add `--no-json-metadata`.
+
 ```sh
 rails generate double_entry:install
 ```
@@ -67,7 +72,7 @@ rake db:migrate
 ## Interface
 
 The entire API for recording financial transactions is available through a few
-methods in the **DoubleEntry** module. For full details on
+methods in the [DoubleEntry](lib/double_entry.rb) module. For full details on
 what the API provides, please view the documentation on these methods.
 
 A configuration file should be used to define a set of accounts, and potential
@@ -88,12 +93,12 @@ than scoped accounts due to lock contention.
 To get a particular account:
 
 ```ruby
-account = DoubleEntry.account(:spending, :scope => user)
+account = DoubleEntry.account(:spending, scope: user)
 ```
 
 (This actually returns an Account::Instance object.)
 
-See **DoubleEntry::Account** for more info.
+See [DoubleEntry::Account](lib/double_entry/account.rb) for more info.
 
 
 ### Balances
@@ -114,15 +119,15 @@ To transfer money between accounts:
 ```ruby
 DoubleEntry.transfer(
   Money.new(20_00),
-  :from => one_account,
-  :to   => another_account,
-  :code => :a_business_code_for_this_type_of_transfer,
+  from: one_account,
+  to:   another_account,
+  code: :a_business_code_for_this_type_of_transfer,
 )
 ```
 
 The possible transfers, and their codes, should be defined in the configuration.
 
-See **DoubleEntry::Transfer** for more info.
+See [DoubleEntry::Transfer](lib/double_entry/transfer.rb) for more info.
 
 ### Metadata
 
@@ -131,10 +136,10 @@ 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'},
+  from: one_account,
+  to:   another_account,
+  code: :a_business_code_for_this_type_of_transfer,
+  metadata: {key1: ['value 1', 'value 2'], key2: 'value 3'},
 )
 ```
 
@@ -147,7 +152,7 @@ manually lock the accounts you're using:
 ```ruby
 DoubleEntry.lock_accounts(account_a, account_b) do
   # Perhaps transfer some money
-  DoubleEntry.transfer(Money.new(20_00), :from => account_a, :to => account_b, :code => :purchase)
+  DoubleEntry.transfer(Money.new(20_00), from: account_a, to: account_b, code: :purchase)
   # Perform other tasks that should be commited atomically with the transfer of funds...
 end
 ```
@@ -155,8 +160,23 @@ end
 The lock_accounts call generates a database transaction, which must be the
 outermost transaction.
 
-See **DoubleEntry::Locking** for more info.
+See [DoubleEntry::Locking](lib/double_entry/locking.rb) for more info.
+
+### Account Checker/Fixer
+
+Although it's unlikely, DoubleEntry has tools for checking accounts to make sure they tie out, and optionally fixing them if there is a discrepancy. It's recommended to run this in a scheduled job, somewhere on the order of hourly to daily, depending on transaction volume. Keep in mind that this process locks accounts as it inspects their balances, so it will have an prevent new transactions from being written for a short time.
 
+Here are examples that could go in your scheduled job, depending on your needs:
+
+```ruby
+# Check all accounts & write the results to the double_entry_line_checks table
+DoubleEntry::Validation::LineCheck.perform!
+
+# Check & fix accounts (results will also be written to the table)
+DoubleEntry::Validation::LineCheck.perform!(fixer: DoubleEntry::Validation::AccountFixer.new)
+```
+
+See [DoubleEntry::Validation](lib/double_entry/validation) for more info.
 
 ## Implementation
 
@@ -168,13 +188,12 @@ Lines table entries also store the running balance for the account. To retrieve
 the current balance for an account, we find the most recent lines table entry
 for it.
 
-See **DoubleEntry::Line** for more info.
+See [DoubleEntry::Line](lib/double_entry/line.rb) 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.
+Transfer metadata is stored in a json(b) column on both the source and destination lines of the transfer.
 
 ## Configuration
 
@@ -182,7 +201,7 @@ A configuration file should be used to define a set of accounts, optional scopes
 the accounts, and permitted transfers between those accounts.
 
 The configuration file should be kept in your application's load path.  For example,
-*config/initializers/double_entry.rb*
+*config/initializers/double_entry.rb*. By default, this file will be created when you run the installer, but you will need to fill out your accounts.
 
 For example, the following specifies two accounts, savings and checking.
 Each account is scoped by User (where User is an object with an ID), meaning
@@ -194,15 +213,21 @@ This configuration also specifies that money can be transferred between the two
 require 'double_entry'
 
 DoubleEntry.configure do |config|
+  # Use json(b) column in double_entry_lines table to store metadata instead of separate metadata table
+  config.json_metadata = true
+
   config.define_accounts do |accounts|
-    user_scope = accounts.active_record_scope_identifier(User)
-    accounts.define(:identifier => :savings,  :scope_identifier => user_scope, :positive_only => true)
-    accounts.define(:identifier => :checking, :scope_identifier => user_scope)
+    user_scope = ->(user) do
+      raise 'not a User' unless user.class.name == 'User'
+      user.id
+    end
+    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
 ```
@@ -215,7 +240,7 @@ Transfers between accounts of different currencies are not allowed.
 ```ruby
 DoubleEntry.configure do |config|
   config.define_accounts do |accounts|
-    accounts.define(:identifier => :savings,  :scope_identifier => user_scope, :currency => :aud)
+    accounts.define(identifier: :savings,  scope_identifier: user_scope, currency: 'AUD')
   end
 end
 ```
@@ -267,40 +292,78 @@ See the Github project [issues](https://github.com/envato/double_entry/issues).
 
 ## Development Environment Setup
 
+We're using Docker to provide a convenient and consistent environment for
+executing tests during development. This allows engineers to quickly set up
+a productive development environment.
+
+Note: Most development files are mounted in the Docker container. This
+enables engineers to edit files in their favourite editor (on the host
+OS) and have the changes immediately available in the Docker container
+to be exercised.
+
+One exception to this is the RSpec configuration. Changes to these files will
+require a rebuild of the Docker image (step 2).
+
+Prerequisites:
+
+* Docker
+* Docker Compose
+* Git
+
 1. Clone this repo.
 
     ```sh
     git clone git@github.com:envato/double_entry.git && cd double_entry
     ```
 
-2. Run the included setup script to install the gem dependencies.
+2. Build the Docker image we'll use to run tests
 
     ```sh
-    ./script/setup.sh
+    docker-compose build --pull double_entry
     ```
 
-3. Install MySQL, PostgreSQL and SQLite. We run tests against all three databases.
-4. Create a database in MySQL.
+3. Startup a container and attach a terminal. This will also start up a
+   MySQL and Postgres database.
 
     ```sh
-    mysql -u root -e 'create database double_entry_test;'
+    docker-compose run --rm double_entry ash
     ```
 
-5. Create a database in PostgreSQL.
+4. Run the tests
 
     ```sh
-    psql -c 'create database double_entry_test;' -U postgres
+    DB=mysql bundle exec rspec
+    DB=postgres bundle exec rspec
+    DB=sqlite bundle exec rspec
     ```
 
-6. Specify how the tests should connect to the database
+5. When finished, exit the container terminal and shut down the databases.
 
     ```sh
-    cp spec/support/{database.example.yml,database.yml}
-    vim spec/support/database.yml
+    exit
+    docker-compose down
     ```
 
-7. Run the tests
-
-    ```sh
-    bundle exec rake
-    ```
+## Contributors
+
+Many thanks to those who have contributed to both this gem, and the library upon which it was based, over the years:
+  * Anthony Sellitti - @asellitt
+  * Clinton Forbes - @clinton
+  * Eaden McKee - @eadz
+  * Giancarlo Salamanca - @salamagd
+  * Jiexin Huang - @jiexinhuang
+  * Keith Pitt - @keithpitt
+  * Kelsey Hannan - @KelseyDH
+  * Mark Turnley - @rabidcarrot
+  * Martin Jagusch - @MJIO
+  * Martin Spickermann - @spickermann
+  * Mary-Anne Cosgrove - @macosgrove
+  * Orien Madgwick - @orien
+  * Pete Yandall - @notahat
+  * Rizal Muthi - @rizalmuthi
+  * Ryan Allen - @ryan-allen
+  * Samuel Cochran - @sj26
+  * Stefan Wrobel - @swrobel
+  * Stephanie Staub - @stephnacios
+  * Trung Lê - @joneslee85
+  * Vahid Ta'eed - @vahid

data/double_entry.gemspec

@@ -1,4 +1,4 @@
-# encoding: utf-8
+
 lib = File.expand_path('../lib', __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 
@@ -7,67 +7,40 @@ require 'double_entry/version'
 Gem::Specification.new do |gem|
   gem.name                  = 'double_entry'
   gem.version               = DoubleEntry::VERSION
-  gem.authors               = ['Anthony Sellitti', 'Keith Pitt', 'Martin Jagusch', 'Martin Spickermann', 'Mark Turnley', 'Orien Madgwick', 'Pete Yandall', 'Stephanie Staub', 'Giancarlo Salamanca']
-  gem.email                 = ['anthony.sellitti@envato.com', 'me@keithpitt.com', '_@mj.io', 'spickemann@gmail.com', 'mark@envato.com', '_@orien.io', 'pete@envato.com', 'staub.steph@gmail.com', 'giancarlo@salamanca.net.au']
+  gem.authors               = ['Envato']
+  gem.email                 = ['rubygems@envato.com']
   gem.summary               = 'Tools to build your double entry financial ledger'
   gem.homepage              = 'https://github.com/envato/double_entry'
-
-  gem.files                 = `git ls-files`.split($/)
-  gem.executables           = gem.files.grep(%r{bin/}).map { |f| File.basename(f) }
-  gem.test_files            = gem.files.grep(%r{^(test|spec|features)/})
+  gem.license               = 'MIT'
+
+  gem.metadata = {
+    'bug_tracker_uri'   => 'https://github.com/envato/double_entry/issues',
+    'changelog_uri'     => "https://github.com/envato/double_entry/blob/v#{gem.version}/CHANGELOG.md",
+    'documentation_uri' => "https://www.rubydoc.info/gems/double_entry/#{gem.version}",
+    'source_code_uri'   => "https://github.com/envato/double_entry/tree/v#{gem.version}",
+  }
+
+  gem.files                 = `git ls-files -z`.split("\x0").select do |f|
+    f.match(%r{^(?:double_entry.gemspec|README|LICENSE|CHANGELOG|lib/)})
+  end
   gem.require_paths         = ['lib']
+  gem.required_ruby_version = '>= 2.3.0'
 
-  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'
+  gem.add_dependency 'money',                 '>= 6.0.0'
   gem.add_dependency 'railties',              '>= 3.2.0'
 
-  gem.add_development_dependency 'rake'
   gem.add_development_dependency 'mysql2'
   gem.add_development_dependency 'pg'
+  gem.add_development_dependency 'rake'
   gem.add_development_dependency 'sqlite3'
 
-  gem.add_development_dependency 'rspec'
-  gem.add_development_dependency 'rspec-its'
-  gem.add_development_dependency 'rspec-instafail'
   gem.add_development_dependency 'database_cleaner'
+  gem.add_development_dependency 'factory_bot'
   gem.add_development_dependency 'generator_spec'
-  gem.add_development_dependency 'machinist'
-  gem.add_development_dependency 'timecop'
-  gem.add_development_dependency 'test-unit'
-
-  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 'rspec'
+  gem.add_development_dependency 'rspec-its'
   gem.add_development_dependency 'ruby-prof'
+  gem.add_development_dependency 'timecop'
 end

data/lib/active_record/locking_extensions.rb

@@ -18,7 +18,7 @@ module ActiveRecord
       yield
     rescue ActiveRecord::StatementInvalid => exception
       if exception.message =~ /deadlock/i || exception.message =~ /database is locked/i
-        ActiveSupport::Notifications.publish('deadlock_restart.active_record', :exception => exception)
+        ActiveSupport::Notifications.publish('deadlock_restart.double_entry', exception: exception)
 
         raise ActiveRecord::RestartTransaction
       else
@@ -46,7 +46,7 @@ module ActiveRecord
       yield
     rescue ActiveRecord::StatementInvalid, ActiveRecord::RecordNotUnique => exception
       if  exception.message =~ /duplicate/i || exception.message =~ /ConstraintException/
-        ActiveSupport::Notifications.publish('duplicate_ignore.active_record', :exception => exception)
+        ActiveSupport::Notifications.publish('duplicate_ignore.double_entry', exception: exception)
 
         # Just ignore it...someone else has already created the record.
       else
@@ -63,7 +63,7 @@ module ActiveRecord
       if exception.message =~ /deadlock/i || exception.message =~ /database is locked/i
         # Somebody else is in the midst of creating the record. We'd better
         # retry, so we ensure they're done before we move on.
-        ActiveSupport::Notifications.publish('deadlock_retry.active_record', :exception => exception)
+        ActiveSupport::Notifications.publish('deadlock_retry.double_entry', exception: exception)
 
         retry
       else

data/lib/active_record/locking_extensions/log_subscriber.rb

@@ -26,4 +26,4 @@ module ActiveRecord
   end
 end
 
-ActiveRecord::LockingExtensions::LogSubscriber.attach_to :active_record
+ActiveRecord::LockingExtensions::LogSubscriber.attach_to :double_entry

data/lib/double_entry.rb

@@ -4,6 +4,7 @@ require 'active_record/locking_extensions'
 require 'active_record/locking_extensions/log_subscriber'
 require 'active_support/all'
 require 'money'
+require 'rails/railtie'
 
 require 'double_entry/version'
 require 'double_entry/errors'
@@ -14,9 +15,6 @@ require 'double_entry/account_balance'
 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'
 
 # Keep track of all the monies!
@@ -24,6 +22,16 @@ require 'double_entry/validation'
 # This module provides the public interfaces for everything to do with
 # transferring money around the system.
 module DoubleEntry
+  class Railtie < ::Rails::Railtie
+    # So we can access user config from initializer in their app
+    config.after_initialize do
+      unless DoubleEntry.config.json_metadata
+        require 'double_entry/line_metadata'
+      end
+      require 'double_entry/line'
+    end
+  end
+
   class << self
     # Get the particular account instance with the provided identifier and
     # scope.
@@ -58,9 +66,9 @@ module DoubleEntry
     #   savings_account  = DoubleEntry.account(:savings,  scope: user)
     #   DoubleEntry.transfer(
     #     20.dollars,
-    #     :from => checking_account,
-    #     :to   => savings_account,
-    #     :code => :save,
+    #     from: checking_account,
+    #     to:   savings_account,
+    #     code: :save,
     #   )
     # @param [Money] amount The quantity of money to transfer from one account
     #   to the other.
@@ -83,35 +91,35 @@ module DoubleEntry
     # Get the current or historic balance of an account.
     #
     # @example Obtain the current balance of my checking account
-    #   checking_account = DoubleEntry.account(:checking, :scope => user)
+    #   checking_account = DoubleEntry.account(:checking, scope: user)
     #   DoubleEntry.balance(checking_account)
     # @example Obtain the current balance of my checking account (without account or user model)
-    #   DoubleEntry.balance(:checking, :scope => user_id)
+    #   DoubleEntry.balance(:checking, scope: user_id)
     # @example Obtain a historic balance of my checking account
-    #   checking_account = DoubleEntry.account(:checking, :scope => user)
-    #   DoubleEntry.balance(checking_account, :at => Time.new(2012, 1, 1))
+    #   checking_account = DoubleEntry.account(:checking, scope: user)
+    #   DoubleEntry.balance(checking_account, at: Time.new(2012, 1, 1))
     # @example Obtain the net balance of my checking account during may
-    #   checking_account = DoubleEntry.account(:checking, :scope => user)
+    #   checking_account = DoubleEntry.account(:checking, scope: user)
     #   DoubleEntry.balance(
     #     checking_account,
-    #     :from => Time.new(2012, 5,  1,  0,  0,  0),
-    #     :to   => Time.new(2012, 5, 31, 23, 59, 59),
+    #     from: Time.new(2012, 5,  1,  0,  0,  0),
+    #     to:   Time.new(2012, 5, 31, 23, 59, 59),
     #   )
     # @example Obtain the balance of salary deposits made to my checking account during may
-    #   checking_account = DoubleEntry.account(:checking, :scope => user)
+    #   checking_account = DoubleEntry.account(:checking, scope: user)
     #   DoubleEntry.balance(
     #     checking_account,
-    #     :code => :salary,
-    #     :from => Time.new(2012, 5,  1,  0,  0,  0),
-    #     :to   => Time.new(2012, 5, 31, 23, 59, 59),
+    #     code: :salary,
+    #     from: Time.new(2012, 5,  1,  0,  0,  0),
+    #     to:   Time.new(2012, 5, 31, 23, 59, 59),
     #   )
     # @example Obtain the balance of salary & lottery deposits made to my checking account during may
-    #   checking_account = DoubleEntry.account(:checking, :scope => user)
+    #   checking_account = DoubleEntry.account(:checking, scope: user)
     #   DoubleEntry.balance(
     #     checking_account,
-    #     :codes => [ :salary, :lottery ],
-    #     :from  => Time.new(2012, 5,  1,  0,  0,  0),
-    #     :to    => Time.new(2012, 5, 31, 23, 59, 59),
+    #     codes: [ :salary, :lottery ],
+    #     from:  Time.new(2012, 5,  1,  0,  0,  0),
+    #     to:    Time.new(2012, 5, 31, 23, 59, 59),
     #   )
     # @param [DoubleEntry::Account:Instance, Symbol] account Find the balance
     #   for this account