paper_trail-human 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a4ca501d7c667357906931d0e4460948d92dcd0b8595f1162b0a25d980650c72
-  data.tar.gz: 87e69c7b0461fcf423fece4f6f8f6471214861f0fd2300ad484795a3eacc19c6
+  metadata.gz: 4dea24fd23784bda5b3b0f6d704f5f3a53a2ab00c8ed8500fe69a1b432eb3f47
+  data.tar.gz: 6c074d6f13efd43f93e1c201e36d9310420095c516980bc80c74dc6116551105
 SHA512:
-  metadata.gz: d16233ba896c6f145177f3852b763aa7f8390cd12b68ae2077e2d9b7287e7cbb93d0944f940fafc77241161a5e5a0db764d160b75fde29338cc6e14143e14165
-  data.tar.gz: 342d5cdf3e9742e00bc58dab8ccfaca91b3a47e990d4dcfde4bc4b184c54e1a7f42af4830548f74bc444b2fd5ffcc8213759255950bc205049522595d9b4cdce
+  metadata.gz: bf9745f8aba245105b94e41f5739ec4358d657311d7cc9b5527db3353ff1e217243955f3f033cd576f98fd0d8fa0a6079f927496f101a4be31813bc734ac75bd
+  data.tar.gz: e5fb5fc24f36be842103d727af163f64545c0208229178dd7bc93f2559b09022d5177cffb4c82e448aed78a21a5564a6ff79376875184c9501b298685ff37e37

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 # 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
+- N+1 queries on `item_name` in `format_collection` and `timeline` (batch preloads records)
+- `Number` resolver with `format: :currency` and `unit: nil` no longer produces leading space
+- `format_collection` with `as:` option now joins entries with separators (double newline for text/markdown, newline for HTML)
+
+### Changed
+- Extracted `ItemNameLoader` and `RelationLoader` from `BatchPresenter` for better cohesion
+
 ## [0.3.0] - 2026-05-30
 
 ### Added

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.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

@@ -26,7 +26,8 @@ module PaperTrail
             model_config,
             version.item_type,
             field_name_resolver: @configuration.field_name_resolver,
-            preloaded: preloaded
+            preloaded: preloaded,
+            custom_resolvers: @configuration.custom_resolvers
           )
 
           result = {

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/item_name_loader.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module PaperTrail
+  module Human
+    module Core
+      class ItemNameLoader
+        def initialize(configuration)
+          @configuration = configuration
+        end
+
+        def preload(versions)
+          grouped = group_batchable(versions)
+
+          grouped.each_with_object({}) do |(item_type, ids), cache|
+            load_names(item_type, ids, cache)
+          end
+        end
+
+        def resolve(version, cache)
+          model_config = @configuration.config_for(version.item_type)
+          return nil unless model_config&.item_name_attribute
+
+          attr = model_config.item_name_attribute
+          return attr.call(version) if attr.respond_to?(:call)
+
+          cache[[version.item_type, version.item_id]]
+        end
+
+        private
+
+        def group_batchable(versions)
+          versions.each_with_object({}) do |version, grouped|
+            model_config = @configuration.config_for(version.item_type)
+            next unless model_config&.item_name_attribute
+            next if model_config.item_name_attribute.respond_to?(:call)
+
+            (grouped[version.item_type] ||= Set.new).add(version.item_id)
+          end
+        end
+
+        def load_names(item_type, ids, cache)
+          attr = @configuration.config_for(item_type).item_name_attribute
+          klass = Object.const_get(item_type)
+          klass.where(id: ids.to_a).each do |record|
+            cache[[item_type, record.id]] = record.public_send(attr)
+          end
+        rescue NameError
+          nil
+        end
+      end
+    end
+  end
+end

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/core/relation_loader.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module PaperTrail
+  module Human
+    module Core
+      class RelationLoader
+        def initialize(configuration)
+          @configuration = configuration
+        end
+
+        def preload(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
+
+        private
+
+        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 { |record| [record.id, record.public_send(attribute)] }
+        rescue NameError
+          {}
+        end
+      end
+    end
+  end
+end

data/lib/paper_trail/human/version.rb

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

data/lib/paper_trail/human.rb

@@ -9,16 +9,8 @@ require_relative 'human/core/presenter'
 require_relative 'human/core/batch_presenter'
 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
@@ -28,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
 
@@ -57,18 +49,21 @@ module PaperTrail
         as ? results.map { |r| formatter(as).call(r) } : results
       end
 
+      def timeline(versions, group_by: :day, only: nil, except: nil)
+        Core::Timeline.new(configuration).call(versions, group_by: group_by, only: only, except: except)
+      end
+
       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
-
-      def timeline(versions, group_by: :day, only: nil, except: nil)
-        Core::Timeline.new(configuration).call(versions, group_by: group_by, only: only, except: except)
-      end
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: paper_trail-human
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  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
@@ -67,7 +69,9 @@ files:
 - lib/paper_trail/human/core/change_extractor.rb
 - lib/paper_trail/human/core/event_translator.rb
 - lib/paper_trail/human/core/field_formatter.rb
+- lib/paper_trail/human/core/item_name_loader.rb
 - lib/paper_trail/human/core/presenter.rb
+- lib/paper_trail/human/core/relation_loader.rb
 - lib/paper_trail/human/core/timeline.rb
 - lib/paper_trail/human/ports/resolver.rb
 - lib/paper_trail/human/railtie.rb