ledger_accountable 0.0.10.pre → 0.1.4.pre

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5185deffdccca1762bd55e3bf11b7ec79b9201607fa2d6bc8a4602283b39f9bf
-  data.tar.gz: 2fa716533f24eca0310aeafb8fb8aac0a569c06073e26f71580d1db5139c7940
+  metadata.gz: f94845e66b1f81f8b7897908a9c88fe5c12d63d91882045e721ade66851dca5b
+  data.tar.gz: 32851e373387e7da3ad970b810cd4b445f9a033e72bf77883698939e1c2caeea
 SHA512:
-  metadata.gz: 60cd04d24b22c787305f3f323b028633120acb7aeae914621c2b6485caa31613c48ae64f2e700e18e717407a277a2cf3d1e4afd1478a2c7a4f775e479787715e
-  data.tar.gz: 89952404a101ca76e8bf6563ea8a41eb22df5fb30967f9a2924b4865ec9d6d328b9f14dad6d85179991e404b6518395584de3a6c6a848cd95cdff93d64a3ea0b
+  metadata.gz: c652558bbafd396ed31cf47c2f354c16d986b9f6a087f09c8601e7d93e12772feb850f103b2e265abf51184bba80e5c6af19089f71b431ea438cea1054883da2
+  data.tar.gz: 2b9395f031cddb37a6392608f77c038382b8f6d45d625edebec41fb7248302a7d5d2ef1a6b8919b5bc58ea3708fcdda6111337fa9f0596b734bacaa445f4abf0

data/README.md

@@ -26,17 +26,37 @@ $ rails generate ledger_accountable
 
 ## Usage
 
-Include `LedgerAccountable` in any model to enable ledger accounting functionality.
+### `LedgerAccountable::LedgerOwner`
+
+Include **`LedgerAccountable::LedgerOwner`** in any model which maintains a ledger - that is, a model whose instances have a sum balance of debits and credits based on the values of Ledger Item associations.
 
 ```ruby
-class Order < ApplicationRecord
-  has_many :ledger_entries, as: :owner
+class Order < ActiveRecord::Base
+  include LedgerAccountable::LedgerOwner
+
   has_many :order_items, dependent: :destroy
   has_many :payments, dependent: :destroy
 end
+```
+
+This provides methods for tracking the ledger:
+
+- **`balance`** - Net sum of all ledger entries
+- **`credit_total`** - Sum of all credit entries (e.g., payments)
+- **`debit_total`** - Sum of all debit entries (e.g., charges)
+
+### `LedgerAccountable::LedgerItem`
 
-class OrderItem < ApplicationRecord
-  include LedgerAccountable
+Include `LedgerAccountable::LedgerItem` in any associated model of a `LedgerAccountable::LedgerOwner` to trigger ledger entries when:
+
+- Instances of that model are associated to the Ledger Owner
+- Instances of that model are unassociated from the Ledger Owner
+- Associated instances of that model are changed
+- Associated instances of that model are destroyed
+
+```ruby
+class OrderItem < ActiveRecord::Base
+  include LedgerAccountable::LedgerItem
 
   belongs_to :order
 
@@ -46,6 +66,7 @@ class OrderItem < ApplicationRecord
                amount: :cost,
                net_amount: :net_cost_change,
                type: :debit
+
   def cost
     quantity * unit_price
   end
@@ -57,13 +78,40 @@ class OrderItem < ApplicationRecord
   end
 end
 
-
-class Payment < ApplicationRecord
-  include LedgerAccountable
+class Payment < ActiveRecord::Base
+  include LedgerAccountable::LedgerItem
 
   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
+
+class Refund < ActiveRecord::Base
+  include LedgerAccountable::LedgerItem
+
+  belongs_to :order
+
+  # Track ledger changes on order with the amount attribute and mark it as a debit
+  track_ledger :order, amount: :amount, type: :debit
+end
 ```
+
+The track_ledger method accepts the following options:
+
+- **`amount`**: Method or attribute that determines the ledger amount (required)
+- **`type`**: :debit or :credit (defaults to :credit)
+- **`net_amount`**: Method to calculate amount changes for updates (optional)
+- **`ledger_attributes`**: Additional attributes that should trigger ledger entries when changed (optional)
+
+### Ledger Entry Types
+
+Ledger entries are automatically created in the following scenarios:
+
+- **`:addition`** - When a new item is added to a ledger
+- **`:deletion`** - When an item is removed from a ledger
+- **`:modification`** - When an item's amount changes
+
+When a LedgerItem changes owners, both a `deletion` entry for the old owner and an `addition` entry for the new owner are created in the same transaction
+
+<!-- TODO: documentation for alternate object destruction libraries: callbacks to trigger ledger removal for objects that aren't destroyed -->

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

@@ -16,6 +16,7 @@ class LedgerEntry < ActiveRecord::Base
 
   scope :debits, -> { where(transaction_type: :debit) }
   scope :credits, -> { where(transaction_type: :credit) }
+  scope :with_ledger_item_type, -> (type) { where(ledger_item_type: type) }
 
   def to_itemized_s(line_type = :line)
     I18n.t!("#{TRANSLATION_PREFIX}.#{ledger_item_type.constantize.model_name.param_key}.#{line_type}",

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

@@ -2,7 +2,7 @@ class CreateLedgerEntries < ActiveRecord::Migration[6.1]
   def change
     create_table :ledger_entries do |t|
       t.references :owner, polymorphic: true, null: false
-      t.references :ledger_item, polymorphic: true, null: false
+      t.references :ledger_item, polymorphic: true, type: :string, null: false
       t.integer :transaction_type, null: false
       t.integer :entry_type, null: false
       t.integer :amount_cents, default: 0, null: false

data/lib/ledger_accountable/ledger_item/entry_creator.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module LedgerAccountable
+  module LedgerItem
+    # Creates a single LedgerEntry.
+    class EntryCreator
+      def self.create(item:, owner:, amount:, type:, entry_type:, metadata: {})
+        LedgerEntry.create!(
+          # create! will raise if the ledger entry fails to be created,
+          # which will rollback the attempt to save the LedgerAccountable object
+          owner: owner,
+          ledger_item: item,
+          transaction_type: type,
+          entry_type: entry_type,
+          amount_cents: amount,
+          metadata: metadata
+        )
+      end
+    end
+  end
+end

data/lib/ledger_accountable/ledger_item/state_transition.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+module LedgerAccountable
+  module LedgerItem
+    # Manages ledger entry creation during model lifecycle changes.
+    # Determines which entries are needed (addition, deletion, modification) and
+    # ensures all entries are created within the same transaction as the model changes.
+    #
+    # Simplified control flow:
+    # Am I already in a ledger?
+    #   YES
+    #     am I still in that ledger?
+    #       YES
+    #         has my amount changed?
+    #           YES
+    #             => create entry with the net change
+    #           NO
+    #             => no update unless overridden
+    #       NO
+    #         => create a deletion ledger entry
+    #         do I have a new ledger?
+    #           YES
+    #             => create a new ledger entry
+    #   NO
+    #     => create a new ledger entry
+    class StateTransition
+      def self.execute(item, &block)
+        new(item).execute(&block)
+      end
+
+      def initialize(item)
+        @item = item
+      end
+
+      def execute(&block)
+        return yield unless should_record_entry?
+
+        # Compute all values that depend on object state BEFORE the save
+        ledger_entries_to_create = determine_required_entries
+        metadata = @item.build_ledger_metadata
+
+        ActiveRecord::Base.transaction do
+          with_required_save(&block)
+          # Create all necessary entries after the save
+          ledger_entries_to_create.each do |entry_params|
+            record_entry(
+              owner: entry_params[:owner],
+              amount: entry_params[:amount],
+              entry_type: entry_params[:entry_type],
+              metadata: metadata
+            )
+          end
+        end
+      end
+
+      private
+
+      def with_required_save
+        # attempt to save or destroy the object
+        commit_successful = yield
+
+        # Proceed only if the save or destroy operation was successful
+        raise ActiveRecord::Rollback if !commit_successful && LedgerItem.require_successful_entries
+      end
+
+      def should_record_entry?
+        return false unless @item.should_persist_in_ledger?
+
+        if @item.to_be_destroyed?
+          true
+        else
+          should_record_addition? || should_record_update? || should_record_removal?
+        end
+      end
+
+      def determine_required_entries
+        entries = []
+
+        if @item.to_be_destroyed?
+          entries << build_destruction_entry
+        else
+          entries << build_removal_entry if should_record_removal?
+          entries << build_addition_entry if should_record_addition?
+          entries << build_modification_entry if should_record_update?
+        end
+
+        entries
+      end
+
+      def build_destruction_entry
+        {
+          type: @item.transaction_type,
+          entry_type: :deletion,
+          owner: @item.current_owner,
+          amount: -@item.ledger_amount
+        }
+      end
+
+      def build_removal_entry
+        {
+          type: @item.transaction_type,
+          entry_type: :deletion,
+          owner: @item.previous_owner,
+          amount: -@item.ledger_amount
+        }
+      end
+
+      def build_addition_entry
+        {
+          type: @item.transaction_type,
+          entry_type: :addition,
+          owner: @item.current_owner,
+          amount: @item.ledger_amount
+        }
+      end
+
+      def build_modification_entry
+        {
+          type: @item.transaction_type,
+          entry_type: :modification,
+          owner: @item.current_owner,
+          amount: @item.net_ledger_amount
+        }
+      end
+
+      def record_entry(owner:, amount:, entry_type:, metadata:)
+        EntryCreator.create(
+          item: @item,
+          owner: owner,
+          amount: amount,
+          type: @item.transaction_type,
+          entry_type: entry_type,
+          metadata: metadata
+        )
+      rescue ActiveRecord::RecordInvalid => e
+        raise e if LedgerItem.require_successful_entries
+      end
+
+      def determine_owner
+        case determine_entry_type
+        when :deletion
+          if @item.to_be_destroyed?
+            # the item is being destroyed, so use its current owner
+            @item.current_owner
+          else
+            # the item is removed from the ledger, so use its previous owner
+            @item.previous_owner
+          end
+        else
+          @item.current_owner
+        end
+      end
+
+      def calculate_amount
+        case determine_entry_type
+        when :modification
+          @item.net_ledger_amount
+        when :deletion
+          if @item.current_owner.present?
+            -@item.ledger_amount
+          else
+            @item.net_ledger_amount
+          end
+        else
+          @item.ledger_amount
+        end
+      end
+
+      def determine_entry_type
+        if @item.to_be_destroyed?
+          :deletion
+        elsif should_record_removal?
+          :deletion
+        elsif should_record_addition?
+          :addition
+        else
+          :modification
+        end
+      end
+
+      def should_record_addition?
+        return false unless @item.current_owner.present?
+
+        !@item.entries_for_current_owner? || @item.last_entry_was?('deletion')
+      end
+
+      def should_record_removal?
+        if @item.current_owner.nil?
+          @item.entries_for_previous_owner? && !@item.last_entry_was?('deletion')
+        elsif @item.previous_owner.present? && @item.current_owner.present?
+          @item.entries_for_previous_owner? &&
+            @item.ledger_entries.where(owner: @item.previous_owner).last&.entry_type != 'deletion'
+        else
+          false
+        end
+      end
+
+      def should_record_update?
+        return false unless @item.should_persist_in_ledger?
+
+        if @item.entries_for_current_owner?
+          @item.ledger_attributes_changed? || @item.would_change_ledger_balance?
+        else
+          false
+        end
+      end
+    end
+  end
+end

data/lib/ledger_accountable/ledger_item.rb

@@ -0,0 +1,274 @@
+# frozen_string_literal: true
+
+# LedgerAccountable::LedgerItem adds ledger functionality to any model that acts as an item in a ledger.
+#
+# It supports tracking two types of ledger entries:
+# 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
+# addition/deletion/update events relative to its ledger owner.
+#
+# Specify `ledger_owner`, the owner of the ledger entries, and optionally `ledger_attributes`
+# to track specific attributes changes.
+#
+# Example:
+# ```ruby
+# 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::LedgerItem
+#
+#   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::LedgerItem
+#
+#   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
+# ```
+#
+# Note:
+#  - The `ledger_owner` association must exist in the LedgerAccountable::LedgerItem model.
+#
+module LedgerAccountable
+  module LedgerItem
+    autoload :EntryCreator, 'ledger_accountable/ledger_item/entry_creator'
+    autoload :StateTransition, 'ledger_accountable/ledger_item/state_transition'
+
+    extend ActiveSupport::Concern
+
+    class InitializationError < StandardError
+    end
+
+    class InvalidLedgerOwnerError < InitializationError
+    end
+
+    # Toggle for whether ledger entry creation should be required for updates to
+    # LedgerAccountable objects.
+    # If set to `true`, failed ledger entries will roll back all changes.
+    # Defaults to all non-production environments.
+    mattr_accessor :require_successful_entries
+    @@require_successful_entries = !Rails.env.production?
+
+    # The time at which ledger entries began.
+    # Defaults to Unix Epoch (1970-01-01 00:00:00 +0000)
+    mattr_accessor :epoch
+    @@epoch = Time.at(0)
+
+    included do
+      has_many :ledger_entries, as: :ledger_item
+
+      # around_[action] are used below to ensure that these callbacks run after model callbacks
+      # which may modify object values in a commit lifecycle
+      around_create :process_ledger_transition
+      around_update :process_ledger_transition
+      around_destroy :process_ledger_transition
+      # the owner of the ledger entries
+      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 :transaction_type
+      # attributes of the LedgerAccountable that should trigger a ledger entry when changed
+      class_attribute :ledger_attributes
+    end
+
+    class_methods do
+      # registers the model as a ledger item for ledger_owner,
+      # 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_transaction_type(options)
+        validate_and_assign_ledger_amount_attribute(options)
+        validate_net_amount_method(options)
+        validate_and_assign_ledger_attributes(options)
+      end
+
+      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 InvalidLedgerOwnerError, "LedgerAccountable::LedgerItem 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_transaction_type(options)
+        if options[:type].present?
+          raise 'LedgerAccountable type must be :debit or :credit' unless %i[debit credit].include?(options[:type])
+
+          self.transaction_type = options[:type]
+        else
+          self.transaction_type = :credit
+        end
+      end
+
+      def validate_and_assign_ledger_amount_attribute(options)
+        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]
+      end
+
+      def validate_net_amount_method(options)
+        return unless options[:net_amount].present?
+        raise 'track_ledger :net_amount must be a symbol' unless options[:net_amount].is_a?(Symbol)
+
+        self.ledger_net_amount_method = options[:net_amount]
+      end
+
+      def validate_and_assign_ledger_attributes(options)
+        # verify that provided ledger attributes are correctly formatted
+        if options[:ledger_attributes].present? && options[:ledger_attributes].any? { |attr| !attr.is_a?(Symbol) }
+          raise "LedgerAccountable attributes must be symbols. Did you mean #{options[:ledger_attributes].map do |attr|
+            ":#{attr}"
+          end.join(', ')}?"
+        end
+
+        self.ledger_attributes = options[:ledger_attributes]
+      end
+    end
+
+    # the amount to be recorded in the ledger entry on creation or deletion; typically the full amount on the
+    # LedgerAccountable object
+    def ledger_amount
+      unless respond_to?(self.class.ledger_amount_attribute)
+        raise NotImplementedError,
+              "LedgerAccountable::LedgerItem 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 * (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
+      if self.class.ledger_net_amount_method
+        net_amount_result = send(self.class.ledger_net_amount_method)
+        ledger_amount_multiplier * net_amount_result
+      else
+        unless attribute_method?(self.class.ledger_amount_attribute.to_s)
+          # if a method is provided to compute ledger_amount,
+          logger.warn "
+LedgerAccountable::LedgerItem 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 = ledger_amount_multiplier * attribute_was(self.class.ledger_amount_attribute)
+        # p 'prev:', previous_ledger_amount, 'cur:', ledger_amount
+        ledger_amount - (previous_ledger_amount || 0)
+      end
+    end
+
+    def ledger_attributes_changed?
+      # if no ledger attributes are specified, only trigger if the balance changed
+      return false if ledger_attributes.blank?
+
+      changed_attributes.keys.any? { |key| ledger_attributes.include?(key.to_sym) }
+    end
+
+    def would_change_ledger_balance?
+      net_ledger_amount != 0
+    end
+
+    def current_owner
+      send(self.class.ledger_owner)
+    end
+
+    def previous_owner
+      if current_owner.nil?
+        # if the owner was removed, get the owner of its last ledger entry
+        ledger_entries.reload.last&.owner
+      else
+        # otherwise get the owner from the last entry NOT for its current owner
+        ledger_entries.reload.where.not(owner: current_owner).last&.owner
+      end
+    end
+
+    def build_ledger_metadata
+      # can be overridden to return a hash of metadata values
+      {}
+    end
+
+    def last_entry_was?(entry_type)
+      if current_owner.present?
+        ledger_entries.reload.where(owner: current_owner).last&.entry_type == entry_type
+      elsif previous_owner.present?
+        ledger_entries.reload.where(owner: previous_owner).last&.entry_type == entry_type
+      else
+        false
+      end
+    end
+
+    # An overrideable method to determine if the object should be persisted in the ledger
+    #
+    # For example, payments should not be recorded in a ledger until they're finalized
+    # by default, a LedgerAccountable should persist in a ledger if has a ledger_owner via
+    # track_ledger
+    def should_persist_in_ledger?
+      # 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::LedgerItem model #{model_name} must include track_ledger to use ledger functionality"
+      end
+
+      self.class.ledger_owner.present? && has_current_or_previous_ledger?
+    end
+
+    def entries_for_current_owner?
+      ledger_entries.reload.where(owner: current_owner).any?
+    end
+
+    def entries_for_previous_owner?
+      ledger_entries.reload.where(owner: previous_owner).any?
+    end
+
+    def to_be_destroyed?
+      @_destroy_callback_already_called ||= false
+    end
+
+    private
+
+    def process_ledger_transition(&block)
+      StateTransition.execute(self, &block)
+    end
+
+    def ledger_amount_multiplier
+      self.class.transaction_type == :credit ? 1 : -1
+    end
+
+    def has_current_or_previous_ledger?
+      previous_owner.present? || current_owner.present?
+    end
+  end
+end

data/lib/ledger_accountable/ledger_owner.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module LedgerAccountable
+  #
+  # LedgerAccountable::LedgerOwner is intended to be included in models
+  # which act as the owner of a ledger.
+  #
+  module LedgerOwner
+    extend ActiveSupport::Concern
+
+    included do
+      has_many :ledger_entries, as: :owner
+    end
+
+    def balance
+      ledger_entries.sum(:amount_cents)
+    end
+
+    # The absolute value of the sum of the LedgerOwner's credit entries.
+    # This can be used to determine the total amount credited to the ledger -
+    # for example, its total revenue.
+    def credit_total
+      ledger_entries.credits.sum(:amount_cents).abs
+    end
+
+    # The absolute value of the sum of the LedgerOwner's debit entries.
+    # This can be used to determine the total amount owed to the ledger -
+    # for example, the aggregate value of the items sold.
+    def debit_total
+      ledger_entries.debits.sum(:amount_cents).abs
+    end
+  end
+end

data/lib/ledger_accountable/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module LedgerAccountable
-  VERSION = "0.0.10.pre".freeze
+  VERSION = '0.1.4.pre'
 end

data/lib/ledger_accountable.rb

@@ -1,387 +1,10 @@
-# 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: 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
-# addition/deletion/update events relative to its ledger owner.
-#
-# Specify `ledger_owner`, the owner of the ledger entries, and optionally `ledger_attributes`
-# to track specific attributes changes.
-#
-# Example:
-# ```ruby
-# 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
-#
-#   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
-# ```
-#
-# Note:
-#  - The `ledger_owner` association must exist in the LedgerAccountable model.
-#
 module LedgerAccountable
-  extend ActiveSupport::Concern
+  autoload :LedgerItem, 'ledger_accountable/ledger_item'
+  autoload :LedgerOwner, 'ledger_accountable/ledger_owner'
 
-  # Toggle for whether ledger entry creation should be required for updates to
-  # LedgerAccountable objects.
-  # If set to `true`, failed ledger entries will roll back all changes.
-  # Defaults to all non-production environments.
-  mattr_accessor :require_successful_entries
-  @@require_successful_entries = !Rails.env.production?
-
-  # The time at which ledger entries began.
-  # Defaults to Unix Epoch (1970-01-01 00:00:00 +0000)
-  mattr_accessor :epoch
-  @@epoch = Time.at(0)
-
-  included do
-    has_many :ledger_entries, as: :ledger_item
-
-    # around_[action] are used below to ensure that these callbacks run after model callbacks
-    # which may modify object values in a commit lifecycle
-    around_create :record_ledger_addition, if: :should_record_ledger_addition? # record a ledger entry when the LedgerAccountable is created or updated
-    around_update :record_ledger_addition, if: :should_record_ledger_addition? # record a ledger entry when the LedgerAccountable is created or updated
-    around_update :record_ledger_removal, if: :should_record_ledger_removal? # record a ledger entry when the LedgerAccountable is created or updated
-    around_update :record_ledger_update, if: :should_record_ledger_update? # record a ledger entry when the LedgerAccountable is updated
-    around_destroy :record_ledger_destruction, if: :should_persist_in_ledger? # record a ledger entry when the LedgerAccountable is destroyed
-    # the owner of the ledger entries
-    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 :transaction_type
-    # attributes of the LedgerAccountable that should trigger a ledger entry when changed
-    class_attribute :ledger_attributes
-  end
-
-  class_methods do
-    # registers the model as a ledger item for ledger_owner,
-    # 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_transaction_type(options)
-      validate_and_assign_ledger_amount_attribute(options)
-      validate_net_amount_method(options)
-      validate_and_assign_ledger_attributes(options)
-    end
-
-    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 #{model_name} must respond to the provided value for ledger_owner (#{ledger_owner})."
-      end
-
-      self.ledger_owner = ledger_owner
-    end
-
-    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.transaction_type = options[:type]
-      else
-        self.transaction_type = :credit
-      end
-    end
-
-    def validate_and_assign_ledger_amount_attribute(options)
-      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]
-    end
-
-    def validate_net_amount_method(options)
-      return unless options[:net_amount].present?
-      raise 'track_ledger :net_amount must be a symbol' unless options[:net_amount].is_a?(Symbol)
-
-      self.ledger_net_amount_method = options[:net_amount]
-    end
-
-    def validate_and_assign_ledger_attributes(options)
-      # verify that provided ledger attributes are correctly formatted
-      if options[:ledger_attributes].present? && options[:ledger_attributes].any? { |attr| !attr.is_a?(Symbol) }
-        raise "LedgerAccountable attributes must be symbols. Did you mean #{options[:ledger_attributes].map do |attr|
-                                                                              ":#{attr}"
-                                                                            end.join(', ')}?"
-      end
-
-      self.ledger_attributes = options[:ledger_attributes]
-    end
-  end
-
-  # Default way to set up LedgerAccountable. Run rails generate ledger_accountable to create
-  # a fresh initializer with all configuration values.
+  # Default way to configure LedgerAccountable. Run rails generate ledger_accountable to create
+  # or update an initializer with default configuration values.
   def self.setup
     yield self
   end
-
-  # the amount to be recorded in the ledger entry on creation or deletion; typically the full amount on the
-  # LedgerAccountable object
-  def ledger_amount
-    unless respond_to?(self.class.ledger_amount_attribute)
-      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 * (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
-    if self.class.ledger_net_amount_method
-      net_amount_result = send(self.class.ledger_net_amount_method)
-      ledger_amount_multiplier * net_amount_result
-    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 = ledger_amount_multiplier * attribute_was(self.class.ledger_amount_attribute)
-      ledger_amount - (previous_ledger_amount || 0)
-    end
-  end
-
-  private
-
-  # Am I already in a ledger?
-  #   YES
-  #     am I still in that ledger?
-  #       YES
-  #         has my amount changed?
-  #           YES
-  #             => create entry with the net change
-  #           NO
-  #             => no update unless overriden
-  #       NO
-  #         => create a deletion ledger entry
-  #         do I have a new ledger?
-  #           YES
-  #             => create a new ledger entry
-  #   NO
-  #     => create a new ledger entry
-
-  # by default, a LedgerAccountable should record a ledger entry when the ledger_attributes are changed
-  # or if the update would otherwise change the ledger balance
-  def should_record_ledger_update?
-    return false unless should_persist_in_ledger?
-
-    if ledger_entries.where(owner: current_owner).any?
-      ledger_attributes_changed? || would_change_ledger_balance?
-    else
-      false
-    end
-  end
-
-  def should_record_ledger_addition?
-    should_persist_in_ledger? && added_to_ledger?
-  end
-
-  def should_record_ledger_removal?
-    should_persist_in_ledger? && removed_from_ledger?
-  end
-
-  def ledger_attributes_changed?
-    # if no ledger attributes are specified, only trigger if the balance changed
-    return false if ledger_attributes.blank?
-
-    changed_attributes.keys.any? { |key| ledger_attributes.include?(key.to_sym) }
-  end
-
-  def removed_from_ledger?
-    if current_owner.nil?
-      # if the owner was removed, check if its has non-deletion entries for its
-      # previous owner
-      entries_for_previous_owner? && !last_entry_was?('deletion')
-    elsif previous_owner.present? && current_owner.present?
-      # if the owner has changed, check if it was removed from its last owner's ledger
-      entries_for_previous_owner? && ledger_entries.where(owner: previous_owner).last&.entry_type != 'deletion'
-    else
-      false
-    end
-  end
-
-  def added_to_ledger?
-    if current_owner.present?
-      !entries_for_current_owner? || last_entry_was?('deletion')
-    else
-      false
-    end
-  end
-
-  def would_change_ledger_balance?
-    net_ledger_amount != 0
-  end
-
-  # create an :addition ledger entry with the full ledger amount
-  def record_ledger_addition(&block)
-    metadata = build_ledger_metadata
-    owner = send(self.class.ledger_owner)
-
-    record_ledger_entry(owner, ledger_amount, :addition, metadata, &block)
-  end
-
-  # create a :deletion ledger entry with an amount dependent on its owner's presence
-  def record_ledger_removal(&block)
-    metadata = build_ledger_metadata
-    owner = previous_owner
-    # if the owner is no longer present, remove the Accountable's full amount
-    # from the ledger; otherwise, remove the net ledger amount
-    amount_to_remove = current_owner.present? ? -ledger_amount : net_ledger_amount
-
-    record_ledger_entry(owner, amount_to_remove, :deletion, metadata, &block)
-  end
-
-  # create a :deletion ledger entry with the full ledger amount
-  # varies slightly from record_ledger_removal in that:
-  #  - it always records its full negative ledger amount
-  #  - it records an entry on its current ledger owner rather than its previous owner
-  def record_ledger_destruction(&block)
-    metadata = build_ledger_metadata
-    owner = current_owner
-
-    record_ledger_entry(owner, -ledger_amount, :deletion, metadata, &block)
-  end
-
-  # create a :modification ledger entry with the net change in net_ledger_amount
-  def record_ledger_update(&block)
-    metadata = build_ledger_metadata
-    owner = current_owner
-
-    record_ledger_entry(owner, net_ledger_amount, :modification, metadata, &block)
-  end
-
-  def record_ledger_entry(owner, amount, entry_type, metadata = nil, &block)
-    ActiveRecord::Base.transaction do
-      with_required_save(&block)
-
-      if owner.present? && amount.present?
-        begin
-          LedgerEntry.create!(
-            # create! will raise if the ledger entry fails to be created,
-            # 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
-          )
-        rescue ActiveRecord::RecordInvalid => e
-          raise e if @@require_successful_entries
-        end
-      end
-    end
-  end
-
-  def with_required_save
-    commit_successful = yield # attempt to save or destroy the object
-
-    # Proceed only if the save or destroy operation was successful
-    raise ActiveRecord::Rollback if !commit_successful && @@require_successful_entries
-  end
-
-  def current_owner
-    send(self.class.ledger_owner)
-  end
-
-  def previous_owner
-    if current_owner.nil?
-      # if the owner was removed, get the owner of its last ledger entry
-      ledger_entries.last&.owner
-    else
-      # otherwise get the owner from the last entry NOT for its current owner
-      ledger_entries.where.not(owner: current_owner).last&.owner
-    end
-  end
-
-  def build_ledger_metadata
-    # can be overridden to return a hash of metadata values
-    {}
-  end
-
-  def last_entry_was?(entry_type)
-    if current_owner.present?
-      ledger_entries.where(owner: current_owner).last&.entry_type == entry_type
-    elsif previous_owner.present?
-      ledger_entries.where(owner: previous_owner).last&.entry_type == entry_type
-    else
-      false
-    end
-  end
-
-  def ledger_amount_multiplier
-    self.class.transaction_type == :credit ? 1 : -1
-  end
-
-  # An overrideable method to determine if the object should be persisted in the ledger
-  #
-  # For example, payments should not be recorded in a ledger until they're finalized
-  # by default, a LedgerAccountable should persist in a ledger if has a ledger_owner via
-  # track_ledger
-  def should_persist_in_ledger?
-    # 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 #{model_name} must include track_ledger to use ledger functionality"
-    end
-
-    self.class.ledger_owner.present?
-  end
-
-  def entries_for_current_owner?
-    ledger_entries.reload.where(owner: current_owner).any?
-  end
-
-  def entries_for_previous_owner?
-    ledger_entries.reload.where(owner: previous_owner).any?
-  end
-
-  def to_be_destroyed?
-    @_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.10.pre
+  version: 0.1.4.pre
 platform: ruby
 authors:
 - Brendan Maclean
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-10-18 00:00:00.000000000 Z
+date: 2024-12-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -52,47 +52,47 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '8'
 - !ruby/object:Gem::Dependency
-  name: rake
+  name: database_cleaner-active_record
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - '='
       - !ruby/object:Gem::Version
-        version: '12.0'
+        version: 2.1.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - '='
       - !ruby/object:Gem::Version
-        version: '12.0'
+        version: 2.1.0
 - !ruby/object:Gem::Dependency
-  name: sqlite3
+  name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.6.9
+        version: '12.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.6.9
+        version: '12.0'
 - !ruby/object:Gem::Dependency
-  name: database_cleaner-active_record
+  name: sqlite3
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 2.1.0
+        version: 1.6.9
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 2.1.0
+        version: 1.6.9
 description: LedgerAccountable is a gem for recording ledger entries to store an accounting
   history in your Rails models.
 email:
@@ -109,6 +109,10 @@ files:
 - lib/generators/ledger_accountable/templates/ledger_entry.rb
 - lib/generators/ledger_accountable/templates/migration.rb
 - lib/ledger_accountable.rb
+- lib/ledger_accountable/ledger_item.rb
+- lib/ledger_accountable/ledger_item/entry_creator.rb
+- lib/ledger_accountable/ledger_item/state_transition.rb
+- lib/ledger_accountable/ledger_owner.rb
 - lib/ledger_accountable/version.rb
 - lib/locale/en.yml
 homepage: https://github.com/bmaclean/ledger-accountable
@@ -117,6 +121,7 @@ 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/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'false'
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -125,14 +130,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.6.5
+      version: 3.0.6
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">"
     - !ruby/object:Gem::Version
       version: 1.3.1
 requirements: []
-rubygems_version: 3.1.6
+rubygems_version: 3.2.33
 signing_key: 
 specification_version: 4
 summary: Ledger accounting for Rails models