ledger_accountable 0.0.4.pre → 0.0.6.pre

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4794daeb706e70aad2fee44a919d9e3662a90626de32c800f83f50cca233f292
-  data.tar.gz: 0b9b5328f240de5a0f981ef4e9377116270c266a0ebf902e414d7530635f3065
+  metadata.gz: b93a1058b37c11487cfe062e040ef27d0a5f903a3d5b16507183cdc43fbcfded
+  data.tar.gz: 1a865fd912346f3930c08ae7cae387fdaeb31fb29ebb511563f2f7215857f1b2
 SHA512:
-  metadata.gz: b0b64654c3e52db811b11a06c4448e7f8bc6b99aab84c9f3614dfb773f1211bbf9ca6030eca0795d979bbdbaf5f7ecb8c0611d7afede41d3106fa76f9376ef7e
-  data.tar.gz: 3e04be4d764af038e55173a9389efcec50eeded14641014a4ae50de728560eafdcfecad286fb2a2804872f3169fa54a7f44b998db632a9e1b699cb536da2892a
+  metadata.gz: bbba69d3d13c3af56660b8ed27ff5eff1ba7df2ad8a2d478bf89e6815e167c314e8521b26b13a662ced307ae868cdc63ceb237c60ea281865b1d37aa75a36a48
+  data.tar.gz: c5312763c5e588b7328a70d732a408464bb7aa8945a5c8a87e262e92b809ca7936beba3eacdf19d1c3d3621d0be53f00d752d1921857517c46438786d41b62fe

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
 

data/lib/ledger_accountable/version.rb

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

data/lib/ledger_accountable.rb

@@ -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,6 +84,8 @@ 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
     # attributes of the LedgerAccountable that should trigger a ledger entry when changed
@@ -95,7 +106,7 @@ 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
@@ -112,20 +123,17 @@ module LedgerAccountable
     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 == :debit ? 1 : -1
-    ledger_amount_multiplier * (send(self.class.ledger_amount_attribute) || 0.0)
+    ledger_amount_multiplier = self.class.ledger_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 == :debit ? 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.ledger_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
@@ -341,7 +361,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?

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ledger_accountable
 version: !ruby/object:Gem::Version
-  version: 0.0.4.pre
+  version: 0.0.6.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-14 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: