hati-command 0.1.0.beta1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8a7695ebc8436769523738139c4283bd648475092fbd41ee4ffbc6ae3c721a5c
-  data.tar.gz: 075c0911c8855a4a811302fac864fe2fda8c55a1cfc358eb3c1eb3918050e180
+  metadata.gz: 44f1b8b3fa48fbee4ab3670fcb0f5f049a1ceb42fa875b13592facfe3ea2b7f5
+  data.tar.gz: 197491d0ed328d16ba627bc5900b360c42982e2b697b351e78fc30d512c25606
 SHA512:
-  metadata.gz: a7c10d976e359912c6a6ef0da1b9b0fc88de2d84ac3d084a2155a6a9437114207254bdc36eefe423938e477f151400e7868dd473ad3fe82c7e677815fdfe6185
-  data.tar.gz: c530a89f9eed5dfa5d2d5b1e25ece68fd422ceb5139a94b98c374af259816f685396a06b8d49974f7170744872f09561efdad4b84589ff65f3bc8f771572cdca
+  metadata.gz: 61aa3b06315beb6a2fb716a98d4322d90e4fd602a702a0cf950a4760938aaa084705bb858570cbd4dd647332b164e57e3d3ef7758595a3d2505417ce057a3e99
+  data.tar.gz: 8296ba06921e87df95911bf10e56995f8d419aebe9d5dd2ff5f973db341025c3fe278362b4ba269646715a7f97b1106f90b6242a4f9a96531314f6a9e5307931

data/README.md

@@ -24,15 +24,19 @@ The `hati-command` gem is designed to simplify command execution, emphasizing ef
   - [Handling Failure](#handling-failure)
   - [Transactional Behavior](#transactional-behavior-fail-fast-with-failure)
 - [Advanced Usage](#advanced-usage)
+
   - [Result Customization](#result-customization)
     - [meta](#meta)
     - [error](#error)
     - [trace](#trace)
   - [Command Configurations](#command-configurations)
+    - [result_inference](#result_inference)
+    - [call_as](#call_as)
     - [failure](#failure)
     - [fail_fast](#fail_fast)
     - [unexpected_err](#unexpected_err)
-    - [result_inference](#result_inference)
+    - [ar_transaction](#ar_transaction)
+
 - [Development](#development)
 - [Contributing](#contributing)
 - [License](#license)
@@ -54,7 +58,13 @@ gem install hati-command
 
 ## Basic Usage
 
-To use the `hati-command` gem, you can create a command class that includes the `HatiCommand::Cmd` module. Here’s a simple example:
+To use the `hati-command` gem, you can create a command class that includes the `HatiCommand::Cmd` module.
+
+Note: No need to nest object APIs under `private` as popular template for `Servie Object` designs
+
+    only main caller method is public by design
+
+#### Example
 
 ```ruby
 require 'hati_command'
@@ -79,6 +89,13 @@ class GreetingCommand
 end
 ```
 
+### Command `API`
+
+```ruby
+result = GreetingCommand.call("Hello, World!") # Outputs: Result
+result = GreetingCommand.new                   # Outputs: private method `new' called
+```
+
 ### Handling `Success`
 
 ```ruby
@@ -92,7 +109,6 @@ puts result.failure  # Outputs: nil
 
 puts result.value    # Outputs: "HELLO, WORLD!"
 puts result.result   # Outputs: HatiCommand::Success
-
 ```
 
 ### Handling `Failure`
@@ -249,11 +265,97 @@ puts result.trace    # Outputs: path/to/cmds/doomed_command.rb:5:in `call'
 
 Provides options for default failure message or errors. Available configs are:
 
-- `failure` - Message or Error
-- `fail_fast` - Message or Error
-- `unexpected_err` - Bool(true) or Message or Error
-- `result_inference` - Bool(true) | implicit Result wrapper
-- `call_as` - Symbol | Main call method name
+- `result_inference`(Bool(true)) => implicit Result wrapper
+- `call_as`(Symbol[:call]) => Main call method name
+- `failure`(String | ErrorClass) => Message or Error
+- `fail_fast`(String || ErrorClass) => Message or Error
+- `unexpected_err`(Bool[true]) => Message or Error
+
+#### Experimental:
+
+- `ar_transaction`(Array[Symbol], returnable: Bool[true]) => methods to wrap in Transaction, requires 'activerecord'
+
+```ruby
+class AppService
+  include HatiCommand::Cmd
+
+  command do
+    result_inference true
+    call_as :perform
+    failure "Default Error"
+    fail_fast "Default Fail Fast Error"
+    unexpected_err BaseServiceError
+  end
+
+  # ...
+end
+
+class PaymentService < AppService
+  command do
+    ar_transaction :perform # WIP: Experimental
+    unexpected_err PaymentServiceTechnicalError
+  end
+
+  def perform(params)
+    account = Account.lock.find(user_id)
+    Failure("User account is inactive") unless user.active?
+
+    CreditTransaction.create!(user_id: user.id, amount: amount)
+    AuditLog.create!(action: 'add_funds', account: account)
+
+    Success('Funds has been add to account')
+  end
+
+  # ...
+end
+
+```
+
+### result_inference
+
+```ruby
+class GreetingCommand
+  include HatiCommand::Cmd
+
+  command do
+    result_inference true # Implicitly wraps non-Result as Success
+  end
+
+  def call
+    42
+  end
+  # ...
+end
+```
+
+```ruby
+result = GreetingCommand.call
+puts result.success  # Outputs: 42
+puts result.failure? # Outputs: false
+```
+
+### call_as
+
+```ruby
+class GreetingCommand
+  include HatiCommand::Cmd
+
+  command do
+    call_as :execute # E.q. :perform, :run, etc.
+  end
+
+  def execute
+    Success(42)
+  end
+  # ...
+end
+```
+
+```ruby
+result = GreetingCommand.execute
+puts result.success  # Outputs: 42
+puts result.failure? # Outputs: false
+```
 
 ### failure
 
@@ -276,9 +378,11 @@ Provides options for default failure message or errors. Available configs are:
 16| end
 ```
 
+NOTE: not configured fail fast uses default error
+
 ```ruby
 result = DoomedCommand.call(fail_fast: true)
-# NOTE: not configured fail fast uses default error
+
 puts result.failure # Outputs: nil
 puts result.error   # Outputs: "Default Error"
 puts result.trace   # Outputs: path/to/cmds/doomed_command.rb:5:in `call'
@@ -360,59 +464,82 @@ puts result.trace   # Outputs: path/to/cmds/greeting_command.rb:9:in `call'
 14| end
 ```
 
+NOTE: Original error becomes value (failure)
+
 ```ruby
 result = GreetingCommand.call
-# NOTE: Original error becomes value (failure)
-puts result.failure # Outputs: TypeError: no implicit conversion of Integer into String
 
+puts result.failure # Outputs: TypeError: no implicit conversion of Integer into String
 puts result.error   # Outputs: GreetingError
 puts result.trace   # Outputs: path/to/cmds/greeting_command.rb:12:in `call'
 ```
 
-### result_inference
+## Experimental
 
-```ruby
-1 | class GreetingCommand
-2 |   include HatiCommand::Cmd
-3 |
-4 |   command do
-5 |     result_inference true # Implicitly wraps non-Result as Success
-5 |   end
-6 |
-7 |   def call
-8 |     42
-9 |   end
-10|   # ...
-11| end
-```
+### ar_transaction
 
-```ruby
-result = GreetingCommand.call
-puts result.success  # Outputs: 42
-puts result.failure? # Outputs: false
-```
+Wraps listed methods in Transaction with blocking non-Result returns.
+At this dev stage relies on 'activerecord'
 
-### call_as
+- NOTE: considering extensicve expirience of usage, we recomend to use some naming convention
+  across codebase for such methods, to keep healthy Elegance-to-Explicitness ratio
+
+  #### E.g. suffixes: \_flow, \_transaction, \_task, etc.
+
+- NOTE: `Failure()` works as transaction break, returns only from called method's as Result (Failure) object
+
+- NOTE: `Failure!()` works on Service level same fail_fast immediately halts execution, return from
+
+- NOTE: Unlike `ActiveRecord::Transaction` Implicit non-Result returns will trigger `TransactionError`,
+  blocking partial commit state unless:
 
 ```ruby
-1 | class GreetingCommand
-2 |   include HatiCommand::Cmd
-3 |
-4 |   command do
-5 |     call_as :execute # E.q. :perform, :run, etc.
-5 |   end
-6 |
-7 |   def execute
-8 |     Success(42)
-9 |   end
-10|   # ...
-11| end
+  ar_transaction :transactional_method_name, returnable: false # Defaults to true
 ```
 
+### Pseudo-Example:
+
 ```ruby
-result = GreetingCommand.execute
-puts result.success  # Outputs: 42
-puts result.failure? # Outputs: false
+  class PaymentService < AppService
+    command do
+      ar_transaction :add_funds_transaction
+      unexpected_err PaymentServiceTechnicalError
+    end
+
+    def call(params)
+      amount = currency_exchange(params[:amount])
+      debit_transaction = add_funds_transaction(amount)
+
+      return debit_transaction if debit_transaction.success?
+
+      Failure(debit_transaction, err: 'Unable to add funds')
+    end
+
+    def currency_exchange
+      # ...
+    end
+
+    # Whole method evaluates in ActiveRecord::Transaction block
+    def add_funds_transaction(amount)
+      account = Account.lock.find(user_id)
+      Failure("User account is inactive") unless user.active?
+
+      # Fires TransactionError, unless :returnable configuration is disabled
+      return 'I am an Error'
+
+      user.balance += amount
+      user.save
+      Failure('Account debit issue') if user.errors
+
+      CreditTransaction.create!(user_id: user.id, amount: amount)
+      AuditLog.create!(action: 'add_funds', account: account)
+
+      # NOTE: result inference won't work, use only Result objects
+      Success('Great Succeess')
+    end
+
+  # ...
+  end
 ```
 
 ## Authors

data/hati-command.gemspec

@@ -8,12 +8,12 @@ require 'hati_command/version'
 Gem::Specification.new do |spec|
   spec.name    = 'hati-command'
   spec.version = HatiCommand::VERSION
-  spec.authors = %w[yurigitsu MarieGiy]
+  spec.authors = ['Mariya Giy', 'Yuri Gi']
   spec.email   = %w[yurigi.pro@gmail.com giy.mariya@gmail.com]
   spec.license = 'MIT'
 
-  spec.summary     = 'A Ruby gem for creating command objects with result handling.'
-  spec.description = 'hati-command is a Ruby gem for implementing the Command pattern with result handling.'
+  spec.summary     = 'A Ruby gem for creating Service objects, Command pattern, and Interactors with result handling.'
+  spec.description = 'hati-command is a Ruby gem for implementing Service objects, Command pattern and Interactors with result handling.'
   spec.homepage    = "https://github.com/hackico-ai/#{spec.name}"
 
   spec.required_ruby_version = '>= 3.0.0'

data/lib/hati_command/befehl.rb

@@ -23,6 +23,9 @@ module HatiCommand
     # Provides class methods for command configuration and execution.
     # These methods are automatically added to any class that extends Befehl.
     module BefehlClassMethods
+      # @module namespace as alias
+      ERR = HatiCommand::Errors
+
       # Configures a command block with specific settings
       # @yield [void] The configuration block
       # @return [Hash] The command configuration
@@ -32,52 +35,99 @@ module HatiCommand
       #     fail_fast true
       #   end
       def command(&block)
-        @__command_config ||= { call_as: :call }
         instance_eval(&block) if block_given?
       end
 
-      # Retrieves the current command configuration
       # @return [Hash] The current command configuration settings
       def command_config
-        @__command_config
+        __command_config
       end
 
       # Sets the result inference behavior for the command.
       # @param value [Boolean] Indicates whether to enable result inference.
       # @return [void]
       def result_inference(value)
-        @__command_config[:result_inference] = value
+        command_config[:result_inference] = value
       end
 
       # Sets the failure handler for the command
       # @param value [Symbol, Proc] The failure handler to be used
       # @return [void]
       def failure(value)
-        @__command_config[:failure] = value
+        command_config[:failure] = value
       end
 
       # Sets the fail-fast behavior for the command
       # @param value [Boolean] Whether to enable fail-fast behavior
       # @return [void]
       def fail_fast(value)
-        @__command_config[:fail_fast] = value
+        command_config[:fail_fast] = value
       end
 
       # Sets the unexpected error handler for the command
       # @param value [Symbol, Proc, Boolean] The error handler to be used
       # @return [void]
       def unexpected_err(value)
-        @__command_config[:unexpected_err] = value
+        command_config[:unexpected_err] = value
       end
 
       # This method checks if a caller method has been set; if not, it defaults to `:call`.
       # @return [Symbol] The name of the method to call.
       def call_as(value = :call)
-        @__command_config[:call_as] = value
+        command_config[:call_as] = value
 
         singleton_class.send(:alias_method, value, :call)
       end
 
+      # WIP: experimental
+      # TODO: set of methods
+      def ar_transaction(*cmd_methods, returnable: true)
+        has_ar_defined = defined?(ActiveRecord::Base) && ActiveRecord::Base.respond_to?(:transaction)
+        raise ERR::ConfigurationError, 'No ActiveRecord defined' unless has_ar_defined
+
+        has_valid_mthds = cmd_methods.any? { |value| value.is_a?(Symbol) }
+        raise ERR::ConfigurationError, 'Invalid types. Accepts Array[Symbol]' unless has_valid_mthds
+
+        command_config[:ar_transaction] = {
+          methods: cmd_methods,
+          returnable: returnable
+        }
+
+        dynamic_module = Module.new do
+          cmd_methods.each do |method_name|
+            define_method(method_name) do |*args, **kwargs, &block|
+              rez = ActiveRecord::Base.transaction do
+                result = super(*args, **kwargs, &block)
+
+                # Rollbacks to prevent partial transaction state
+                if returnable && !result.is_a?(HatiCommand::Result)
+                  raise ERR::ConfigurationError,
+                        'This command configuration requires explicit Result-return from transaction'
+                end
+
+                # Allows explicit partial commit
+                if result.failure?
+                  raise ERR::TransactionError.new('Transaction brake has been triggered', failure_obj: result.value)
+                end
+
+                result
+              end
+
+              rez
+            rescue ERR::TransactionError => e
+              # TODO: process trace corectly (line of code)
+              HatiCommand::Failure.new(e.failure_obj, err: e.message, trace: e.backtrace&.first)
+            # Every other error including FailFast goes to main caller method
+            rescue ActiveRecord::ActiveRecordError => e
+              # TODO: process trace
+              HatiCommand::Failure.new(e, err: e.message, trace: e.backtrace&.first)
+            end
+          end
+        end
+
+        prepend dynamic_module
+      end
+
       # Executes the command with the given arguments.
       #
       # This method creates a new instance of the command class, yields it to an optional block,
@@ -86,36 +136,53 @@ module HatiCommand
       #
       # @param args [Array] Arguments to be passed to the instance method.
       # @yield [Object] Optional block that yields the new instance for additional configuration.
-      # @return [HatiCommand::Result, Object] The result of the command execution, wrapped in a Result object if applicable.
+      # @return [HatiCommand::Result, Object] The result of the command, wrapped in a Result object if applicable.
       # @raise [HatiCommand::Errors::FailFastError] If a fail-fast condition is triggered.
       # @raise [StandardError] If an unexpected error occurs and no handler is configured.
-      def call(...)
-        obj = new
-
-        yield(obj) if block_given?
+      def call(*args, __command_reciever: nil, **kwargs, &block)
+        result = caller_result(*args, __command_reciever: __command_reciever, **kwargs, &block)
 
-        result = obj.send(command_config[:call_as], ...)
         return result unless command_config[:result_inference]
         return result if result.is_a?(HatiCommand::Result)
 
         HatiCommand::Success.new(result)
-      rescue HatiCommand::Errors::FailFastError => e
+      rescue ERR::FailFastError => e
         handle_fail_fast_error(e)
       rescue StandardError => e
         handle_standard_error(e)
       end
 
+      # TODO: think on opts to hide reciever
+      def caller_result(*args, __command_reciever: nil, **kwargs, &block)
+        # expecting pre-configured reciever if given
+        if __command_reciever
+          obj = __command_reciever
+        else
+          obj = new
+          yield(obj) if !obj && block_given?
+        end
+
+        # TODO: add error if no instance method to call
+        obj.send(command_config[:call_as] || :call, *args, **kwargs, &block)
+      end
+
       module_function
 
+      # @return [Hash] The current command configuration settings
+      # @api private
+      def __command_config
+        @__command_config ||= {}
+      end
+
       # Handles fail-fast errors during command execution
       # @param error [HatiCommand::Errors::FailFastError] The fail-fast error to handle
       # @return [HatiCommand::Failure] A failure object containing error details
       # @api private
       def handle_fail_fast_error(error)
-        err_obj = error.err_obj
-        return HatiCommand::Failure.new(error, trace: error.backtrace.first) unless err_obj
+        failure_obj = error.failure_obj
+        return HatiCommand::Failure.new(error, trace: error.backtrace.first) unless failure_obj
 
-        err_obj.tap { |err| err.trace = error.backtrace[1] }
+        failure_obj.tap { |err| err.trace = error.backtrace[1] }
       end
 
       # Handles standard errors during command execution
@@ -130,6 +197,12 @@ module HatiCommand
         err = internal_err.is_a?(TrueClass) ? error : internal_err
         HatiCommand::Failure.new(error, err: err, trace: error.backtrace.first)
       end
+
+      def execute_with_transaction_handling?
+        has_ar_defined = defined?(ActiveRecord::Base) && ActiveRecord::Base.respond_to?(:transaction)
+
+        !!(command_config.dig(:ar_transaction, :methods) && has_ar_defined)
+      end
     end
   end
 end

data/lib/hati_command/callee.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require 'pry'
-
 # @module HatiCommand
 # Provides command handling functionalities and callable patterns.
 module HatiCommand

data/lib/hati_command/cmd.rb

@@ -73,8 +73,8 @@ module HatiCommand
       default_error = self.class.command_config[:fail_fast] || self.class.command_config[:failure]
       error = err || default_error
 
-      err_obj = HatiCommand::Failure.new(value, err: error, meta: meta)
-      raise HatiCommand::Errors::FailFastError.new('Fail Fast Triggered', err_obj: err_obj)
+      failure_obj = HatiCommand::Failure.new(value, err: error, meta: meta)
+      raise HatiCommand::Errors::FailFastError.new('Fail Fast Triggered', failure_obj: failure_obj)
     end
   end
 end

data/lib/hati_command/errors/base_error.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module HatiCommand
+  module Errors
+    # Custom BaseError class for command issues scenarios in HatiCommand
+    #
+    # @example Raising a BaseError with a message
+    #   raise HatiCommand::Error::BaseError, "Operation failed"
+    class BaseError < StandardError
+      DEFAULT_MSG = 'Default message: Oooops! Something went wrong. Please check the logs.'
+
+      attr_reader :failure_obj
+
+      # @param message [String] The error message
+      # @param failure_obj [Object] An optional Error || Failure DTO
+      def initialize(message = nil, failure_obj: nil)
+        msg = build_msg + (message || default_message)
+        super(msg)
+        @failure_obj = failure_obj
+      end
+
+      def error_klass
+        self.class.name
+      end
+
+      def build_msg
+        "[#{error_klass}] "
+      end
+
+      def default_message
+        DEFAULT_MSG
+      end
+    end
+  end
+end

data/lib/hati_command/errors/configuration_error.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module HatiCommand
+  module Errors
+    # Custom error class for configuration issues scenarios in HatiCommand
+    class ConfigurationError < BaseError
+      def default_message
+        'Invalid configurations'
+      end
+    end
+  end
+end

data/lib/hati_command/errors/fail_fast_error.rb

@@ -2,28 +2,10 @@
 
 module HatiCommand
   module Errors
-    # Custom error class for fail-fast scenarios in HatiCommand
-    #
-    # @example Raising a FailFastError with a message
-    #   raise HatiCommand::FailFastError.new("Operation failed")
-    #
-    # @example Raising a FailFastError with a message and error object
-    #   begin
-    #     # Some operation that might fail
-    #   rescue StandardError => e
-    #     raise HatiCommand::FailFastError.new("Operation failed", err_obj: e)
-    #   end
-    class FailFastError < StandardError
-      # @return [Object] The associated error object
-      attr_reader :err_obj
-
-      # Initialize a new FailFastError
-      #
-      # @param message [String] The error message
-      # @param err_obj [Object] An optional error object associated with this error
-      def initialize(message, err_obj: nil)
-        super(message)
-        @err_obj = err_obj
+    # Custom error class for FailFast scenario in HatiCommand
+    class FailFastError < BaseError
+      def default_message
+        'Halt Execution'
       end
     end
   end

data/lib/hati_command/errors/transaction_error.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module HatiCommand
+  module Errors
+    # Custom error class for Transaction issue scenarios in HatiCommand
+    class TransactionError < BaseError
+      def default_message
+        'Transaction Error has been triggerd'
+      end
+    end
+  end
+end

data/lib/hati_command/result.rb

@@ -43,7 +43,7 @@ module HatiCommand
   #   @return [Array<String>, nil] Execution trace information for debugging
   class Result
     attr_reader :value, :meta
-    attr_accessor :trace
+    attr_accessor :trace, :err
 
     # Initializes a new Result instance with a value and optional context.
     #

data/lib/hati_command/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module HatiCommand
-  VERSION = '0.1.0.beta1'
+  VERSION = '0.1.0'
 end

data/lib/hati_command.rb

@@ -2,7 +2,10 @@
 
 require 'hati_command/version'
 # errors
+require 'hati_command/errors/base_error'
+require 'hati_command/errors/configuration_error'
 require 'hati_command/errors/fail_fast_error'
+require 'hati_command/errors/transaction_error'
 # result
 require 'hati_command/result'
 require 'hati_command/success'
@@ -10,4 +13,5 @@ require 'hati_command/failure'
 # core
 require 'hati_command/callee'
 require 'hati_command/befehl'
+# cmd
 require 'hati_command/cmd'

metadata

@@ -1,18 +1,17 @@
 --- !ruby/object:Gem::Specification
 name: hati-command
 version: !ruby/object:Gem::Version
-  version: 0.1.0.beta1
+  version: 0.1.0
 platform: ruby
 authors:
-- yurigitsu
-- MarieGiy
-autorequire:
+- Mariya Giy
+- Yuri Gi
 bindir: bin
 cert_chain: []
-date: 2025-06-14 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description: hati-command is a Ruby gem for implementing the Command pattern with
-  result handling.
+description: hati-command is a Ruby gem for implementing Service objects, Command
+  pattern and Interactors with result handling.
 email:
 - yurigi.pro@gmail.com
 - giy.mariya@gmail.com
@@ -27,7 +26,10 @@ files:
 - lib/hati_command/befehl.rb
 - lib/hati_command/callee.rb
 - lib/hati_command/cmd.rb
+- lib/hati_command/errors/base_error.rb
+- lib/hati_command/errors/configuration_error.rb
 - lib/hati_command/errors/fail_fast_error.rb
+- lib/hati_command/errors/transaction_error.rb
 - lib/hati_command/failure.rb
 - lib/hati_command/result.rb
 - lib/hati_command/success.rb
@@ -43,7 +45,6 @@ metadata:
   source_code_uri: https://github.com/hackico-ai/hati-command
   bug_tracker_uri: https://github.com/hackico-ai/hati-command/issues
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -58,8 +59,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
-summary: A Ruby gem for creating command objects with result handling.
+summary: A Ruby gem for creating Service objects, Command pattern, and Interactors
+  with result handling.
 test_files: []