generalis 0.1.0

data/bin/rubocop

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'rubocop' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../../Gemfile',
+                                           Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path('bundle', __dir__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('rubocop', 'rubocop')

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/generalis.gemspec

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative 'lib/generalis/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'generalis'
+  spec.version       = Generalis::VERSION
+  spec.authors       = ['Minty Fresh']
+  spec.email         = ['7896757+mintyfresh@users.noreply.github.com']
+
+  spec.summary       = 'General Ledger for Ruby of Rails'
+  spec.description   = spec.summary
+  spec.homepage      = 'https://github.com/mintyfresh/generalis'
+  spec.required_ruby_version = Gem::Requirement.new('>= 3.0')
+
+  spec.metadata['allowed_push_host'] = 'https://rubygems.org'
+
+  spec.metadata['homepage_uri']          = spec.homepage
+  spec.metadata['source_code_uri']       = spec.homepage
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features|integration)/}) }
+  end
+
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'activerecord', '>= 5', '< 7'
+  spec.add_dependency 'money-rails', '~> 1.15'
+end

data/lib/generalis/account.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Generalis
+  class Account < ActiveRecord::Base
+    CREDIT_NORMAL = -1
+    DEBIT_NORMAL  = +1
+
+    attr_readonly :type, :coefficient
+
+    belongs_to :owner, optional: true, polymorphic: true
+
+    has_many :entries, dependent: :restrict_with_error, inverse_of: :account
+    has_many :ledger_transactions, through: :entries
+
+    validates :name, presence: true
+    validates :coefficient, inclusion: { in: [CREDIT_NORMAL, DEBIT_NORMAL] }
+
+    # @param name [Symbol, String]
+    # @param owner [ActiveRecord::Base, nil]
+    # @return [Account]
+    def self.define(name, owner: nil)
+      create_or_find_by!(name: name, owner: owner)
+    end
+
+    # @param name [Symbol, String]
+    # @param owner [ActiveRecord::Base, nil]
+    # @return [Account]
+    def self.[](name, owner: nil)
+      find_by!(name: name, owner: owner)
+    end
+
+    # @param name [Symbol, String]
+    # @param owner [ActiveRecord::Base, nil]
+    # @return [Account]
+    def self.lookup(name, owner: nil)
+      find_by!(name: name, owner: owner)
+    end
+
+    # @param balance_type [Symbol]
+    # @return [void]
+    def self.balance_type(balance_type)
+      case balance_type
+      when :credit_normal
+        after_initialize(if: :new_record?) { self.coefficient = CREDIT_NORMAL }
+      when :debit_normal
+        after_initialize(if: :new_record?) { self.coefficient = DEBIT_NORMAL }
+      else
+        raise ArgumentError, "Unsupported balance type: #{balance_type.inspect}. " \
+                             '(Expected on of :credit_normal or :debit_normal.)'
+      end
+    end
+
+    # Acquires a database lock on one or more accounts for balance calculations.
+    # Locks are acquired in a deterministic sequence to prevent deadlocks.
+    #
+    # @param accounts [Array<Account>]
+    # @return [Boolean]
+    def self.lock_for_balance_calculation(accounts)
+      unscoped.where(id: accounts).order(:id).lock(true).ids.present?
+    end
+
+    # @return [Boolean]
+    def credit_normal?
+      coefficient == CREDIT_NORMAL
+    end
+
+    # @return [Boolean]
+    def debit_normal?
+      coefficient == DEBIT_NORMAL
+    end
+
+    # Returns the balance for a given currency on this account.
+    # If no balance is present for the specified currency, 0 is returned.
+    #
+    # @param currency [String]
+    # @param at [Time, nil]
+    # @return [Money]
+    def balance(currency, at: nil)
+      scope = entries.where(currency: currency)
+      scope = scope.at_or_before(at) if at
+
+      scope.last&.balance_after || Money.from_amount(0, currency)
+    end
+
+    # Returns the latest balances for all currencies on this account.
+    #
+    # @param at [Time, nil]
+    # @return [Hash{String => Money}]
+    def balances(at: nil)
+      scope = entries.group(:currency).select(Entry.arel_table[:id].maximum)
+      scope = scope.at_or_before(at) if at
+
+      entries.where(id: scope)
+        .map { |entry| [entry.currency, entry.balance_after] }
+        .to_h
+    end
+  end
+end

data/lib/generalis/accountable.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Generalis
+  module Accountable
+    extend ActiveSupport::Concern
+
+    included do
+      has_many :ledger_accounts, as: :owner, class_name: 'Generalis::Account', dependent: false, inverse_of: :owner
+      has_many :ledger_entries, through: :ledger_accounts, source: :entries
+      has_many :ledger_transactions, through: :ledger_accounts
+    end
+
+    class_methods do
+      # rubocop:disable Naming/PredicateName
+      def has_asset_account(name, auto_create: true, dependent: :restrict_with_error)
+        has_account(name, class_name: 'Generalis::Asset', auto_create: auto_create, dependent: dependent)
+      end
+
+      def has_expense_account(name, auto_create: true, dependent: :restrict_with_error)
+        has_account(name, class_name: 'Generalis::Expense', auto_create: auto_create, dependent: dependent)
+      end
+
+      def has_liability_account(name, auto_create: true, dependent: :restrict_with_error)
+        has_account(name, class_name: 'Generalis::Liability', auto_create: auto_create, dependent: dependent)
+      end
+
+      def has_revenue_account(name, auto_create: true, dependent: :restrict_with_error)
+        has_account(name, class_name: 'Generalis::Revenue', auto_create: auto_create, dependent: dependent)
+      end
+
+      def has_account(name, class_name:, auto_create: true, dependent: :restrict_with_error)
+        has_one(name, -> { where(name: name) },
+                as: :owner, class_name: class_name, # rubocop:disable Rails/ReflectionClassName
+                dependent: dependent, inverse_of: :owner)
+
+        after_create(:"create_#{name}", if: -> { send(name).nil? }) if auto_create
+
+        scope :"without_#{name}", -> { left_joins(name.to_sym).merge(Generalis::Account.where(id: nil)) }
+      end
+      # rubocop:enable Naming/PredicateName
+    end
+  end
+end

data/lib/generalis/asset.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Generalis
+  class Asset < Account
+    balance_type :debit_normal
+  end
+end

data/lib/generalis/config.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'singleton'
+
+module Generalis
+  class Config
+    # @param value [String]
+    attr_writer :table_name_prefix
+
+    # @return [String]
+    def table_name_prefix
+      @table_name_prefix || 'ledger_'
+    end
+  end
+end

data/lib/generalis/credit.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Generalis
+  class Credit < Entry
+    self.coefficient = CREDIT
+  end
+end

data/lib/generalis/debit.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Generalis
+  class Debit < Entry
+    self.coefficient = DEBIT
+  end
+end

data/lib/generalis/entry.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Generalis
+  class Entry < ActiveRecord::Base
+    CREDIT = -1
+    DEBIT  = +1
+
+    attr_readonly :type, :account_id, :transaction_id, :pair_id, :currency, :amount_cents, :coefficient
+
+    belongs_to :account, inverse_of: :entries
+    belongs_to :ledger_transaction, class_name: 'Transaction', foreign_key: :transaction_id, inverse_of: :entries
+
+    validates :currency, presence: true
+    validates :coefficient, inclusion: { in: [CREDIT, DEBIT] }
+
+    with_options with_model_currency: :currency do
+      monetize :amount_cents, numericality: { greater_than_or_equal_to: 0 }
+      monetize :balance_after_cents, allow_nil: true
+    end
+
+    before_create do
+      self.balance_after = account.balance(currency) + net_amount
+    end
+
+    scope :credit, -> { where(coefficient: CREDIT) }
+    scope :debit,  -> { where(coefficient: DEBIT)  }
+
+    scope :before, -> (entry) { where(arel_table[:id].lt(entry.id)) }
+    scope :after,  -> (entry) { where(arel_table[:id].gt(entry.id)) }
+
+    scope :at_or_before, -> (time) { joins(:transaction).merge(Transaction.at_or_before(time)) }
+
+    # @param value [Integer]
+    # @return [void]
+    def self.coefficient=(coefficient)
+      after_initialize(if: :new_record?) { self.coefficient = coefficient }
+    end
+
+    # @return [Boolean]
+    def credit?
+      coefficient == CREDIT
+    end
+
+    # @return [Boolean]
+    def debit?
+      coefficient == DEBIT
+    end
+
+    # The net change in balance that is applied to the account.
+    #
+    # @return [Money]
+    def net_amount
+      amount * coefficient * account.coefficient
+    end
+
+    # @return [Boolean]
+    def no_op?
+      amount.zero?
+    end
+
+    # @return [Entry, nil]
+    def opposite
+      ledger_transaction.entries.find_by(pair_id: pair_id, coefficient: -coefficient)
+    end
+  end
+end

data/lib/generalis/expense.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Generalis
+  class Expense < Account
+    balance_type :debit_normal
+  end
+end

data/lib/generalis/liability.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Generalis
+  class Liability < Account
+    balance_type :credit_normal
+  end
+end

data/lib/generalis/link.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Generalis
+  class Link < ActiveRecord::Base
+    belongs_to :ledger_transaction, class_name: 'Transaction', foreign_key: :transaction_id, inverse_of: :links
+    belongs_to :linkable, polymorphic: true
+
+    validates :name, presence: true
+  end
+end

data/lib/generalis/linkable.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Generalis
+  module Linkable
+    extend ActiveSupport::Concern
+
+    included do
+      has_many :ledger_links, as: :linkable, class_name: 'Generalis::Link',
+                              dependent: :restrict_with_error, inverse_of: :linkable
+
+      has_many :linked_ledger_transactions, class_name: 'Generalis::Transaction',
+                                            through: :ledger_links, source: :ledger_transaction
+    end
+  end
+end

data/lib/generalis/revenue.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Generalis
+  class Revenue < Account
+    balance_type :credit_normal
+  end
+end

data/lib/generalis/rspec.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative '../rspec/change_balance_of_matcher'
+require_relative '../rspec/credit_account_matcher'
+require_relative '../rspec/debit_account_matcher'
+require_relative '../rspec/have_balance_matcher'

data/lib/generalis/transaction/double_entry.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Generalis
+  class Transaction < ActiveRecord::Base
+    DoubleEntry = Struct.new(:credit, :debit, :amount_cents, :currency) do
+      def amount
+        Money.from_cents(amount_cents || 0, currency)
+      end
+
+      def amount=(value)
+        value = Money.from_amount(value, currency) unless value.is_a?(Money)
+
+        self.amount_cents = value.cents
+        self.currency     = value.currency.iso_code
+      end
+
+      # @return [Array<Entry>]
+      def entries
+        credit, debit = self.credit, self.debit
+
+        # Reverse the debit/credit accounts when supplied a negative amount.
+        credit, debit = debit, credit if amount.negative?
+
+        [
+          # Flip the amount back to positive since we've already swapped accounts.
+          Credit.new(account: credit, amount: amount.abs, pair_id: pair_id),
+          Debit.new(account:  debit, amount:  amount.abs, pair_id: pair_id)
+        ]
+      end
+
+      # @return [String]
+      def pair_id
+        @pair_id ||= SecureRandom.uuid
+      end
+    end
+  end
+end

data/lib/generalis/transaction/dsl.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative 'double_entry'
+require_relative 'preparation'
+
+module Generalis
+  class Transaction < ActiveRecord::Base
+    module DSL
+      def self.extended(klass)
+        super(klass)
+
+        klass.include(Preparation)
+        klass.before_validation(:prepare, if: :new_record?)
+      end
+
+      def transaction_id(&block)
+        prepare_with do
+          self.transaction_id = instance_exec(&block)
+        end
+      end
+
+      def description(&block)
+        prepare_with do
+          self.description = instance_exec(&block)
+        end
+      end
+
+      def metadata(&block)
+        prepare_with do
+          self.metadata = instance_exec(&block)
+        end
+      end
+
+      def occurred_at(&block)
+        prepare_with do
+          self.occurred_at = instance_exec(&block)
+        end
+      end
+
+      # @return [void]
+      def credit(&block)
+        prepare_with do
+          credit = Credit.new
+          instance_exec(credit, &block)
+
+          entries << credit
+        end
+      end
+
+      # @return [void]
+      def debit(&block)
+        prepare_with do
+          debit = Debit.new
+          instance_exec(debit, &block)
+
+          entries << debit
+        end
+      end
+
+      def double_entry(&block)
+        prepare_with do
+          pair = DoubleEntry.new
+          instance_exec(pair, &block)
+
+          entries << pair.entries
+        end
+      end
+    end
+  end
+end

data/lib/generalis/transaction/links.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Generalis
+  class Transaction < ActiveRecord::Base
+    module Links
+      # @param name [Symbol]
+      # @param class_name [String]
+      # @return [void]
+      def has_one_linked(name, class_name: name.to_s.classify) # rubocop:disable Naming/PredicateName
+        has_one :"#{name}_link", -> { where(name: name) },
+                class_name: 'Generalis::Link', dependent: :destroy,
+                foreign_key: :transaction_id, inverse_of: :ledger_transaction
+
+        has_one name, through: :"#{name}_link", source: :linkable, source_type: class_name
+      end
+
+      # @param name [Symbol]
+      # @param class_name [String]
+      # @return [void]
+      def has_many_linked(name, class_name: name.to_s.singularize.classify) # rubocop:disable Naming/PredicateName
+        has_many :"#{name}_links", -> { where(name: name) },
+                 class_name: 'Generalis::Link', dependent: :destroy,
+                 foreign_key: :transaction_id, inverse_of: :ledger_transaction
+
+        has_many name, through: :"#{name}_links", source: :linkable, source_type: class_name
+      end
+    end
+  end
+end

data/lib/generalis/transaction/preparation.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Generalis
+  class Transaction < ActiveRecord::Base
+    module Preparation
+      extend ActiveSupport::Concern
+
+      class_methods do
+        def preparations
+          @preparations ||= []
+        end
+
+        def prepare_with(&block)
+          preparations << block
+        end
+      end
+
+      included do
+        define_model_callbacks :prepare
+      end
+
+      # Runs a one-time setup action for the transaction.
+      #
+      # @return [Boolean]
+      def prepare
+        return true if prepared?
+
+        @prepared = true
+
+        run_callbacks(:prepare) do
+          self.class.preparations.each do |preparation|
+            instance_exec(&preparation)
+          end
+        end
+
+        @prepared
+      end
+
+      # @return [Boolean]
+      def prepared?
+        persisted? || @prepared
+      end
+    end
+  end
+end

data/lib/generalis/transaction.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Generalis
+  class Transaction < ActiveRecord::Base
+    autoload :DSL, 'generalis/transaction/dsl'
+    autoload :Links, 'generalis/transaction/links'
+
+    has_many :entries, dependent: :destroy, inverse_of: :ledger_transaction
+    has_many :accounts, through: :entries
+
+    has_many :links, dependent: :destroy, inverse_of: :ledger_transaction do
+      def [](name)
+        if name.is_a?(Symbol) || name.is_a?(String)
+          find_by(name: name.to_s)
+        else
+          super
+        end
+      end
+    end
+
+    validates :transaction_id, presence: true, uniqueness: { on: :create }
+    validates :entries, presence: true
+
+    validate on: :create do
+      errors.add(:base, :trial_balance_nonzero) if credit_amounts != debit_amounts
+    end
+
+    before_create do
+      # Acquire locks on all participating accounts to calculate their balance.
+      # Locks are acquired in a deterministic sequence to prevent deadlocks.
+      Account.lock_for_balance_calculation(entries.map(&:account).reject(&:new_record?))
+    end
+
+    scope :at_or_before, -> (time) { where(occurred_at: ..time) }
+
+    scope :with_account, lambda { |account|
+      entries_on_account = Entry.where(account: account)
+        .where(Entry.arel_table[:transaction_id].eq(arel_table[:id]))
+
+      where(entries_on_account.arel.exists)
+    }
+
+    scope :with_currency, lambda { |currency|
+      entries_in_currency = Entry.where(currency: currency)
+        .where(Entry.arel_table[:transaction_id].eq(arel_table[:id]))
+
+      where(entries_in_currency.arel.exists)
+    }
+
+    scope :imbalanced, lambda {
+      subquery = joins(:entries).group(:id, Entry.arel_table[:currency]).having(
+        (Entry.arel_table[:amount_cents] * Entry.arel_table[:coefficient]).sum.not_eq(0)
+      )
+
+      where(id: subquery.select(:id))
+    }
+
+    # @param attributes [Hash]
+    # @return [void]
+    def add_credit(attributes)
+      raise 'Cannot modify persisted transactions' if persisted?
+
+      entries << Credit.new(attributes)
+    end
+
+    # @param attributes [Hash]
+    # @return [void]
+    def add_debit(attributes)
+      raise 'Cannot modify persisted transactions' if persisted?
+
+      entries << Debit.new(attributes)
+    end
+
+    # @param credit_attributes [Hash]
+    # @param debit_attributes [Hash]
+    # @return [void]
+    def add_double_entry(credit_attributes, debit_attributes)
+      pair_id = SecureRandom.uuid
+
+      add_credit(credit_attributes.merge(pair_id: pair_id))
+      add_debit(debit_attributes.merge(pair_id: pair_id))
+    end
+
+    # @param name [Symbol, String]
+    # @param record [ActiveRecord::Base]
+    # @return [void]
+    def add_link(name, record)
+      links << Link.new(name: name, linkable: record)
+    end
+
+    # @return [Hash{String => Money}]
+    def credit_amounts
+      entries.select(&:credit?).group_by(&:currency).transform_values { |entries| entries.sum(&:amount) }
+    end
+
+    # @return [Hash{String => Money}]
+    def debit_amounts
+      entries.select(&:debit?).group_by(&:currency).transform_values { |entries| entries.sum(&:amount) }
+    end
+
+    # Checks whether the transaction is would have any affect on account balances.
+    # A no-op transaction is one that has no entries with non-zero amounts.
+    #
+    # @return [Boolean]
+    def no_op?
+      entries.all?(&:no_op?)
+    end
+  end
+end

data/lib/generalis/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Generalis
+  VERSION = '0.1.0'
+end