ledger_accountable 0.0.5.pre → 0.0.7.pre

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a4d8258d74e78940001a6017772df0823788a51a4d7351776e8da084ec1e1a49
-  data.tar.gz: a798ff75abf3860b1a12e62e6eb9e51d53cc7210f7cdd8da8f33aa880ff86637
+  metadata.gz: 48f3873cdd4caaaaa4c8f344219e844ee8ef97283fa00fadd21a9e8859c64f2c
+  data.tar.gz: 34cea07b1a0ddd62b0b1287431e4c2269851c9b1a437dbe8e29372699a08553c
 SHA512:
-  metadata.gz: 37f453f5fbcd0203b46fae44f3e064b725bff016f7e9da79111bd29b7a46a9c1654056be9f235c68127659f68884bba2c224bc50b8f5da309629b14ff013ee2c
-  data.tar.gz: 60a703495fe59638a5d48bd1596eaf15707d37970c050d7c2375e5267270d2502fc967809b04c3b74957115e63fe7f69d47751392cbbd1424f42d6f1d4650783
+  metadata.gz: f13c5e378ea3c65ef9f917043d027b0f8ffc17179644ad29619874f8697e767ae6a5ea22db777cc6461474c83c9ef854dc7e4cd0f24d098398ffcd7b2f6711e8
+  data.tar.gz: ef5abc2f95dbae36a2a300c5ba7d1d28f4b137f4e0e87e2159c8cc4d5abe79bf64e5c4bc78909c2f12d5d1ebf24cba3cc5e32ef89a707c1133f4e34775b812b8

data/README.md

@@ -29,11 +29,41 @@ $ rails generate ledger_accountable
 Include `LedgerAccountable` in any model to enable ledger accounting functionality.
 
 ```ruby
-class YourModel < ApplicationRecord
+class Order < ApplicationRecord
+  has_many :ledger_entries, as: :owner
+  has_many :order_items, dependent: :destroy
+  has_many :payments, dependent: :destroy
+end
+
+class OrderItem < ApplicationRecord
   include LedgerAccountable
 
-  track_ledger :ledger_owner, 
-               amount: :total,
-               type: :credit
+  belongs_to :order
+
+  # Track ledger changes on order with the cost method and provide a net_amount
+  # to dynamically compute net changes to its cost
+  track_ledger :order,
+               amount: :cost,
+               net_amount: :net_cost_change,
+               type: :debit
+  def cost
+    quantity * unit_price
+  end
+
+  private
+
+  def net_cost_change
+    cost - (quantity_was * unit_price_was)
+  end
+end
+
+
+class Payment < ApplicationRecord
+  include LedgerAccountable
+
+  belongs_to :order
+
+  # Track ledger changes on order with the amount attribute and mark it as a credit
+  track_ledger :order, amount: :amount, type: :credit
 end
 ```

data/lib/generators/ledger_accountable/templates/ledger_entry.rb

@@ -1,4 +1,4 @@
-class LedgerEntry < ApplicationRecord
+class LedgerEntry < ActiveRecord::Base
   # used for internationalization via config/locales/ledger.en.yml
   TRANSLATION_PREFIX = 'ledger'.freeze
 
@@ -6,9 +6,11 @@ class LedgerEntry < ApplicationRecord
   belongs_to :ledger_item, polymorphic: true, optional: false
 
   enum entry_type: { addition: 0, deletion: 1, modification: 2 }
+  enum transaction_type: { debit: 0, credit: 1 }
 
   store :metadata, coder: JSON
 
+  validates :transaction_type, presence: true
   validates :amount_cents, presence: true
   validates :entry_type, presence: true
 

data/lib/generators/ledger_accountable/templates/migration.rb

@@ -3,6 +3,7 @@ class CreateLedgerEntries < ActiveRecord::Migration[6.1]
     create_table :ledger_entries do |t|
       t.references :owner, polymorphic: true, null: false
       t.references :ledger_item, polymorphic: true, null: false
+      t.integer :transaction_type, null: false
       t.integer :entry_type, null: false
       t.integer :amount_cents, default: 0, null: false
       t.text :metadata

data/lib/ledger_accountable/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module LedgerAccountable
-  VERSION = "0.0.5.pre".freeze
+  VERSION = "0.0.7.pre".freeze
 end

data/lib/ledger_accountable.rb

@@ -1,8 +1,8 @@
 # LedgerAccountable adds ledger functionality to any model that acts as an item in a ledger.
 #
 # It supports tracking two types of ledger entries:
-# 1. Debits: items which decrease the ledger balance (for example, an item being sold)
-# 2. Credits: items which increase the ledger balance (for example, a payment taken)
+# 1. Debits: outgoing items which decrease the ledger balance (for example, an item being sold)
+# 2. Credits: incoming items which increase the ledger balance (for example, a payment taken)
 #
 # Usage:
 # Include LedgerAccountable in a model to have it generate ledger entries based on its
@@ -24,12 +24,21 @@
 #
 #   belongs_to :order
 #
-#   # Track ledger changes on order with the cost method and mark it as a debit
-#   track_ledger :order, amount: :cost, type: :debit
-#
+#   # Track ledger changes on order with the cost method and provide a net_amount
+#   # to dynamically compute net changes to its cost
+#   track_ledger :order,
+#                amount: :cost,
+#                net_amount: :net_cost_change,
+#                type: :debit
 #   def cost
 #     quantity * unit_price
 #   end
+# 
+#   private
+# 
+#   def net_cost_change
+#     cost - (quantity_was * unit_price_was)
+#   end
 # end
 #
 #
@@ -75,8 +84,10 @@ module LedgerAccountable
     class_attribute :ledger_owner
     # the name of the attribute or method which determines the ledger amount
     class_attribute :ledger_amount_attribute
+    # the name of the attribute or method which determines the ledger amount
+    class_attribute :ledger_net_amount_method
     # the type of ledger entry to create - debit or credit
-    class_attribute :ledger_type
+    class_attribute :transaction_type
     # attributes of the LedgerAccountable that should trigger a ledger entry when changed
     class_attribute :ledger_attributes
   end
@@ -86,7 +97,7 @@ module LedgerAccountable
     # to be updated when the provided attributes (or ledger owner) are changed
     def track_ledger(ledger_owner, options = {})
       validate_and_assign_ledger_owner(ledger_owner)
-      validate_and_assign_entry_type(options)
+      validate_and_assign_transaction_type(options)
       validate_and_assign_ledger_amount_attribute(options)
       validate_net_amount_method(options)
       validate_and_assign_ledger_attributes(options)
@@ -95,37 +106,34 @@ module LedgerAccountable
     def validate_and_assign_ledger_owner(ledger_owner)
       # verify that an instance of the LedgerAccountable model can respond to ledger_owner
       unless instance_methods.include?(ledger_owner)
-        raise "LedgerAccountable model must respond to the provided value for ledger_owner (#{ledger_owner})."
+        raise "LedgerAccountable model #{model_name} must respond to the provided value for ledger_owner (#{ledger_owner})."
       end
 
       self.ledger_owner = ledger_owner
     end
 
-    def validate_and_assign_entry_type(options)
+    def validate_and_assign_transaction_type(options)
       if options[:type].present?
         raise 'LedgerAccountable type must be :debit or :credit' unless %i[debit credit].include?(options[:type])
 
-        self.ledger_type = options[:type]
+        self.transaction_type = options[:type]
       else
-        self.ledger_type = :credit
+        self.transaction_type = :credit
       end
     end
 
     def validate_and_assign_ledger_amount_attribute(options)
-      if options[:amount].present?
-        raise 'LedgerAccountable amount must be an attribute or a method' if instance_methods.include?(options[:amount])
+      raise "track_ledger :amount is required in #{model_name}" unless options[:amount].present?
+      raise 'track_ledger :amount must be a symbol' unless options[:amount].is_a?(Symbol)
 
-        self.ledger_amount_attribute = options[:amount]
-      elsif instance_methods.include?(:amount)
-        raise "LedgerAccountable amount must be specified on #{self.class.name}"
-      end
+      self.ledger_amount_attribute = options[:amount]
     end
 
     def validate_net_amount_method(options)
-      # TODO: should we be able to provide a method to calculate the net amount?
-      return unless options[:net_amount].present? && !instance_methods.include?(options[:net_amount])
+      return unless options[:net_amount].present?
+      raise 'track_ledger :net_amount must be a symbol' unless options[:net_amount].is_a?(Symbol)
 
-      raise 'LedgerAccountable net_amount must be a method'
+      self.ledger_net_amount_method = options[:net_amount]
     end
 
     def validate_and_assign_ledger_attributes(options)
@@ -150,19 +158,31 @@ module LedgerAccountable
   # LedgerAccountable object
   def ledger_amount
     unless respond_to?(self.class.ledger_amount_attribute)
-      raise NotImplementedError, "Implement #{self.class.ledger_amount_attribute} in #{self.class.name}"
+      raise NotImplementedError,
+            "LedgerAccountable model '#{model_name}' specified #{self.class.ledger_amount_attribute} for track_ledger :amount, but does not implement #{self.class.ledger_amount_attribute}"
     end
 
-    ledger_amount_multiplier = self.class.ledger_type == :credit ? 1 : -1
-    ledger_amount_multiplier * (send(self.class.ledger_amount_attribute) || 0.0)
+    ledger_amount_multiplier = self.class.transaction_type == :credit ? 1 : -1
+    ledger_amount_multiplier * (send(self.class.ledger_amount_attribute) || 0)
   end
 
   # the amount to be recorded in the ledger entry on update; typically a net change to the dollar amount
   # stored on the LedgerAccountable object
   def net_ledger_amount
-    previous_ledger_amount = attribute_was(self.class.ledger_amount_attribute)
-    ledger_amount_multiplier = self.class.ledger_type == :credit ? 1 : -1
-    ledger_amount_multiplier * (ledger_amount - (previous_ledger_amount || 0.0))
+    if self.class.ledger_net_amount_method
+      send(self.class.ledger_net_amount_method)
+    else
+      unless attribute_method?(self.class.ledger_amount_attribute.to_s)
+        # if a method is provided to compute ledger_amount,
+        logger.warn "
+LedgerAccountable model '#{model_name}' appears to use a method for track_ledger :amount, \
+but did not provide an option for :net_amount. This can lead to unexpected ledger entry amounts when modifying #{model_name}.
+"
+      end
+      previous_ledger_amount = attribute_was(self.class.ledger_amount_attribute)
+      ledger_amount_multiplier = self.class.transaction_type == :credit ? 1 : -1
+      ledger_amount_multiplier * (ledger_amount - (previous_ledger_amount || 0))
+    end
   end
 
   private
@@ -233,7 +253,7 @@ module LedgerAccountable
   end
 
   def would_change_ledger_balance?
-    net_ledger_amount&.to_f != 0.00
+    net_ledger_amount != 0
   end
 
   # create an :addition ledger entry with the full ledger amount
@@ -285,6 +305,7 @@ module LedgerAccountable
             # which will rollback the attempt to save the LedgerAccountable object
             owner: owner,
             ledger_item: self,
+            transaction_type: self.transaction_type,
             entry_type: entry_type,
             amount_cents: amount,
             metadata: metadata
@@ -341,7 +362,7 @@ module LedgerAccountable
     # warning log if the ledger owner is not set - the LedgerAccountable model must
     # include track_ledger
     if self.class.ledger_owner.blank?
-      Rails.logger.warn "LedgerAccountable model #{self.class.name} must include track_ledger to use ledger functionality"
+      Rails.logger.warn "LedgerAccountable model #{model_name} must include track_ledger to use ledger functionality"
     end
 
     self.class.ledger_owner.present?
@@ -359,3 +380,4 @@ module LedgerAccountable
     @_destroy_callback_already_called ||= false
   end
 end
+

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ledger_accountable
 version: !ruby/object:Gem::Version
-  version: 0.0.5.pre
+  version: 0.0.7.pre
 platform: ruby
 authors:
 - Brendan Maclean
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-06-13 00:00:00.000000000 Z
+date: 2024-06-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -31,6 +31,26 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 6.0.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 6.0.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7.1'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -46,19 +66,33 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '12.0'
 - !ruby/object:Gem::Dependency
-  name: rspec
+  name: sqlite3
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - '='
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: 1.6.9
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.6.9
+- !ruby/object:Gem::Dependency
+  name: database_cleaner-active_record
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 2.1.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: 2.1.0
 description: LedgerAccountable is a gem for recording ledger entries to store an accounting
   history in your Rails models.
 email:
@@ -82,7 +116,7 @@ licenses: []
 metadata:
   homepage_uri: https://github.com/bmaclean/ledger-accountable
   source_code_uri: https://github.com/bmaclean/ledger-accountable
-  changelog_uri: https://github.com/bmaclean/ledger-accountable/CHANGELOG.md
+  changelog_uri: https://github.com/bmaclean/ledger-accountable/blob/main/CHANGELOG.md
 post_install_message: 
 rdoc_options: []
 require_paths: