paper_trail-human 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f7c20298a4e2c9c68d4fe4b9a4e403b571fe3590d8970b32fd9cf20a8a902df9
-  data.tar.gz: 7f0e47633690bed45da988a5ff96f26cb9c83e61635710c27e15923da25322ce
+  metadata.gz: 4dea24fd23784bda5b3b0f6d704f5f3a53a2ab00c8ed8500fe69a1b432eb3f47
+  data.tar.gz: 6c074d6f13efd43f93e1c201e36d9310420095c516980bc80c74dc6116551105
 SHA512:
-  metadata.gz: faa5dd4c0f7d9b3598656b603225bab94fbcabe1e3fdc2a997a70e4357bfcf040508aa1c332dd0b13ca64b3ee8f6869f30df4a2e2a6edfc49e6607d602aa32e2
-  data.tar.gz: 319ccffdef16b6a533e7ec47ba422c2cc14d5a35dd75e8127064b0b5d523df15f682b269df89b8319cfe376722dbd0b3dec5b65b9bbb95f48e12cabbf15ddad8
+  metadata.gz: bf9745f8aba245105b94e41f5739ec4358d657311d7cc9b5527db3353ff1e217243955f3f033cd576f98fd0d8fa0a6079f927496f101a4be31813bc734ac75bd
+  data.tar.gz: e5fb5fc24f36be842103d727af163f64545c0208229178dd7bc93f2559b09022d5177cffb4c82e448aed78a21a5564a6ff79376875184c9501b298685ff37e37

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## [0.4.0] - 2026-05-31
+
+### Added
+- Custom resolver registration via `config.register_resolver(:type, MyResolver)`
+- Custom formatter registration via `config.register_formatter(:type, MyFormatter)`
+- Lazy loading of adapters with `autoload` (faster boot for apps using few resolvers)
+
+### Changed
+- Extracted `Adapters::Resolvers` and `Adapters::Formatters` into autoload modules
+- `FORMATTERS` constant uses string references for deferred loading
+
 ## [0.3.1] - 2026-05-31
 
 ### Fixed

data/lib/paper_trail/human/adapters/formatters.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module PaperTrail
+  module Human
+    module Adapters
+      module Formatters
+        autoload :Text, 'paper_trail/human/adapters/formatters/text'
+        autoload :Markdown, 'paper_trail/human/adapters/formatters/markdown'
+        autoload :Html, 'paper_trail/human/adapters/formatters/html'
+      end
+    end
+  end
+end

data/lib/paper_trail/human/adapters/resolvers/number.rb

@@ -45,7 +45,7 @@ module PaperTrail
           end
 
           def format_currency(num)
-            @unit ? "#{@unit} #{format_number(num)}" : format_number(num)
+            "#{@unit} #{format_number(num)}"
           end
 
           def format_percentage(num)

data/lib/paper_trail/human/adapters/resolvers.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module PaperTrail
+  module Human
+    module Adapters
+      module Resolvers
+        autoload :Relation, 'paper_trail/human/adapters/resolvers/relation'
+        autoload :Enum, 'paper_trail/human/adapters/resolvers/enum'
+        autoload :Boolean, 'paper_trail/human/adapters/resolvers/boolean'
+        autoload :Custom, 'paper_trail/human/adapters/resolvers/custom'
+        autoload :Text, 'paper_trail/human/adapters/resolvers/text'
+        autoload :Date, 'paper_trail/human/adapters/resolvers/date'
+        autoload :Number, 'paper_trail/human/adapters/resolvers/number'
+      end
+    end
+  end
+end

data/lib/paper_trail/human/configuration.rb

@@ -7,7 +7,7 @@ module PaperTrail
 
       attr_accessor :whodunnit_resolver, :extend_version_model, :field_name_resolver,
                     :translate_events, :after_format
-      attr_reader :ignored_fields
+      attr_reader :ignored_fields, :custom_resolvers, :custom_formatters
 
       def initialize
         @model_configs = {}
@@ -17,6 +17,8 @@ module PaperTrail
         @translate_events = false
         @extend_version_model = false
         @after_format = nil
+        @custom_resolvers = {}
+        @custom_formatters = {}
         @mutex = Mutex.new
       end
 
@@ -30,6 +32,14 @@ module PaperTrail
         @mutex.synchronize { @model_configs[model_name.to_s] = model_config.freeze }
       end
 
+      def register_resolver(type, klass)
+        @mutex.synchronize { @custom_resolvers[type.to_sym] = klass }
+      end
+
+      def register_formatter(type, klass)
+        @mutex.synchronize { @custom_formatters[type.to_sym] = klass }
+      end
+
       def config_for(model_name)
         @model_configs[model_name.to_s]
       end

data/lib/paper_trail/human/core/batch_presenter.rb

@@ -7,45 +7,30 @@ module PaperTrail
         def initialize(configuration)
           @configuration = configuration
           @change_extractor = ChangeExtractor.new
-          @item_name_loader = ItemNameLoader.new(configuration)
-          @relation_loader = RelationLoader.new(configuration)
         end
 
         def call(versions, only: nil, except: nil)
           versions_data = versions.map { |v| [v, @change_extractor.call(v)] }
-          preloaded = @relation_loader.preload(versions_data)
-          item_names = @item_name_loader.preload(versions)
+          preloaded = preload_relations(versions_data)
 
           versions_data.map do |version, changes|
-            format_version(version, changes, preloaded, item_names, only: only, except: except)
+            format_version(version, changes, preloaded, only: only, except: except)
           end
         end
 
         private
 
-        # rubocop:disable Metrics/ParameterLists
-        def format_version(version, changes, preloaded, item_names, only: nil, except: nil)
-          # rubocop:enable Metrics/ParameterLists
-          formatter = build_formatter(version, preloaded)
-          result = base_result(version, changes, formatter, only: only, except: except)
-
-          item_name = @item_name_loader.resolve(version, item_names)
-          result[:item_name] = item_name if item_name
-
-          apply_after_format(result, version)
-        end
-
-        def build_formatter(version, preloaded)
+        def format_version(version, changes, preloaded, only: nil, except: nil)
           model_config = @configuration.config_for(version.item_type)
-          FieldFormatter.new(
-            model_config, version.item_type,
+          formatter = FieldFormatter.new(
+            model_config,
+            version.item_type,
             field_name_resolver: @configuration.field_name_resolver,
-            preloaded: preloaded
+            preloaded: preloaded,
+            custom_resolvers: @configuration.custom_resolvers
           )
-        end
 
-        def base_result(version, changes, formatter, only: nil, except: nil)
-          {
+          result = {
             user: @configuration.resolve_whodunnit(version.whodunnit),
             event: EventTranslator.call(version.event, translate: @configuration.translate_events),
             model: version.item_type,
@@ -53,6 +38,11 @@ module PaperTrail
             created_at: version.created_at,
             fields: build_fields(changes, formatter, version.event, only: only, except: except)
           }
+
+          item_name = @configuration.resolve_item_name(version)
+          result[:item_name] = item_name if item_name
+
+          apply_after_format(result, version)
         end
 
         def build_fields(changes, formatter, event, only: nil, except: nil)
@@ -65,6 +55,7 @@ module PaperTrail
         def filter_field?(field, only, except)
           field_s = field.to_s
           return only.map(&:to_s).include?(field_s) if only
+
           return !except.map(&:to_s).include?(field_s) if except
 
           true
@@ -73,13 +64,65 @@ module PaperTrail
         def format_field(formatter, field, values, event)
           previous_value, new_value = Array(values)
           result = formatter.call(field, previous_value, new_value)
+
           case event
-          when 'create' then result.delete(:previous_value)
-          when 'destroy' then result.delete(:value)
+          when 'create'
+            result.delete(:previous_value)
+          when 'destroy'
+            result.delete(:value)
           end
+
           result
         end
 
+        def preload_relations(versions_data)
+          relation_fields = collect_relation_fields(versions_data)
+          return {} if relation_fields.empty?
+
+          relation_fields.each_with_object({}) do |(key, ids), cache|
+            class_name, attribute = key
+            cache[key] = load_records(class_name, attribute, ids)
+          end
+        end
+
+        def collect_relation_fields(versions_data)
+          result = Hash.new { |h, k| h[k] = Set.new }
+
+          versions_data.each do |version, changes|
+            collect_from_version(result, version, changes)
+          end
+
+          result
+        end
+
+        def collect_from_version(result, version, changes)
+          model_config = @configuration.config_for(version.item_type)
+          return unless model_config
+
+          changes.each do |field, values|
+            field_cfg = model_config.fields[field.to_s]
+            next unless field_cfg && field_cfg[:type] == :relation
+
+            key = relation_key(field_cfg)
+            Array(values).compact.each { |v| result[key].add(v) }
+          end
+        end
+
+        def relation_key(field_cfg)
+          class_name = field_cfg[:options][:class_name] || field_cfg[:options][:class].to_s
+          attribute = field_cfg[:options][:attribute] || :name
+          [class_name, attribute]
+        end
+
+        def load_records(class_name, attribute, ids)
+          klass = Object.const_get(class_name)
+          klass.where(id: ids.to_a).to_h do |record|
+            [record.id, record.public_send(attribute)]
+          end
+        rescue NameError
+          {}
+        end
+
         def apply_after_format(result, version)
           return result unless @configuration.after_format
 

data/lib/paper_trail/human/core/field_formatter.rb

@@ -14,11 +14,12 @@ module PaperTrail
           number: 'PaperTrail::Human::Adapters::Resolvers::Number'
         }.freeze
 
-        def initialize(model_config, item_type, field_name_resolver: nil, preloaded: nil)
+        def initialize(model_config, item_type, field_name_resolver: nil, preloaded: nil, custom_resolvers: {})
           @model_config = model_config
           @item_type = item_type
           @field_name_resolver = field_name_resolver
           @preloaded = preloaded || {}
+          @custom_resolvers = custom_resolvers
         end
 
         def call(field_name, previous_value, new_value)
@@ -43,16 +44,23 @@ module PaperTrail
         def build_resolver(config, field_name = nil)
           return nil unless config
 
-          class_name = RESOLVER_MAP[config[:type]]
-          raise Error, "Unknown resolver type: #{config[:type]}" unless class_name
+          klass = resolve_class(config[:type])
+          raise Error, "Unknown resolver type: #{config[:type]}" unless klass
 
-          klass = Object.const_get(class_name)
           opts = config[:options]
           opts = opts.merge(cache: relation_cache(config)) if config[:type] == :relation
           opts = opts.merge(field: field_name) if config[:type] == :enum && opts[:from_model]
           klass.new(**opts)
         end
 
+        def resolve_class(type)
+          if @custom_resolvers.key?(type)
+            @custom_resolvers[type]
+          elsif RESOLVER_MAP.key?(type)
+            Object.const_get(RESOLVER_MAP[type])
+          end
+        end
+
         def relation_cache(config)
           class_name = config[:options][:class_name] || config[:options][:class].to_s
           attribute = config[:options][:attribute] || :name

data/lib/paper_trail/human/core/presenter.rb

@@ -11,12 +11,7 @@ module PaperTrail
 
         def call(version, only: nil, except: nil)
           changes = @change_extractor.call(version)
-          model_config = @configuration.config_for(version.item_type)
-          formatter = FieldFormatter.new(
-            model_config,
-            version.item_type,
-            field_name_resolver: @configuration.field_name_resolver
-          )
+          formatter = build_formatter(version)
 
           result = {
             user: @configuration.resolve_whodunnit(version.whodunnit),
@@ -35,6 +30,15 @@ module PaperTrail
 
         private
 
+        def build_formatter(version)
+          model_config = @configuration.config_for(version.item_type)
+          FieldFormatter.new(
+            model_config, version.item_type,
+            field_name_resolver: @configuration.field_name_resolver,
+            custom_resolvers: @configuration.custom_resolvers
+          )
+        end
+
         def build_fields(changes, formatter, event, only: nil, except: nil)
           changes
             .reject { |field, _| @configuration.ignored_fields.include?(field.to_s) }

data/lib/paper_trail/human/version.rb

@@ -2,6 +2,6 @@
 
 module PaperTrail
   module Human
-    VERSION = '0.3.1'
+    VERSION = '0.4.0'
   end
 end

data/lib/paper_trail/human.rb

@@ -7,20 +7,10 @@ require_relative 'human/core/field_formatter'
 require_relative 'human/core/event_translator'
 require_relative 'human/core/presenter'
 require_relative 'human/core/batch_presenter'
-require_relative 'human/core/item_name_loader'
-require_relative 'human/core/relation_loader'
 require_relative 'human/core/timeline'
 require_relative 'human/ports/resolver'
-require_relative 'human/adapters/resolvers/relation'
-require_relative 'human/adapters/resolvers/enum'
-require_relative 'human/adapters/resolvers/boolean'
-require_relative 'human/adapters/resolvers/custom'
-require_relative 'human/adapters/resolvers/text'
-require_relative 'human/adapters/resolvers/date'
-require_relative 'human/adapters/resolvers/number'
-require_relative 'human/adapters/formatters/text'
-require_relative 'human/adapters/formatters/markdown'
-require_relative 'human/adapters/formatters/html'
+require_relative 'human/adapters/resolvers'
+require_relative 'human/adapters/formatters'
 
 module PaperTrail
   module Human
@@ -30,9 +20,9 @@ module PaperTrail
     private_constant :MUTEX
 
     FORMATTERS = {
-      text: Adapters::Formatters::Text,
-      markdown: Adapters::Formatters::Markdown,
-      html: Adapters::Formatters::Html
+      text: 'PaperTrail::Human::Adapters::Formatters::Text',
+      markdown: 'PaperTrail::Human::Adapters::Formatters::Markdown',
+      html: 'PaperTrail::Human::Adapters::Formatters::Html'
     }.freeze
     private_constant :FORMATTERS
 
@@ -56,11 +46,7 @@ module PaperTrail
 
       def format_collection(versions, only: nil, except: nil, as: nil)
         results = Core::BatchPresenter.new(configuration).call(versions, only: only, except: except)
-        return results unless as
-
-        formatted = results.map { |r| formatter(as).call(r) }
-        separator = as.to_sym == :html ? "\n" : "\n\n"
-        formatted.join(separator)
+        as ? results.map { |r| formatter(as).call(r) } : results
       end
 
       def timeline(versions, group_by: :day, only: nil, except: nil)
@@ -70,9 +56,12 @@ module PaperTrail
       private
 
       def formatter(type)
-        klass = FORMATTERS[type.to_sym]
-        raise Error, "Unknown format: #{type}. Available: #{FORMATTERS.keys.join(', ')}" unless klass
+        sym = type.to_sym
+        klass = configuration.custom_formatters[sym] || FORMATTERS[sym]
+        available = (FORMATTERS.keys + configuration.custom_formatters.keys).join(', ')
+        raise Error, "Unknown format: #{type}. Available: #{available}" unless klass
 
+        klass = Object.const_get(klass) if klass.is_a?(String)
         klass.new
       end
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: paper_trail-human
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Gabriel
@@ -52,9 +52,11 @@ files:
 - lib/generators/paper_trail/human/templates/initializer.rb
 - lib/paper_trail-human.rb
 - lib/paper_trail/human.rb
+- lib/paper_trail/human/adapters/formatters.rb
 - lib/paper_trail/human/adapters/formatters/html.rb
 - lib/paper_trail/human/adapters/formatters/markdown.rb
 - lib/paper_trail/human/adapters/formatters/text.rb
+- lib/paper_trail/human/adapters/resolvers.rb
 - lib/paper_trail/human/adapters/resolvers/boolean.rb
 - lib/paper_trail/human/adapters/resolvers/custom.rb
 - lib/paper_trail/human/adapters/resolvers/date.rb