transmutation 0.6.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 84b0d0743fade5189b104186c820f4e26cbe080e9d11a4897571bd8ddb385eb9
-  data.tar.gz: 6e840a6211c0d8a323f3e0881722982c5de597a3234f77546ecd2161db9f159e
+  metadata.gz: 55d12ac9787b8517a2e9cc9a5b94a21877e040d74871aa419f7cb916a56b8466
+  data.tar.gz: 5e9ba27e9d68248e735db47f1bcfdf57224a19276ad9e6d4ad3261c5721b4919
 SHA512:
-  metadata.gz: 36a016fa29e03c5bdd297bd162ad0c4d059b33ae0c723ea55bb97fd91450bcb5bf8c9f589cad9754a5cdf96ec794ed283f73530f5c6c1baad6022762458464f4
-  data.tar.gz: e34f4863e99f1f60279a3bde9635c70a483d7488bc8238137da482c52fb9df86522d5c0b6dc7ed75f7ca70fd251182e553c055b4edf5e9c6e964128efb36bdfd
+  metadata.gz: 11f50b0905cb83e1abdbe37e7e7f8a5dc9ae021277fe931497255e169f6d23e74032befa82c5014402b30daf38bd536b4f015f40dcdcee7028b6dfc18ccef645
+  data.tar.gz: 19b616c7aa56b1fce83d1089df02d5ddeeb170d0a5c7b1259fd7264b8100dc57c20f0b2497592b880dbbaa306769e4abd271aae0b14474d88d0d44c3527a1780

data/lib/transmutation/association.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Transmutation
+  # @api private
+  #
+  # An association: resolves the associated object (via a block or a method on the object) and
+  # serializes it with the looked up serializer, one level deeper. Only rendered within `max_depth`.
+  class Association < Field
+    def initialize(name, namespace: nil, serializer: nil, **options, &block)
+      super(name, **options, &block)
+
+      @namespace = namespace
+      @serializer = serializer
+    end
+
+    def render?(serializer)
+      super && serializer.depth < serializer.max_depth
+    end
+
+    def value(serializer, options)
+      target = block ? serializer.instance_exec(&block) : serializer.object.send(name)
+
+      serializer.serialize(
+        target,
+        namespace: @namespace,
+        serializer: @serializer,
+        depth: serializer.depth + 1,
+        max_depth: serializer.max_depth,
+        context: serializer.context
+      ).as_json(options)
+    end
+  end
+end

data/lib/transmutation/attribute.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Transmutation
+  # @api private
+  #
+  # A plain attribute: either a block evaluated in the serializer's context, or a method sent to the
+  # serialized object.
+  class Attribute < Field
+    def value(serializer, _options)
+      block ? serializer.instance_exec(&block) : serializer.object.send(name)
+    end
+  end
+end

data/lib/transmutation/field.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Transmutation
+  # @api private
+  #
+  # Base class for a serializable field. Encapsulates the name, the precomputed JSON key, and the
+  # optional `if:`/`unless:` rendering conditions shared by attributes and associations.
+  class Field
+    attr_reader :name, :key
+
+    def initialize(name, **options, &block)
+      @name = name
+      @key = name.to_s.freeze
+      @block = block
+      @if = options[:if]
+      @unless = options[:unless]
+    end
+
+    # Whether this field should be rendered for the given serializer instance.
+    def render?(serializer)
+      return false if @if && !evaluate(@if, serializer)
+      return false if @unless && evaluate(@unless, serializer)
+
+      true
+    end
+
+    private
+
+    attr_reader :block
+
+    # A Symbol condition is sent to the serializer; anything else (e.g. a Proc) runs in its context.
+    def evaluate(condition, serializer)
+      condition.is_a?(Symbol) ? serializer.send(condition) : serializer.instance_exec(&condition)
+    end
+  end
+end

data/lib/transmutation/serialization/rendering.rb

@@ -19,11 +19,12 @@ module Transmutation
         namespace = kwargs.delete(:namespace)
         serializer = kwargs.delete(:serializer)
         max_depth = kwargs.delete(:max_depth) || Transmutation.max_depth
+        context = kwargs.delete(:context) { self }
 
         return super(**kwargs) unless json
         return super(**kwargs, json:) unless should_serialize
 
-        super(**kwargs, json: serialize(json, namespace:, serializer:, max_depth:))
+        super(**kwargs, json: serialize(json, namespace:, serializer:, max_depth:, context:))
       end
     end
   end

data/lib/transmutation/serialization.rb

@@ -8,14 +8,14 @@ module Transmutation
     # @param namespace [String, Symbol, Module] The namespace to lookup the serializer in.
     # @param serializer [String, Symbol, Class] The serializer to use.
     # @param max_depth [Integer] The maximum depth of nested associations to serialize.
+    # @param context [Object] Arbitrary context made available to the serializer as `#context`.
+    #   Defaults to the caller (e.g. the controller), so serializers can reach `context.current_user`.
     #
     # @return [Transmutation::Serializer] The serialized object. This will respond to `#as_json` and `#to_json`.
-    def serialize(object, namespace: nil, serializer: nil, depth: 0, max_depth: Transmutation.max_depth)
-      if object.respond_to?(:map) && !object.respond_to?(:to_hash)
-        return object.map { |item| serialize(item, namespace:, serializer:, depth:, max_depth:) }
-      end
+    def serialize(object, namespace: nil, serializer: nil, depth: 0, max_depth: Transmutation.max_depth, context: self)
+      return serialize_collection(object, namespace:, serializer:, depth:, max_depth:, context:) if collection?(object)
 
-      lookup_serializer(object, namespace:, serializer:).new(object, depth:, max_depth:)
+      lookup_serializer(object, namespace:, serializer:).new(object, depth:, max_depth:, context:)
     end
 
     # Lookup the serializer for the given object.
@@ -50,6 +50,32 @@ module Transmutation
       @namespace ||= self.class.name.to_s[0, self.class.name.rindex("::") || 0]
     end
 
+    private
+
+    def collection?(object)
+      object.respond_to?(:map) && !object.respond_to?(:to_hash)
+    end
+
+    # Serialize each item in a collection.
+    #
+    # Items of the same class resolve to the same serializer, so the lookup is memoised on the item's
+    # class and reused across siblings rather than rebuilding the cache key (and hashing it) per item.
+    def serialize_collection(collection, namespace:, serializer:, depth:, max_depth:, context:)
+      serializer_class = nil
+      serialized_class = nil
+
+      collection.map do |item|
+        next serialize(item, namespace:, serializer:, depth:, max_depth:, context:) if collection?(item)
+
+        if item.class != serialized_class
+          serializer_class = lookup_serializer(item, namespace:, serializer:)
+          serialized_class = item.class
+        end
+
+        serializer_class.new(item, depth:, max_depth:, context:)
+      end
+    end
+
     private_class_method def self.included(base)
       base.include(Rendering) if base.method_defined?(:render)
     end

data/lib/transmutation/serializer.rb

@@ -20,10 +20,11 @@ module Transmutation
 
     include Transmutation::Serialization
 
-    def initialize(object, depth: 0, max_depth: 1)
+    def initialize(object, depth: 0, max_depth: 1, context: nil)
       @object = object
       @depth = depth
       @max_depth = max_depth
+      @context = context
     end
 
     def to_json(options = {})
@@ -31,12 +32,8 @@ module Transmutation
     end
 
     def as_json(options = {})
-      attributes_config.each_with_object({}) do |(attr_name, attr_options), hash|
-        if attr_options[:association]
-          hash[attr_name.to_s] = instance_exec(&attr_options[:block]).as_json(options) if @depth + 1 <= @max_depth
-        else
-          hash[attr_name.to_s] = attr_options[:block] ? instance_exec(&attr_options[:block]) : object.send(attr_name)
-        end
+      fields.each_with_object({}) do |field, hash|
+        hash[field.key] = field.value(self, options) if field.render?(self)
       end
     end
 
@@ -44,6 +41,9 @@ module Transmutation
       # Define an attribute to be serialized
       #
       # @param attribute_name [Symbol] The name of the attribute to serialize
+      # @param if [Symbol, Proc] Only include the attribute when the condition evaluates truthy
+      # @param unless [Symbol, Proc] Exclude the attribute when the condition evaluates truthy
+      #   - A Symbol is sent to the serializer instance, a Proc is evaluated in its context
       # @yield [object] The block to call to get the value of the attribute
       #   - The block is called in the context of the serializer instance
       #
@@ -54,9 +54,11 @@ module Transmutation
       #     attribute :full_name do
       #       "#{object.first_name} #{object.last_name}".strip
       #     end
+      #
+      #     attribute :email, if: :admin?
       #   end
-      def attribute(attribute_name, &block)
-        attributes_config[attribute_name] = { block: }
+      def attribute(attribute_name, **options, &block)
+        fields[attribute_name] = Attribute.new(attribute_name, **options, &block)
       end
 
       # Define an association to be serialized
@@ -66,6 +68,8 @@ module Transmutation
       # @param association_name [Symbol] The name of the association to serialize
       # @param namespace [String, Symbol, Module] The namespace to lookup the association's serializer in
       # @param serializer [String, Symbol, Class] The serializer to use for the association's serialization
+      # @param if [Symbol, Proc] Only include the association when the condition evaluates truthy
+      # @param unless [Symbol, Proc] Exclude the association when the condition evaluates truthy
       # @yield [object] The block to call to get the value of the association
       #   - The block is called in the context of the serializer instance
       #   - The return value from the block is automatically serialized
@@ -78,14 +82,8 @@ module Transmutation
       #       object.posts.archived
       #     end
       #   end
-      def association(association_name, namespace: nil, serializer: nil, &custom_block)
-        block = lambda do
-          association_instance = custom_block ? instance_exec(&custom_block) : object.send(association_name)
-
-          serialize(association_instance, namespace:, serializer:, depth: @depth + 1, max_depth: @max_depth)
-        end
-
-        attributes_config[association_name] = { block:, association: true }
+      def association(association_name, namespace: nil, serializer: nil, **options, &block)
+        fields[association_name] = Association.new(association_name, namespace:, serializer:, **options, &block)
       end
 
       # Shorthand for defining multiple attributes
@@ -121,15 +119,24 @@ module Transmutation
       alias has_many associations
     end
 
+    # @return [Object] the object being serialized
+    # @return [Integer] depth the current nesting depth
+    # @return [Integer] max_depth the maximum nesting depth to serialize
+    # @return [Object, nil] context the caller-supplied context (defaults to the caller of `serialize`)
+    attr_reader :object, :depth, :max_depth, :context
+
     private
 
-    class_attribute :attributes_config, instance_writer: false, default: {}
+    class_attribute :fields, instance_accessor: false, default: {}
 
-    attr_reader :object
+    # The fields declared on this serializer, in declaration order.
+    def fields
+      self.class.fields.values
+    end
 
     private_class_method def self.inherited(subclass)
       super
-      subclass.attributes_config = attributes_config.dup
+      subclass.fields = fields.dup
     end
   end
 end

data/lib/transmutation/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Transmutation
-  VERSION = "0.6.1"
+  VERSION = "0.7.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: transmutation
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.7.0
 platform: ruby
 authors:
 - nitemaeric
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-04-04 00:00:00.000000000 Z
+date: 2026-07-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -48,7 +48,10 @@ extensions: []
 extra_rdoc_files: []
 files:
 - lib/transmutation.rb
+- lib/transmutation/association.rb
+- lib/transmutation/attribute.rb
 - lib/transmutation/class_attributes.rb
+- lib/transmutation/field.rb
 - lib/transmutation/object_serializer.rb
 - lib/transmutation/serialization.rb
 - lib/transmutation/serialization/lookup.rb