mime_actor 0.5.1 → 0.5.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 21576d34311aa9a06ac9542d118390900d8b9e3d9860fb6ed7d1a4a9b672bf96
-  data.tar.gz: a2ca714375f7892e1506bf55b5fcdbbaa3b1ea7884b9f2ad7a1b4284d3fed08a
+  metadata.gz: 709cab49cc347653da124ec9147c7527b96f71df08059b6eab45a5d9b5b06888
+  data.tar.gz: ac9a75000c8711550971fa0d6e4f0ba3bc2b9e706ebd1654702df1b56d3e0f5d
 SHA512:
-  metadata.gz: c24629937c5b2d7626588b1ef8ffa1d334450bda5dafe90693d0c65bfc5200d8122e0fdbd315206538c85cb6d8aae29eedf7f07289b3971a13f0a6903d757c0b
-  data.tar.gz: 07d9061ef2e41f55b0e5e9718f9a719a4da2309232be87bf59f638e2a0f9502cfbcdaa6f054f9e2764b9c9b5a9bb1cd5a3a8544a6844902d5dd1f72d07b8ea1f
+  metadata.gz: 40fe1d6ba3560b836c12ec423d8285497f2576f231a385ecf910942cedd8be7c36ea1d20077283f2aa336c0aa1beab92a6472b998a63fde4a3b9de1e71f5a9c3
+  data.tar.gz: 5dc2dcc8697d65e386bf47f898b4ed85b8fe7d364ddfce84be873b966653c713e788c994a57e879e439ae1f6401e69092905dd88319a52c94f8c1be817daa1ca

data/COMPARE.md

@@ -0,0 +1,124 @@
+## Comparison in Rails
+
+### MIME Rendering
+
+#### before
+```rb
+class EventsController < ActionController::Base
+    def index
+        @events = Event.all
+        respond_to do |format|
+            format.html do
+                @event_categories = EventCategory.all
+
+                # render html using @events and @event_categories
+                render :index 
+            end
+            format.json { render json: @events } # render json using #as_json
+        end
+    end
+end
+```
+#### after
+```rb
+class EventsController < ActionController::Base
+    include MimeActor::Action
+
+    before_action only: :index { @events = Event.all }
+
+    # dynamically defines the action method according to on: argument
+    compose_scene :html, :json, on: :index 
+
+    def index_html
+        @event_categories = EventCategory.all
+        
+        # render html using @events and @event_categories
+        render :index
+    end
+
+    def index_json
+        # render json using #as_json
+        render json: @events
+    end
+end
+```
+
+### MIME Rescuing
+
+#### before
+```rb
+class EventsController < ActionController::Base
+    # AbstractController::Callbacks here to load model with params
+    before_action only: [:show, :update] { @event = Event.find(params.require(:event_id)) }
+
+    rescue_from ActiveRecord::RecordNotFound do |ex|
+        case action_name.to_s
+        when "show"
+            respond_to do |format|
+                format.html { redirect_to events_path } # redirect to index
+                format.json { render status: :bad_request, json: { error: ex.message } }
+            end
+        when "update"
+            respond_to do |format|
+                format.html { render :edit }
+                format.json { render status: :bad_request, json: { error: ex.message } }
+            end
+        else
+            raise ex # re-raise since we are not handling it
+        end
+    end
+
+    def show
+        respond_to do |format|
+            format.html { render :show } # render html using @event
+            format.json { render json: @event } # render json using #as_json
+        end
+    end
+
+    def update
+        # ...
+        respond_to do |format|
+            format.html { redirect_to event_path(@event.id)  } # redirect to show upon sucessful update
+            format.json { render json: @event } # render json using #as_json
+        end
+    end
+end
+```
+#### after
+```rb
+class EventsController < ActionController::Base
+    include MimeActor::Action
+
+    # AbstractController::Callbacks here to load model with params
+    before_action only: [:show, :update] { @event = Event.find(params.require(:event_id)) }
+
+    compose_scene :html, :json, on: [:show, :update]
+
+    rescue_actor_from ActiveRecord::RecordNotFound, format: :json do |ex|
+        render status: :bad_request, json: { error: ex.message }
+    end
+
+    rescue_actor_from ActiveRecord::RecordNotFound, format: :html, action: :show do |ex|
+        redirect_to events_path
+    end
+
+    def show_html
+        render :show # render html using @event
+    end
+
+    def update_html
+        redirect_to event_path(@event.id) # redirect to show upon sucessful update
+    rescue ActiveRecord::RecordNotFound
+        render :edit
+    end
+
+    def show_json
+        render json: @event # render json using #as_json
+    end
+
+    def update_json
+        # ...
+        render json: @event # render json using #as_json
+    end
+end
+```

data/README.md

@@ -1,10 +1,11 @@
 # mime_actor
 
-[![Gem Version](https://badge.fury.io/rb/mime_actor.png)](https://badge.fury.io/rb/mime_actor)
-[![codecov](https://codecov.io/gh/ryancyq/mime_actor/graph/badge.svg?token=4C091RHXC3)](https://codecov.io/gh/ryancyq/mime_actor)
-[![Build](https://github.com/ryancyq/mime_actor/actions/workflows/build.yml/badge.svg)](https://github.com/ryancyq/mime_actor/actions/workflows/build.yml)
+[![Version][rubygems_badge]][rubygems]
+[![CI][ci_badge]][ci_workflows]
+[![Coverage][coverage_badge]][coverage]
+[![Maintainability][maintainability_badge]][maintainability]
 
-Render + Rescue handlers for different MIME types in Rails
+Action Render + Rescue handlers for different MIME types in Rails
 
 ## Usage
 
@@ -56,13 +57,19 @@ class EventsController < ActionController::Base
 end
 ```
 
+Seems useful? See the [Comparison][doc_comparison] on how it can improve your existing code
+
 ## Features
 
-- Action customisation for ActionController per MIME type
+- Action customisation for [ActionController][doc_action_controller] per MIME type
 - Customisation are deduplicated automatically when configured multiple times
 - Flexible rescue handler definition for the combination of Action/MIME type or both
-- Built on top of `ActionController::Metal::MimeResponds`
-- Fully compatible with other `ActionController` functionalities 
+- Built on top of [ActionController::Metal::MimeResponds][doc_action_controller_mime_responds]
+- Fully compatible with other [ActionController][doc_action_controller] functionalities 
+
+## Documentation
+
+You can find the documentation on [RubyDoc][doc_mime_actor].
 
 ## Requirements
 
@@ -93,3 +100,17 @@ Please see [LICENSE](https://github.com/ryancyq/mime_actor/blob/main/LICENSE) fo
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/ryancyq/mime_actor.
+
+[rubygems_badge]: https://img.shields.io/gem/v/mime_actor.svg
+[rubygems]: https://rubygems.org/gems/mime_actor
+[ci_badge]: https://github.com/ryancyq/mime_actor/actions/workflows/build.yml/badge.svg
+[ci_workflows]: https://github.com/ryancyq/mime_actor/actions/workflows/
+[coverage_badge]: https://codecov.io/gh/ryancyq/mime_actor/graph/badge.svg?token=4C091RHXC3
+[coverage]: https://codecov.io/gh/ryancyq/mime_actor
+[maintainability_badge]: https://api.codeclimate.com/v1/badges/06689606dc3f3945dc1b/maintainability
+[maintainability]: https://codeclimate.com/github/ryancyq/mime_actor/maintainability
+
+[doc_mime_actor]: https://rubydoc.info/gems/mime_actor
+[doc_action_controller]: https://rubydoc.info/gems/actionpack/ActionController/Metal
+[doc_action_controller_mime_responds]: https://rubydoc.info/gems/actionpack/ActionController/MimeResponds
+[doc_comparison]: https://github.com/ryancyq/mime_actor/blob/main/COMPARE.md

data/lib/mime_actor/action.rb

@@ -10,6 +10,12 @@ require "abstract_controller/rendering"
 require "action_controller/metal/mime_responds"
 
 module MimeActor
+  # # MimeActor Action
+  #
+  # Action is the recommended Module to be included in ActionController.
+  #
+  # Provides intuitive way of action rendering for a specific MIME type with rescue handlers.
+  #
   module Action
     extend ActiveSupport::Concern
 
@@ -21,6 +27,8 @@ module MimeActor
     include Rescue
     include Logging
 
+    ##
+    # The core logic where rendering logics are collected as Proc through configuration and passed over to ActionController::MimeResponds
     def start_scene(action)
       action = action&.to_sym
       formats = acting_scenes.fetch(action, Set.new)

data/lib/mime_actor/logging.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 require "active_support/concern"
 require "active_support/configurable"
 require "active_support/isolated_execution_state" # required by active_support/logger
@@ -7,6 +9,9 @@ require "active_support/logger"
 require "active_support/tagged_logging"
 
 module MimeActor
+  # # MimeActor Logging
+  # 
+  # Provides a configurable logger.
   module Logging
     extend ActiveSupport::Concern
 

data/lib/mime_actor/rescue.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 require "mime_actor/stage"
 require "mime_actor/validator"
 
@@ -9,6 +11,10 @@ require "active_support/core_ext/module/attribute_accessors"
 require "active_support/core_ext/string/inflections"
 
 module MimeActor
+  # # MimeActor Rescue
+  #
+  # Simillar to ActionController::Rescue but with additional filtering logic on Action/Format.
+  #
   module Rescue
     extend ActiveSupport::Concern
 
@@ -20,6 +26,15 @@ module MimeActor
     end
 
     module ClassMethods
+      ##
+      # Registers a rescue handler for the given error classes with action/format filter
+      #
+      # rescue_actor_from StandardError, format: :json, action: :show do |ex|
+      #   render status: :bad_request, json: { error: ex.message }
+      # end
+      #
+      # rescue_actor_from StandardError, format: :html, with: :handle_html_error
+      #
       def rescue_actor_from(*klazzes, action: nil, format: nil, with: nil, &block)
         raise ArgumentError, "error filter is required" if klazzes.empty?
 
@@ -58,6 +73,9 @@ module MimeActor
         end
       end
 
+      ##
+      # Resolve the error provided with the registered handlers.
+      # The handled error will be returned to indicate successful handling
       def rescue_actor(error, action: nil, format: nil, context: self, visited: [])
         return if visited.include?(error)
 

data/lib/mime_actor/scene.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 require "mime_actor/errors"
 require "mime_actor/validator"
 
@@ -9,6 +11,15 @@ require "active_support/core_ext/array/wrap"
 require "active_support/core_ext/module/attribute_accessors"
 
 module MimeActor
+  # # MimeActor Scene
+  #
+  # Scene provides configuration for Action + Format definitions
+  #
+  # compose_scene :html, on: :index
+  # compose_scene :html, :json , on: [:index, :show]
+  #
+  # NOTE: Calling the same action/format multiple times will overwrite previous Action + Format definitions.
+  #
   module Scene
     extend ActiveSupport::Concern
 
@@ -19,6 +30,10 @@ module MimeActor
     end
 
     module ClassMethods
+      ##
+      # Register Action + Format definitions.
+      #
+      # For each unique action being registered, it will have a corresponding method being defined.
       def compose_scene(*options)
         config = options.extract_options!
         validate!(:formats, options)

data/lib/mime_actor/stage.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 require "mime_actor/errors"
 require "mime_actor/logging"
 
@@ -7,6 +9,10 @@ require "active_support/concern"
 require "active_support/core_ext/module/attribute_accessors"
 
 module MimeActor
+  # # MimeActor Stage
+  #
+  # Stage provides helpers for actor lookup and invocation.
+  #
   module Stage
     extend ActiveSupport::Concern
 
@@ -17,6 +23,8 @@ module MimeActor
     end
 
     module ClassMethods
+      ##
+      # Determine if the name belongs to a public instance method excluding methods inherited from ancesstors
       def actor?(actor_name)
         # exclude public methods from ancestors
         found = public_instance_methods(false).include?(actor_name.to_sym)
@@ -27,7 +35,11 @@ module MimeActor
         found
       end
 
+      ##
+      # Wraps the given block with lambda, rescue any error raised from the block via #rescue_actor if defined, otherwise, error will be re-raised
       def dispatch_cue(action: nil, format: nil, context: self, &block)
+        raise ArgumentError, "block must be provided" unless block_given?
+
         lambda do
           context.instance_exec(&block)
         rescue StandardError => e
@@ -36,6 +48,10 @@ module MimeActor
       end
     end
 
+    ##
+    # Call the actor method if defined, supports passing arguments to the actor method.
+    # 
+    # If a block is given, the result from the actor method will be yieled to the block
     def cue_actor(actor_name, *args)
       unless self.class.actor?(actor_name)
         raise MimeActor::ActorNotFound, actor_name if raise_on_missing_actor

data/lib/mime_actor/validator.rb

@@ -1,10 +1,23 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 require "active_support/concern"
 require "set" # required by mime_type with ruby <= 3.1
 require "action_dispatch/http/mime_type"
 
 module MimeActor
+  # # MimeActor Validator
+  #
+  # Validator provides validation rules for action, format, and rescue handlers by default.
+  #
+  # # raise error when rule is violated
+  # validate!(:action, action_param)
+  #
+  # # return the error when rule is violated
+  # ex = validate_action(action_param)
+  # raise ex if error
+  #
   module Validator
     extend ActiveSupport::Concern
 
@@ -13,6 +26,8 @@ module MimeActor
     end
 
     module ClassMethods
+      ##
+      # Raise the error returned by validator if present.
       def validate!(rule, *args)
         validator = "validate_#{rule}"
         raise NameError, "Validator not found, got: #{validator}" unless respond_to?(validator, true)
@@ -21,21 +36,29 @@ module MimeActor
         raise error if error
       end
 
+      ##
+      # validate :action must be a Symbol
       def validate_action(unchecked)
         ArgumentError.new("action must be a Symbol") unless unchecked.is_a?(Symbol)
       end
 
+      ##
+      # validate :actions must be an Array of Symbol
       def validate_actions(unchecked)
         rejected = unchecked.reject { |action| action.is_a?(Symbol) }
         NameError.new("invalid actions, got: #{rejected.join(", ")}") if rejected.size.positive?
       end
 
+      ##
+      # validate :format must be a Symbol + a valid MIME type
       def validate_format(unchecked)
         return ArgumentError.new("format must be a Symbol") unless unchecked.is_a?(Symbol)
 
         NameError.new("invalid format, got: #{unchecked}") unless scene_formats.include?(unchecked)
       end
 
+      ##
+      # validate :formats must be an Array of Symbol which each of them is a valid MIME type
       def validate_formats(unchecked)
         unfiltered = unchecked.to_set
         filtered = unfiltered & scene_formats
@@ -44,6 +67,8 @@ module MimeActor
         NameError.new("invalid formats, got: #{rejected.join(", ")}") if rejected.size.positive?
       end
 
+      ##
+      # validate :with or &block must be provided + :with must be a Symbol or Proc
       def validate_with(unchecked, block)
         if unchecked.present? && block.present?
           return ArgumentError.new("provide either the with: keyword argument or a block")

data/lib/mime_actor/version.rb

@@ -12,7 +12,7 @@ module MimeActor
   module VERSION
     MAJOR = 0
     MINOR = 5
-    BUILD = 1
+    BUILD = 3
     PRE   = nil
 
     STRING = [MAJOR, MINOR, BUILD, PRE].compact.join(".")

data/lib/mime_actor.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+# :include: ../README.md
+
 require "mime_actor/version"
 require "mime_actor/errors"
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mime_actor
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.5.3
 platform: ruby
 authors:
 - Ryan Chang
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2024-06-28 00:00:00.000000000 Z
+date: 2024-06-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack
@@ -63,6 +63,7 @@ files:
 - ".rspec"
 - ".rubocop.yml"
 - ".ruby-version"
+- COMPARE.md
 - LICENSE
 - README.md
 - Rakefile
@@ -103,5 +104,5 @@ requirements: []
 rubygems_version: 3.5.9
 signing_key: 
 specification_version: 4
-summary: action rendering and rescue with mime type via configuration in actionpack
+summary: Action Render + Rescue handlers for different MIME types in Rails
 test_files: []