transmutation 0.2.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3bf7696ac47e240fb64569d269e95f1cb2d369b34397a84c356469ab8975b4b5
-  data.tar.gz: 1b8a064d00de95904fa5aabbc49598cd18a5fa8432b35494f050ec5d1f24508a
+  metadata.gz: a1184809d63cb5abaad091e433a5e150579f5ca634a5522c57b7dd49c3465a3c
+  data.tar.gz: a0e2bddde883737a82369d14cd4bc75235ea1dee366c7a0234a262e29930a74c
 SHA512:
-  metadata.gz: 8f2590ad630f228024acd3b6fa229ef4fb61c2b0abf590098aeda6ebbd4d52b3f74d4fbba398977594998873dc3f758865c176bf0de947c353478b74666647d4
-  data.tar.gz: 7d1e9ff02220ec546e1226dbdd201960585668fcc4f03e702c484fd19273226ec90e550bde8ce877ffad1724f7167121db9b5902ba440b5ad96c5de42ffd2de8
+  metadata.gz: ee23262517dba8436c182542b02bd3e1b15df0225b84eae7dedb106c4d155cf6dd78db791e9a98d44c57654dcf87d9aa8110e87cde6bface0943952199f8e2a5
+  data.tar.gz: 8b23bfbd305587fde6d6fef4a714840a73e4415d27902c3169dd06561f141b127944d64f13029a37f9aaf10d88bdab5b1059554ae132fc4584c899f6ecb3148e

data/.rubocop.yml

@@ -16,4 +16,8 @@ Style/StringLiteralsInInterpolation:
 Layout/LineLength:
   Max: 120
 
+Metrics/ParameterLists:
+  Enabled: true
+  CountKeywordArgs: false
+
 require: rubocop-rspec

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    transmutation (0.2.2)
+    transmutation (0.3.0)
       zeitwerk (~> 2.6.15)
 
 GEM

data/README.md

@@ -2,19 +2,29 @@
 
 Transmutation is a Ruby gem that provides a simple way to serialize Ruby objects into JSON.
 
-It takes inspiration from the [Active Model Serializers](https://github.com/rails-api/active_model_serializers) gem, but strips away adapters.
+It also adds an opinionated way to automatically find and use serializer classes based on the object's class name and the caller's namespace - it takes inspiration from the [Active Model Serializers](https://github.com/rails-api/active_model_serializers) gem, but strips away adapters.
 
 It aims to be a performant and elegant solution for serializing Ruby objects into JSON, with a touch of opinionated "magic" :sparkles:.
 
 ## Installation
 
-Install the gem and add to the application's Gemfile by executing:
+Install the gem and add to your application's Gemfile by executing:
 
-    $ bundle add transmutation
+```bash
+bundle add transmutation
+```
+
+or manually add the following to your Gemfile:
+
+```ruby
+gem "transmutation"
+```
 
 If bundler is not being used to manage dependencies, install the gem by executing:
 
-    $ gem install transmutation
+```bash
+gem install transmutation
+```
 
 ## Usage
 
@@ -48,13 +58,16 @@ If bundler is not being used to manage dependencies, install the gem by executin
 
   As long as your object responds to the attributes defined in the serializer, it can be serialized.
 
-  - Struct
+  <details>
+    <summary>Struct</summary>
 
     ```ruby
     User = Struct.new(:id, :name, :email)
     ```
+  </details>
 
-  - Class
+  <details>
+    <summary>Class</summary>
 
     ```ruby
     class User
@@ -67,8 +80,10 @@ If bundler is not being used to manage dependencies, install the gem by executin
       end
     end
     ```
+  </details>
 
-  - ActiveRecord
+  <details>
+    <summary>ActiveRecord</summary>
 
     ```ruby
     # == Schema Information
@@ -81,15 +96,142 @@ If bundler is not being used to manage dependencies, install the gem by executin
     class User < ApplicationRecord
     end
     ```
+  </details>
+
+### The `#serialize` method
+
+When you include the `Transmutation::Serialization` module in your class, you can use the `#serialize` method to serialize an object.
+
+It will attempt to find a serializer class based on the object's class name along with the caller's namespace.
+
+```ruby
+include Transmutation::Serialization
+
+serialize(User.new) # => UserSerializer.new(User.new)
+```
+
+If no serializer class is found, it will return the object as is.
+
+### With Ruby on Rails
+
+When then `Transmutation::Serialization` module is included in a Rails controller, it also extends your `render` calls.
+
+```ruby
+class Api::V1::UsersController < ApplicationController
+  include Transmutation::Serialization
+
+  def show
+    user = User.find(params[:id])
 
-### Using the `Transmutation::Serialization` module
+    render json: user
+  end
+end
+```
+
+This will attempt to bubble up the controller namespaces to find a defined serializer class:
+
+- `Api::V1::UserSerializer`
+- `Api::UserSerializer`
+- `UserSerializer`
+
+This calls the `#serialize` method under the hood.
+
+If no serializer class is found, it will fall back to the default behavior of rendering the object as JSON.
+
+You can disable this behaviour by passing `serialize: false` to the `render` method.
+
+```ruby
+render json: user, serialize: false # => user.to_json
+```
+
+## Configuration
+
+You can override the serialization lookup by passing the following options:
+
+- `namespace`: The namespace to use when looking up the serializer class.
+
+  ```ruby
+  render json: user, namespace: "V1" # => Api::V1::V1::UserSerializer
+  ```
+
+  To prevent caller namespaces from being appended to the provided namespace, prefix the namespace with `::`.
+
+  ```ruby
+  render json: user, namespace: "::V1" # => V1::UserSerializer
+  ```
+
+  The `namespace` key is forwarded to the `#serialize` method.
+
+  ```ruby
+  render json: user, namespace: "V1" # => serialize(user, namespace: "V1")
+  ```
+
+- `serializer`: The serializer class to use.
+
+  ```ruby
+  render json: user, serializer: "SuperUserSerializer" # => Api::V1::SuperUserSerializer
+  ```
+
+  To prevent all namespaces from being appended to the serializer class, prefix the serializer class with `::`.
+
+  ```ruby
+  render json: user, serializer: "::SuperUserSerializer" # => SuperUserSerializer
+  ```
+
+  The `serializer` key is forwarded to the `#serialize` method.
+
+  ```ruby
+  render json: user, serializer: "SuperUserSerializer" # => serialize(user, serializer: "SuperUserSerializer")
+  ```
+
+## Opinionated Architecture
+
+If you follow the pattern outlined below, you can take full advantage of the automatic serializer lookup.
+
+### File Structure
+
+```
+.
+└── app/
+    ├── controllers/
+    │   └── api/
+    │       ├── v1/
+    │       │   └── users_controller.rb
+    │       └── v2
+    │           └── users_controller.rb
+    ├── models/
+    │   └── user.rb
+    └── serializers/
+        └── api/
+            ├── v1/
+            │   └── user_serializer.rb
+            ├── v2/
+            │   └── user_serializer.rb
+            └── user_serializer.rb
+```
+
+### Serializers
+
+```ruby
+class Api::UserSerializer < Transmutation::Serializer
+  attributes :id, :name, :email
+end
+
+class Api::V1::UserSerializer < Api::UserSerializer
+  attributes :phone # Added in V1
+end
+
+class Api::V2::UserSerializer < Api::UserSerializer
+  attributes :avatar # Added in V2
+end
+```
+
+To remove attributes, it is recommended to redefine all attributes and start anew. This acts as a reset and makes serializer inheritance much easier to follow.
 
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
-
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/spellbook-technology/transmutation. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/spellbook-technology/transmutation/blob/main/CODE_OF_CONDUCT.md).

data/lib/transmutation/serialization/lookup.rb

@@ -12,9 +12,9 @@ module Transmutation
       # Bubbles up the namespace until we find a matching serializer.
       #
       # @see Transmutation::Serialization#lookup_serializer
+      # @note This never bubbles up the object's namespace, only the caller's namespace.
       #
-      # Example:
-      #
+      # @example
       #   namespace: Api::V1::Admin::Detailed
       #   serializer: Chat::User
       #
@@ -25,11 +25,7 @@ module Transmutation
       #   - 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?("::")
@@ -38,7 +34,7 @@ module Transmutation
           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)
+        raise SerializerNotFound.new(object, namespace: serializer_namespace, name: serializer_name)
       end
 
       # Returns the highest specificity serializer name for the given object.
@@ -47,8 +43,6 @@ module Transmutation
       #
       # @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
 

data/lib/transmutation/serialization/rendering.rb

@@ -3,11 +3,11 @@
 module Transmutation
   module Serialization
     module Rendering
-      def render(json: nil, serialize: true, **args)
+      def render(json: nil, serialize: true, namespace: nil, serializer: nil, max_depth: 1, **args)
         return super(**args) unless json
-        return super(json: json, **args) unless serialize
+        return super(**args, json: json) unless serialize
 
-        super(**args, json: serialize(json))
+        super(**args, json: serialize(json, namespace: namespace, serializer: serializer, max_depth: max_depth))
       end
     end
   end

data/lib/transmutation/serialization.rb

@@ -8,10 +8,18 @@ module Transmutation
     # @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.
+    # @param max_depth [Integer] The maximum depth of nested associations to serialize.
     #
     # @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)
+    def serialize(object, namespace: nil, serializer: nil, depth: 0, max_depth: 1)
+      if object.respond_to?(:map)
+        return object.map do |item|
+          serialize(item, namespace: namespace, serializer: serializer, depth: depth, max_depth: max_depth)
+        end
+      end
+
+      lookup_serializer(object, namespace: namespace, serializer: serializer)
+        .new(object, depth: depth, max_depth: max_depth)
     end
 
     # Lookup the serializer for the given object.
@@ -29,7 +37,7 @@ module Transmutation
     end
 
     private_class_method def self.included(base)
-      base.include(Rendering) if base.respond_to?(:render)
+      base.include(Rendering) if base.method_defined?(:render)
     end
   end
 end

data/lib/transmutation/serializer.rb

@@ -10,12 +10,20 @@ module Transmutation
   #     attribute :full_name do
   #       "#{object.first_name} #{object.last_name}".strip
   #     end
+  #
+  #     belongs_to :organization
+  #
+  #     has_many :posts
   #   end
   class Serializer
     extend ClassAttributes
 
-    def initialize(object)
+    include Transmutation::Serialization
+
+    def initialize(object, depth: 0, max_depth: 1)
       @object = object
+      @depth = depth
+      @max_depth = max_depth
     end
 
     def to_json(options = {})
@@ -24,39 +32,84 @@ module Transmutation
 
     def as_json(_options = {})
       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)
+        if attr_options[:association]
+          hash[attr_name.to_s] = instance_exec(&attr_options[:block]) if @depth + 1 <= @max_depth
+        else
+          hash[attr_name.to_s] = attr_options[:block] ? instance_exec(&attr_options[:block]) : object.send(attr_name)
+        end
       end
     end
 
-    # 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
+    class << self
+      # 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 attribute(attribute_name, &block)
+        attributes_config[attribute_name] = { block: block }
+      end
+
+      # Define an association to be serialized
+      #
+      # @note By default, the serializer for the association is looked up in the same namespace as the serializer
+      #
+      # @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
+      #
+      # @example
+      #   class UserSerializer < Transmutation::Serializer
+      #     association :posts
+      #     association :comments, namespace: "Nested", serializer: "User::CommentSerializer"
+      #   end
+      def association(association_name, namespace: nil, serializer: nil)
+        block = lambda do
+          serialize(object.send(association_name), namespace: namespace, serializer: serializer, depth: @depth + 1)
+        end
+
+        attributes_config[association_name] = { block: block, association: true }
+      end
+
+      alias belongs_to association
+      alias has_one association
+      alias has_many association
+
+      # 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 attributes(*attribute_names)
+        attribute_names.each do |attribute_name|
+          attribute(attribute_name)
+        end
+      end
 
-    # 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)
+      # Shorthand for defining multiple associations
+      #
+      # @param association_names [Array<Symbol>] The names of the associations to serialize
+      #
+      # @example
+      #   class UserSerializer < Transmutation::Serializer
+      #     associations :posts, :comments
+      #   end
+      def associations(*association_names)
+        association_names.each do |association_name|
+          association(association_name)
+        end
       end
     end
 

data/lib/transmutation/version.rb

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

data/transmutation.gemspec

@@ -16,6 +16,7 @@ Gem::Specification.new do |spec|
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = "https://github.com/spellbook-technology/transmutation"
   spec.metadata["changelog_uri"] = "https://github.com/spellbook-technology/transmutation/CHANGELOG.md"
+  spec.metadata["documentation_uri"] = "https://rubydoc.info/gems/transmutation"
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: transmutation
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.3.0
 platform: ruby
 authors:
 - nitemaeric
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2024-06-05 00:00:00.000000000 Z
+date: 2024-06-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: zeitwerk
@@ -46,7 +46,6 @@ files:
 - 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
@@ -62,6 +61,7 @@ metadata:
   homepage_uri: https://github.com/spellbook-technology/transmutation
   source_code_uri: https://github.com/spellbook-technology/transmutation
   changelog_uri: https://github.com/spellbook-technology/transmutation/CHANGELOG.md
+  documentation_uri: https://rubydoc.info/gems/transmutation
 post_install_message: 
 rdoc_options: []
 require_paths:

data/lib/transmutation/collection_serializer.rb

@@ -1,31 +0,0 @@
-# frozen_string_literal: true
-
-module Transmutation
-  # 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: nil, serializer: nil)
-      @objects = objects
-      @namespace = namespace
-      @serializer = serializer
-    end
-
-    def as_json(options = {})
-      objects.map { |item| serialize(item, namespace: namespace, serializer: serializer).as_json(options) }
-    end
-
-    def to_json(options = {})
-      as_json(options).to_json
-    end
-
-    private
-
-    attr_reader :objects, :namespace, :serializer
-  end
-end