minato-rails-serializer 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e17119448417a63faa76e8a5096b0632d588ac6d08ff854535f1e8f2dded7135
+  data.tar.gz: cfc22d1e98188787a38f9db34c3538ba4b5dc38c3edc923225d2dde6c08df25b
+SHA512:
+  metadata.gz: 0c8bd8c28eb59cfb4b875865836c2c496f1656aa110d3618ebc77fb1023ff2e1f0b28f62463fac35524e1e73deb5f5de623e43e861b384e3813ee27ca2548711
+  data.tar.gz: 26b23b31e4d1df071b6b316ee604b66253ca6b1cab8f59b4ff58c8b089a880821ac4fcd01d12ff650219d74a6f2d5d41335a7856b5d318910417172972784fdf

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,22 @@
+require:
+  - rubocop-rspec
+
+AllCops:
+  DisplayCopNames: true
+  DisplayStyleGuide: true
+  ExtraDetails: false
+  NewCops: enable
+  TargetRubyVersion: 3.1
+
+Metrics/BlockLength:
+  IgnoredMethods: ['describe']
+  Max: 50
+
+RSpec/EmptyExampleGroup:
+  Enabled: false
+
+RSpec/ImplicitExpect:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,155 @@
+# Minato Rails Serializer
+
+A lightweight and high-performance JSON serialization layer for Rails, built on top of the Panko Serializer.
+
+Minato::Rails::Serializer seamlessly integrates with Rails' render json:, offering automatic serializer detection, a simple DSL for root keys, and the flexibility to override behavior directly in the controller, all with a focus on convention over configuration.
+
+## Installation
+Add this line to your application's Gemfile:
+
+```Ruby
+gem 'minato-rails-serializer'
+```
+
+And then execute:
+
+```Bash
+$ bundle install
+```
+
+## Usage
+The gem is designed to be as intuitive as possible, integrating with the standard Rails workflow.
+
+### 1. Creating a Serializer
+Create your serializers by inheriting from the `Minato::Rails::Serializer::Base` base class.
+
+```Ruby
+# app/serializers/post_serializer.rb
+class PostSerializer < Minato::Rails::Serializer::Base
+  attributes :id, :title, :body
+end
+```
+
+### 2. Basic Rendering in Controllers
+
+Thanks to the included Railtie, the gem modifies render json: to automatically detect and use the corresponding serializer for your model.
+
+In your controller, you can simply render the object:
+
+```Ruby
+class PostsController < ApplicationController
+  def show
+    @post = Post.find(params[:id])
+    # The gem will automatically look for `PostSerializer`
+    render json: @post
+  end
+
+  def index
+    @posts = Post.all
+    # It also works for collections
+    render json: @posts
+  end
+end
+```
+
+### 3. Using the root DSL
+You can define a default root key directly in your serializer, which will be used to wrap the JSON output.
+
+```Ruby
+# app/serializers/user_serializer.rb
+class UserSerializer < Minato::Rails::Serializer::Base
+  # Sets 'user' as the root for single objects and infers 'users' for collections
+  root :user
+
+  attributes :id, :name, :email
+end
+```
+
+Now, when rendering:
+
+```Ruby
+# In a `show` action
+render json: @user
+# Output:
+# {
+#   "user": { "id": 1, "name": "...", "email": "..." }
+# }
+
+# In an `index` action
+render json: @users
+# Output:
+# {
+#   "users": [
+#     { "id": 1, "name": "...", "email": "..." },
+#     { "id": 2, "name": "...", "email": "..." }
+#   ]
+# }
+```
+
+You can also specify a custom plural name:
+
+```Ruby
+class ProductSerializer < Minato::Rails::Serializer::Base
+  root :product, :products_list
+
+  # ...
+end
+```
+
+### 4. Overriding Options in the render Call
+
+The gem offers full flexibility, allowing you to override the default behavior directly in the render call.
+
+Overriding the Serializer
+Use the :serializer option to force the use of a different serializer than the inferred default.
+
+```Ruby
+# Assuming an AdminUserSerializer exists with more attributes
+def show
+  @user = User.find(params[:id])
+  render json: @user, serializer: AdminUserSerializer
+end
+```
+
+Overriding the Root Key (:root)
+Use the :root option to set a custom root key for a specific request, overriding the DSL.
+
+```Ruby
+def profile
+  @user = current_user
+  # The output will be wrapped in "profile", ignoring the `root :user` from the DSL.
+  render json: @user, root: :profile
+end
+```
+
+Disabling the Root Key
+To remove the root key (even if defined in the DSL), pass root: false.
+
+```Ruby
+def show
+  @user = User.find(params[:id])
+  # Returns the JSON object without any root key
+  render json: @user, root: false
+end
+```
+
+## Development
+
+This project uses Docker and Docker Compose to ensure a consistent development and testing environment.
+
+**Run the test suite:**
+
+```bash
+$ docker compose run run minato-rails-serializer
+```
+
+The entrypoint script defined in `compose.yml` will automatically create, migrate, and prepare the test database for the dummy application before the RSpec suite is executed. Manual database setup is no longer required.
+
+To open an interactive shell inside the container for debugging or running other commands (like `rails c` from the dummy app), use:
+
+```bash
+$ docker compose run minato-rails-serializer sh
+```
+
+## License
+The gem is available as open source under the terms of the MIT License.

data/Rakefile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+
+require 'bundler/gem_tasks'

data/compose.yml

@@ -0,0 +1,12 @@
+services:
+  minato-rails-serializer:
+    image: us-east1-docker.pkg.dev/minato-cloud/images/ruby-minato:1.0.0-dev
+    working_dir: /usr/src/app
+    volumes:
+      - .:/usr/src/app:cached
+      - bundle:/home/rails/.bundle
+    entrypoint: ./entrypoint.sh
+    command: rspec
+
+volumes:
+  bundle:

data/entrypoint.sh

@@ -0,0 +1,7 @@
+#!/bin/sh
+
+set -e
+
+bundle install
+
+exec "$@"

data/lib/minato/rails/serializer/base.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require 'panko_serializer'
+
+module Minato
+  module Rails
+    module Serializer
+      class Base < Panko::Serializer
+        class << self
+          def render(data, options = {})
+            rendered = render_data(data, options)
+            root = get_root(data, options)
+            return { root => rendered } if root.present?
+
+            rendered
+          end
+
+          protected
+
+          def root(name, plural_name = nil)
+            plural_root_name = plural_name || (name.pluralize if name.is_a?(String))
+            define_singleton_method(:root_name) { name }
+            define_singleton_method(:plural_root_name) { plural_root_name }
+          end
+
+          private
+
+          attr_accessor :root_name, :plural_root_name
+
+          def render_data(data, options = {})
+            if data.is_a?(Array) || data.is_a?(ActiveRecord::Relation) || data.respond_to?(:each)
+              return render_array(data, options)
+            end
+
+            render_object(data, options)
+          end
+
+          def render_array(data, options = {})
+            return [] if data.blank?
+
+            Panko::ArraySerializer.new(data, options.merge(each_serializer: self)).to_a
+          end
+
+          def render_object(data, options = {})
+            return nil if data.nil?
+
+            new(options[:options] || {}).serialize(data)
+          end
+
+          def get_root(data, options = {}) # rubocop:disable Metrics/CyclomaticComplexity
+            return nil if options[:root] == false
+            return options[:root] if options.key?(:root)
+            return nil if root_name.nil?
+
+            plural = plural_root_name || root_name&.to_s&.pluralize
+            data.is_a?(Enumerable) ? plural : root_name
+          end
+        end
+      end
+    end
+  end
+end

data/lib/minato/rails/serializer/railtie.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+# lib/minato/rails/serializer/railtie.rb
+
+require 'rails/railtie'
+
+module Minato
+  module Rails
+    module Serializer
+      class Railtie < ::Rails::Railtie
+        initializer 'minato.rails.serializer.add_json_renderer' do
+          ActionController::Renderers.remove(:json)
+
+          find_serializer_for_model = lambda do |obj|
+            klass = obj.is_a?(Enumerable) ? obj.first&.class : obj.class
+            return nil unless klass && defined?(ActiveRecord::Base) && klass < ActiveRecord::Base
+
+            "#{klass.name}Serializer".safe_constantize
+          end
+
+          ActionController::Renderers.add :json do |object, options|
+            self.content_type ||= Mime[:json]
+            serializer = options[:serializer].presence || find_serializer_for_model.call(object)
+
+            if serializer
+              serializer_options = options.slice(:root)
+              serializer.render(object, serializer_options).to_json
+            else
+              object = { options[:root] => object } if options[:root].present?
+              object.to_json(options.except(:root))
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/minato/rails/serializer/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Minato
+  module Rails
+    module Serializer
+      VERSION = '0.1.0'
+    end
+  end
+end

data/lib/minato/rails/serializer.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative 'serializer/version'
+require_relative 'serializer/base'
+require_relative 'serializer/railtie'

data/minato-rails-serializer.gemspec

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative 'lib/minato/rails/serializer/version'
+
+Gem::Specification.new do |spec|
+  spec.name        = 'minato-rails-serializer'
+  spec.version     = Minato::Rails::Serializer::VERSION
+  spec.authors     = ['Ferreri']
+  spec.email       = ['contato@ferreri.co']
+
+  spec.summary = 'Serializer for Minato Rails Apps.'
+  spec.homepage = 'https://gitlab.com/ferreri/minato/minato-rails-serializer'
+  spec.license = 'MIT'
+  spec.required_ruby_version = '>= 3.1.0'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://gitlab.com/ferreri/minato/minato-rails-serializer'
+  spec.metadata['changelog_uri'] = 'https://gitlab.com/ferreri/minato/minato-rails-serializer/-/blob/main/CHANGELOG.md?ref_type=heads'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  # 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.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .circleci appveyor Gemfile])
+    end
+  end
+  spec.bindir = 'exe'
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'panko_serializer', '>= 0.8.3'
+  spec.add_dependency 'rails', '>= 7.0.0'
+end

metadata

@@ -0,0 +1,87 @@
+--- !ruby/object:Gem::Specification
+name: minato-rails-serializer
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ferreri
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-09-11 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: panko_serializer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.8.3
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.8.3
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.0.0
+description:
+email:
+- contato@ferreri.co
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- MIT-LICENSE
+- README.md
+- Rakefile
+- compose.yml
+- entrypoint.sh
+- lib/minato/rails/serializer.rb
+- lib/minato/rails/serializer/base.rb
+- lib/minato/rails/serializer/railtie.rb
+- lib/minato/rails/serializer/version.rb
+- minato-rails-serializer.gemspec
+homepage: https://gitlab.com/ferreri/minato/minato-rails-serializer
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://gitlab.com/ferreri/minato/minato-rails-serializer
+  source_code_uri: https://gitlab.com/ferreri/minato/minato-rails-serializer
+  changelog_uri: https://gitlab.com/ferreri/minato/minato-rails-serializer/-/blob/main/CHANGELOG.md?ref_type=heads
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Serializer for Minato Rails Apps.
+test_files: []