hanikamu-operation 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c0b23bd074385d4c3f45c13b8c247fd39e3b367567bc64b03a2a55db400f3b2a
-  data.tar.gz: d2c55ea2d5f6aac49462c6c964ccb2d81c568b37ac3cb85143285521eb85ab86
+  metadata.gz: b935969d9ffb9b34935f54e2f9d8adf907603906916a4c1b555499bd25e97f28
+  data.tar.gz: 2fada67131e16535eb5c6480c3a80999315efd0306753aae615a6a582d9cb43d
 SHA512:
-  metadata.gz: '049de88ca1deb2c3604300762ce87fb3b7dad4657f6ffcbd553c33cc086cda780971b5859e84be171ca6800dca2a75c9cbb0de439bef7ad2999bda6c96e953e8'
-  data.tar.gz: 80f4dfb5e621dd5c914fc853596828277f940c13cbbc1935d30ed64ea2b42ceb1c79bbeeb1ab14d135a768b581bca2d77a83e2c9fbcaa1a5f9dc5728852cb88e
+  metadata.gz: cc5970b13fd6511a024b14071b273350604ef811f8bb944ca03f6839ed7f03051d106c63f550225f2b4de181d60c7698f545ecd1219faa1bb813aaa76be340a3
+  data.tar.gz: a691099d6fb2be177d4e19bcfff74e9760716465b2a9ceaff2fa0df33a63027e199377749e285f4a8b9cad02224c93e347e4b229eab60f159aa2d4bc5e585454

data/.cursor/rules/docker-environment.mdc

@@ -0,0 +1,30 @@
+---
+description: Development environment runs via docker-compose. Use Makefile targets instead of local commands.
+alwaysApply: true
+---
+
+# Docker-Compose Development Environment
+
+This project runs entirely inside Docker. Never run Ruby, Bundler, or Redis commands directly on the host.
+
+## Makefile Targets
+
+Use these instead of raw commands:
+
+| Task | Command |
+|------|---------|
+| Run tests | `make rspec` |
+| Run linter (auto-fix) | `make cops` |
+| Open a shell in the container | `make shell` |
+| Open an IRB console | `make console` |
+| Install gems & rebuild | `make bundle` |
+| Build the Docker image | `make build` |
+
+## Important
+
+- All `make` targets use `docker-compose run --rm app` under the hood.
+- Redis is provided as a linked service (`redis://redis:6379/15`) — no local Redis needed.
+- After changing the Gemfile or gemspec, run `make build` to reinstall dependencies.
+- Never use `bundle exec` directly on the host; always go through `make` or `make shell`.
+- Run `make` commands directly without `cd` — use the `working_directory` parameter instead.
+- After every code change, run `make rspec` to verify specs still pass before moving on.

data/.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+  "rubyLsp.rubyVersionManager": {
+    "identifier": "mise"
+  }
+}

data/Dockerfile

@@ -1,5 +1,5 @@
 # Base image
-FROM ruby:3.4.4
+FROM ruby:4.0
 
 WORKDIR "/app"
 

data/Makefile

@@ -14,6 +14,10 @@ console: ## build the image
 rspec: ## build the image
 	docker-compose run --rm app bash -c "bundle exec rspec"
 
+.PHONY: bundle
+bundle: ## install gems and rebuild image
+	docker-compose run --rm app bundle install
+	$(MAKE) build
 
 .PHONY: cops
 cops: ## build the image

data/README.md

@@ -66,7 +66,7 @@ Requires Ruby 3.4.0 or later.
 
 ```ruby
 # Gemfile
-gem 'hanikamu-operation', '~> 0.1.2'
+gem 'hanikamu-operation', '~> 0.2.0'
 ```
 
 ```bash
@@ -135,7 +135,7 @@ Requires Ruby 3.4.0 or later.
 
 ```ruby
 # Gemfile
-gem 'hanikamu-operation', '~> 0.1.2'
+gem 'hanikamu-operation', '~> 0.2.0'
 ```
 
 ```bash
@@ -332,6 +332,38 @@ def mutex_lock
 end
 ```
 
+**Conditional locking with `:if` / `:unless`**:
+
+When the lock key is derived from an optional attribute, a `nil` value produces a degenerate shared key (e.g., `"Order$"`) that serializes all operations. Use `:if` or `:unless` to skip the Redis lock entirely when it isn't needed:
+
+```ruby
+class ProcessOrderOperation < Hanikamu::Operation
+  attribute :order_id?, Types::Params::Integer.optional
+
+  within_mutex(:mutex_lock, if: -> { order_id.present? })
+
+  def execute
+    # ...
+    response(successful: true)
+  end
+
+  def mutex_lock
+    "Order$#{order_id}"
+  end
+end
+```
+
+- When `order_id` is present, the lock is acquired on `"Order$42"` as usual.
+- When `order_id` is `nil`, no Redis round-trip occurs — the operation runs without a lock.
+
+The `:unless` option works inversely:
+
+```ruby
+within_mutex(:mutex_lock, unless: -> { order_id.nil? })
+```
+
+The lambda is evaluated via `instance_exec` on the operation instance, so it has access to all attributes and methods. Providing both `:if` and `:unless` raises `ArgumentError`.
+
 ### Database Transactions with `within_transaction`
 
 Ensure multiple database changes succeed or fail together atomically. If any database operation raises an exception, all changes are rolled back.

data/lib/hanikamu/operation.rb

@@ -6,7 +6,7 @@ module Hanikamu
   class Operation < Hanikamu::Service
     include ActiveModel::Validations
 
-    Error = Class.new(Hanikamu::Service::Error)
+    class Error < Hanikamu::Service::Error; end
 
     # Error classes
     class FormError < Hanikamu::Service::Error
@@ -91,9 +91,15 @@ module Hanikamu
       end
 
       # DSL methods
-      def within_mutex(lock_key, expire_milliseconds: nil)
+      def within_mutex(lock_key, expire_milliseconds: nil, if: nil, unless: nil)
+        if_condition = binding.local_variable_get(:if)
+        unless_condition = binding.local_variable_get(:unless)
+        validate_mutex_conditions!(if_condition, unless_condition)
+
         @_mutex_lock_key = lock_key
         @_mutex_expire_milliseconds = expire_milliseconds || Hanikamu::Operation.config.mutex_expire_milliseconds
+        @_mutex_if_condition = if_condition
+        @_mutex_unless_condition = unless_condition
       end
 
       def within_transaction(klass)
@@ -144,7 +150,24 @@ module Hanikamu
       end
       # rubocop:enable Metrics/MethodLength
 
-      attr_reader :_mutex_lock_key, :_mutex_expire_milliseconds, :_transaction_klass, :_block
+      attr_reader :_mutex_lock_key, :_mutex_expire_milliseconds, :_mutex_if_condition, :_mutex_unless_condition,
+                  :_transaction_klass, :_block
+
+      private
+
+      def validate_mutex_conditions!(if_condition, unless_condition)
+        if if_condition && unless_condition
+          raise ArgumentError, "Cannot specify both :if and :unless conditions for within_mutex"
+        end
+
+        if if_condition && !if_condition.respond_to?(:call)
+          raise ArgumentError, "within_mutex :if condition must be a callable (e.g. a Proc or lambda)"
+        end
+
+        return unless unless_condition && !unless_condition.respond_to?(:call)
+
+        raise ArgumentError, "within_mutex :unless condition must be a callable (e.g. a Proc or lambda)"
+      end
     end
 
     def call!(&block)
@@ -167,15 +190,11 @@ module Hanikamu
     end
 
     def within_mutex!(&)
-      return yield if _lock_key.nil?
-
-      Hanikamu::Operation.redis_lock.lock!(_lock_key, self.class._mutex_expire_milliseconds, &)
-    end
-
-    def _lock_key
-      return if self.class._mutex_lock_key.blank?
+      return yield if self.class._mutex_lock_key.blank?
+      return yield unless _should_apply_mutex?
 
-      public_send(self.class._mutex_lock_key)
+      lock_key = public_send(self.class._mutex_lock_key)
+      Hanikamu::Operation.redis_lock.lock!(lock_key, self.class._mutex_expire_milliseconds, &)
     end
 
     def within_transaction!(&)
@@ -186,6 +205,13 @@ module Hanikamu
 
     private
 
+    def _should_apply_mutex?
+      return false if self.class._mutex_if_condition && !instance_exec(&self.class._mutex_if_condition)
+      return false if self.class._mutex_unless_condition && instance_exec(&self.class._mutex_unless_condition)
+
+      true
+    end
+
     def transaction_class
       return if self.class._transaction_klass.nil?
       return ActiveRecord::Base if self.class._transaction_klass == :base

metadata

@@ -1,15 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hanikamu-operation
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Nicolai Seerup
 - Alejandro Jimenez
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-12-05 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -102,11 +101,12 @@ dependencies:
 description: |
   Ruby gem for building robust service operations with guard validations, distributed mutex locks via Redlock,
   database transactions, and comprehensive error handling. Thread-safe and designed for production Rails applications.
-email:
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".cursor/rules/docker-environment.mdc"
+- ".vscode/settings.json"
 - CHANGELOG.md
 - Dockerfile
 - LICENSE.txt
@@ -124,7 +124,6 @@ metadata:
   source_code_uri: https://github.com/Hanikamu/hanikamu-operation
   changelog_uri: https://github.com/Hanikamu/hanikamu-operation/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -139,8 +138,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.3
-signing_key:
+rubygems_version: 4.0.3
 specification_version: 4
 summary: Service objects with guards, distributed locks, and transactions
 test_files: []