hati-operation 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: eaa8b845b9e4b4606f8d19f71c4af9718c794469376a242476ee3ebe30b57085
+  data.tar.gz: cd6f76883931c8b29f566b18cb76fbeae85404ab8b9d1f29e3b4f85713ea5acd
+SHA512:
+  metadata.gz: eb41943860ad28b45f31de2d7bc23beb3c52bea08c4a40248645116c4da20f78d98fe113354a3d0d000ef134f8b26d6e3f39a9deb59b649c5605acd11f57dd50
+  data.tar.gz: 79e6e7bd186fcd52206e8774a6240337d5b1aa81dc86f15b604ce20e3f32c3dbe9800ac6fa1a6a91892031dc330bad7c08889a94facba2017d609ac59e97cd86

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 hackico.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,243 @@
+# HatiOperation
+
+[![Gem Version](https://badge.fury.io/rb/hati_operation.svg)](https://rubygems.org/gems/hati_operation)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](#license)
+
+HatiOperation is a lightweight Ruby toolkit that helps you compose domain logic into clear, reusable **operations**. Built on top of [hati-command](https://github.com/hackico-ai/ruby-hati-command), it serves as an **aggregator** that orchestrates multiple services and commands into cohesive business operations.
+
+## ✨ Key Features
+
+- **Step-based execution** – write each unit of work as a small service object and compose them with `step`
+- **Implicit result propagation** – methods return `Success(...)` or `Failure(...)` and are automatically unpacked
+- **Fail-fast transactions** – stop the chain as soon as a step fails
+- **Dependency injection (DI)** – override steps at call-time for ultimate flexibility
+- **Macro DSL** – declaratively configure validation, error mapping, transactions and more
+- **Service aggregation** – orchestrate multiple services into cohesive business operations
+
+## 🏗️ Architecture
+
+HatiOperation builds on top of [hati-command](https://github.com/hackico-ai/ruby-hati-command) and serves as an **aggregator pattern** implementation:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    HatiOperation                            │
+│                   (Aggregator Layer)                        │
+├─────────────────────────────────────────────────────────────┤
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │
+│  │  Service A  │  │  Service B  │  │  Service C  │          │
+│  │ (Command)   │  │ (Command)   │  │ (Command)   │          │
+│  └─────────────┘  └─────────────┘  └─────────────┘          │
+├─────────────────────────────────────────────────────────────┤
+│                   hati-command                              │
+│                 (Foundation Layer)                          │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## 📋 Table of Contents
+
+1. [Installation](#installation)
+2. [Quick Start](#quick-start)
+3. [Step DSL](#step-dsl)
+4. [Dependency Injection](#dependency-injection)
+5. [Alternative DSL Styles](#alternative-dsl-styles)
+6. [Testing](#testing)
+7. [Contributing](#contributing)
+8. [License](#license)
+
+## 🚀 Installation
+
+Add HatiOperation to your Gemfile and bundle:
+
+```ruby
+# Gemfile
+gem 'hati_operation'
+```
+
+```bash
+bundle install
+```
+
+Alternatively:
+
+```bash
+gem install hati_operation
+```
+
+## 🎯 Quick Start
+
+The example below shows how HatiOperation can be leveraged inside a **Rails API** controller to aggregate multiple services:
+
+```ruby
+# app/controllers/api/v1/withdrawal_controller.rb
+class Api::V1::WithdrawalController < ApplicationController
+  def create
+    result = Withdrawal::Operation::Create.call(params: params.to_unsafe_h)
+
+    run_and_render(result)
+  end
+
+  private
+
+  def run_and_render(result)
+    if result.success?
+      render json: TransferSerializer.new.serialize(result.value), status: :created
+    else
+      error = ApiError.new(result.value)
+      render json: error.to_json, status: error.status
+    end
+  end
+end
+```
+
+### 🔧 Defining the Operation
+
+```ruby
+# app/operations/withdrawal/operation/create.rb
+class Withdrawal::Operation::Create < HatiOperation::Base
+  # Wrap everything in DB transaction
+  ar_transaction :funds_transfer_transaction!
+
+  def call(params:)
+    params = step MyApiContract.call(params), err: ApiErr.call(422)
+    transfer = step funds_transfer_transaction(params[:account_id])
+    EventBroadcast.new.stream(transfer.to_event)
+
+    transfer.meta
+  end
+
+  def funds_transfer_transaction(acc_id)
+    acc = Account.find_by(find_by: acc_id).presence : Failure!(err: ApiErr.call(404))
+
+    withdrawal = step WithdrawalService.call(acc), err: ApiErr.call(409)
+    transfer = step ProcessTransferService.call(withdrawal), err: ApiErr.call(503)
+
+    Success(transfer)
+  end
+end
+```
+
+### 🎛️ Base Operation Configuration
+
+```ruby
+class ApiOperation < HatiOperation::Base
+  operation do
+    unexpected_err ApiErr.call(500)
+  end
+end
+```
+
+## 🛠️ Step DSL
+
+The DSL gives you fine-grained control over every stage of the operation:
+
+### Core DSL Methods
+
+- `step` – register a dependency service
+- `params` – validate/transform incoming parameters
+- `on_success` – handle successful operation results
+- `on_failure` – map and handle failure results
+
+### Extended Configuration
+
+> 📖 **See:** [hati-command](https://github.com/hackico-ai/ruby-hati-command) for all configuration options
+
+- `ar_transaction` – execute inside database transaction
+- `fail_fast` – configure fail-fast behavior
+- `failure` – set default failure handling
+- `unexpected_err` – configure generic error behavior
+
+## 🔄 Dependency Injection
+
+At runtime you can swap out any step for testing, feature-flags, or different environments:
+
+```ruby
+result = Withdrawal::Operation::Create.call(params) do
+  step broadcast: DummyBroadcastService
+  step transfer:  StubbedPaymentProcessor
+end
+```
+
+## 🎨 Alternative DSL Styles
+
+### Declarative Style
+
+Prefer more declarative code? Use the class-level DSL:
+
+```ruby
+class Withdrawal::Operation::Create < ApiOperation
+  params CreateContract, err: ApiErr.call(422)
+
+  ar_transaction :funds_transfer_transaction!
+
+  step withdrawal: WithdrawalService, err: ApiErr.call(409)
+  step transfer: ProcessTransferService, err: ApiErr.call(503)
+  step broadcast: Broadcast
+
+  on_success SerializerService.call(Transfer, status: 201)
+  on_failure ApiErrorSerializer
+
+  # requires :params keyword to access overwritten params
+  # same as params = step CreateContract.call(params), err: ApiErr.call(422)
+  def call(params:)
+    transfer = step funds_transfer_transaction!(params[:account_id])
+    broadcast.new.stream(transfer.to_event)
+    transfer.meta
+  end
+
+  def funds_transfer_transaction!(acc_id)
+    acc = step(err: ApiErr.call(404)) { User.find(id) }
+
+    withdrawal = step withdrawal.call(acc)
+    transfer = step transfer.call(withdrawal)
+    Success(transfer)
+  end
+end
+
+class Api::V2::WithdrawalController < ApiController
+  def create
+    run_and_render Withdrawal::Operation::Create
+  end
+
+  private
+
+  def run_and_render(operation, &block)
+   render JsonResult.prepare operation.call(params.to_unsafe_h).value
+  end
+end
+```
+
+### 🏗️ Full-Stack DI Example
+
+```ruby
+class Api::V2::WithdrawalController < ApplicationController
+  def create
+    run_and_render Withdrawal::Operation::Create.call(params.to_unsafe_h) do
+      step broadcast: API::V2::BroadcastService
+      step transfer:  API::V2::PaymentProcessorService
+      step serializer: ExtendedTransferSerializer
+    end
+  end
+end
+```
+
+## 🧪 Testing
+
+Run the test-suite with:
+
+```bash
+bundle exec rspec
+```
+
+HatiOperation is fully covered by RSpec. See `spec/` for reference examples including stubbed services and DI.
+
+## 🤝 Contributing
+
+Bug reports and pull requests are welcome on GitHub. Please:
+
+1. Fork the project and create your branch from `main`
+2. Run `bundle exec rspec` to ensure tests pass
+3. Submit a pull request with a clear description of your changes
+
+## 📄 License
+
+HatiOperation is released under the MIT License.

data/hati-operation.gemspec

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require 'hati_operation/version'
+
+Gem::Specification.new do |spec|
+  spec.name    = 'hati-operation'
+  spec.version = HatiOperation::VERSION
+  spec.authors = ['Mariya Giy']
+  spec.email   = %w[giy.mariya@gmail.com]
+  spec.license = 'MIT'
+
+  spec.summary     = 'A Ruby gem for encapsulating business logic in reusable, testable operation classes.'
+  spec.description = 'Encapsulates business logic in isolated, reusable operation classes for clarity and testability'
+  spec.homepage    = "https://github.com/hackico-ai/#{spec.name}"
+
+  spec.required_ruby_version = '>= 3.0.0'
+
+  spec.files  = Dir['CHANGELOG.md', 'LICENSE', 'README.md', 'hati-operation.gemspec', 'lib/**/*']
+  spec.bindir = 'bin'
+  spec.executables   = []
+  spec.require_paths = ['lib']
+
+  spec.metadata['repo_homepage']     = spec.homepage
+  spec.metadata['allowed_push_host'] = 'https://rubygems.org'
+
+  spec.metadata['homepage_uri']    = spec.homepage
+  spec.metadata['changelog_uri']   = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata['source_code_uri'] = spec.homepage
+  spec.metadata['bug_tracker_uri'] = "#{spec.homepage}/issues"
+
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  # TODO: while in dev
+  # spec.add_dependency 'hati-command'
+end

data/lib/hati_operation/base.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require 'hati_command'
+
+# Dev version Feautures
+# - implicit result return
+# - object lvl step for <#value> unpacking
+# - forced logical transactional behavior - always fail_fast! on
+#   failure step unpacking
+# - class lvl macro for DI:
+#     * step validate: Validator
+#     * operation for customization (alias to command)
+# - always fail fast on step unpacking
+
+module HatiOperation
+  class Base
+    include HatiCommand::Cmd
+
+    class << self
+      alias operation command
+
+      def operation_config
+        @operation_config ||= {}
+      end
+
+      def params(command, err: nil)
+        operation_config[:params] = command
+        operation_config[:params_err] = err
+      end
+
+      def on_success(command)
+        operation_config[:on_success] = command
+      end
+
+      def on_failure(command)
+        operation_config[:on_failure] = command
+      end
+
+      # TODO: validate type
+      def step(**kwargs)
+        # TODO: add specific error
+        raise 'Invalid Step type. Expected HatiCommand::Cmd' unless included_modules.include?(HatiCommand::Cmd)
+
+        name, command = kwargs.first
+
+        if kwargs[:err]
+          error_name = "#{name}_error".to_sym
+          operation_config[error_name] = kwargs[:err]
+        end
+
+        # WIP: restructure
+        operation_config[name] = command
+
+        define_method(name) do
+          configs = self.class.operation_config
+
+          step_exec_stack.append({ step: name, err: configs[error_name], done: false })
+
+          step_configs[name] || configs[name]
+        end
+      end
+
+      def call(*args, **kwargs, &block)
+        reciever = nil
+        injected_params = nil
+
+        if block_given?
+          reciever = new
+          container = StepConfigContainer.new
+
+          container.instance_eval(&block)
+          # WIP: work on defaults for DSL
+          reciever.step_configs.merge!(container.configurations)
+          injected_params = reciever.step_configs[:params]
+        end
+
+        params_modifier = injected_params || operation_config[:params]
+        # TODO: naming
+        if params_modifier
+          unless kwargs[:params]
+            raise 'If operation config :params is set, caller method must have :params keyword argument'
+          end
+
+          params_rez = params_modifier.call(kwargs[:params])
+          reciever_configs = reciever&.step_configs || {}
+          params_err = reciever_configs[:params_err] || operation_config[:params_err]
+
+          if params_rez.failure?
+            # WIP: override or nest ???
+            params_rez.err = params_err if params_err
+
+            return params_rez
+          end
+
+          kwargs[:params] = params_rez.value
+        end
+
+        result = super(*args, __command_reciever: reciever, **kwargs)
+        # Wrap for implicit
+        rez = result.respond_to?(:success?) ? result : HatiCommand::Success.new(result)
+
+        # TODO: extract
+        success_wrap = operation_config[:on_success]
+        failure_wrap = operation_config[:on_failure]
+
+        return success_wrap&.call(rez) if success_wrap && rez.success?
+        return failure_wrap&.call(rez) if failure_wrap && rez.failure?
+
+        rez
+      end
+    end
+
+    def step_configs
+      @step_configs ||= {}
+    end
+
+    # keep track of step macro calls
+    def step_exec_stack
+      @step_exec_stack ||= []
+    end
+
+    # unpack result
+    # wraps implicitly
+    def step(result = nil, err: nil, &block)
+      return __step_block_call!(err: err, &block) if block_given?
+
+      last_step = step_exec_stack.last
+      err ||= last_step[:err] if last_step
+
+      if result.is_a?(HatiCommand::Result)
+        Failure!(result, err: err || result.error) if result.failure?
+
+        step_exec_stack.last[:done] = true if last_step
+
+        return result.value
+      end
+
+      Failure!(result, err: err) if err && result.nil?
+
+      step_exec_stack.last[:done] = true if last_step
+
+      result
+    end
+
+    def __step_block_call!(err: nil)
+      yield
+    rescue StandardError => e
+      err ? Failure!(e, err: err) : Failure!(e)
+    end
+  end
+end

data/lib/hati_operation/step_configs_container.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module HatiOperation
+  class StepConfigContainer
+    def configurations
+      @configurations ||= {}
+    end
+
+    def step(**kwargs)
+      step_name, step_klass = kwargs.first
+
+      configurations[step_name] = step_klass
+    end
+
+    # WIP: so far as API adapter
+    def params(command = nil, err: nil)
+      configurations[:params] = command
+      configurations[:params_err] = err
+    end
+  end
+end

data/lib/hati_operation/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module HatiOperation
+  VERSION = '0.1.0'
+end

data/lib/hati_operation.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require 'hati_operation/version'
+require 'hati_operation/step_configs_container'
+require 'hati_operation/base'
+# errors
+# require 'hati_operation/errors/base_error'
+# require 'hati_operation/errors/configuration_error'
+# require 'hati_operation/errors/fail_fast_error'
+# require 'hati_operation/errors/transaction_error'

metadata

@@ -0,0 +1,56 @@
+--- !ruby/object:Gem::Specification
+name: hati-operation
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Mariya Giy
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Encapsulates business logic in isolated, reusable operation classes for
+  clarity and testability
+email:
+- giy.mariya@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- hati-operation.gemspec
+- lib/hati_operation.rb
+- lib/hati_operation/base.rb
+- lib/hati_operation/step_configs_container.rb
+- lib/hati_operation/version.rb
+homepage: https://github.com/hackico-ai/hati-operation
+licenses:
+- MIT
+metadata:
+  repo_homepage: https://github.com/hackico-ai/hati-operation
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/hackico-ai/hati-operation
+  changelog_uri: https://github.com/hackico-ai/hati-operation/blob/main/CHANGELOG.md
+  source_code_uri: https://github.com/hackico-ai/hati-operation
+  bug_tracker_uri: https://github.com/hackico-ai/hati-operation/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: A Ruby gem for encapsulating business logic in reusable, testable operation
+  classes.
+test_files: []