activefunction-core 0.2.2 → 0.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3a045fbb4310661d2138bc88e36d439cc3550ad2cc624ff3926a5fb318b401be
-  data.tar.gz: 4998dcbf2e70ccd30faf4dae572c4603eebb7089bf779a1e12722a7f3a1b78c7
+  metadata.gz: 8a465c40b90d43fd3c76b4317525e8d17e3550eca9d63b17f876bf020bb9a32c
+  data.tar.gz: a97b604efa34aa7ddc56bc0c9bf15becbbe50fe953e572a1195d0cdf5a0585b0
 SHA512:
-  metadata.gz: 2dd8fd3d26f7a265de9b86d514697b12d6eda475cafbd06fb09918a0aa67d0b0aed7245b0c785a8689e4d7f3ccf678c6f4522790c4c1084607e06545a9eeff91
-  data.tar.gz: aef48c75c71d2b71e72489e63480c5565e445ee0483e42444789303b9f82b217af0d862f7d541699eb1407ac321605c99d0edfda017e05697034eeaed40ba782
+  metadata.gz: 03d8ae8f232799054b8452a71fb070021cd44b10d0b6dbcf1ee4dd85308266ede988cffdcf9d8447bd60a5eb2d92601bd740c5eb4d9775c885e8434ce4760f61
+  data.tar.gz: 623a32ed667bd7ef18006b619b6aafb025ebd232fe12bc111a9a8f5526e61cc23216a7637b6d31546b56cd379a0878374d00a8183e6c7737f121ebbdf3e246eb

data/CHANGELOG.md

@@ -19,3 +19,9 @@
 
 - Republish 0.2.1
 
+## [0.2.3]
+
+- YARD Doc Added
+
+## [0.2.4]
+- Fix Plugins

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)
@@ -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,11 +168,18 @@ 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 #{callback_options.keys} options") if (options.keys - callback_options.keys).any?
@@ -115,7 +189,14 @@ module ActiveFunctionCore
 
         # 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)
@@ -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,11 +168,18 @@ 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 #{callback_options.keys} options") if (options.keys - callback_options.keys).any?
@@ -115,7 +189,14 @@ module ActiveFunctionCore
 
         # 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)
@@ -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,11 +168,18 @@ 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 #{callback_options.keys} options") if (options.keys - callback_options.keys).any?
@@ -115,7 +189,14 @@ module ActiveFunctionCore
 
         # 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)
@@ -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,11 +168,18 @@ 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 #{callback_options.keys} options") if (options.keys - callback_options.keys).any?
@@ -115,7 +189,14 @@ module ActiveFunctionCore
 
         # 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)
@@ -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,11 +168,18 @@ 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 #{callback_options.keys} options") if (options.keys - callback_options.keys).any?
@@ -115,7 +189,14 @@ module ActiveFunctionCore
 
         # 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.2"
+  VERSION = "0.2.4"
 end

data/lib/active_function_core.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: activefunction-core
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.2.4
 platform: ruby
 authors:
 - Nerbyk
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-01-11 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