activefunction 0.3.5 → 0.4.1

data/lib/.rbnext/3.0/active_function.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "active_function_core"
+require "active_function/version"
+require "active_function/base"
+
+RubyNext::Language.setup_gem_load_path(transpile: true)
+
+module ActiveFunction
+  class << self
+    # Configure ActiveFunction through DSL method calls.
+    # Setups {ActiveFunction::Base} with provided internal and custom plugins.
+    # Also freezes plugins and {ActiveFunction::Base}.
+    #
+    # @example
+    #  ActiveFunction.config do
+    #    plugin :callbacks
+    #  end
+    #
+    # @param block [Proc] class_eval'ed block in ActiveFunction module.
+    # @return [void]
+    def config(&block)
+      class_eval(&block)
+      @_plugins.freeze
+      self::Base.freeze
+    end
+
+    # List of registered internal plugins.
+    def plugins ;  @_plugins ||= {}; end
+
+    # Register internal Symbol'ed plugin.
+    #
+    # @param [Symbol] symbol name of internal plugin,
+    #   should match file name in ./lib/active_function/functions/*.rb
+    # @param [Module] mod module to register.
+    def register_plugin(symbol, mod)
+      plugins[symbol] = mod
+    end
+
+    # Add plugin to ActiveFunction::Base.
+    #
+    # @example
+    #  ActiveFunction.plugin :callbacks
+    #  ActiveFunction.plugin CustomPlugin
+    #
+    # @param [Symbol, Module] mod
+    # @return [void]
+    def plugin(mod)
+      if mod.is_a? Symbol
+        begin
+          require "active_function/functions/#{mod}"
+          mod = plugins.fetch(mod)
+        rescue LoadError
+          raise ArgumentError, "Unknown plugin #{mod}"
+        end
+      end
+
+      self::Base.include(mod)
+    end
+  end
+
+  plugin :response
+end

data/lib/.rbnext/3.1/active_function/functions/response.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module ActiveFunction
+  module Functions
+    # The only required plugin for {ActiveFunction::Base} to work.
+    # Provides a simple {Response} object to manage response details.
+    #
+    # @example
+    #   response = Response.new.tap do |r|
+    #     r.body = "Hello World!"
+    #     r.headers = {"Content-Type" => "text/plain"}
+    #     r.commit!
+    #   end
+    #
+    #   response.performed? # => true
+    #   response.to_h # => { statusCode: 200, headers: { "Content-Type" => "text/plain" }, body: "Hello World!" }
+    module Response
+      ActiveFunction.register_plugin :response, self
+
+      class Response < Struct.new(:status, :headers, :body, :committed)
+        # Initializes a new Response instance with default values.
+        #
+        # @param status [Integer] HTTP status code.
+        # @param headers [Hash] HTTP headers.
+        # @param body [Object] Response body.
+        # @param committed [Boolean] Indicates whether the response has been committed (default is false).
+        def initialize(status: 200, headers: {}, body: nil, committed: false) = super(status, headers, body, committed)
+
+        # Converts the Response instance to a hash for JSON serialization.
+        #
+        # @return [Hash{statusCode: Integer, headers: Hash, body: Object}]
+        def to_h
+          {
+            statusCode: status,
+            headers: headers,
+            body: body
+          }
+        end
+
+        # Marks the response as committed.
+        def commit!
+          self.committed = true
+        end
+
+        alias_method :committed?, :committed
+      end
+    end
+  end
+end

data/lib/active_function/base.rb

@@ -1,20 +1,58 @@
 # frozen_string_literal: true
 
 module ActiveFunction
-  class Base
-    require "active_function/functions/core"
-    require "active_function/functions/callbacks"
-    require "active_function/functions/strong_parameters"
-    require "active_function/functions/rendering"
-    require "active_function/functions/response"
-
-    include Functions::Core
-    include Functions::Callbacks
-    include Functions::Rendering
-    include Functions::StrongParameters
-
-    def self.process(action_name, request = {}, response = Functions::Response.new)
-      new.dispatch(action_name, request, response)
+  # Abstract base class with request processing logic.
+  class SuperBase
+    attr_reader :action_name, :request, :response
+
+    def initialize(action_name, request, response)
+      @action_name = action_name
+      @request     = request
+      @response    = response
+    end
+
+    # Executes specified @action_name instance method and returns Hash'ed response object
+    def dispatch
+      process(action_name)
+
+      @response.commit! unless performed?
+
+      @response.to_h
+    end
+
+    def process(action) = public_send(action)
+
+    private def performed? = @response.committed?
+  end
+
+  # The main base class for defining functions using the ActiveFunction framework.
+  # Public methods of this class are considered as actions and be proceeded on {ActiveFunction::Base.process} call.
+  #
+  # @example
+  #   class MyFunction < ActiveFunction::Base
+  #      def index
+  #         if user = User.find(@request.dig(:data, :user, :id))
+  #             @response.body = user.to_h
+  #         else
+  #             @response.status = 404
+  #         end
+  #      end
+  #   end
+  class Base < SuperBase
+    Error = Class.new(StandardError)
+
+    # Processes specified action and returns Hash'ed {ActiveFunction::Functions::Response::Response} object.
+    #
+    # @example
+    #   MyFunction.process :index, { data: { user: { id: 1 } } } # => { statusCode: 200, body: { id: 1, name: "Pupa" }, headers: {} }
+    #
+    # @param [String, Symbol] action_name - name of method to call
+    # @param [Hash] request - request parameters.
+    # @param [Response] response - Functions::Response response object.
+    def self.process(action_name, request = {}, response = Response.new)
+      raise ArgumentError, "Action method #{action_name} is not defined" unless method_defined?(action_name)
+
+      new(action_name, request, response).dispatch
     end
   end
 end

data/lib/active_function/functions/callbacks.rb

@@ -1,69 +1,69 @@
 # frozen_string_literal: true
 
 module ActiveFunction
-  class MissingCallbackContext < Error
-    MESSAGE_TEMPLATE = "Missing callback context: %s"
-
-    attr_reader :message
-
-    def initialize(context)
-      @message = MESSAGE_TEMPLATE % context
-    end
-  end
-
   module Functions
+    # Setups {before_action} and {after_action} callbacks around {ActiveFunction::SuperBase#process}
+    # using {ActiveFunctionCore::Plugins::Hooks}. Also provides {define_hooks_for} and {set_callback_options} for
+    # defining custom hooks & options.
+    #
+    # @example
+    #   ActiveFunction.plugin :callbacks
+    #
+    #   class MessagingApp < ActiveFunction::Base
+    #     set_callback_options retries: ->(times, context:) { context.retry if context.retries < times }
+    #     define_hooks_for :retry
+    #
+    #     after_action :retry, if: :failed?, only: %i[send_message], retries: 3
+    #     after_retry :increment_retries
+    #
+    #     def send_message
+    #       @response.status = 200 if SomeApi.send(@request[:message_content]).success?
+    #     end
+    #
+    #     def retry
+    #       @response.committed = false
+    #       process
+    #     end
+    #
+    #     private def increment_retries = @response.body[:tries] += 1
+    #     private def failed? = @response.status != 200
+    #     private def retries = @response.body[:tries] ||= 0
+    #   end
+    #
+    #   MessagingApp.process(:send_message, { sender_name: "Alice", message_content: "How are you?" })
+    # defining custom hooks & options.
     module Callbacks
-      def self.included(base)
-        base.extend(ClassMethods)
-      end
-
-      private
-
-      def process(*)
-        _run_callbacks :before
-
-        super
-
-        _run_callbacks :after
-      end
-
-      def _run_callbacks(type)
-        self.class.callbacks[type].each do |callback_method, options|
-          raise MissingCallbackContext, callback_method unless respond_to?(callback_method, true)
-
-          send(callback_method) if _executable?(options)
-        end
-      end
+      ActiveFunction.register_plugin :callbacks, self
 
-      def _executable?(options)
-        return false if options[:only] && !options[:only].include?(@action_name)
-        return false if options[:if] && !send(options[:if])
-        true
+      # Setup callbacks around {ActiveFunction::Base#process} method using {ActiveFunctionCore::Plugins::Hooks}.
+      # Also provides :only option for filtering callbacks by action name.
+      def self.included(base)
+        base.include ActiveFunctionCore::Plugins::Hooks
+        base.define_hooks_for :process, name: :action
+        base.set_callback_options only: ->(args, context:) { args.to_set === context.action_name }
       end
 
-      module ClassMethods
-        def inherited(subclass)
-          subclass.instance_variable_set(:@__callbacks, @__callbacks)
-        end
-
-        def before_action(method, options = {})
-          set_callback :before, method, options
-        end
-
-        def after_action(method, options = {})
-          set_callback :after, method, options
-        end
-
-        def set_callback(type, method, options = {})
-          callbacks[type][method] = options
-        end
-
-        def callbacks
-          @__callbacks ||= {before: {}, after: {}}
-
-          @__callbacks
-        end
-      end
+      # @!method before_action(target, options)
+      #  @param [Symbol, String] target - method name to call
+      #  @option options [Symbol, String] :if - method name to check before executing the callback.
+      #  @option options [Symbol, String] :unless - method name to check before executing the callback.
+      #  @option options [Array<Symbol, String>] :only - array of action names.
+      #  @see ActiveFunctionCore::Plugins::Hooks::ClassMethods#set_callback
+      # @!method after_action(target, options)
+      #  @param [Symbol, String] target - method name to call
+      #  @option options [Symbol, String] :if - method name to check before executing the callback.
+      #  @option options [Symbol, String] :unless - method name to check before executing the callback.
+      #  @option options [Array<Symbol, String>] :only - array of action names.
+      #  @see ActiveFunctionCore::Plugins::Hooks::ClassMethods#set_callback
+
+      # @!method set_callback(type, hook_name, target, options)
+      #  @see ActiveFunctionCore::Plugins::Hooks::ClassMethods#set_callback
+
+      # @!method define_hooks_for(method_name, name: method_name)
+      #  @see ActiveFunctionCore::Plugins::Hooks::ClassMethods#define_hooks_for
+
+      # @!method set_callback_options(options)
+      #  @see ActiveFunctionCore::Plugins::Hooks::ClassMethods#set_callback_options
     end
   end
 end

data/lib/active_function/functions/rendering.rb

@@ -3,20 +3,47 @@
 require "json"
 
 module ActiveFunction
-  class DoubleRenderError < Error
-    MESSAGE_TEMPLATE = "#render was called multiple times in action: %s"
+  module Functions
+    # Allows manipulations with {ActiveFunction::SuperBase#response} via {render} instance method.
+    #
+    # @example
+    #   require "active_function"
+    #
+    #   ActiveFunction.config do
+    #     plugin :rendering
+    #   end
+    #
+    #   class PostsFunction < ActiveFunction::Base
+    #     def index
+    #       render json: {id: 1, name: "Pupa"}, status: 200, head: {"Some-Header" => "Some-Value"}
+    #     end
+    #   end
+    #
+    #   PostFunction.process(:index) # => { :statusCode=>200, :headers=> {"Content-Type"=>"application/json", "Some-Header" => "Some-Value"}, :body=>"{\"id\":1,\"name\":\"Pupa\"}" }
+    module Rendering
+      ActiveFunction.register_plugin :rendering, self
 
-    attr_reader :message
+      Error = Class.new(StandardError)
 
-    def initialize(context)
-      @message = MESSAGE_TEMPLATE % context
-    end
-  end
+      class DoubleRenderError < Error
+        MESSAGE_TEMPLATE = "#render was called multiple times in action: %s"
+
+        attr_reader :message
+
+        def initialize(context)
+          @message = MESSAGE_TEMPLATE % context
+        end
+      end
 
-  module Functions
-    module Rendering
       DEFAULT_HEADER = {"Content-Type" => "application/json"}.freeze
 
+      # Render JSON response.
+      #
+      # @param status [Integer] HTTP status code (default is 200).
+      # @param json [Hash] JSON data to be rendered (default is an empty hash).
+      # @param head [Hash] Additional headers to be included in the response (default is an empty hash).
+      #
+      # @raise [DoubleRenderError] Raised if #render is called multiple times in the same action.
       def render(status: 200, json: {}, head: {})
         raise DoubleRenderError, @action_name if performed?
 

data/lib/active_function/functions/response.rb

@@ -2,29 +2,48 @@
 
 module ActiveFunction
   module Functions
-    class Response
-      attr_accessor :status, :headers, :body
+    # The only required plugin for {ActiveFunction::Base} to work.
+    # Provides a simple {Response} object to manage response details.
+    #
+    # @example
+    #   response = Response.new.tap do |r|
+    #     r.body = "Hello World!"
+    #     r.headers = {"Content-Type" => "text/plain"}
+    #     r.commit!
+    #   end
+    #
+    #   response.performed? # => true
+    #   response.to_h # => { statusCode: 200, headers: { "Content-Type" => "text/plain" }, body: "Hello World!" }
+    module Response
+      ActiveFunction.register_plugin :response, self
 
-      def initialize(status: 200, headers: {}, body: nil)
-        @status     = status
-        @headers    = headers
-        @body       = body
-        @committed  = false
-      end
+      class Response < Struct.new(:status, :headers, :body, :committed)
+        # Initializes a new Response instance with default values.
+        #
+        # @param status [Integer] HTTP status code.
+        # @param headers [Hash] HTTP headers.
+        # @param body [Object] Response body.
+        # @param committed [Boolean] Indicates whether the response has been committed (default is false).
+        def initialize(status: 200, headers: {}, body: nil, committed: false) = super(status, headers, body, committed)
 
-      def to_h
-        {
-          statusCode: status,
-          headers:    headers,
-          body:       body
-        }
-      end
+        # Converts the Response instance to a hash for JSON serialization.
+        #
+        # @return [Hash{statusCode: Integer, headers: Hash, body: Object}]
+        def to_h
+          {
+            statusCode: status,
+            headers:,
+            body:
+          }
+        end
 
-      def commit!
-        @committed = true
-      end
+        # Marks the response as committed.
+        def commit!
+          self.committed = true
+        end
 
-      def committed? = @committed
+        alias_method :committed?, :committed
+      end
     end
   end
 end

data/lib/active_function/functions/strong_parameters.rb

@@ -3,54 +3,80 @@
 require "forwardable"
 
 module ActiveFunction
-  class ParameterMissingError < Error
-    MESSAGE_TEMPLATE = "Missing parameter: %s"
-
-    attr_reader :message
-
-    def initialize(param)
-      MESSAGE_TEMPLATE % param
-    end
-  end
+  module Functions
+    # Allows manipulations with {ActiveFunction::SuperBase#request} via {params} instance method and {Parameters} object.
+    #
+    # @example
+    #   require "active_function"
+    #
+    #   ActiveFunction.config do
+    #     plugin :strong_parameters
+    #   end
+    #
+    #   class PostsFunction < ActiveFunction::Base
+    #     def index
+    #       @response.body = permitted_params
+    #     end
+    #
+    #     def permitted_params
+    #       params.require(:data).permit(:id, :name).to_h
+    #     end
+    #   end
+    #
+    #   PostsFunction.process(:index, data: { id: 1, name: "Pupa" })
+    module StrongParameters
+      ActiveFunction.register_plugin :strong_parameters, self
 
-  class UnpermittedParameterError < Error
-    MESSAGE_TEMPLATE = "Unpermitted parameter: %s"
+      Error = Class.new(StandardError)
+      # The Parameters class encapsulates the parameter handling logic.
+      class Parameters < Data.define(:params, :permitted)
+        class ParameterMissingError < Error
+          MESSAGE_TEMPLATE = "Missing parameter: %s"
 
-    attr_reader :message
+          attr_reader :message
 
-    def initialize(param)
-      MESSAGE_TEMPLATE % param
-    end
-  end
+          def initialize(param)
+            MESSAGE_TEMPLATE % param
+          end
+        end
 
-  module Functions
-    module StrongParameters
-      def params
-        @_params ||= Parameters.new(@request)
-      end
+        class UnpermittedParameterError < Error
+          MESSAGE_TEMPLATE = "Unpermitted parameter: %s"
 
-      class Parameters
-        extend Forwardable
-        def_delegators :@parameters, :each, :map
-        include Enumerable
+          attr_reader :message
 
-        def initialize(parameters, permitted: false)
-          @parameters = parameters
-          @permitted  = permitted
+          def initialize(param)
+            MESSAGE_TEMPLATE % param
+          end
         end
 
+        protected :params
+
+        # Allows access to parameters by key.
+        #
+        # @param attribute [Symbol] The key of the parameter.
+        # @return [Parameters, Object] The value of the parameter.
         def [](attribute)
-          nested_attribute(parameters[attribute])
+          nested_attribute(params[attribute])
         end
 
+        # Requires the presence of a specific parameter.
+        #
+        # @param attribute [Symbol] The key of the required parameter.
+        # @return [Parameters, Object] The value of the required parameter.
+        # @raise [ParameterMissingError] if the required parameter is missing.
         def require(attribute)
-          value = self[attribute]
-
-          raise ParameterMissingError, attribute if value.nil?
-
-          value
+          if (value = self[attribute])
+            value
+          else
+            raise ParameterMissingError, attribute
+          end
         end
 
+        # Specifies the allowed parameters.
+        #
+        # @param attributes [Array<Symbol, Hash<Symbol, Array<Symbol>>>] The attributes to permit.
+        # @return [Parameters] A new instance with permitted parameters.
         def permit(*attributes)
           pparams = {}
 
@@ -60,28 +86,40 @@ module ActiveFunction
                 pparams[k] = process_nested(self[k], :permit, v)
               end
             else
-              next unless parameters.key?(attribute)
+              next unless params.key?(attribute)
 
               pparams[attribute] = self[attribute]
             end
           end
 
-          Parameters.new(pparams, permitted: true)
+          with(params: pparams, permitted: true)
         end
 
+        # Converts parameters to a hash.
+        #
+        # @return [Hash] The hash representation of the parameters.
+        # @raise [UnpermittedParameterError] if any parameters are unpermitted.
         def to_h
-          raise UnpermittedParameterError, parameters.keys unless @permitted
+          raise UnpermittedParameterError, params.keys unless permitted
 
-          parameters.transform_values { process_nested(_1, :to_h) }
+          params.transform_values { process_nested(_1, :to_h) }
+        end
+
+        def hash
+          @attributes.to_h.hash
+        end
+
+        def with(params:, permitted: false)
+          self.class.new(params, permitted)
         end
 
         private
 
         def nested_attribute(attribute)
           if attribute.is_a? Hash
-            Parameters.new(attribute)
+            with(params: attribute)
           elsif attribute.is_a?(Array) && attribute[0].is_a?(Hash)
-            attribute.map { Parameters.new(_1) }
+            attribute.map { |it| with(params: it) }
           else
             attribute
           end
@@ -96,8 +134,13 @@ module ActiveFunction
             attribute
           end
         end
+      end
 
-        attr_reader :parameters
+      # Return params object with {ActiveFunction::SuperBase#request}.
+      #
+      # @return [Parameters] instance of {Parameters} class.
+      def params
+        @_params ||= Parameters.new(@request, false)
       end
     end
   end

data/lib/active_function/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ActiveFunction
-  VERSION = "0.3.5"
+  VERSION = "0.4.1"
 end