activefunction 0.4.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4f2bbae1e08a02af0dbabf4b235ece3823d17aec26e76b24ad7f4b514ea8526c
-  data.tar.gz: 6097f177bb4b5dff0583c21c40d45c67aeb4bd81eb6551b52e59c440b3e5e027
+  metadata.gz: 777be794ab7e9eb091472b8f886b0b8da55c338c6c617afb9ee95acc9a946cba
+  data.tar.gz: faf687684919e61cd2bb9a2b8217f029945971898ae4469593f166d7ab34508a
 SHA512:
-  metadata.gz: 51cfd314a65879813c1e8c8c23ea80b32621a1479a5c4ea09c789557ddcc80b05b29af2d84181fec90984c4137f8cc4735bd24e76a6eb2e38d81cfa543605ea7
-  data.tar.gz: 2ea0d89e66aa2a3c89f3b011a84bed5628a9e2e1de78c506f24d93393ab389922581ba1429509c3f8e30883a6788216069078aec3d38cd692c6eda1314b6a69f
+  metadata.gz: 20bb5768a3dcf00582d6f32b99c600c51a9e83c9e5b7ef78ecf81c7e560d63f7d83ea02005d01ef19cd4e2a87a5161f47627e7c305c45d2c18dab6744cd5134a
+  data.tar.gz: 7e866bc6a9fe14cd56b8f08985a2a83ce10e57c54560e54e3c954116508638dc0128878d0dc6b2d16f7c8c2c11775ba2681515a58229632bc752e20b76fd79dd

data/CHANGELOG.md

@@ -53,4 +53,6 @@
 - Introduce Plugin system
 - Global refactoring
 
+# [0.4.1] - 2024-01-14
 
+- YARD Doc Added

data/README.md

@@ -1,8 +1,10 @@
 # ActiveFunction
+[![Build](https://github.com/DanilMaximov/activefunction/actions/workflows/build.yml/badge.svg)](DanilMaximov/activefunction/actions)
+[![Gem Version](https://badge.fury.io/rb/activefunction.svg)](https://badge.fury.io/rb/activefunction)
+[![RubyDoc](https://img.shields.io/badge/RubyDoc-Documentation-blue.svg)](https://rubydoc.info/gems/activefunction)
 
-Playground gem for Ruby 3.2+ features and more.
 
-Collection of gems designed to be used with FaaS (Function as a Service) computing instances. Inspired by aws-sdk v3 gem structure & rails/activesupport.
+Playground gem for Ruby 3.2+ features initially designed to be used with FaaS (Function as a Service) computing instances. Inspired by aws-sdk v3 gem structure & rails/activesupport.
 
 ## Features
 
@@ -10,7 +12,7 @@ Collection of gems designed to be used with FaaS (Function as a Service) computi
 - **Type Safety:** Achieves type safety through the use of RBS and [Steep](https://github.com/soutaro/steep). (CI'ed)
   - Note: disabled due to the presence of Ruby::UnsupportedSyntax errors.
 - **Plugins System:** Provides a simple Plugin system (inspired by [Polishing Ruby Programming by Jeremy Evans](https://github.com/PacktPublishing/Polished-Ruby-Programming)) to load gem plugins as well as self-defined plugins.
-- **Gem Collection** Provides a collection of gems designed to be used within ActiveFunction or standalone.
+- **Gem Collection:** Provides a collection of gems designed to be used within ActiveFunction or standalone.
 
 # Gems
 
@@ -20,7 +22,7 @@ Collection of gems designed to be used with FaaS (Function as a Service) computi
 
 ## Quick Start
 
-Here's a simple example of a function that uses ActiveFunction:
+Here's a simple example of a function that uses ActiveFunction(w/o plugins):
 
 ```ruby
 require "active_function"
@@ -31,9 +33,7 @@ class AppFunction < ActiveFunction::Base
 
     return if performed?
 
-    @response.status  = 200
-    @response.headers = {"Content-Type" => "application/json"}
-    @response.body    = @request[:data]
+    @response.body = @request[:data]
   end
 
   private def response_with_error
@@ -42,15 +42,24 @@ class AppFunction < ActiveFunction::Base
   end
 end
 
-AppFunction.process(:index, {data: {id: 1}}) # => { :statusCode=>200, :headers=> {"Content-Type"=>"application/json"}, :body=>{id: 1}"}
 ```
 
+The `#process` method is used to run the function.
+
+```ruby
+AppFunction.process(:index, {data: {id: 1}}) # => { 
+#   :statusCode => 200, 
+#   :headers => { }, 
+#   :body => {id: 1}"
+# }
+``` 
+
 ## Plugins
 
 ActiveFunction supports plugins which can be loaded by `ActiveFunction.config` method. Currently, there are 3 plugins available:
-  - [:callbacks](#callbacks) - provides `:before_action` and `:after_action` callbacks with `:if`, `:unless` & `:only` options.
-  - [:strong_parameters](#strong-parameters) - provides strong parameters support via `#params` instance method.
-  - [:rendering](#rendering) - provides rendering support via `#render` instance method.
+  - [:callbacks](#callbacks) - provides `:before_action`, `:after_action` & `:set_callback` DSL with `:if`, `:unless` & `:only` options.
+  - [:strong_parameters](#strong-parameters) - provides strong parameters support via `#params` instance method around `@request` object.
+  - [:rendering](#rendering) - provides rendering support via `#render` instance method around `@response` object.
 
 ## Configuration
 
@@ -78,15 +87,15 @@ class AppFunction < ActiveFunction::Base
 
   private def parse_user_data = @user_data = params.require(:data).permit(:id, :name).to_h
 end
-```
-
-Use `#process` method to proceed the request:
 
-```ruby
-# handler.rb
-AppFunction.process(:index, {data: { id: 1, name: 2}}) # => { :statusCode=>200, :headers=> {"Content-Type"=>"application/json"}, :body=>"{\"id\":1,\"name\":2}"}
+AppFunction.process(:index, {data: { id: 1, name: 2}}) # => { 
+#   :statusCode => 200, 
+#   :headers => {"Content-Type"=>"application/json"}, 
+#   :body=>"{\"id\":1,\"name\":2}"
+# }
 ```
 
+[See Plugins Docs](https://rubydoc.info/gems/activefunction/ActiveFunction#plugin-class_method) for more details.
 
 ## Callbacks
 
@@ -129,7 +138,38 @@ class AppFunction < ActiveFunction::Base
   private def request_valid? = true
 end
 ```
-More details in [ActiveFunctionCore::Plugins::Hooks readme](https://github.com/DanilMaximov/activefunction/tree/master/gems/activefunction-core#hooks)
+
+### Defining Custom Callbacks
+
+External Plugin `ActiveFunctionCore::Plugins::Hooks` provides `:define_hooks_for` & `:set_callback_options` DSL to define custom callbacks & options.
+
+```ruby
+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?" })
+```
+
+[See Callbacks Doc](https://rubydoc.info/gems/activefunction/ActiveFunction/Functions/Callbacks) for more details.
 
 ## Strong Parameters
 
@@ -170,6 +210,8 @@ Strong params supports nested attributes
 params.permit(:id, :name, :address => [:city, :street])
 ```
 
+[See StrongParameters Doc](https://rubydoc.info/gems/activefunction/ActiveFunction/Functions/StrongParameters) for more details.
+
 ## Rendering
 
 ActiveFunction supports rendering of JSON. The #render method is used for rendering responses. It accepts the following options:
@@ -197,6 +239,8 @@ end
 PostFunction.process(:index) # => { :statusCode=>200, :headers=> {"Content-Type"=>"application/json", "Some-Header" => "Some-Value"}, :body=>"{\"id\":1,\"name\":\"Pupa\"}"}
 ```
 
+[See Rendering Doc](https://rubydoc.info/gems/activefunction/ActiveFunction/Functions/Rendering) for more details.
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -207,9 +251,9 @@ gem "activefunction"
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `bin/rake test` to run the tests and `bin/rake steep` to run type checker.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `bin/rake test:all` to run the tests and `bin/rake steep` to run type checker.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `bundle exec rake install`.
 
 ## Contributing
 

data/lib/.rbnext/2.7/active_function/functions/strong_parameters.rb

@@ -4,11 +4,31 @@ require "forwardable"
 
 module ActiveFunction
   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
 
       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"
@@ -32,10 +52,19 @@ module ActiveFunction
 
         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(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)
           if (value = self[attribute])
             value
@@ -44,6 +73,10 @@ module ActiveFunction
           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 = {}
 
@@ -62,7 +95,10 @@ module ActiveFunction
           with(params: pparams, permitted: true)
         end
 
-        # Redefines RubyNext::Core::Data instance methods
+        # 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, params.keys unless permitted
 
@@ -100,6 +136,9 @@ module ActiveFunction
         end
       end
 
+      # Return params object with {ActiveFunction::SuperBase#request}.
+      #
+      # @return [Parameters] instance of {Parameters} class.
       def params
         @_params ||= Parameters.new(@request, false)
       end

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

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module ActiveFunction
+  # Abstract base class with request processing logic.
   class SuperBase
     attr_reader :action_name, :request, :response
 
@@ -10,6 +11,7 @@ module ActiveFunction
       @response    = response
     end
 
+    # Executes specified @action_name instance method and returns Hash'ed response object
     def dispatch
       process(action_name)
 
@@ -23,12 +25,30 @@ module ActiveFunction
     private def performed? ;  @response.committed?; end
   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 params, accessible through `#params` method
-    # @param [Response] response - response object
+    # @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)
 

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

@@ -2,12 +2,33 @@
 
 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); end
 
+        # Converts the Response instance to a hash for JSON serialization.
+        #
+        # @return [Hash{statusCode: Integer, headers: Hash, body: Object}]
         def to_h
           {
             statusCode: status,
@@ -16,6 +37,7 @@ module ActiveFunction
           }
         end
 
+        # Marks the response as committed.
         def commit!
           self.committed = true
         end

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

@@ -8,9 +8,16 @@ RubyNext::Language.setup_gem_load_path(transpile: true)
 
 module ActiveFunction
   class << self
-    # Configure ActiveFunction.
+    # Configure ActiveFunction through DSL method calls.
+    # Setups {ActiveFunction::Base} with provided internal and custom plugins.
+    # Also freezes plugins and {ActiveFunction::Base}.
     #
-    # @param block [Proc]
+    # @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)
@@ -18,19 +25,25 @@ module ActiveFunction
       self::Base.freeze
     end
 
+    # List of registered internal plugins.
     def plugins ;  @_plugins ||= {}; end
 
-    # Register plugin.
+    # Register internal Symbol'ed plugin.
     #
-    # @param symbol [Symbol]
-    # @param mod [Module]
+    # @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
 
-    # Monkey patch ActiveFunction::Base with provided plugin.
+    # Add plugin to ActiveFunction::Base.
+    #
+    # @example
+    #  ActiveFunction.plugin :callbacks
+    #  ActiveFunction.plugin CustomPlugin
     #
-    # @param mod [Symbol, Module]
+    # @param [Symbol, Module] mod
     # @return [void]
     def plugin(mod)
       if mod.is_a? Symbol

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

@@ -2,12 +2,33 @@
 
 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,
@@ -16,6 +37,7 @@ module ActiveFunction
           }
         end
 
+        # Marks the response as committed.
         def commit!
           self.committed = true
         end

data/lib/active_function/base.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module ActiveFunction
+  # Abstract base class with request processing logic.
   class SuperBase
     attr_reader :action_name, :request, :response
 
@@ -10,6 +11,7 @@ module ActiveFunction
       @response    = response
     end
 
+    # Executes specified @action_name instance method and returns Hash'ed response object
     def dispatch
       process(action_name)
 
@@ -23,12 +25,30 @@ module ActiveFunction
     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 params, accessible through `#params` method
-    # @param [Response] response - response object
+    # @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)
 

data/lib/active_function/functions/callbacks.rb

@@ -2,14 +2,68 @@
 
 module ActiveFunction
   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
       ActiveFunction.register_plugin :callbacks, self
 
+      # 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
+
+      # @!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

@@ -4,6 +4,22 @@ require "json"
 
 module ActiveFunction
   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
 
@@ -21,6 +37,13 @@ module ActiveFunction
 
       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,12 +2,33 @@
 
 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,
@@ -16,6 +37,7 @@ module ActiveFunction
           }
         end
 
+        # Marks the response as committed.
         def commit!
           self.committed = true
         end

data/lib/active_function/functions/strong_parameters.rb

@@ -4,11 +4,31 @@ require "forwardable"
 
 module ActiveFunction
   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
 
       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"
@@ -32,10 +52,19 @@ module ActiveFunction
 
         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(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)
           if (value = self[attribute])
             value
@@ -44,6 +73,10 @@ module ActiveFunction
           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 = {}
 
@@ -62,7 +95,10 @@ module ActiveFunction
           with(params: pparams, permitted: true)
         end
 
-        # Redefines RubyNext::Core::Data instance methods
+        # 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, params.keys unless permitted
 
@@ -100,6 +136,9 @@ module ActiveFunction
         end
       end
 
+      # Return params object with {ActiveFunction::SuperBase#request}.
+      #
+      # @return [Parameters] instance of {Parameters} class.
       def params
         @_params ||= Parameters.new(@request, false)
       end

data/lib/active_function/version.rb

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

data/lib/active_function.rb

@@ -8,9 +8,16 @@ RubyNext::Language.setup_gem_load_path(transpile: true)
 
 module ActiveFunction
   class << self
-    # Configure ActiveFunction.
+    # Configure ActiveFunction through DSL method calls.
+    # Setups {ActiveFunction::Base} with provided internal and custom plugins.
+    # Also freezes plugins and {ActiveFunction::Base}.
     #
-    # @param block [Proc]
+    # @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)
@@ -18,19 +25,25 @@ module ActiveFunction
       self::Base.freeze
     end
 
+    # List of registered internal plugins.
     def plugins = @_plugins ||= {}
 
-    # Register plugin.
+    # Register internal Symbol'ed plugin.
     #
-    # @param symbol [Symbol]
-    # @param mod [Module]
+    # @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
 
-    # Monkey patch ActiveFunction::Base with provided plugin.
+    # Add plugin to ActiveFunction::Base.
+    #
+    # @example
+    #  ActiveFunction.plugin :callbacks
+    #  ActiveFunction.plugin CustomPlugin
     #
-    # @param mod [Symbol, Module]
+    # @param [Symbol, Module] mod
     # @return [void]
     def plugin(mod)
       if mod.is_a? Symbol

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: activefunction
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.1
 platform: ruby
 authors:
 - Nerbyk
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-01-12 00:00:00.000000000 Z
+date: 2024-01-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activefunction-core
@@ -24,6 +24,76 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 0.2.2
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: ruby-next
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 5.15.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 5.15.0
+- !ruby/object:Gem::Dependency
+  name: minitest-reporters
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.4.3
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.4.3
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.1.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.1.0
 description: "\n    ActiveFunction is a collection of gems designed to be used with
   Function as a Service (FaaS) computing instances. Inspired by aws-sdk v3 gem structure
   and rails/activesupport.\n\n    Features:\n    - Ruby Version Compatibility: Implemented
@@ -43,11 +113,6 @@ files:
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
-- bin/console
-- bin/rake
-- bin/rubocop
-- bin/ruby-next
-- bin/setup
 - lib/.rbnext/2.7/active_function/functions/strong_parameters.rb
 - lib/.rbnext/3.0/active_function.rb
 - lib/.rbnext/3.0/active_function/base.rb

data/bin/console

@@ -1,15 +0,0 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-require "bundler/setup"
-require "active_function"
-
-# You can add fixtures and/or initialization code here to make experimenting
-# with your gem easier. You can also use a different console, if you like.
-
-# (If you use this, don't forget to add pry to your Gemfile!)
-# require "pry"
-# Pry.start
-
-require "irb"
-IRB.start(__FILE__)

data/bin/rake

@@ -1,27 +0,0 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-#
-# This file was generated by Bundler.
-#
-# The application 'rake' is installed as part of a gem, and
-# this file is here to facilitate running it.
-#
-
-ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
-
-bundle_binstub = File.expand_path("bundle", __dir__)
-
-if File.file?(bundle_binstub)
-  if File.read(bundle_binstub, 300) =~ /This file was generated by Bundler/
-    load(bundle_binstub)
-  else
-    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
-Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
-  end
-end
-
-require "rubygems"
-require "bundler/setup"
-
-load Gem.bin_path("rake", "rake")

data/bin/rubocop

@@ -1,27 +0,0 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-#
-# This file was generated by Bundler.
-#
-# The application 'rubocop' is installed as part of a gem, and
-# this file is here to facilitate running it.
-#
-
-ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
-
-bundle_binstub = File.expand_path("bundle", __dir__)
-
-if File.file?(bundle_binstub)
-  if File.read(bundle_binstub, 300).include?("This file was generated by Bundler")
-    load(bundle_binstub)
-  else
-    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
-Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
-  end
-end
-
-require "rubygems"
-require "bundler/setup"
-
-load Gem.bin_path("rubocop", "rubocop")

data/bin/ruby-next

@@ -1,16 +0,0 @@
-#!/usr/bin/env ruby
-
-lib_path = File.expand_path("../lib", __dir__)
-$LOAD_PATH.unshift(lib_path) unless $LOAD_PATH.include?(lib_path)
-
-require "ruby-next/cli"
-
-begin
-  cli = RubyNext::CLI.new
-  cli.run(ARGV)
-rescue => e
-  raise e if $DEBUG
-  STDERR.puts e.message
-  STDERR.puts e.backtrace.join("\n") if ENV["RUBY_NEXT_DEBUG"] == "1"
-  exit 1
-end

data/bin/setup

@@ -1,8 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-IFS=$'\n\t'
-set -vx
-
-bundle install
-
-# Do any other automated setup that you need to do here