mime_actor 0.4.0 → 0.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7f099315434127b3b7044aad85eca2f69664521753dd339af0f8b6829e0ef8dc
-  data.tar.gz: f8d79ab0813b5f3d63a8a991c9a0f39f328cc67e991738a21030a7fcaee3eae6
+  metadata.gz: a7a720ab3e8cb8cb9c3ba54e47f7b05272d0420ec2ba3194b739b07c4dee9e9b
+  data.tar.gz: 1f359c60a87f39261fbcab5b6f0d153a79a4fd936439e7d8d749970a544c2a59
 SHA512:
-  metadata.gz: ba11f403b7031051f9d56577a34dc7b2c63906aabe7b6e663fa9ef87225e0a9334d3a9f08eabbefc5f85a201c8ed73e231e4c616a2f0bac7d1a37e05607a4e81
-  data.tar.gz: 3f21642e23e14ef5a175740e7916618ed3fb99b8395197d7b5239abe0ead83d0ea498ed1b6f63fa4830e9803e2bc16c04f32c43b25544bcf57c9986f2999f528
+  metadata.gz: d40d5fdd4e8b21f4a1b1e30e26ed66f653caef5f0ee0696cc844a2dfe355eeda95be62911b2973293f0c97c048d06c0b9e7a2ed0ae2733223340433a2abab9cb
+  data.tar.gz: 16ff17b8a4c96a99a396e7d417ad4f5f0fa50dce86f82b5071f35e88994f6bc4155e9bdd85dc59c3ef1902ed60282267c946f9509478566132155d71097dc8bf

data/.hound.yml

@@ -0,0 +1,2 @@
+rubocop:
+  enabled: false

data/.rubocop.yml

@@ -7,6 +7,7 @@ AllCops:
   NewCops: enable
   Exclude:
     - bin/*
+    - vendor/**/*
 
 Style/Documentation:
   Enabled: false

data/README.md

@@ -1,25 +1,96 @@
 # mime_actor
 
-[![Gem Version](https://badge.fury.io/rb/mime_actor.png)](https://badge.fury.io/rb/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]
 
-Action rendering and rescue with mime type via configuration in actionpack
+Action Render + Rescue handlers for different MIME types in Rails
 
-## Installation
+## Usage
 
-Install the gem and add to the application's Gemfile by executing:
+MimeActor allows you to do something like below:
+```rb
+class EventsController < ActionController::Base
+    # AbstractController::Callbacks here to load model with params
+    before_action only: :index { @events = Event.all }
+    before_action only: [:show, :update] { @event = Event.find(params.require(:event_id)) }
 
-    $ bundle add mime_actor
+    compose_scene :html, :json, on: :index
+    compose_scene :html, :json, on: [:show, :update]
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+    rescue_actor_from ActiveRecord::RecordNotFound, format: :json do |ex|
+        render status: :bad_request, json: { error: "Resouce not found" }
+    end
+
+    rescue_actor_from ActiveRecord::RecordNotFound, format: :html, action: :show do |ex|
+        redirect_to events_path
+    end
+
+    def index_html
+        @event_categories = EventCategory.all
+        render :index # render html using @events and @event_categories
+    end
+
+    def index_json
+        render json: @events # render json using #as_json
+    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
+```
+
+Seems useful? See the [Comparison][doc_comparison] on how it can improve your existing code
+
+## Features
 
-    $ gem install mime_actor
+- 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][doc_action_controller_mime_responds]
+- Fully compatible with other [ActionController][doc_action_controller] functionalities 
 
-## Getting Started
+## Documentation
+
+You can find the documentation on [RubyDoc][doc_mime_actor].
+
+## Requirements
+
+- Ruby: MRI 3.1+
+- Rails: 5.0+
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+```sh
+bundle add mime_actor
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+```sh
+gem install mime_actor
+```
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec 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).
 
@@ -29,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/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/lib/mime_actor/{act.rb → action.rb}

@@ -10,7 +10,13 @@ require "abstract_controller/rendering"
 require "action_controller/metal/mime_responds"
 
 module MimeActor
-  module Act
+  # # 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
 
     include AbstractController::Rendering # required by MimeResponds
@@ -21,12 +27,14 @@ 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)
 
       if formats.empty?
-        logger.warn { "format is empty, action: #{action}" }
+        logger.warn { "format is empty for action :#{action}" }
         return
       end
 

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,11 +48,15 @@ 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
 
-        logger.warn { "actor not found, got: #{actor_name}" }
+        logger.warn { "actor not found, expected :#{actor_name}" }
         return
       end
 

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

@@ -11,8 +11,8 @@ module MimeActor
 
   module VERSION
     MAJOR = 0
-    MINOR = 4
-    BUILD = 0
+    MINOR = 5
+    BUILD = 2
     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"
 
@@ -8,7 +11,7 @@ require "active_support/dependencies/autoload"
 module MimeActor
   extend ActiveSupport::Autoload
 
-  autoload :Act
+  autoload :Action
   autoload :Scene
   autoload :Stage
   autoload :Rescue

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mime_actor
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.2
 platform: ruby
 authors:
 - Ryan Chang
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2024-06-27 00:00:00.000000000 Z
+date: 2024-06-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack
@@ -59,14 +59,16 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".hound.yml"
 - ".rspec"
 - ".rubocop.yml"
 - ".ruby-version"
 - LICENSE
 - README.md
 - Rakefile
+- lib/COMPARE.md
 - lib/mime_actor.rb
-- lib/mime_actor/act.rb
+- lib/mime_actor/action.rb
 - lib/mime_actor/errors.rb
 - lib/mime_actor/logging.rb
 - lib/mime_actor/rescue.rb
@@ -102,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: []