transmutation 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e34773430c58186f819264aea12092ad75e712c2c7e6142ecc8cc872f670741a
-  data.tar.gz: 21a4b0a2c8b8dae95455d47a4401536e3f99d61fa88254c717ae00edbd8fddc1
+  metadata.gz: 0dd356719d0c48951dd08d327c72b1b94b7b7ef4437c105fcbc7a22558bf4c14
+  data.tar.gz: efc9997ee8be40ce11894d7a64e570e7d53f617a3251bebb48c4f940050065be
 SHA512:
-  metadata.gz: 34b55f58bc7b23bb41e64cfe696f5852567b9afee1f2c86623b24ee606ec3e17dd4896518602937b998019ea34c92a47c89932a3fc13f4c2a3f101eef62d0882
-  data.tar.gz: e46827b2eebf91448544faa63b042e4ce082ecae26c4533b88ebe853cd00fb00c6a2b4be1b03961ad26bfebef798ad9567e0847cd1abf3deedff7e42bf5d015d
+  metadata.gz: 93784f5a82ac13bcb4dc2560a12fccdee59135e5576dad82a556f4cb5f709811b7909aaa024273e1a38c1900d0534f47abc0f3ff3410c0b3dbce215365f31b84
+  data.tar.gz: 29daa074911fb3d8f984a5088963686155939093126a467940e54bd9d836b00705bfd6c13e54f1d2ed5199c4bdff18fc4d513ec9e692102f6065726d3a9fd994

data/.rubocop.yml

@@ -1,3 +1,5 @@
+inherit_from: .rubocop_todo.yml
+
 AllCops:
   TargetRubyVersion: 3.0
   NewCops: disable

data/.rubocop_todo.yml

@@ -0,0 +1,16 @@
+# This configuration was generated by
+# `rubocop --auto-gen-config`
+# on 2024-06-05 00:21:36 UTC using RuboCop version 1.63.4.
+# The point is for the user to remove these configuration records
+# one by one as the offenses are removed from the code base.
+# Note that changes in the inspected code, or installation of new
+# versions of RuboCop, may require this file to be generated again.
+
+# Offense count: 2
+# Configuration parameters: AllowedConstants.
+Style/Documentation:
+  Exclude:
+    - 'spec/**/*'
+    - 'test/**/*'
+    - 'lib/transmutation/serialization.rb'
+    - 'lib/transmutation/serialization/rendering.rb'

data/Gemfile

@@ -15,3 +15,5 @@ gem "rubocop-rspec", require: false
 gem "simplecov"
 gem "simplecov-lcov"
 gem "undercover"
+
+gem "pry"

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    transmutation (0.1.1)
+    transmutation (0.2.0)
       zeitwerk (~> 2.6.15)
 
 GEM
@@ -9,21 +9,27 @@ GEM
   specs:
     ast (2.4.2)
     bigdecimal (3.1.7)
+    coderay (1.1.3)
     diff-lcs (1.5.1)
     docile (1.4.0)
     imagen (0.1.8)
       parser (>= 2.5, != 2.5.1.1)
     json (2.7.2)
     language_server-protocol (3.17.0.3)
+    method_source (1.1.0)
     parallel (1.24.0)
     parser (3.3.1.0)
       ast (~> 2.4.1)
       racc
+    pry (0.14.2)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
     racc (1.7.3)
     rainbow (3.1.1)
     rake (13.2.1)
     regexp_parser (2.9.0)
-    rexml (3.2.6)
+    rexml (3.2.8)
+      strscan (>= 3.0.9)
     rspec (3.13.0)
       rspec-core (~> 3.13.0)
       rspec-expectations (~> 3.13.0)
@@ -70,6 +76,7 @@ GEM
     simplecov-html (0.12.3)
     simplecov-lcov (0.8.0)
     simplecov_json_formatter (0.1.4)
+    strscan (3.1.0)
     undercover (0.5.0)
       bigdecimal
       imagen (>= 0.1.8)
@@ -83,6 +90,7 @@ PLATFORMS
   ruby
 
 DEPENDENCIES
+  pry
   rake (~> 13.0)
   rspec (~> 3.0)
   rubocop (~> 1.21)

data/lib/transmutation/class_attributes.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Transmutation
+  # @api private
+  module ClassAttributes
+    def class_attribute(
+      *names,
+      instance_accessor: true,
+      instance_reader: instance_accessor,
+      instance_writer: instance_accessor,
+      default: nil
+    )
+      class_attribute_reader(*names, instance_reader: instance_reader, default: default)
+      class_attribute_writer(*names, instance_writer: instance_writer, default: default)
+    end
+
+    def class_attribute_reader(*names, instance_reader: true, default: nil)
+      names.each do |name|
+        self.class.define_method(name) do
+          instance_variable_get("@#{name}")
+        end
+
+        define_method(name) { self.class.send(name) } if instance_reader
+
+        instance_variable_set("@#{name}", default)
+      end
+    end
+
+    def class_attribute_writer(*names, instance_writer: true, default: nil)
+      names.each do |name|
+        self.class.define_method("#{name}=") do |value|
+          instance_variable_set("@#{name}", value)
+        end
+
+        define_method("#{name}=") { |value| self.class.send("#{name}=", value) } if instance_writer
+
+        instance_variable_set("@#{name}", default)
+      end
+    end
+  end
+end

data/lib/transmutation/collection_serializer.rb

@@ -1,21 +1,27 @@
 # frozen_string_literal: true
 
 module Transmutation
-  class CollectionSerializer # rubocop:disable Style/Documentation
+  # Out-of-the-box collection serializer.
+  #
+  # This serializer will be used to serialize all collections of objects.
+  #
+  # @example Basic usage
+  #   Transmutation::CollectionSerializer.new([object, object]).to_json
+  class CollectionSerializer
     include Transmutation::Serialization
 
-    def initialize(objects, namespace: "", serializer: nil)
+    def initialize(objects, namespace: nil, serializer: nil)
       @objects = objects
       @namespace = namespace
       @serializer = serializer
     end
 
     def as_json(options = {})
-      serializers = serialize(objects, namespace: namespace, serializer: serializer)
+      objects.map { |item| serialize(item, namespace: namespace, serializer: serializer).as_json(options) }
+    end
 
-      serializers.map do |serializer|
-        serializer.as_json(options)
-      end
+    def to_json(options = {})
+      as_json(options).to_json
     end
 
     private

data/lib/transmutation/serialization/lookup/serializer_not_found.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Transmutation
+  module Serialization
+    class Lookup
+      # @api public
+      class SerializerNotFound < Transmutation::Error
+        attr_reader :object, :namespace, :name
+
+        def initialize(object, namespace: nil, name: nil)
+          @object = object
+          @namespace = namespace
+          @name = name
+
+          super [
+            "Couldn't find serializer for #{object.class.name}#{namespace.empty? ? "" : " in #{namespace}"}.",
+            "Tried looking for the following classes: #{attempted_lookups}."
+          ].join(" ")
+        end
+
+        private
+
+        def attempted_lookups
+          namespaces_chain.map { |namespace| [namespace, name].join("::") }.join(", ")
+        end
+
+        def namespaces_chain
+          @namespaces_chain ||= begin
+            namespace_parts = namespace.split("::")
+
+            namespace_parts.filter_map.with_index do |part, index|
+              [*namespace_parts[...index], part].join("::")
+            end.reverse
+          end
+        end
+      end
+    end
+  end
+end

data/lib/transmutation/serialization/lookup.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Transmutation
+  module Serialization
+    # @api private
+    class Lookup
+      def initialize(caller, namespace: nil)
+        @caller = caller
+        @namespace = namespace
+      end
+
+      # Bubbles up the namespace until we find a matching serializer.
+      #
+      # @see Transmutation::Serialization#lookup_serializer
+      #
+      # Example:
+      #
+      #   namespace: Api::V1::Admin::Detailed
+      #   serializer: Chat::User
+      #
+      #   This method will attempt to find a serializer defined in the following order:
+      #
+      #   - Api::V1::Admin::Detailed::Chat::UserSerializer
+      #   - Api::V1::Admin::Chat::UserSerializer
+      #   - Api::V1::Chat::UserSerializer
+      #   - Api::Chat::UserSerializer
+      #   - Chat::UserSerializer
+      #
+      #   Note: This never bubbles up the object's namespace, only the caller's namespace.
+      def serializer_for(object, serializer: nil)
+        return Transmutation::CollectionSerializer if object.respond_to?(:map)
+
+        serializer_name = serializer_name_for(object, serializer: serializer)
+
+        return constantize_serializer!(Object, serializer_name, object: object) if serializer_name.start_with?("::")
+
+        potential_namespaces.each do |potential_namespace|
+          return potential_namespace.const_get(serializer_name) if potential_namespace.const_defined?(serializer_name)
+        end
+
+        raise SerializerNotFound.new(@object, namespace: serializer_namespace, name: serializer_name)
+      end
+
+      # Returns the highest specificity serializer name for the given object.
+      #
+      # @param object [Object] The object to find the serializer name for.
+      #
+      # @return [String] The serializer name.
+      def serializer_name_for(object, serializer: nil)
+        return "::Transmutation::CollectionSerializer" if object.respond_to?(:map)
+
+        "#{serializer&.delete_suffix("Serializer") || object.class.name}Serializer"
+      end
+
+      private
+
+      def potential_namespaces
+        @potential_namespaces ||= begin
+          namespace_parts = serializer_namespace.split("::")
+
+          namespace_parts.filter_map.with_index do |part, index|
+            namespace = [*namespace_parts[...index], part].join("::")
+
+            next if namespace.empty?
+
+            Object.const_get(namespace) if Object.const_defined?(namespace)
+          end.reverse
+        end
+      end
+
+      def serializer_namespace
+        return caller_namespace if @namespace.nil?
+        return @namespace       if @namespace.start_with?("::")
+
+        "#{caller_namespace}::#{@namespace}"
+      end
+
+      def caller_namespace
+        @caller_namespace ||= @caller.class.name.split("::")[...-1].join("::")
+      end
+
+      def constantize_serializer!(namespace, name, object:)
+        raise SerializerNotFound.new(object, namespace: namespace, name: name) unless namespace.const_defined?(name)
+
+        namespace.const_get(name)
+      end
+    end
+  end
+end

data/lib/transmutation/serialization/rendering.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Transmutation
+  module Serialization
+    module Rendering
+      def render(json: nil, serialize: true, **args)
+        return super(**args) unless json
+        return super(json: json, **args) unless serialize
+
+        super(**args, json: serialize(json))
+      end
+    end
+  end
+end

data/lib/transmutation/serialization.rb

@@ -1,123 +1,35 @@
 # frozen_string_literal: true
 
-module Transmutation # rubocop:disable Style/Documentation
-  using Transmutation::StringRefinements
-
-  module Serialization # rubocop:disable Style/Documentation
-    def self.included(base)
-      caller_class = (base.instance_of?(Class) ? base.to_s : self.class.to_s)
-      caller_namespace = caller_class.include?("::") ? caller_class.split("::").first : ""
-      base.class_eval do
-        @caller_namespace = caller_namespace
-      end
-    end
-
-    BY_CALLER_NAMESPACE_WITH_NAMESPACE_AND_SERIALIZER = lambda do |caller, _resource_class, namespace:, serializer:|
-      caller_namespace = namespace.to_s.include?("::") ? "" : get_caller_namespace(caller.class)
-
-      converted_namespace = convert_namespace(namespace)
-
-      converted_serializer = convert_serializer(serializer)
-
-      serializer_name = serializer_from_resource_name(converted_serializer)
-
-      "#{caller_namespace}::#{converted_namespace}::#{serializer_name}"
-    end
-
-    BY_RESOURCE_CALLER_NAMESPACE_WITH_NAMESPACE = lambda do |caller, resource_class, namespace:, **_|
-      caller_namespace = namespace.to_s.include?("::") ? "" : get_caller_namespace(caller.class)
-
-      converted_namespace = convert_namespace(namespace)
-
-      serializer_name = serializer_from_resource_name(resource_class)
-
-      "#{caller_namespace}::#{converted_namespace}::#{serializer_name}"
-    end
-
-    BY_CALLER_NAMESPACE_WITH_SERIALIZER = lambda do |caller, _resource_class, serializer:, **_|
-      caller_namespace = get_caller_namespace(caller.class)
-
-      converted_serializer = convert_serializer(serializer)
-
-      serializer_name = serializer_from_resource_name(converted_serializer)
-
-      "#{caller_namespace}::#{serializer_name}"
-    end
-
-    BY_RESOURCE_CALLER_NAMESPACE = lambda do |caller, resource_class, **_|
-      caller_namespace = get_caller_namespace(caller.class)
-
-      serializer_name = serializer_from_resource_name(resource_class)
-
-      "#{caller_namespace}::#{serializer_name}"
-    end
-
-    BY_RESOURCE = lambda do |_caller, resource_class, **_|
-      serializer_name = serializer_from_resource_name(resource_class)
-
-      "::#{serializer_name}"
-    end
-
-    LOOKUP_STRATEGIES = [
-      BY_CALLER_NAMESPACE_WITH_NAMESPACE_AND_SERIALIZER,
-      BY_RESOURCE_CALLER_NAMESPACE_WITH_NAMESPACE,
-      BY_CALLER_NAMESPACE_WITH_SERIALIZER,
-      BY_RESOURCE_CALLER_NAMESPACE,
-      BY_RESOURCE
-    ].freeze
-
-    def lookup_serializer(object, namespace: "", serializer: nil)
-      lookup_serializer!(object, namespace: namespace, serializer: serializer)
-    rescue NameError
-      nil
-    end
-
-    def render(**args)
-      return super(**args) unless args[:json]
-      return super(**args) if args[:serialize] == false
-
-      super(**args, json: serialize(args[:json]))
-    end
-
-    def lookup_serializer!(object, namespace: "", serializer: nil)
-      LOOKUP_STRATEGIES.each do |strategy|
-        return Object.const_get(strategy.call(self, object.class, namespace: namespace, serializer: serializer))
-      rescue NameError
-        next
-      end
-
-      raise NameError, "Serializer not found for #{object.class}"
-    end
-
-    def serialize(object, namespace: "", serializer: nil)
-      unless object.respond_to?(:map)
-        return lookup_serializer!(object, namespace: namespace,
-                                          serializer: serializer).new(object)
-      end
-
-      object.map do |entry_object|
-        lookup_serializer!(entry_object, namespace: namespace, serializer: serializer).new(entry_object)
-      end
-    end
-
-    module_function
-
-    def get_caller_namespace(base)
-      base.class_eval do
-        @caller_namespace
-      end
-    end
-
-    def convert_namespace(namespace)
-      namespace.to_s.camelcase
-    end
-
-    def convert_serializer(serializer)
-      serializer.to_s.camelcase.gsub("Serializer", "")
-    end
-
-    def serializer_from_resource_name(name)
-      "#{name}Serializer"
+module Transmutation
+  module Serialization
+    # Serialize a given object with the looked up serializer.
+    #
+    #
+    # @param object [Object] The object to serialize.
+    # @param namespace [String, Symbol, Module] The namespace to lookup the serializer in.
+    # @param serializer [String, Symbol, Class] The serializer to use.
+    #
+    # @return [Transmutation::Serializer] The serialized object. This will respond to `#as_json` and `#to_json`.
+    def serialize(object, namespace: nil, serializer: nil)
+      lookup_serializer(object, namespace: namespace, serializer: serializer).new(object)
+    end
+
+    # Lookup the serializer for the given object.
+    #
+    # This calls {Transmutation::Serialization::Lookup#serializer_for} to find the serializer for the given object.
+    #
+    # @param object [Object] The object to lookup the serializer for.
+    # @param namespace [String, Symbol, Module] The namespace to lookup the serializer in.
+    # @param serializer [String, Symbol, Class] The serializer to use.
+    #
+    # @return [Class<Transmutation::Serializer>] The serializer for the given object.
+    #
+    def lookup_serializer(object, namespace: nil, serializer: nil)
+      Lookup.new(self, namespace: namespace).serializer_for(object, serializer: serializer)
+    end
+
+    private_class_method def self.included(base)
+      base.include(Rendering) if base.respond_to?(:render)
     end
   end
 end

data/lib/transmutation/serializer.rb

@@ -1,7 +1,19 @@
 # frozen_string_literal: true
 
 module Transmutation
-  class Serializer # rubocop:disable Style/Documentation
+  # Base class for your serializers.
+  #
+  # @example Basic usage
+  #   class UserSerializer < Transmutation::Serializer
+  #     attributes :first_name, :last_name
+  #
+  #     attribute :full_name do
+  #       "#{object.first_name} #{object.last_name}".strip
+  #     end
+  #   end
+  class Serializer
+    extend ClassAttributes
+
     def initialize(object)
       @object = object
     end
@@ -11,31 +23,52 @@ module Transmutation
     end
 
     def as_json(_options = {})
-      _attributes.each_with_object({}) do |(attr_name, attr_options), hash|
+      attributes_config.each_with_object({}) do |(attr_name, attr_options), hash|
         hash[attr_name.to_s] = attr_options[:block] ? instance_exec(&attr_options[:block]) : object.send(attr_name)
       end
     end
 
-    def self.attribute(attr_name, &block)
-      _attributes[attr_name] = { block: block }
+    # Define an attribute to be serialized
+    #
+    # @param attribute_name [Symbol] The name of the attribute to serialize
+    # @param block [Proc] The block to call to get the value of the attribute.
+    #   The block is called in the context of the serializer instance.
+    #
+    # @example
+    #   class UserSerializer < Transmutation::Serializer
+    #     attribute :first_name
+    #
+    #     attribute :full_name do
+    #       "#{object.first_name} #{object.last_name}".strip
+    #     end
+    #   end
+    def self.attribute(attribute_name, &block)
+      attributes_config[attribute_name] = { block: block }
     end
 
-    def self.attributes(*attr_name)
-      attr_name.each do |name|
-        attribute(name)
+    # Shorthand for defining multiple attributes
+    #
+    # @param attribute_names [Array<Symbol>] The names of the attributes to serialize
+    #
+    # @example
+    #   class UserSerializer < Transmutation::Serializer
+    #     attributes :first_name, :last_name
+    #   end
+    def self.attributes(*attribute_names)
+      attribute_names.each do |attr_name|
+        attribute(attr_name)
       end
     end
 
-    def self._attributes
-      @@attributes ||= {} # rubocop:disable Style/ClassVars
-    end
-
-    def _attributes
-      self.class._attributes
-    end
-
     private
 
+    class_attribute :attributes_config, instance_writer: false, default: {}
+
     attr_reader :object
+
+    private_class_method def self.inherited(subclass)
+      super
+      subclass.attributes_config = attributes_config.dup
+    end
   end
 end

data/lib/transmutation/version.rb

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

data/lib/transmutation.rb

@@ -4,6 +4,43 @@ require "zeitwerk"
 loader = Zeitwerk::Loader.for_gem
 loader.setup
 
+# A performant and expressive solution for serializing Ruby objects into JSON, with a touch of opinionated "magic" ✨.
+#
+# @example Basic usage
+#   # Define a data class.
+#   class User
+#     attr_reader :name, :email
+#
+#     def initialize(name:, email:)
+#       @name = name
+#       @email = email
+#     end
+#   end
+#
+#   # Define a serializer.
+#   class UserSerializer < Transmutation::Serializer
+#     attribute :name
+#   end
+#
+#   # Create an instance of the data class.
+#   user = User.new(name: "John", email: "john@example.com")
+#
+#   # Serialize the data class instance.
+#   UserSerializer.new(user).to_json # => "{\"name\":\"John\"}"
+#
+# @example Within a Rails controller
+#   class UsersController < ApplicationController
+#     include Transmutation::Serialization
+#
+#     def show
+#       user = User.find(params[:id])
+#
+#       # Automatically lookup the UserSerializer
+#       # Serialize the data class instance using the UserSerializer
+#       # Render the result as JSON to the client
+#       render json: user # => "{\"name\":\"John\"}"
+#     end
+#   end
 module Transmutation
   class Error < StandardError; end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: transmutation
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - nitemaeric
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-05-30 00:00:00.000000000 Z
+date: 2024-06-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: zeitwerk
@@ -35,6 +35,7 @@ extra_rdoc_files: []
 files:
 - ".rspec"
 - ".rubocop.yml"
+- ".rubocop_todo.yml"
 - ".ruby-version"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
@@ -44,10 +45,13 @@ files:
 - README.md
 - Rakefile
 - lib/transmutation.rb
+- lib/transmutation/class_attributes.rb
 - lib/transmutation/collection_serializer.rb
 - lib/transmutation/serialization.rb
+- lib/transmutation/serialization/lookup.rb
+- lib/transmutation/serialization/lookup/serializer_not_found.rb
+- lib/transmutation/serialization/rendering.rb
 - lib/transmutation/serializer.rb
-- lib/transmutation/string_refinements.rb
 - lib/transmutation/version.rb
 - sig/transmutation.rbs
 homepage: https://github.com/spellbook-technology/transmutation

data/lib/transmutation/string_refinements.rb

@@ -1,37 +0,0 @@
-# frozen_string_literal: true
-
-module Transmutation
-  module StringRefinements # rubocop:disable Style/Documentation
-    DELIMITERS = %r{[a-z][A-Z]|\s*-\s*|\s*/\s*|\s*:+\s*|\s*_\s*|\s+}
-
-    refine String do
-      def camelcase
-        return capitalize unless match? DELIMITERS
-
-        split(%r{\s*-\s*|\s*/\s*|\s*:+\s*}).then { |parts| combine parts, :capitalize, "::" }
-                                           .then { |text| text.split(/\s*_\s*|\s+/) }
-                                           .then { |parts| combine parts, :capitalize }
-      end
-
-      def first(maximum = 0)
-        return self if empty?
-        return self[0] if maximum.zero?
-        return "" if maximum.negative?
-
-        self[..(maximum - 1)]
-      end
-
-      def capitalize = empty? ? self : first.upcase + self[1, size]
-
-      private
-
-      def combine(parts, method, delimiter = "")
-        parts.reduce "" do |result, part|
-          next part.public_send method if result.empty?
-
-          "#{result}#{delimiter}#{part.__send__ method}"
-        end
-      end
-    end
-  end
-end