standard_procedure_operations 0.2.3 → 0.2.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 27f6593a2e233607d6247450ca043995e23d33dcb4af69129c314d4e89d2dab1
-  data.tar.gz: 6ba1683666c67b27de61f3d99ed61a4f2badb962622f06e7174cb71a09ccee93
+  metadata.gz: 278552bfcbf35e101f4022a0d95004cc593473803b0b6578349afe945c1b6d18
+  data.tar.gz: 6be975b9b3d9b88e67eb63cef2cb582c9fbb12ff7b881a1ceb288f33ac74c21d
 SHA512:
-  metadata.gz: b40b93fd31799d31f53294a234733c492520731332aeeea6bc6e1fa747fa19c550a5d407a4573f0fd0161404ba4e63a046454ce28b423ddb0b384700139812cf
-  data.tar.gz: 0d4e28d7e9a5d4d77343d8bcb56b0deff90f76c79d1da0bb980e8134354302e68bdf745d71f97e0d86f43ade3c419ed8486db444e47a92ba03597e33605b4f78
+  metadata.gz: d271751ea12a1efd3083b32445ae3dfceeadcdea464702515ff83bfbf1c91157192bf4797149557ca0a1009d9963a97fcd62910359b78375d15eb2225f5c9612
+  data.tar.gz: 670ac183d0f130c4086ac4d0057e265fc69bdc5f7898628837fd8ed831588551d5cf1c37b9c81e8a4cfa104a957ba4caee870fc943f655201ab38baf1a9909b8

data/README.md

@@ -48,27 +48,38 @@ class PrepareDocumentForDownload < Operations::Task
   starts_with :authorised?
 
   decision :authorised? do
+    inputs :user
+
     if_true :within_download_limits?
     if_false { fail_with "unauthorised" }
   end
 
   decision :within_download_limits? do
+    inputs :user
+
     if_true :use_filename_scrambler?
     if_false { fail_with "download_limit_reached" }
   end
 
   decision :use_filename_scrambler? do
+    inputs :use_filename_scrambler
     condition { use_filename_scrambler }
+
     if_true :scramble_filename
     if_false :return_filename
   end
 
   action :scramble_filename do
+    inputs :document
+
     self.filename = "#{Faker::Lorem.word}#{File.extname(document.filename.to_s)}"
     go_to :return_filename
   end
 
   result :return_filename do |results|
+    inputs :document
+    optional :filename
+
     results.filename = filename || document.filename.to_s
   end
 
@@ -89,6 +100,7 @@ It's up to you whether you define the condition as a block, as part of the decis
 ```ruby
 decision :is_it_the_weekend? do 
   condition { Date.today.wday.in? [0, 6] }
+
   if_true :have_a_party 
   if_false :go_to_work
 end
@@ -104,6 +116,7 @@ def is_it_the_weekend?(data)
   Date.today.wday.in? [0, 6]
 end
 ```
+
 A decision can also mark a failure, which will terminate the task.  
 ```ruby
 decision :authorised? do 
@@ -113,6 +126,20 @@ decision :authorised? do
 end
 ```
 
+You can specify the data that is required for a decision handler to run by specifying `inputs` and `optionals`:
+```ruby
+decision :authorised? do 
+  inputs  :user 
+  optionals :override
+
+  condition { override || user.administrator? }
+
+  if_true :do_some_work 
+  if_false { fail_with "Unauthorised" }
+end
+```
+In this case, the task will fail if there is no `user` specified.  However, `override` is optional (and in fact the `optional` method is just there to help you document your operations).
+
 ### Actions
 An action handler does some work, then moves to another state.  
 
@@ -124,7 +151,21 @@ action :have_a_party do
   go_to :send_invitations
 end
 ```
-Again, instead of using a block in the action handler, you could provide a method to do the work.
+You can specify the required and optional data for your action handler within the block.  `optional` is decorative and to help with your documentation.  Ensure you call `inputs` at the start of the block.  
+
+```ruby 
+action :have_a_party do
+  inputs :task 
+  optional :music 
+
+  self.food = task.buy_some_food_for(number_of_guests)
+  self.beer = task.buy_some_beer_for(number_of_guests)
+  self.music ||= task.plan_a_party_playlist
+  go_to :send_invitations
+end
+```
+
+Again, instead of using a block in the action handler, you could provide a method to do the work.  However, you cannot specify `inputs` or `optional` data when using a method.  
 
 ```ruby
 action :have_a_party
@@ -143,6 +184,8 @@ Do not forget to call `go_to` from your action handler, otherwise the operation
 ### 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 in the database (as many operations may have a large set of working data).  
 
+There is no method equivalent to a block handler.  
+
 ```ruby
 action :send_invitations do 
   self.invited_friends = (0..number_of_guests).collect do |i|
@@ -165,6 +208,24 @@ result :go_to_work
 ```
 In this case, the task will be marked as `completed?`, the task's state will be `go_to_work` and `results` will be empty.  
 
+You can also specify the required and optional data for your result handler within the block.  `optional` is decorative and to help with your documentation.  Ensure you call `inputs` at the start of the block.  
+```ruby
+action :send_invitations do 
+  inputs :number_of_guests
+  self.invited_friends = (0..number_of_guests).collect do |i|
+    friend = friends.pop
+    FriendsMailer.with(recipient: friend).party_invitation.deliver_later
+    friend 
+  end
+  go_to :ready_to_party
+end
+
+result :ready_to_party do |results|
+  inputs :invited_friends 
+
+  results.invited_friends = invited_friends
+end
+
 ### Calling an operation
 You would use the earlier [PrepareDocumentForDownload](spec/examples/prepare_document_for_download_spec.rb) operation in a controller like this:
 
@@ -312,6 +373,7 @@ The gem is available as open source under the terms of the [LGPL License](/LICEN
 
 ## Roadmap
 
+- [x] Specify inputs (required and optional) per-state, not just at the start
 - [ ] Always raise errors instead of just recording a failure (will be useful when dealing with sub-tasks)
 - [ ] Simplify calling sub-tasks (and testing the same)
 - [ ] Split out the state-management definition stuff from the task class (so you can use it without subclassing Operations::Task)

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

@@ -4,4 +4,11 @@ class Operations::Task::DataCarrier < OpenStruct
   def fail_with(message) = task.fail_with(message)
 
   def complete(results) = task.complete(results)
+
+  def inputs(*names)
+    missing_inputs = (names.map(&:to_sym) - to_h.keys)
+    raise ArgumentError.new("Missing inputs: #{missing_inputs.join(", ")}") if missing_inputs.any?
+  end
+
+  def optional(*names) = nil
 end

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

@@ -0,0 +1,17 @@
+module Operations::Task::InputValidation
+  def inputs(*names) = @required_inputs = names.map(&:to_sym)
+
+  def optional(*names) = @optional_inputs = names.map(&:to_sym)
+
+  def optional_inputs = @optional_inputs ||= []
+
+  def required_inputs = @required_inputs ||= []
+
+  def required_inputs_are_present_in?(hash) = missing_inputs_from(hash).empty?
+
+  def missing_inputs_from(hash) = (required_inputs - hash.keys.map(&:to_sym))
+
+  def validate_inputs! hash
+    raise ArgumentError, "Missing inputs: #{missing_inputs_from(hash).join(", ")}" unless required_inputs_are_present_in?(hash)
+  end
+end

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

@@ -0,0 +1,12 @@
+class Operations::Task::StateManagement::ActionHandler
+  def initialize name, inputs = [], optional = [], &action
+    @name = name.to_sym
+    @required_inputs = inputs
+    @optional_inputs = optional
+    @action = action
+  end
+
+  def call(task, data)
+    @action.nil? ? task.send(@name, data) : data.instance_exec(&@action)
+  end
+end

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

@@ -0,0 +1,14 @@
+class Operations::Task::StateManagement::CompletionHandler
+  def initialize name, inputs = [], optional = [], &handler
+    @name = name.to_sym
+    @required_inputs = inputs
+    @optional_inputs = optional
+    @handler = handler
+  end
+
+  def call(task, data)
+    results = OpenStruct.new
+    data.instance_exec(results, &@handler) unless @handler.nil?
+    data.complete(results)
+  end
+end

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

@@ -0,0 +1,24 @@
+class Operations::Task::StateManagement::DecisionHandler
+  include Operations::Task::InputValidation
+
+  def initialize name, &config
+    @name = name.to_sym
+    @condition = nil
+    @true_state = nil
+    @false_state = nil
+    instance_eval(&config)
+  end
+
+  def condition(&condition) = @condition = condition
+
+  def if_true(state = nil, &handler) = @true_state = state || handler
+
+  def if_false(state = nil, &handler) = @false_state = state || handler
+
+  def call(task, data)
+    validate_inputs! data.to_h
+    result = @condition.nil? ? task.send(@name, data) : data.instance_exec(&@condition)
+    next_state = result ? @true_state : @false_state
+    next_state.respond_to?(:call) ? data.instance_eval(&next_state) : data.go_to(next_state, data)
+  end
+end

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

@@ -7,27 +7,19 @@ module Operations::Task::StateManagement
   end
 
   class_methods do
-    def inputs(*names) = @required_inputs = names.map(&:to_sym)
-
-    def required_inputs = @required_inputs ||= []
-
     def starts_with(value) = @initial_state = value.to_sym
 
     def initial_state = @initial_state
 
     def decision(name, &config) = state_handlers[name.to_sym] = DecisionHandler.new(name, &config)
 
-    def action(name, &handler) = state_handlers[name.to_sym] = ActionHandler.new(name, &handler)
+    def action(name, inputs: [], optional: [], &handler) = state_handlers[name.to_sym] = ActionHandler.new(name, inputs, optional, &handler)
 
-    def result(name, &results) = state_handlers[name.to_sym] = CompletionHandler.new(name, &results)
+    def result(name, inputs: [], optional: [], &results) = state_handlers[name.to_sym] = CompletionHandler.new(name, inputs, optional, &results)
 
     def state_handlers = @state_handlers ||= {}
 
     def handler_for(state) = state_handlers[state.to_sym]
-
-    def required_inputs_are_present_in?(data) = missing_inputs_from(data).empty?
-
-    def missing_inputs_from(data) = (required_inputs - data.keys.map(&:to_sym))
   end
 
   private def handler_for(state) = self.class.handler_for(state.to_sym)
@@ -39,50 +31,4 @@ module Operations::Task::StateManagement
   private def state_is_valid
     errors.add :state, :invalid if state.blank? || handler_for(state.to_sym).nil?
   end
-
-  class ActionHandler
-    def initialize name, &action
-      @name = name.to_sym
-      @action = action
-    end
-
-    def call(task, data)
-      @action.nil? ? task.send(@name, data) : data.instance_exec(&@action)
-    end
-  end
-
-  class DecisionHandler
-    def initialize name, &config
-      @name = name.to_sym
-      @condition = nil
-      @true_state = nil
-      @false_state = nil
-      instance_eval(&config)
-    end
-
-    def condition(&condition) = @condition = condition
-
-    def if_true(state = nil, &handler) = @true_state = state || handler
-
-    def if_false(state = nil, &handler) = @false_state = state || handler
-
-    def call(task, data)
-      result = @condition.nil? ? task.send(@name, data) : data.instance_exec(&@condition)
-      next_state = result ? @true_state : @false_state
-      next_state.respond_to?(:call) ? data.instance_eval(&next_state) : data.go_to(next_state, data)
-    end
-  end
-
-  class CompletionHandler
-    def initialize name, &handler
-      @name = name.to_sym
-      @handler = handler
-    end
-
-    def call(task, data)
-      results = OpenStruct.new
-      data.instance_exec(results, &@handler) unless @handler.nil?
-      data.complete(results)
-    end
-  end
 end

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

@@ -10,7 +10,7 @@ module Operations::Task::Testing
     end
   end
 
-  class TestResultCarrier < OpenStruct
+  class TestResultCarrier < Operations::Task::DataCarrier
     def go_to(state, message = nil)
       self.next_state = state
       self.status_message = message || next_state.to_s

data/app/models/operations/task.rb

@@ -3,11 +3,13 @@ module Operations
     include StateManagement
     include Deletion
     include Testing
+    extend InputValidation
+
     enum :status, in_progress: 0, completed: 1, failed: -1
     serialize :results, coder: Operations::GlobalIDSerialiser, type: Hash, default: {}
 
     def self.call(data = {})
-      raise MissingInputsError, "Missing inputs: #{missing_inputs_from(data).join(", ")}" unless required_inputs_are_present_in?(data)
+      validate_inputs! data
       create!(state: initial_state, status_message: "").tap do |task|
         task.send(:process_current_state, DataCarrier.new(data.merge(task: task)))
       end

data/lib/operations/version.rb

@@ -1,3 +1,3 @@
 module Operations
-  VERSION = "0.2.3"
+  VERSION = "0.2.5"
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: standard_procedure_operations
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.2.5
 platform: ruby
 authors:
 - Rahoul Baruah
 bindir: bin
 cert_chain: []
-date: 2025-01-31 00:00:00.000000000 Z
+date: 2025-02-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -36,7 +36,11 @@ files:
 - app/models/operations/task.rb
 - app/models/operations/task/data_carrier.rb
 - app/models/operations/task/deletion.rb
+- app/models/operations/task/input_validation.rb
 - app/models/operations/task/state_management.rb
+- app/models/operations/task/state_management/action_handler.rb
+- app/models/operations/task/state_management/completion_handler.rb
+- app/models/operations/task/state_management/decision_handler.rb
 - app/models/operations/task/testing.rb
 - config/routes.rb
 - db/migrate/20250127160616_create_operations_tasks.rb