standard_procedure_operations 0.3.0 → 0.3.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f99019aca1964cfe7e6607d45c1c253ed73f8081702b596bb6fdbb918c7d74f7
-  data.tar.gz: 8c6599fe4f7227226ecc23773902eb8f2c3e0a5d37d2f6f3a918a8dfff8ee35b
+  metadata.gz: 71a0ca8e718085505be26fcb316ed4a1e2f9338a12ea55901626696fe5e15269
+  data.tar.gz: 3b94981a2c8b8193bc01ee4f414db2c34161ac111c85a59f68eb3c88dd3b7aa6
 SHA512:
-  metadata.gz: 2d40c6a60efea70434ae993ad37d5872f71173cf1c4d6e61cf436f735538dc9e72c9d268a40a7c7be81ebb66a7bc46ff70b868ff6af66bf30db1c574eca8787b
-  data.tar.gz: 5931d257ab4d45b04d20f96244ce20a65d292808bf10eae66930fcfe0bf35e52d1c539bde83c8fabf8ddff0cdb44be548f763b0949671aaaa5309bda039f285d
+  metadata.gz: 970184f8761aa729ceebf0cc5fa00a0c8c24a8ef9b1afaa3203b990d92c7c992441a51ef07579efcc93f4948f94d4da4b21c5df07df2adea700523cdb290d13d
+  data.tar.gz: 970e42aecaf9a622c259e27eb830a283ff1be70a4545ab01a4a42debe65ccf2cfcf68aa817a3778c2cfee503957cbf0c96de59e0ace254e2d773e1bb41d5c96e

data/README.md

@@ -116,6 +116,20 @@ end
 ```
 (In theory the block used in the `fail_with` case can do anything within the [DataCarrier context](#data-and-results) - so you could set internal state or call methods on the containing task - but I've not tried this yet).
 
+Alternatively, you can evaluate multiple conditions in your decision handler.  
+
+```ruby 
+decision :is_the_weather_good? do 
+  condition { weather_forecast.sunny? }
+  go_to :the_beach 
+  condition { weather_forecast.rainy? }
+  go_to :grab_an_umbrella 
+  condition { weather_forecast.snowing? }
+  go_to :build_a_snowman 
+end
+```
+If no conditions are matched then the task fails with a `NoDecision` exception.
+
 You can specify the data that is required for a decision handler to run by specifying `inputs` and `optionals`:
 ```ruby
 decision :authorised? do 
@@ -158,7 +172,20 @@ end
 Do not forget to call `go_to` from your action handler, otherwise the operation will just stop whilst still being marked as in progress.  (TODO: don't let this happen).
 
 ### Waiting
-Wait handlers only work within [background tasks](#background-operations-and-pauses).  They define a condition that is evaluated; if it is false, the task is paused and the condition re-evaluated later.  If it is true, the task moves to the next state.  
+Wait handlers are very similar to decision handlers but only work within [background tasks](#background-operations-and-pauses).  
+
+```ruby 
+wait_until :weather_forecast_available? do 
+  condition { weather_forecast.sunny? }
+  go_to :the_beach 
+  condition { weather_forecast.rainy? }
+  go_to :grab_an_umbrella 
+  condition { weather_forecast.snowing? }
+  go_to :build_a_snowman 
+end
+```
+
+If no conditions are met, then, unlike a decision handler, the task continues waiting in the same state.  
 
 ### Results
 A result handler marks the end of an operation, optionally returning some results.  You need to copy your desired results from your [data](#data-and-results) to your results object.  This is so only the information that matters to you is stored as the results.  
@@ -431,6 +458,19 @@ class UserRegistration < Operations::Task
 end
 ```
 
+Instead of failing with an `Operations::Timeout` exception, you define an `on_timeout` handler for any special processing should the time-out occur.  
+
+```ruby 
+class WaitForSomething < Operations::Task 
+  timeout 10.minutes 
+  delay 1.minute 
+
+  on_timeout do 
+    Notifier.send_timeout_notification
+  end
+end>
+```
+
 ## Testing
 Because operations are intended to model long, complex, flowcharts of decisions and actions, it can be a pain coming up with the combinations of inputs to test every path through the sequence.  
 

data/app/models/operations/task/background.rb

@@ -10,17 +10,23 @@ module Operations::Task::Background
       @execution_timeout = value
     end
 
+    def on_timeout(&handler) = @on_timeout = handler
+
     def background_delay = @background_delay ||= 1.second
 
     def execution_timeout = @execution_timeout ||= 5.minutes
 
+    def timeout_handler = @on_timeout
+
     def with_timeout(data) = data.merge(_execution_timeout: execution_timeout.from_now.utc)
   end
 
   private def background_delay = self.class.background_delay
   private def execution_timeout = self.class.execution_timeout
+  private def timeout_handler = self.class.timeout_handler
   private def timeout!
-    raise Operations::Timeout.new("Timeout expired", self) if timeout_expired?
+    return unless timeout_expired?
+    timeout_handler.nil? ? raise(Operations::Timeout.new("Timeout expired", self)) : timeout_handler.call
   end
   private def timeout_expired? = data[:_execution_timeout].present? && data[:_execution_timeout] < Time.now.utc
 end

data/app/models/operations/task/state_management/decision_handler.rb

@@ -3,13 +3,16 @@ class Operations::Task::StateManagement::DecisionHandler
 
   def initialize name, &config
     @name = name.to_sym
-    @condition = nil
+    @conditions = []
+    @destinations = []
     @true_state = nil
     @false_state = nil
     instance_eval(&config)
   end
 
-  def condition(&condition) = @condition = condition
+  def condition(&condition) = @conditions << condition
+
+  def go_to(destination) = @destinations << destination
 
   def if_true(state = nil, &handler) = @true_state = state || handler
 
@@ -17,7 +20,20 @@ class Operations::Task::StateManagement::DecisionHandler
 
   def call(task, data)
     validate_inputs! data.to_h
-    next_state = data.instance_eval(&@condition) ? @true_state : @false_state
+    has_true_false_handlers? ? handle_single_condition(task, data) : handle_multiple_conditions(task, data)
+  end
+
+  private def has_true_false_handlers? = !@true_state.nil? || !@false_state.nil?
+
+  private def handle_single_condition(task, data)
+    next_state = data.instance_eval(&@conditions.first) ? @true_state : @false_state
     next_state.respond_to?(:call) ? data.instance_eval(&next_state) : data.go_to(next_state)
   end
+
+  private def handle_multiple_conditions(task, data)
+    condition = @conditions.find { |condition| data.instance_eval(&condition) }
+    raise Operations::NoDecision.new("No conditions matched #{@name}") if condition.nil?
+    index = @conditions.index condition
+    data.go_to @destinations[index]
+  end
 end

data/app/models/operations/task/state_management/wait_handler.rb

@@ -1,18 +1,27 @@
 class Operations::Task::StateManagement::WaitHandler
   def initialize name, &config
     @name = name.to_sym
-    @next_state = nil
-    @condition = nil
+    @conditions = []
+    @destinations = []
     instance_eval(&config)
+    puts "Configured"
   end
 
-  def condition(&condition) = @condition = condition
+  def condition(&condition) = @conditions << condition
 
-  def go_to(state) = @next_state = state
+  def go_to(state) = @destinations << state
 
   def call(task, data)
     raise Operations::CannotWaitInForeground.new("#{task.class} cannot wait in the foreground", task) unless task.background?
-    next_state = data.instance_eval(&@condition) ? @next_state : task.state
-    data.go_to(next_state)
+    puts "Searching"
+    condition = @conditions.find { |condition| data.instance_eval(&condition) }
+    if condition.nil?
+      puts "None"
+      data.go_to task.state
+    else
+      index = @conditions.index condition
+      puts "Found #{@destinations[index]}"
+      data.go_to @destinations[index]
+    end
   end
 end

data/lib/operations/no_decision.rb

@@ -0,0 +1,2 @@
+class Operations::NoDecision < Operations::Error
+end

data/lib/operations/version.rb

@@ -1,3 +1,3 @@
 module Operations
-  VERSION = "0.3.0"
+  VERSION = "0.3.5"
 end

data/lib/operations.rb

@@ -14,4 +14,5 @@ module Operations
   require "operations/failure"
   require "operations/cannot_wait_in_foreground"
   require "operations/timeout"
+  require "operations/no_decision"
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: standard_procedure_operations
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.5
 platform: ruby
 authors:
 - Rahoul Baruah
 bindir: bin
 cert_chain: []
-date: 2025-02-05 00:00:00.000000000 Z
+date: 2025-03-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -54,6 +54,7 @@ files:
 - lib/operations/failure.rb
 - lib/operations/global_id_serialiser.rb
 - lib/operations/matchers.rb
+- lib/operations/no_decision.rb
 - lib/operations/timeout.rb
 - lib/operations/version.rb
 - lib/standard_procedure_operations.rb