hanikamu-operation 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8ff21656b7650f8c722178312ccfe54ed372086a165bcf13bd358f27d5880dd6
-  data.tar.gz: 2b22c2521306b5e64a07bc510631c088d84100298947248fd4c27d8fdda8f3f2
+  metadata.gz: c0b23bd074385d4c3f45c13b8c247fd39e3b367567bc64b03a2a55db400f3b2a
+  data.tar.gz: d2c55ea2d5f6aac49462c6c964ccb2d81c568b37ac3cb85143285521eb85ab86
 SHA512:
-  metadata.gz: 33b2a094c24b6d9690e2666a60cf2453d93b2e73113a8d7a247a46f7a0bfeca661301f61f711c26fa94a911d55655b4c9b181930a9fcb5b8f4bbbc8e416db55e
-  data.tar.gz: 536172f90b5899eed4abf90c95984498dabc4695aa340109430b8be7835076fccca466fad27ce377e01e94c518105ca2e211fc496030560d765ddd2331f8163b
+  metadata.gz: '049de88ca1deb2c3604300762ce87fb3b7dad4657f6ffcbd553c33cc086cda780971b5859e84be171ca6800dca2a75c9cbb0de439bef7ad2999bda6c96e953e8'
+  data.tar.gz: 80f4dfb5e621dd5c914fc853596828277f940c13cbbc1935d30ed64ea2b42ceb1c79bbeeb1ab14d135a768b581bca2d77a83e2c9fbcaa1a5f9dc5728852cb88e

data/CHANGELOG.md

@@ -7,3 +7,10 @@
 ## [0.1.1] - 2025-11-26
 
 - Updated Gemfile.lock
+
+## [0.1.2] - 2025-12-05
+
+- **Breaking Change**: Minimum Ruby version is now 3.4.0
+- Removed `redis-client` as direct dependency (now transitive through `redlock`)
+- Updated CI to test only Ruby 3.4
+- Improved README with clearer FormError vs GuardError examples

data/README.md

@@ -8,9 +8,8 @@ A Ruby gem that extends [hanikamu-service](https://github.com/Hanikamu/hanikamu-
 
 1. [Why Hanikamu::Operation?](#why-hanikamuoperation)
 2. [Quick Start](#quick-start)
-3. [Installation](#installation)
-4. [Setup](#setup)
-5. [Usage](#usage)
+3. [Setup](#setup)
+4. [Usage](#usage)
    - [Basic Operation](#basic-operation)
    - [Distributed Locking](#distributed-locking-with-within_mutex)
    - [Database Transactions](#database-transactions-with-within_transaction)
@@ -18,14 +17,14 @@ A Ruby gem that extends [hanikamu-service](https://github.com/Hanikamu/hanikamu-
    - [Guard Conditions](#guard-conditions)
    - [Block Requirements](#block-requirements)
    - [Complete Example](#complete-example-combining-all-features)
-6. [Error Handling](#error-handling)
-7. [Best Practices](#best-practices)
-8. [Configuration Reference](#configuration-reference)
-9. [Testing](#testing)
-10. [Development](#development)
-11. [Contributing](#contributing)
-12. [License](#license)
-13. [Credits](#credits)
+5. [Error Handling](#error-handling)
+6. [Best Practices](#best-practices)
+7. [Configuration Reference](#configuration-reference)
+8. [Testing](#testing)
+9. [Development](#development)
+10. [Contributing](#contributing)
+11. [License](#license)
+12. [Credits](#credits)
 
 ## Why Hanikamu::Operation?
 
@@ -63,9 +62,11 @@ Use `Hanikamu::Operation` (instead of plain `Hanikamu::Service`) when your busin
 
 **1. Install the gem**
 
+Requires Ruby 3.4.0 or later.
+
 ```ruby
 # Gemfile
-gem 'hanikamu-operation', '~> 0.1.1'
+gem 'hanikamu-operation', '~> 0.1.2'
 ```
 
 ```bash
@@ -122,32 +123,19 @@ else
 end
 ```
 
-## Installation
-
-Add to your application's Gemfile:
-
-```ruby
-gem 'hanikamu-operation', '~> 0.1.1'
-```
-
-Then execute:
-
-```bash
-bundle install
-```
-
 ## Setup
 
-### Rails Application Setup Guide
+### Rails Application Setup
 
 Follow these steps to integrate Hanikamu::Operation into a Rails application:
 
 **Step 1: Add the gem to your Gemfile**
 
+Requires Ruby 3.4.0 or later.
+
 ```ruby
 # Gemfile
-gem 'hanikamu-operation', '~> 0.1.1'
-gem 'redis-client', '~> 0.22'  # Required for distributed locking
+gem 'hanikamu-operation', '~> 0.1.2'
 ```
 
 ```bash
@@ -214,68 +202,7 @@ brew services start redis
 REDIS_URL=redis://localhost:6379/0
 ```
 
-**Step 5: Create your first operation**
-
-```bash
-# Create operations directory
-mkdir -p app/operations/users
-```
-
-```ruby
-# app/operations/users/create_user_operation.rb
-module Users
-  class CreateUserOperation < Hanikamu::Operation
-    attribute :email, Types::String
-    attribute :password, Types::String
-
-    validates :email, presence: true, format: { with: URI::MailTo::EMAIL_REGEXP }
-    validates :password, length: { minimum: 8 }
-
-    within_transaction(:base)
-
-    def execute
-      user = User.create!(
-        email: email,
-        password: password
-      )
-
-      response user: user
-    end
-  end
-end
-```
-
-**Step 6: Use in your controller**
-
-```ruby
-# app/controllers/users_controller.rb
-class UsersController < ApplicationController
-  def create
-    result = Users::CreateUserOperation.call(user_params)
-
-    if result.success?
-      user = result.success.user
-      render json: { user: user }, status: :created
-    else
-      error = result.failure
-      case error
-      when Hanikamu::Operation::FormError
-        render json: { errors: error.errors.full_messages }, status: :unprocessable_entity
-      else
-        render json: { error: error.message }, status: :internal_server_error
-      end
-    end
-  end
-
-  private
-
-  def user_params
-    params.require(:user).permit(:email, :password)
-  end
-end
-```
-
-**Step 7: Configure for production**
+**Step 5: Production configuration**
 
 Set your Redis URL in production (Heroku, AWS, etc.):
 
@@ -284,71 +211,11 @@ Set your Redis URL in production (Heroku, AWS, etc.):
 heroku addons:create heroku-redis:mini
 # REDIS_URL is automatically set
 
-# Or set manually
+# Or set manually for other providers
 heroku config:set REDIS_URL=redis://your-redis-host:6379/0
 ```
 
-### Detailed Configuration Options
-
-If you need more control, create a detailed initializer:
-
-```ruby
-# config/initializers/hanikamu_operation.rb
-require 'redis-client'
-
-Hanikamu::Operation.configure do |config|
-  # Required: Redis client for distributed locking
-  config.redis_client = RedisClient.new(
-    url: ENV.fetch('REDIS_URL', 'redis://localhost:6379/0'),
-    reconnect_attempts: 3,
-    timeout: 1.0
-  )
-
-  # Optional: Customize Redlock settings (these are the defaults)
-  config.mutex_expire_milliseconds = 1500  # Lock TTL
-  config.redlock_retry_count = 6           # Number of retry attempts
-  config.redlock_retry_delay = 500         # Milliseconds between retries
-  config.redlock_retry_jitter = 50         # Random jitter to prevent thundering herd
-  config.redlock_timeout = 0.1             # Redis command timeout
-
-  # Optional: Add errors to whitelist (Redlock::LockError is always included by default)
-  config.whitelisted_errors = [CustomBusinessError]
-end
-```
-
-### Redis Setup by Environment
-
-**For Development (Docker Compose)**:
-
-```yaml
-# docker-compose.yml
-services:
-  redis:
-    image: redis:7-alpine
-    volumes:
-      - redis_data:/data
-    networks:
-      - app_network
-
-  app:
-    # ... your app config
-    environment:
-      REDIS_URL: redis://redis:6379/0
-    depends_on:
-      - redis
-    networks:
-      - app_network
-
-volumes:
-  redis_data:
-
-networks:
-  app_network:
-```
-
-**For Production**:
-
-Use a managed Redis service (AWS ElastiCache, Heroku Redis, Redis Labs, etc.) and set the `REDIS_URL` environment variable.
+For advanced configuration options, see the [Configuration Reference](#configuration-reference) section below.
 
 ## Usage
 
@@ -764,52 +631,68 @@ Operations validate at three distinct levels, each serving a specific purpose:
 
 ### FormError vs GuardError: Practical Examples
 
-**FormError Example** - Invalid or incorrect input arguments:
+Here's a complete example demonstrating the difference between form validations and guard conditions:
 
 ```ruby
-# Attempting to create a user with invalid inputs
-result = Users::CreateUserOperation.call(
-  email: "taken@example.com",
-  password: "short",
-  password_confirmation: "wrong"
-)
-# => Failure(#<Hanikamu::Operation::FormError: 
-#      Email has been taken, 
-#      Password is too short, 
-#      Password confirmation does not match password>)
-
-# Correcting the arguments allows success
-result = Users::CreateUserOperation.call(
-  email: "unique@example.com",
-  password: "securePassword123!",
-  password_confirmation: "securePassword123!"
-)
-# => Success(#<struct user=#<User id: 46, email: "unique@example.com">>)
+class TestOperation < Hanikamu::Operation
+  attribute :sentence, Types::String
+
+  # Form validation - checks input value format/content
+  validates :sentence, presence: true
+  validates :sentence, exclusion: { in: ["form_error"], message: "is not allowed" }
+
+  # Guard validation - checks business rules/state
+  guard do
+    delegates :sentence
+
+    validates :sentence, exclusion: { in: ["guard_error"], message: "is not allowed" }
+  end
+
+  within_mutex(:mutex_lock)
+  within_transaction(:base)
+
+  def execute
+    response(message: sentence.reverse)
+  end
+
+  def mutex_lock
+    self.class.name
+  end
+end
 ```
 
-**GuardError Example** - Valid arguments but invalid system state:
+**FormError Example** - Invalid input value triggers form validation:
 
 ```ruby
-# First attempt succeeds
-result = Users::CompleteUserOperation.call!(user_id: 46)
-# => Success(#<struct user=#<User id: 46, completed_at: "2025-11-26">>)
+# Form validation fails - input itself is invalid
+result = TestOperation.call(sentence: "form_error")
+# => Failure(#<Hanikamu::Operation::FormError: Sentence is not allowed>)
+
+# Correcting the input allows the operation to proceed
+result = TestOperation.call(sentence: "hello world")
+# => Success(#<struct message="dlrow olleh">)
+```
 
-# Second attempt fails due to state, even with valid arguments
-result = Users::CompleteUserOperation.call!(user_id: 46)
-# => Failure(#<Hanikamu::Operation::GuardError: User has already been completed>)
+**GuardError Example** - Valid input but business rule violated:
 
-# The arguments are still correct, but the operation cannot proceed
-# because the user's state has changed
+```ruby
+# Input passes form validation, but guard fails
+result = TestOperation.call(sentence: "guard_error")
+# => Failure(#<Hanikamu::Operation::GuardError: Sentence is not allowed>)
+
+# The input format is valid, but the business rule prevents execution
 ```
 
 **Type Error Example** - Wrong argument type:
 
 ```ruby
-# Passing wrong type raises immediately
-Users::CompleteUserOperation.call!(user_id: "not-a-number")
+# Passing wrong type raises immediately before any validations
+TestOperation.call!(sentence: 123)
 # => Raises Dry::Struct::Error
 ```
 
+**Key Insight**: Form validations check if the *input is correct*, while guards check if the *operation can proceed* given the current state.
+
 ### Using `.call!` (Raises Exceptions)
 
 ```ruby

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hanikamu-operation
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Nicolai Seerup
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-11-27 00:00:00.000000000 Z
+date: 2025-12-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -132,7 +132,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.2.0
+      version: 3.4.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="