mime_actor 0.5.3 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 709cab49cc347653da124ec9147c7527b96f71df08059b6eab45a5d9b5b06888
-  data.tar.gz: ac9a75000c8711550971fa0d6e4f0ba3bc2b9e706ebd1654702df1b56d3e0f5d
+  metadata.gz: 031455cd4203f02b1760129516e1a8722af2f84d7580cf1799f886d98262cdea
+  data.tar.gz: 78b2841148310600b408fd3d2932741ab61280f24afb28f0b251e62bcba91419
 SHA512:
-  metadata.gz: 40fe1d6ba3560b836c12ec423d8285497f2576f231a385ecf910942cedd8be7c36ea1d20077283f2aa336c0aa1beab92a6472b998a63fde4a3b9de1e71f5a9c3
-  data.tar.gz: 5dc2dcc8697d65e386bf47f898b4ed85b8fe7d364ddfce84be873b966653c713e788c994a57e879e439ae1f6401e69092905dd88319a52c94f8c1be817daa1ca
+  metadata.gz: 2852a58bb4dc628d293e6d5974b452144496be454a2a594aec90baaffcf5fbbcdd096745778853f36cc5e8ef4eb577340175bd76533ba2be1852799ddf5cc2a6
+  data.tar.gz: f548c1d8fe2c32a2aba34c4b9189e3e02272fdcfdc850d8b88e6cb6eea54514a1c95cc8ede181656f5ba0e92111f2566db1cbc98b647dd77f0922cd2ff1357be

data/.rubocop.yml

@@ -19,6 +19,10 @@ Style/BlockComments:
 Metrics/AbcSize:
   Enabled: false
   
+Metrics/BlockLength:
+  AllowedMethods:
+    - class_methods
+
 Metrics/CyclomaticComplexity:
   Enabled: false
 

data/.yardopts

@@ -0,0 +1,2 @@
+--markup markdown
+lib/**/*.rb

data/COMPARE.md

@@ -27,7 +27,7 @@ class EventsController < ActionController::Base
     before_action only: :index { @events = Event.all }
 
     # dynamically defines the action method according to on: argument
-    compose_scene :html, :json, on: :index 
+    act_on_format :html, :json, on: :index 
 
     def index_html
         @event_categories = EventCategory.all
@@ -92,13 +92,13 @@ class EventsController < ActionController::Base
     # 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]
+    act_on_format :html, :json, on: [:show, :update]
 
-    rescue_actor_from ActiveRecord::RecordNotFound, format: :json do |ex|
+    rescue_act_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|
+    rescue_act_from ActiveRecord::RecordNotFound, format: :html, action: :show do |ex|
         redirect_to events_path
     end
 

data/README.md

@@ -16,14 +16,14 @@ class EventsController < ActionController::Base
     before_action only: :index { @events = Event.all }
     before_action only: [:show, :update] { @event = Event.find(params.require(:event_id)) }
 
-    compose_scene :html, :json, on: :index
-    compose_scene :html, :json, on: [:show, :update]
+    act_on_format :html, :json, on: :index
+    act_on_format :html, :json, on: [:show, :update]
 
-    rescue_actor_from ActiveRecord::RecordNotFound, format: :json do |ex|
+    rescue_act_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|
+    rescue_act_from ActiveRecord::RecordNotFound, format: :html, action: :show do |ex|
         redirect_to events_path
     end
 

data/lib/mime_actor/action.rb

@@ -12,9 +12,9 @@ require "action_controller/metal/mime_responds"
 module MimeActor
   # # MimeActor Action
   #
-  # Action is the recommended Module to be included in ActionController.
+  # `Action` is the recommended `Module` to be included in the `ActionController`.
   #
-  # Provides intuitive way of action rendering for a specific MIME type with rescue handlers.
+  # Provides intuitive way of `action` rendering for a specific MIME type with rescue handlers.
   #
   module Action
     extend ActiveSupport::Concern
@@ -27,8 +27,21 @@ module MimeActor
     include Rescue
     include Logging
 
-    ##
-    # The core logic where rendering logics are collected as Proc through configuration and passed over to ActionController::MimeResponds
+    # The core logic where rendering logics are collected as `Proc` and passed over to `ActionController::MimeResponds`
+    #
+    # @param action the `action` of the controller
+    #
+    # @example process `create` action
+    #   start_scene(:create)
+    #
+    #   # it is equivalent to the following if `create` action is configured with `html` and `json` formats
+    #   def create
+    #     respond_to |format|
+    #       format.html { public_send(:create_html) }
+    #       format.json { public_send(:create_json) }
+    #     end
+    #   end
+    #
     def start_scene(action)
       action = action&.to_sym
       formats = acting_scenes.fetch(action, Set.new)

data/lib/mime_actor/logging.rb

@@ -10,7 +10,7 @@ require "active_support/tagged_logging"
 
 module MimeActor
   # # MimeActor Logging
-  # 
+  #
   # Provides a configurable logger.
   module Logging
     extend ActiveSupport::Concern

data/lib/mime_actor/rescue.rb

@@ -13,7 +13,10 @@ require "active_support/core_ext/string/inflections"
 module MimeActor
   # # MimeActor Rescue
   #
-  # Simillar to ActionController::Rescue but with additional filtering logic on Action/Format.
+  # Simillar to `ActionController::Rescue` but with additional filtering logic on `action`/`format`.
+  #
+  # @example Rescue RuntimeError when raised for any action with `json` format
+  #   rescue_act_from RuntimeError, format: :json, with: :handle_json_error
   #
   module Rescue
     extend ActiveSupport::Concern
@@ -25,57 +28,56 @@ module MimeActor
       mattr_accessor :actor_rescuers, instance_writer: false, default: []
     end
 
-    module ClassMethods
-      ##
-      # Registers a rescue handler for the given error classes with action/format filter
+    class_methods do
+      # Registers a rescue handler for the given error classes with `action`/`format` filter
+      #
+      # @param klazzes the error classes to rescue
+      # @param action the `action` filter
+      # @param format the `format` filter
+      # @param with the rescue hanlder when `block` is not provided
+      # @param block the `block` to evaluate when `with` is not provided
       #
-      # rescue_actor_from StandardError, format: :json, action: :show do |ex|
-      #   render status: :bad_request, json: { error: ex.message }
-      # end
+      # @example Rescue StandardError when raised for any action with `html` format
+      #   rescue_act_from StandardError, format: :html, with: :handle_html_error
       #
-      # rescue_actor_from StandardError, format: :html, with: :handle_html_error
+      # @example Rescue StandardError when raised for `show` action with `json` format
+      #   rescue_act_from StandardError, format: :json, action: :show do |ex|
+      #     render status: :bad_request, json: { error: ex.message }
+      #   end
       #
-      def rescue_actor_from(*klazzes, action: nil, format: nil, with: nil, &block)
+      def rescue_act_from(*klazzes, action: nil, format: nil, with: nil, &block)
         raise ArgumentError, "error filter is required" if klazzes.empty?
 
         validate!(:with, with, block)
         with = block if block_given?
 
         if action.present?
-          if action.is_a?(Enumerable)
-            validate!(:actions, action)
-          else
-            validate!(:action, action)
-          end
+          action.is_a?(Enumerable) ? validate!(:actions, action) : validate!(:action, action)
         end
 
         if format.present?
-          if format.is_a?(Enumerable)
-            validate!(:formats, format)
-          else
-            validate!(:format, format)
-          end
+          format.is_a?(Enumerable) ? validate!(:formats, format) : validate!(:format, format)
         end
 
         klazzes.each do |klazz|
-          error = case klazz
-                  when Module
-                    klazz.name
-                  when String
-                    klazz
-                  else
-                    message = "#{klazz.inspect} must be a Class/Module or a String referencing a Class/Module"
-                    raise ArgumentError, message
-                  end
+          validate!(:klazz, klazz)
+          error = klazz.is_a?(Module) ? klazz.name : klazz
 
           # append at the end because strategies are read in reverse.
           actor_rescuers << [error, format, action, with]
         end
       end
 
-      ##
       # Resolve the error provided with the registered handlers.
-      # The handled error will be returned to indicate successful handling
+      #
+      # The handled error will be returned to indicate successful handling.
+      #
+      # @param error the error instance to rescue
+      # @param action the `action` filter
+      # @param format the `format` filter
+      # @param context the context to evaluate for rescue handler
+      # @param visited the errors to skip after no rescue handler matched the filter
+      #
       def rescue_actor(error, action: nil, format: nil, context: self, visited: [])
         return if visited.include?(error)
 

data/lib/mime_actor/scene.rb

@@ -13,12 +13,14 @@ require "active_support/core_ext/module/attribute_accessors"
 module MimeActor
   # # MimeActor Scene
   #
-  # Scene provides configuration for Action + Format definitions
+  # Scene provides configuration for `action` + `format` definitions
   #
-  # compose_scene :html, on: :index
-  # compose_scene :html, :json , on: [:index, :show]
+  # @example register a `html` format on action `index`
+  #     act_on_format :html, on: :index
+  # @example register `html`, `json` formats on actions `index`, `show`
+  #     act_on_format :html, :json , on: [:index, :show]
   #
-  # NOTE: Calling the same action/format multiple times will overwrite previous Action + Format definitions.
+  # NOTE: Calling the same `action`/`format` multiple times will overwrite previous `action` + `format` definitions.
   #
   module Scene
     extend ActiveSupport::Concern
@@ -29,46 +31,60 @@ module MimeActor
       mattr_accessor :acting_scenes, instance_writer: false, default: {}
     end
 
-    module ClassMethods
-      ##
-      # Register Action + Format definitions.
+    class_methods do
+      # Register `action` + `format` definitions.
       #
-      # For each unique action being registered, it will have a corresponding method being defined.
-      def compose_scene(*options)
+      # @param options [Array]
+      # @option options [Array] klazzes the collection of `format`
+      # @option options [Hash] on the collection of `action`
+      #
+      # @example register a `html` format on action `index`
+      #   act_on_format :html, on: :index
+      # @example register `html`, `json` formats on actions `index`, `show`
+      #   act_on_format :html, :json , on: [:index, :show]
+      #
+      # For each unique `action` being registered, it will have a corresponding `action` method being defined.
+      def act_on_format(*options)
         config = options.extract_options!
         validate!(:formats, options)
 
-        actions = config[:on]
-        if !actions
-          raise ArgumentError, "action is required"
-        elsif actions.is_a?(Enumerable)
+        case actions = config[:on]
+        when Enumerable
           validate!(:actions, actions)
-        else
+        when Symbol, String
           validate!(:action, actions)
+        else
+          raise ArgumentError, "action is required"
         end
 
-        options.each do |format|
-          Array.wrap(actions).each do |action|
-            action_defined = (instance_methods + private_instance_methods).include?(action.to_sym)
-            raise MimeActor::ActionExisted, action if !acting_scenes.key?(action) && action_defined
+        Array.wrap(actions).each do |action|
+          options.each { |format| compose_scene(action, format) }
+        end
+      end
 
-            acting_scenes[action] ||= Set.new
-            acting_scenes[action] |= [format]
+      private
 
-            next if action_defined
+      def compose_scene(action, format)
+        action_defined = (instance_methods + private_instance_methods).include?(action.to_sym)
+        raise MimeActor::ActionExisted, action if !acting_scenes.key?(action) && action_defined
 
-            class_eval(
-              # def index
-              #   self.respond_to?(:start_scene) && self.start_scene(:index)
-              # end
-              <<-RUBY, __FILE__, __LINE__ + 1
-                def #{action}
-                  self.respond_to?(:start_scene) && self.start_scene(:#{action})
-                end
-              RUBY
-            )
-          end
-        end
+        acting_scenes[action] ||= Set.new
+        acting_scenes[action] |= [format]
+
+        define_scene(action) unless action_defined
+      end
+
+      def define_scene(action)
+        class_eval(
+          # def index
+          #   self.respond_to?(:start_scene) && self.start_scene(:index)
+          # end
+          <<-RUBY, __FILE__, __LINE__ + 1
+            def #{action}
+              self.respond_to?(:start_scene) && self.start_scene(:#{action})
+            end
+        RUBY
+        )
       end
     end
   end

data/lib/mime_actor/stage.rb

@@ -11,7 +11,7 @@ require "active_support/core_ext/module/attribute_accessors"
 module MimeActor
   # # MimeActor Stage
   #
-  # Stage provides helpers for actor lookup and invocation.
+  # Stage provides helper methods for actor lookup and invocation.
   #
   module Stage
     extend ActiveSupport::Concern
@@ -22,9 +22,11 @@ module MimeActor
       mattr_accessor :raise_on_missing_actor, instance_writer: false, default: false
     end
 
-    module ClassMethods
-      ##
-      # Determine if the name belongs to a public instance method excluding methods inherited from ancesstors
+    class_methods do
+      # Determine if the `actor_name` belongs to a public instance method excluding methods inherited from ancestors
+      #
+      # @param actor_name
+      #
       def actor?(actor_name)
         # exclude public methods from ancestors
         found = public_instance_methods(false).include?(actor_name.to_sym)
@@ -35,8 +37,21 @@ 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
+      # Wraps the given `block` with a `lambda`, rescue any error raised from the `block`.
+      # Otherwise, error will be re-raised.
+      #
+      # @param action the `action` to be passed on to `rescue_actor`
+      # @param format the `format` to be passed on to `rescue_actor`
+      # @param context the context for the block evaluation
+      # @param block the `block` to be evaluated
+      #
+      # @example Dispatch a cue that prints out a text
+      #   dispatch = self.class.dispatch_cue(action: :create, format: :json, context: self) do
+      #       puts "completed the dispatch"
+      #   end
+      #
+      #   dispatch.call == "completed the dispatch" # true
+      #
       def dispatch_cue(action: nil, format: nil, context: self, &block)
         raise ArgumentError, "block must be provided" unless block_given?
 
@@ -48,10 +63,11 @@ 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
+    # Calls 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.
+    #
+    # @param actor_name
     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

@@ -9,14 +9,14 @@ require "action_dispatch/http/mime_type"
 module MimeActor
   # # MimeActor Validator
   #
-  # Validator provides validation rules for action, format, and rescue handlers by default.
+  # Validator provides validation rules for `action`, `format`, and `with` handlers by default.
   #
-  # # raise error when rule is violated
-  # validate!(:action, action_param)
+  # @example 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
+  # @example Return the error when rule is violated
+  #   ex = validate_action(action_param)
+  #   raise ex if error
   #
   module Validator
     extend ActiveSupport::Concern
@@ -25,9 +25,10 @@ module MimeActor
       mattr_accessor :scene_formats, instance_writer: false, default: Mime::SET.symbols.to_set
     end
 
-    module ClassMethods
-      ##
-      # Raise the error returned by validator if present.
+    class_methods do
+      # Raise the error returned by validator if any.
+      #
+      # @param rule the name of validator
       def validate!(rule, *args)
         validator = "validate_#{rule}"
         raise NameError, "Validator not found, got: #{validator}" unless respond_to?(validator, true)
@@ -36,29 +37,33 @@ module MimeActor
         raise error if error
       end
 
-      ##
-      # validate :action must be a Symbol
+      # Validate `action` must be a Symbol
+      #
+      # @param unchecked the `action` to be validated
       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
+      # Validate `actions` must be a collection of Symbol
+      #
+      # @param unchecked the `actions` to be validated
       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
+      # Validate `format` must be a Symbol and a valid MIME type
+      #
+      # @param unchecked the `format` to be validated
       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
+      # Validate `formats` must be an collection of Symbol which each of them is a valid MIME type
+      #
+      # @param unchecked the `formats` to be validated
       def validate_formats(unchecked)
         unfiltered = unchecked.to_set
         filtered = unfiltered & scene_formats
@@ -67,8 +72,19 @@ 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
+      # Validate `klazz` must be a Class/Module or a String referencing a Class/Module
+      #
+      # @param unchecked the `klazz` to be validated
+      def validate_klazz(unchecked)
+        return if unchecked.is_a?(Module) || unchecked.is_a?(String)
+
+        ArgumentError.new("#{unchecked.inspect} must be a Class/Module or a String referencing a Class/Module")
+      end
+
+      # Validate `with` or `block` must be provided and if `with` is provided, it must be a Symbol or Proc
+      #
+      # @param unchecked the `with` to be validated
+      # @param block the `block` to be valiated
       def validate_with(unchecked, block)
         if unchecked.present? && block.present?
           return ArgumentError.new("provide either the with: keyword argument or a block")
@@ -76,9 +92,7 @@ module MimeActor
         unless unchecked.present? || block.present?
           return ArgumentError.new("provide the with: keyword argument or a block")
         end
-
-        return if block.present?
-        return if unchecked.is_a?(Proc) || unchecked.is_a?(Symbol)
+        return if block.present? || unchecked.is_a?(Proc) || unchecked.is_a?(Symbol)
 
         ArgumentError.new("with handler must be a Symbol or Proc, got: #{unchecked.inspect}")
       end

data/lib/mime_actor/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mime_actor
 version: !ruby/object:Gem::Version
-  version: 0.5.3
+  version: 0.6.0
 platform: ruby
 authors:
 - Ryan Chang
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2024-06-29 00:00:00.000000000 Z
+date: 2024-07-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack
@@ -63,6 +63,7 @@ files:
 - ".rspec"
 - ".rubocop.yml"
 - ".ruby-version"
+- ".yardopts"
 - COMPARE.md
 - LICENSE
 - README.md