activefunction-core 0.2.0 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0b2cfe13205db0147f98083ea9d83b4f6ee0a1a1baaec08f848bf7a650a6e844
-  data.tar.gz: 136a5559b4c123ba50c384cfaf4beb05a5a9dca14ae398866e9a98a32d72338c
+  metadata.gz: a1f66462455352552a6c2746a76a215f3a497b04610d05ad43db175d2ac9b811
+  data.tar.gz: ce06fea28a775ef62692599895ca6e96035efa69f7ba02a0f659c7baf499ca48
 SHA512:
-  metadata.gz: 5b2a5470029dc54aab1677f6d08af01d1eaca7673d38003745630a82355e44d810085a66c4f4dbafe50409fb4f2e730e3cacc17384883093943e97169ed4ddfe
-  data.tar.gz: 8865302a689494285e6ffc23ba6197aca98b2ae6ee3049364c8c0084bfeb3a5507df4e5d3d674277037e5b0621b1a42afacad08d94d2604b13c30a7f496af26c
+  metadata.gz: 44a481313a83af1eaf5dd6de1356f8ff7e16d7d49572a812da8eee33b76618dd2afb3811a19d35d6bb1fb75e701d41b62d4b10bc06cef79caef29e278cc4ec0c
+  data.tar.gz: e2a37509372b1d0762b1412eb1ad52b7ed83fa7c2d1ef410e27c308324a0d544095653934ff2c0727e4fc97dcbe7892a303483b3da134cc05cd192c6943edbb7

data/CHANGELOG.md

@@ -11,3 +11,14 @@
 - Added Plugins support
 - Added Hooks plugin - refactored ActiveFunction::Functions::Callbacks implementation.
 
+## [0.2.1] - Yanked due to invalid .rbnext files 
+
+- Fixed Plugins options handling
+
+## [0.2.2]
+
+- Republish 0.2.1
+
+## [0.2.3]
+
+- YARD Doc Added

data/README.md

@@ -57,7 +57,7 @@ Supports options for `before_[method_name]` & `after_[method_name]` callbacks. E
 ```ruby
 
 class YourClass
-  include ActiveFunction::Core::Plugins::Hooks
+  include ActiveFunctionCore::Plugins::Hooks
 
   define_hooks_for :your_method
 

data/lib/.rbnext/2.7/{plugins → active_function_core/plugins}/hooks.rb

@@ -11,15 +11,60 @@ end
 
 module ActiveFunctionCore
   module Plugins
+    # Provides ActiveSupport::Callbacks like DSL for defining before and after callbacks around methods
+    # @see ClassMethods DSL methods.
+    # @example Hooks with default callback options
+    #   class YourClass
+    #     include ActiveFunctionCore::Plugins::Hooks
+    #
+    #     define_hooks_for :your_method
+    #
+    #     before_your_method :do_something_before, if: :condition_met?
+    #     after_your_method :do_something_after, unless: :condition_met?
+    #
+    #     def your_method
+    #       # Method implementation here...
+    #     end
+    #
+    #     private
+    #
+    #     def condition_met?
+    #       # Condition logic here...
+    #     end
+    #
+    #     def do_something_before
+    #       # Callback logic to execute before your_method
+    #     end
+    #
+    #     def do_something_after
+    #       # Callback logic to execute after your_method
+    #     end
+    #   end
+    # @example Hooks with custom callback options
+    #   class YourClass
+    #     include ActiveFunction::Core::Plugins::Hooks
+    #
+    #     set_callback_options only: ->(only_methods, context:) { only_methods.include?(context.action) }
+    #
+    #     define_hooks_for :your_method
+    #
+    #     before_your_method :do_something_before, only: %[foo bar]
+    #
+    #     def action = "foo"
+    #   end
     module Hooks
+      # Represents a hook with callbacks for a specific method.
       class Hook < Data.define(:method_name, :callbacks)
         DEFAULT_CALLBACK_OPTIONS = {
           if:     ->(v, context:) { context.send(v) if context.respond_to?(v, true) },
           unless: ->(v, context:) { !context.send(v) if context.respond_to?(v, true) }
         }.freeze
         SUPPORTED_CALLBACKS      = %i[before after].freeze
-
-        Callback = Data.define(:options, :target) do
+        # Represents a callback with options.
+        Callback                 = Data.define(:options, :target) do
+          # Runs the callback within the specified contex.
+          #
+          # @param context [Object] instance of class with callbacks.
           def run(context)
             raise ArgumentError, "Callback target #{target} is not defined" unless context.respond_to?(target, true)
             raise ArgumentError, ":callback_options is not defined in #{context.class}" unless context.class.respond_to?(:callback_options)
@@ -31,7 +76,7 @@ module ActiveFunctionCore
 
           private def normalized_options(options, context)
             options.map do |option|
-              name, arg = option.first
+              name, arg = option
               -> { context.class.callback_options[name].call(arg, context: context) }
             end
           end
@@ -41,6 +86,14 @@ module ActiveFunctionCore
           super(callbacks: callbacks.to_h { |_1| [_1, []] }, **__kwrest__)
         end
 
+        # Adds a callback to the hook.
+        #
+        # @param type [Symbol] the type of callback, `:before` or `:after`
+        # @param target [Symbol] the name of the callback method.
+        # @param options [Hash] the options for the callback.
+        # @options options [Symbol] :if the name of the method to check before executing the callback.
+        # @options options [Symbol] :unless the name of the method to check before executing the callback.
+        # @raise [ArgumentError] if callback already defined.
         def add_callback(type:, target:, options: {})
           callbacks[type] << Callback[options, target].tap do |callback|
             next unless callbacks[type].map(&:hash).to_set === callback.hash
@@ -49,6 +102,11 @@ module ActiveFunctionCore
           end
         end
 
+        # Runs all callbacks for the hook.
+        #
+        # @param context [Object] instance of class with defined hook.
+        # @yield [*args] block of code around which callbacks will be executed.
+        # @return the result of the block.
         def run_callbacks(context, &block)
           callbacks[:before].each { |it| it.run(context) }
 
@@ -60,24 +118,33 @@ module ActiveFunctionCore
         end
       end
 
-      def self.included(base)
-        base.extend(ClassMethods)
-      end
-
+      # DSL method for {ActiveFunctionCore::Plugins::Hooks}
       module ClassMethods
+        # Returns all setuped hooks for the class.
         def hooks            ;  @__hooks ||= {}; end
+
+        # Returns all setuped custom callback options for the class.
         def callback_options ;  @__callback_options ||= Hook::DEFAULT_CALLBACK_OPTIONS.dup; end
 
+        # Inherited callback to ensure that callbacks are inherited from the base class.
         def inherited(subclass)
           subclass.instance_variable_set(:@__hooks, Marshal.load(Marshal.dump(hooks)))
           subclass.instance_variable_set(:@__callback_options, callback_options.dup)
         end
 
+        # Setups hooks for provided method.
         # Redefines method providing callbacks calls around it.
-        # Defines `before_[name]` and `after_[name]` methods for setting callbacks.
+        # Defines *before_[name]* and *after_[name]* methods for setting callbacks.
+        #
+        # @example
+        #   define_hooks_for :process, name: :action
+        #   before_action :set_first
+        #   after_action :set_last, if: :ok?
         #
         # @param method [Symbol] the name of the callbackable method.
         # @param name [Symbol] alias for hooked method before_[name] & after_[name] methods.
+        # @raise [ArgumentError] if hook for method already defined.
+        # @raise [ArgumentError] if method is not defined.
         def define_hooks_for(method, name: method)
           raise(ArgumentError, "Hook for #{method} are already defined") if hooks.key?(method)
           raise(ArgumentError, "Method #{method} is not defined") unless method_defined?(method)
@@ -101,21 +168,35 @@ module ActiveFunctionCore
 
         # Sets a callback for an existing hook'ed method.
         #
+        # @example
+        #   define_hooks_for :action
+        #   set_callback :before, :action, :set_first
+        #
         # @param type [Symbol] the type of callback, `:before` or `:after`
         # @param method_name [Symbol] the name of the callbackable method.
         # @param target [Symbol] the name of the callback method.
         # @param options [Hash] the options for the callback.
-        # @options options [Symbol] :if the name of the method to check before executing the callback.
+        # @option options [Symbol] :if the name of the booled method to call before executing the callback.
+        # @option options [Symbol] :unless the name of the booled method to call before executing the callback.
+        # @raise [ArgumentError] if hook for provided method is not setuped via ::define_hooks_for.
+        # @raise [ArgumentError] if unsupported @options was passed.
         def set_callback(type, method_name, target, options = {})
           raise(ArgumentError, "Hook for :#{method_name} is not defined") unless hooks.key?(method_name)
-          raise(ArgumentError, "Hook Callback accepts only #{options.keys} options") if (options.keys - callback_options.keys).any?
+          raise(ArgumentError, "Hook Callback accepts only #{callback_options.keys} options") if (options.keys - callback_options.keys).any?
 
           hooks[method_name].add_callback(type: type, target: target, options: options)
         end
 
         # Sets a custom callback option.
         #
-        # @param name [Symbol] the name of the option.
+        # @example
+        #   set_callback_option only: ->(args, context:) { args.to_set === context.current_action }
+        #   define_hooks_for :action
+        #   before_action :set_first, only: :index
+        #
+        # @param option [Hash{Symbol => Proc}] The custom callback option as a single-value hash.
+        #   - :name [Symbol] The name of the option.
+        #   - :block [Proc] The block to call.
         # @yield [*attrs, context:] the block to call.
         # @yieldparam attrs [*] the attributes passed to the option.
         # @yieldparam context [Object] the instance context (optional).
@@ -125,6 +206,10 @@ module ActiveFunctionCore
           callback_options[name] = block
         end
       end
+
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
     end
   end
 end

data/lib/.rbnext/3.0/{plugins → active_function_core/plugins}/hooks.rb

@@ -11,15 +11,60 @@ end
 
 module ActiveFunctionCore
   module Plugins
+    # Provides ActiveSupport::Callbacks like DSL for defining before and after callbacks around methods
+    # @see ClassMethods DSL methods.
+    # @example Hooks with default callback options
+    #   class YourClass
+    #     include ActiveFunctionCore::Plugins::Hooks
+    #
+    #     define_hooks_for :your_method
+    #
+    #     before_your_method :do_something_before, if: :condition_met?
+    #     after_your_method :do_something_after, unless: :condition_met?
+    #
+    #     def your_method
+    #       # Method implementation here...
+    #     end
+    #
+    #     private
+    #
+    #     def condition_met?
+    #       # Condition logic here...
+    #     end
+    #
+    #     def do_something_before
+    #       # Callback logic to execute before your_method
+    #     end
+    #
+    #     def do_something_after
+    #       # Callback logic to execute after your_method
+    #     end
+    #   end
+    # @example Hooks with custom callback options
+    #   class YourClass
+    #     include ActiveFunction::Core::Plugins::Hooks
+    #
+    #     set_callback_options only: ->(only_methods, context:) { only_methods.include?(context.action) }
+    #
+    #     define_hooks_for :your_method
+    #
+    #     before_your_method :do_something_before, only: %[foo bar]
+    #
+    #     def action = "foo"
+    #   end
     module Hooks
+      # Represents a hook with callbacks for a specific method.
       class Hook < Data.define(:method_name, :callbacks)
         DEFAULT_CALLBACK_OPTIONS = {
           if:     ->(v, context:) { context.send(v) if context.respond_to?(v, true) },
           unless: ->(v, context:) { !context.send(v) if context.respond_to?(v, true) }
         }.freeze
         SUPPORTED_CALLBACKS      = %i[before after].freeze
-
-        Callback = Data.define(:options, :target) do
+        # Represents a callback with options.
+        Callback                 = Data.define(:options, :target) do
+          # Runs the callback within the specified contex.
+          #
+          # @param context [Object] instance of class with callbacks.
           def run(context)
             raise ArgumentError, "Callback target #{target} is not defined" unless context.respond_to?(target, true)
             raise ArgumentError, ":callback_options is not defined in #{context.class}" unless context.class.respond_to?(:callback_options)
@@ -31,7 +76,7 @@ module ActiveFunctionCore
 
           private def normalized_options(options, context)
             options.map do |option|
-              name, arg = option.first
+              name, arg = option
               -> { context.class.callback_options[name].call(arg, context: context) }
             end
           end
@@ -41,6 +86,14 @@ module ActiveFunctionCore
           super(callbacks: callbacks.to_h { [_1, []] }, **__kwrest__)
         end
 
+        # Adds a callback to the hook.
+        #
+        # @param type [Symbol] the type of callback, `:before` or `:after`
+        # @param target [Symbol] the name of the callback method.
+        # @param options [Hash] the options for the callback.
+        # @options options [Symbol] :if the name of the method to check before executing the callback.
+        # @options options [Symbol] :unless the name of the method to check before executing the callback.
+        # @raise [ArgumentError] if callback already defined.
         def add_callback(type:, target:, options: {})
           callbacks[type] << Callback[options, target].tap do |callback|
             next unless callbacks[type].map(&:hash).to_set === callback.hash
@@ -49,6 +102,11 @@ module ActiveFunctionCore
           end
         end
 
+        # Runs all callbacks for the hook.
+        #
+        # @param context [Object] instance of class with defined hook.
+        # @yield [*args] block of code around which callbacks will be executed.
+        # @return the result of the block.
         def run_callbacks(context, &block)
           callbacks[:before].each { |it| it.run(context) }
 
@@ -60,24 +118,33 @@ module ActiveFunctionCore
         end
       end
 
-      def self.included(base)
-        base.extend(ClassMethods)
-      end
-
+      # DSL method for {ActiveFunctionCore::Plugins::Hooks}
       module ClassMethods
+        # Returns all setuped hooks for the class.
         def hooks            ;  @__hooks ||= {}; end
+
+        # Returns all setuped custom callback options for the class.
         def callback_options ;  @__callback_options ||= Hook::DEFAULT_CALLBACK_OPTIONS.dup; end
 
+        # Inherited callback to ensure that callbacks are inherited from the base class.
         def inherited(subclass)
           subclass.instance_variable_set(:@__hooks, Marshal.load(Marshal.dump(hooks)))
           subclass.instance_variable_set(:@__callback_options, callback_options.dup)
         end
 
+        # Setups hooks for provided method.
         # Redefines method providing callbacks calls around it.
-        # Defines `before_[name]` and `after_[name]` methods for setting callbacks.
+        # Defines *before_[name]* and *after_[name]* methods for setting callbacks.
+        #
+        # @example
+        #   define_hooks_for :process, name: :action
+        #   before_action :set_first
+        #   after_action :set_last, if: :ok?
         #
         # @param method [Symbol] the name of the callbackable method.
         # @param name [Symbol] alias for hooked method before_[name] & after_[name] methods.
+        # @raise [ArgumentError] if hook for method already defined.
+        # @raise [ArgumentError] if method is not defined.
         def define_hooks_for(method, name: method)
           raise(ArgumentError, "Hook for #{method} are already defined") if hooks.key?(method)
           raise(ArgumentError, "Method #{method} is not defined") unless method_defined?(method)
@@ -101,21 +168,35 @@ module ActiveFunctionCore
 
         # Sets a callback for an existing hook'ed method.
         #
+        # @example
+        #   define_hooks_for :action
+        #   set_callback :before, :action, :set_first
+        #
         # @param type [Symbol] the type of callback, `:before` or `:after`
         # @param method_name [Symbol] the name of the callbackable method.
         # @param target [Symbol] the name of the callback method.
         # @param options [Hash] the options for the callback.
-        # @options options [Symbol] :if the name of the method to check before executing the callback.
+        # @option options [Symbol] :if the name of the booled method to call before executing the callback.
+        # @option options [Symbol] :unless the name of the booled method to call before executing the callback.
+        # @raise [ArgumentError] if hook for provided method is not setuped via ::define_hooks_for.
+        # @raise [ArgumentError] if unsupported @options was passed.
         def set_callback(type, method_name, target, options = {})
           raise(ArgumentError, "Hook for :#{method_name} is not defined") unless hooks.key?(method_name)
-          raise(ArgumentError, "Hook Callback accepts only #{options.keys} options") if (options.keys - callback_options.keys).any?
+          raise(ArgumentError, "Hook Callback accepts only #{callback_options.keys} options") if (options.keys - callback_options.keys).any?
 
           hooks[method_name].add_callback(type: type, target: target, options: options)
         end
 
         # Sets a custom callback option.
         #
-        # @param name [Symbol] the name of the option.
+        # @example
+        #   set_callback_option only: ->(args, context:) { args.to_set === context.current_action }
+        #   define_hooks_for :action
+        #   before_action :set_first, only: :index
+        #
+        # @param option [Hash{Symbol => Proc}] The custom callback option as a single-value hash.
+        #   - :name [Symbol] The name of the option.
+        #   - :block [Proc] The block to call.
         # @yield [*attrs, context:] the block to call.
         # @yieldparam attrs [*] the attributes passed to the option.
         # @yieldparam context [Object] the instance context (optional).
@@ -125,6 +206,10 @@ module ActiveFunctionCore
           callback_options[name] = block
         end
       end
+
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
     end
   end
 end

data/lib/.rbnext/3.1/{plugins → active_function_core/plugins}/hooks.rb

@@ -11,15 +11,60 @@ end
 
 module ActiveFunctionCore
   module Plugins
+    # Provides ActiveSupport::Callbacks like DSL for defining before and after callbacks around methods
+    # @see ClassMethods DSL methods.
+    # @example Hooks with default callback options
+    #   class YourClass
+    #     include ActiveFunctionCore::Plugins::Hooks
+    #
+    #     define_hooks_for :your_method
+    #
+    #     before_your_method :do_something_before, if: :condition_met?
+    #     after_your_method :do_something_after, unless: :condition_met?
+    #
+    #     def your_method
+    #       # Method implementation here...
+    #     end
+    #
+    #     private
+    #
+    #     def condition_met?
+    #       # Condition logic here...
+    #     end
+    #
+    #     def do_something_before
+    #       # Callback logic to execute before your_method
+    #     end
+    #
+    #     def do_something_after
+    #       # Callback logic to execute after your_method
+    #     end
+    #   end
+    # @example Hooks with custom callback options
+    #   class YourClass
+    #     include ActiveFunction::Core::Plugins::Hooks
+    #
+    #     set_callback_options only: ->(only_methods, context:) { only_methods.include?(context.action) }
+    #
+    #     define_hooks_for :your_method
+    #
+    #     before_your_method :do_something_before, only: %[foo bar]
+    #
+    #     def action = "foo"
+    #   end
     module Hooks
+      # Represents a hook with callbacks for a specific method.
       class Hook < Data.define(:method_name, :callbacks)
         DEFAULT_CALLBACK_OPTIONS = {
           if:     ->(v, context:) { context.send(v) if context.respond_to?(v, true) },
           unless: ->(v, context:) { !context.send(v) if context.respond_to?(v, true) }
         }.freeze
         SUPPORTED_CALLBACKS      = %i[before after].freeze
-
-        Callback = Data.define(:options, :target) do
+        # Represents a callback with options.
+        Callback                 = Data.define(:options, :target) do
+          # Runs the callback within the specified contex.
+          #
+          # @param context [Object] instance of class with callbacks.
           def run(context)
             raise ArgumentError, "Callback target #{target} is not defined" unless context.respond_to?(target, true)
             raise ArgumentError, ":callback_options is not defined in #{context.class}" unless context.class.respond_to?(:callback_options)
@@ -31,7 +76,7 @@ module ActiveFunctionCore
 
           private def normalized_options(options, context)
             options.map do |option|
-              name, arg = option.first
+              name, arg = option
               -> { context.class.callback_options[name].call(arg, context: context) }
             end
           end
@@ -41,6 +86,14 @@ module ActiveFunctionCore
           super(callbacks: callbacks.to_h { [_1, []] }, **__kwrest__)
         end
 
+        # Adds a callback to the hook.
+        #
+        # @param type [Symbol] the type of callback, `:before` or `:after`
+        # @param target [Symbol] the name of the callback method.
+        # @param options [Hash] the options for the callback.
+        # @options options [Symbol] :if the name of the method to check before executing the callback.
+        # @options options [Symbol] :unless the name of the method to check before executing the callback.
+        # @raise [ArgumentError] if callback already defined.
         def add_callback(type:, target:, options: {})
           callbacks[type] << Callback[options, target].tap do |callback|
             next unless callbacks[type].map(&:hash).to_set === callback.hash
@@ -49,6 +102,11 @@ module ActiveFunctionCore
           end
         end
 
+        # Runs all callbacks for the hook.
+        #
+        # @param context [Object] instance of class with defined hook.
+        # @yield [*args] block of code around which callbacks will be executed.
+        # @return the result of the block.
         def run_callbacks(context, &block)
           callbacks[:before].each { |it| it.run(context) }
 
@@ -60,24 +118,33 @@ module ActiveFunctionCore
         end
       end
 
-      def self.included(base)
-        base.extend(ClassMethods)
-      end
-
+      # DSL method for {ActiveFunctionCore::Plugins::Hooks}
       module ClassMethods
+        # Returns all setuped hooks for the class.
         def hooks            = @__hooks ||= {}
+
+        # Returns all setuped custom callback options for the class.
         def callback_options = @__callback_options ||= Hook::DEFAULT_CALLBACK_OPTIONS.dup
 
+        # Inherited callback to ensure that callbacks are inherited from the base class.
         def inherited(subclass)
           subclass.instance_variable_set(:@__hooks, Marshal.load(Marshal.dump(hooks)))
           subclass.instance_variable_set(:@__callback_options, callback_options.dup)
         end
 
+        # Setups hooks for provided method.
         # Redefines method providing callbacks calls around it.
-        # Defines `before_[name]` and `after_[name]` methods for setting callbacks.
+        # Defines *before_[name]* and *after_[name]* methods for setting callbacks.
+        #
+        # @example
+        #   define_hooks_for :process, name: :action
+        #   before_action :set_first
+        #   after_action :set_last, if: :ok?
         #
         # @param method [Symbol] the name of the callbackable method.
         # @param name [Symbol] alias for hooked method before_[name] & after_[name] methods.
+        # @raise [ArgumentError] if hook for method already defined.
+        # @raise [ArgumentError] if method is not defined.
         def define_hooks_for(method, name: method)
           raise(ArgumentError, "Hook for #{method} are already defined") if hooks.key?(method)
           raise(ArgumentError, "Method #{method} is not defined") unless method_defined?(method)
@@ -101,21 +168,35 @@ module ActiveFunctionCore
 
         # Sets a callback for an existing hook'ed method.
         #
+        # @example
+        #   define_hooks_for :action
+        #   set_callback :before, :action, :set_first
+        #
         # @param type [Symbol] the type of callback, `:before` or `:after`
         # @param method_name [Symbol] the name of the callbackable method.
         # @param target [Symbol] the name of the callback method.
         # @param options [Hash] the options for the callback.
-        # @options options [Symbol] :if the name of the method to check before executing the callback.
+        # @option options [Symbol] :if the name of the booled method to call before executing the callback.
+        # @option options [Symbol] :unless the name of the booled method to call before executing the callback.
+        # @raise [ArgumentError] if hook for provided method is not setuped via ::define_hooks_for.
+        # @raise [ArgumentError] if unsupported @options was passed.
         def set_callback(type, method_name, target, options = {})
           raise(ArgumentError, "Hook for :#{method_name} is not defined") unless hooks.key?(method_name)
-          raise(ArgumentError, "Hook Callback accepts only #{options.keys} options") if (options.keys - callback_options.keys).any?
+          raise(ArgumentError, "Hook Callback accepts only #{callback_options.keys} options") if (options.keys - callback_options.keys).any?
 
           hooks[method_name].add_callback(type: type, target: target, options: options)
         end
 
         # Sets a custom callback option.
         #
-        # @param name [Symbol] the name of the option.
+        # @example
+        #   set_callback_option only: ->(args, context:) { args.to_set === context.current_action }
+        #   define_hooks_for :action
+        #   before_action :set_first, only: :index
+        #
+        # @param option [Hash{Symbol => Proc}] The custom callback option as a single-value hash.
+        #   - :name [Symbol] The name of the option.
+        #   - :block [Proc] The block to call.
         # @yield [*attrs, context:] the block to call.
         # @yieldparam attrs [*] the attributes passed to the option.
         # @yieldparam context [Object] the instance context (optional).
@@ -125,6 +206,10 @@ module ActiveFunctionCore
           callback_options[name] = block
         end
       end
+
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
     end
   end
 end

data/lib/.rbnext/3.2/{plugins → active_function_core/plugins}/hooks.rb

@@ -11,15 +11,60 @@ end
 
 module ActiveFunctionCore
   module Plugins
+    # Provides ActiveSupport::Callbacks like DSL for defining before and after callbacks around methods
+    # @see ClassMethods DSL methods.
+    # @example Hooks with default callback options
+    #   class YourClass
+    #     include ActiveFunctionCore::Plugins::Hooks
+    #
+    #     define_hooks_for :your_method
+    #
+    #     before_your_method :do_something_before, if: :condition_met?
+    #     after_your_method :do_something_after, unless: :condition_met?
+    #
+    #     def your_method
+    #       # Method implementation here...
+    #     end
+    #
+    #     private
+    #
+    #     def condition_met?
+    #       # Condition logic here...
+    #     end
+    #
+    #     def do_something_before
+    #       # Callback logic to execute before your_method
+    #     end
+    #
+    #     def do_something_after
+    #       # Callback logic to execute after your_method
+    #     end
+    #   end
+    # @example Hooks with custom callback options
+    #   class YourClass
+    #     include ActiveFunction::Core::Plugins::Hooks
+    #
+    #     set_callback_options only: ->(only_methods, context:) { only_methods.include?(context.action) }
+    #
+    #     define_hooks_for :your_method
+    #
+    #     before_your_method :do_something_before, only: %[foo bar]
+    #
+    #     def action = "foo"
+    #   end
     module Hooks
+      # Represents a hook with callbacks for a specific method.
       class Hook < Data.define(:method_name, :callbacks)
         DEFAULT_CALLBACK_OPTIONS = {
           if:     ->(v, context:) { context.send(v) if context.respond_to?(v, true) },
           unless: ->(v, context:) { !context.send(v) if context.respond_to?(v, true) }
         }.freeze
         SUPPORTED_CALLBACKS      = %i[before after].freeze
-
-        Callback = Data.define(:options, :target) do
+        # Represents a callback with options.
+        Callback                 = Data.define(:options, :target) do
+          # Runs the callback within the specified contex.
+          #
+          # @param context [Object] instance of class with callbacks.
           def run(context)
             raise ArgumentError, "Callback target #{target} is not defined" unless context.respond_to?(target, true)
             raise ArgumentError, ":callback_options is not defined in #{context.class}" unless context.class.respond_to?(:callback_options)
@@ -31,7 +76,7 @@ module ActiveFunctionCore
 
           private def normalized_options(options, context)
             options.map do |option|
-              name, arg = option.first
+              name, arg = option
               -> { context.class.callback_options[name].call(arg, context:) }
             end
           end
@@ -41,6 +86,14 @@ module ActiveFunctionCore
           super(callbacks: callbacks.to_h { [_1, []] }, **__kwrest__)
         end
 
+        # Adds a callback to the hook.
+        #
+        # @param type [Symbol] the type of callback, `:before` or `:after`
+        # @param target [Symbol] the name of the callback method.
+        # @param options [Hash] the options for the callback.
+        # @options options [Symbol] :if the name of the method to check before executing the callback.
+        # @options options [Symbol] :unless the name of the method to check before executing the callback.
+        # @raise [ArgumentError] if callback already defined.
         def add_callback(type:, target:, options: {})
           callbacks[type] << Callback[options, target].tap do |callback|
             next unless callbacks[type].map(&:hash).to_set === callback.hash
@@ -49,6 +102,11 @@ module ActiveFunctionCore
           end
         end
 
+        # Runs all callbacks for the hook.
+        #
+        # @param context [Object] instance of class with defined hook.
+        # @yield [*args] block of code around which callbacks will be executed.
+        # @return the result of the block.
         def run_callbacks(context, &block)
           callbacks[:before].each { |it| it.run(context) }
 
@@ -60,24 +118,33 @@ module ActiveFunctionCore
         end
       end
 
-      def self.included(base)
-        base.extend(ClassMethods)
-      end
-
+      # DSL method for {ActiveFunctionCore::Plugins::Hooks}
       module ClassMethods
+        # Returns all setuped hooks for the class.
         def hooks            = @__hooks ||= {}
+
+        # Returns all setuped custom callback options for the class.
         def callback_options = @__callback_options ||= Hook::DEFAULT_CALLBACK_OPTIONS.dup
 
+        # Inherited callback to ensure that callbacks are inherited from the base class.
         def inherited(subclass)
           subclass.instance_variable_set(:@__hooks, Marshal.load(Marshal.dump(hooks)))
           subclass.instance_variable_set(:@__callback_options, callback_options.dup)
         end
 
+        # Setups hooks for provided method.
         # Redefines method providing callbacks calls around it.
-        # Defines `before_[name]` and `after_[name]` methods for setting callbacks.
+        # Defines *before_[name]* and *after_[name]* methods for setting callbacks.
+        #
+        # @example
+        #   define_hooks_for :process, name: :action
+        #   before_action :set_first
+        #   after_action :set_last, if: :ok?
         #
         # @param method [Symbol] the name of the callbackable method.
         # @param name [Symbol] alias for hooked method before_[name] & after_[name] methods.
+        # @raise [ArgumentError] if hook for method already defined.
+        # @raise [ArgumentError] if method is not defined.
         def define_hooks_for(method, name: method)
           raise(ArgumentError, "Hook for #{method} are already defined") if hooks.key?(method)
           raise(ArgumentError, "Method #{method} is not defined") unless method_defined?(method)
@@ -101,21 +168,35 @@ module ActiveFunctionCore
 
         # Sets a callback for an existing hook'ed method.
         #
+        # @example
+        #   define_hooks_for :action
+        #   set_callback :before, :action, :set_first
+        #
         # @param type [Symbol] the type of callback, `:before` or `:after`
         # @param method_name [Symbol] the name of the callbackable method.
         # @param target [Symbol] the name of the callback method.
         # @param options [Hash] the options for the callback.
-        # @options options [Symbol] :if the name of the method to check before executing the callback.
+        # @option options [Symbol] :if the name of the booled method to call before executing the callback.
+        # @option options [Symbol] :unless the name of the booled method to call before executing the callback.
+        # @raise [ArgumentError] if hook for provided method is not setuped via ::define_hooks_for.
+        # @raise [ArgumentError] if unsupported @options was passed.
         def set_callback(type, method_name, target, options = {})
           raise(ArgumentError, "Hook for :#{method_name} is not defined") unless hooks.key?(method_name)
-          raise(ArgumentError, "Hook Callback accepts only #{options.keys} options") if (options.keys - callback_options.keys).any?
+          raise(ArgumentError, "Hook Callback accepts only #{callback_options.keys} options") if (options.keys - callback_options.keys).any?
 
           hooks[method_name].add_callback(type:, target:, options:)
         end
 
         # Sets a custom callback option.
         #
-        # @param name [Symbol] the name of the option.
+        # @example
+        #   set_callback_option only: ->(args, context:) { args.to_set === context.current_action }
+        #   define_hooks_for :action
+        #   before_action :set_first, only: :index
+        #
+        # @param option [Hash{Symbol => Proc}] The custom callback option as a single-value hash.
+        #   - :name [Symbol] The name of the option.
+        #   - :block [Proc] The block to call.
         # @yield [*attrs, context:] the block to call.
         # @yieldparam attrs [*] the attributes passed to the option.
         # @yieldparam context [Object] the instance context (optional).
@@ -125,6 +206,10 @@ module ActiveFunctionCore
           callback_options[name] = block
         end
       end
+
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
     end
   end
 end

data/lib/{plugins → active_function_core/plugins}/hooks.rb

@@ -11,15 +11,60 @@ end
 
 module ActiveFunctionCore
   module Plugins
+    # Provides ActiveSupport::Callbacks like DSL for defining before and after callbacks around methods
+    # @see ClassMethods DSL methods.
+    # @example Hooks with default callback options
+    #   class YourClass
+    #     include ActiveFunctionCore::Plugins::Hooks
+    #
+    #     define_hooks_for :your_method
+    #
+    #     before_your_method :do_something_before, if: :condition_met?
+    #     after_your_method :do_something_after, unless: :condition_met?
+    #
+    #     def your_method
+    #       # Method implementation here...
+    #     end
+    #
+    #     private
+    #
+    #     def condition_met?
+    #       # Condition logic here...
+    #     end
+    #
+    #     def do_something_before
+    #       # Callback logic to execute before your_method
+    #     end
+    #
+    #     def do_something_after
+    #       # Callback logic to execute after your_method
+    #     end
+    #   end
+    # @example Hooks with custom callback options
+    #   class YourClass
+    #     include ActiveFunction::Core::Plugins::Hooks
+    #
+    #     set_callback_options only: ->(only_methods, context:) { only_methods.include?(context.action) }
+    #
+    #     define_hooks_for :your_method
+    #
+    #     before_your_method :do_something_before, only: %[foo bar]
+    #
+    #     def action = "foo"
+    #   end
     module Hooks
+      # Represents a hook with callbacks for a specific method.
       class Hook < Data.define(:method_name, :callbacks)
         DEFAULT_CALLBACK_OPTIONS = {
           if:     ->(v, context:) { context.send(v) if context.respond_to?(v, true) },
           unless: ->(v, context:) { !context.send(v) if context.respond_to?(v, true) }
         }.freeze
         SUPPORTED_CALLBACKS      = %i[before after].freeze
-
-        Callback = Data.define(:options, :target) do
+        # Represents a callback with options.
+        Callback                 = Data.define(:options, :target) do
+          # Runs the callback within the specified contex.
+          #
+          # @param context [Object] instance of class with callbacks.
           def run(context)
             raise ArgumentError, "Callback target #{target} is not defined" unless context.respond_to?(target, true)
             raise ArgumentError, ":callback_options is not defined in #{context.class}" unless context.class.respond_to?(:callback_options)
@@ -31,7 +76,7 @@ module ActiveFunctionCore
 
           private def normalized_options(options, context)
             options.map do |option|
-              name, arg = option.first
+              name, arg = option
               -> { context.class.callback_options[name].call(arg, context:) }
             end
           end
@@ -41,6 +86,14 @@ module ActiveFunctionCore
           super(callbacks: callbacks.to_h { [_1, []] }, **)
         end
 
+        # Adds a callback to the hook.
+        #
+        # @param type [Symbol] the type of callback, `:before` or `:after`
+        # @param target [Symbol] the name of the callback method.
+        # @param options [Hash] the options for the callback.
+        # @options options [Symbol] :if the name of the method to check before executing the callback.
+        # @options options [Symbol] :unless the name of the method to check before executing the callback.
+        # @raise [ArgumentError] if callback already defined.
         def add_callback(type:, target:, options: {})
           callbacks[type] << Callback[options, target].tap do |callback|
             next unless callbacks[type].map(&:hash).to_set === callback.hash
@@ -49,6 +102,11 @@ module ActiveFunctionCore
           end
         end
 
+        # Runs all callbacks for the hook.
+        #
+        # @param context [Object] instance of class with defined hook.
+        # @yield [*args] block of code around which callbacks will be executed.
+        # @return the result of the block.
         def run_callbacks(context, &block)
           callbacks[:before].each { |it| it.run(context) }
 
@@ -60,24 +118,33 @@ module ActiveFunctionCore
         end
       end
 
-      def self.included(base)
-        base.extend(ClassMethods)
-      end
-
+      # DSL method for {ActiveFunctionCore::Plugins::Hooks}
       module ClassMethods
+        # Returns all setuped hooks for the class.
         def hooks            = @__hooks ||= {}
+
+        # Returns all setuped custom callback options for the class.
         def callback_options = @__callback_options ||= Hook::DEFAULT_CALLBACK_OPTIONS.dup
 
+        # Inherited callback to ensure that callbacks are inherited from the base class.
         def inherited(subclass)
           subclass.instance_variable_set(:@__hooks, Marshal.load(Marshal.dump(hooks)))
           subclass.instance_variable_set(:@__callback_options, callback_options.dup)
         end
 
+        # Setups hooks for provided method.
         # Redefines method providing callbacks calls around it.
-        # Defines `before_[name]` and `after_[name]` methods for setting callbacks.
+        # Defines *before_[name]* and *after_[name]* methods for setting callbacks.
+        #
+        # @example
+        #   define_hooks_for :process, name: :action
+        #   before_action :set_first
+        #   after_action :set_last, if: :ok?
         #
         # @param method [Symbol] the name of the callbackable method.
         # @param name [Symbol] alias for hooked method before_[name] & after_[name] methods.
+        # @raise [ArgumentError] if hook for method already defined.
+        # @raise [ArgumentError] if method is not defined.
         def define_hooks_for(method, name: method)
           raise(ArgumentError, "Hook for #{method} are already defined") if hooks.key?(method)
           raise(ArgumentError, "Method #{method} is not defined") unless method_defined?(method)
@@ -101,21 +168,35 @@ module ActiveFunctionCore
 
         # Sets a callback for an existing hook'ed method.
         #
+        # @example
+        #   define_hooks_for :action
+        #   set_callback :before, :action, :set_first
+        #
         # @param type [Symbol] the type of callback, `:before` or `:after`
         # @param method_name [Symbol] the name of the callbackable method.
         # @param target [Symbol] the name of the callback method.
         # @param options [Hash] the options for the callback.
-        # @options options [Symbol] :if the name of the method to check before executing the callback.
+        # @option options [Symbol] :if the name of the booled method to call before executing the callback.
+        # @option options [Symbol] :unless the name of the booled method to call before executing the callback.
+        # @raise [ArgumentError] if hook for provided method is not setuped via ::define_hooks_for.
+        # @raise [ArgumentError] if unsupported @options was passed.
         def set_callback(type, method_name, target, options = {})
           raise(ArgumentError, "Hook for :#{method_name} is not defined") unless hooks.key?(method_name)
-          raise(ArgumentError, "Hook Callback accepts only #{options.keys} options") if (options.keys - callback_options.keys).any?
+          raise(ArgumentError, "Hook Callback accepts only #{callback_options.keys} options") if (options.keys - callback_options.keys).any?
 
           hooks[method_name].add_callback(type:, target:, options:)
         end
 
         # Sets a custom callback option.
         #
-        # @param name [Symbol] the name of the option.
+        # @example
+        #   set_callback_option only: ->(args, context:) { args.to_set === context.current_action }
+        #   define_hooks_for :action
+        #   before_action :set_first, only: :index
+        #
+        # @param option [Hash{Symbol => Proc}] The custom callback option as a single-value hash.
+        #   - :name [Symbol] The name of the option.
+        #   - :block [Proc] The block to call.
         # @yield [*attrs, context:] the block to call.
         # @yieldparam attrs [*] the attributes passed to the option.
         # @yieldparam context [Object] the instance context (optional).
@@ -125,6 +206,10 @@ module ActiveFunctionCore
           callback_options[name] = block
         end
       end
+
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
     end
   end
 end

data/lib/active_function_core/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ActiveFunctionCore
-  VERSION = "0.2.0"
+  VERSION = "0.2.3"
 end

data/lib/active_function_core.rb

@@ -7,7 +7,5 @@ RubyNext::Language.setup_gem_load_path(transpile: true)
 module ActiveFunctionCore
   Error = Class.new(StandardError)
 
-  require "plugins/hooks"
-
   require "active_function_core/version"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: activefunction-core
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.3
 platform: ruby
 authors:
 - Nerbyk
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-01-10 00:00:00.000000000 Z
+date: 2024-01-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby-next
@@ -34,22 +34,23 @@ files:
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
-- lib/.rbnext/2.7/plugins/hooks.rb
-- lib/.rbnext/3.0/plugins/hooks.rb
-- lib/.rbnext/3.1/plugins/hooks.rb
-- lib/.rbnext/3.2/plugins/hooks.rb
+- lib/.rbnext/2.7/active_function_core/plugins/hooks.rb
+- lib/.rbnext/3.0/active_function_core/plugins/hooks.rb
+- lib/.rbnext/3.1/active_function_core/plugins/hooks.rb
+- lib/.rbnext/3.2/active_function_core/plugins/hooks.rb
 - lib/active_function_core.rb
+- lib/active_function_core/plugins/hooks.rb
 - lib/active_function_core/version.rb
-- lib/plugins/hooks.rb
 - sig/active_function_core.rbs
 - sig/manifest.yml
 homepage: https://github.com/DanilMaximov/activefunction
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/DanilMaximov/activefunction-core
-  source_code_uri: https://github.com/DanilMaximov/activefunction-core
-  changelog_uri: https://github.com/DanilMaximov/activefunction-core/CHANGELOG.md
+  homepage_uri: https://github.com/DanilMaximov/activefunction/tree/master/gems/activefunction-core
+  source_code_uri: https://github.com/DanilMaximov/activefunction/tree/master/gems/activefunction-core
+  changelog_uri: https://github.com/DanilMaximov/activefunction/tree/master/gems/activefunction-core/CHANGELOG.md
+  documentation_uri: https://github.com/DanilMaximov/activefunction/tree/master/gems/activefunction-core
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -65,7 +66,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.6
+rubygems_version: 3.5.4
 signing_key: 
 specification_version: 4
 summary: ActiveFunction core gem