standard-procedure-plumbing 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a0bfd8678cd958f92a30d6c1879e664ac790637b400a2fd73302a7ed60a3b450
-  data.tar.gz: f06824216f1d2da14fa645b0f246106180e6e8e69f8fa7d5526e8a343ac77923
+  metadata.gz: 71e621c375dc0a17f928884eee2718fc7ed89a2f113374e90a5e6532914d71ea
+  data.tar.gz: 6632624c924bdee49e9dc4b273da36792916c434d12b867d874bcd1ddb880b8b
 SHA512:
-  metadata.gz: ac2e9872aba1ecb6c4f2831ee6da3689afdcf1162c5bc0b65eaa2298ae1a00f4d698fb7909c34e10daa6b14cd10bcd8ab54cd92839fab7a1107cd93de831c2c5
-  data.tar.gz: 64f585e329a112504b692b788d6b6c9562bc188eb9c621a33001f2aed69d92c6260909c8a3df174436bfeda345791b7ca370afb09fdad2d281d466efcb0784fc
+  metadata.gz: aa02b3cc5688ebeed1ec98f22142077d9c26e952bc34772d9395d6d120f2a5103efc67a5cc0e3f7508c937f6392a294f3d6088d8adca9d7415cf81cb2e7f28e6
+  data.tar.gz: d2a164087e839fc3cd48d9b0c22cee9765541a388e4ffc48f5f614faa4690b69d7aa17a6bfc6d77d03ce2ed91e2af49cb8a02fa98e094117194414d7dbd49470

data/CHANGELOG.md

@@ -1,3 +1,8 @@
+## [0.2.0] - 2024-08-14
+
+ - Added optional Dry::Validation support
+ - Use Async for fiber-based pipes
+
 ## [0.1.2] - 2024-08-14
 
  - Removed dependencies

data/README.md

@@ -99,7 +99,15 @@ end
 
 Define a sequence of operations that proceed in order, passing their output from one operation as the input to another.
 
-You can define pre-conditions (which validate the inputs supplied) or post-conditions (which validate the output).  
+Use `perform` to define a step that takes some input and returns a different output.  
+Use `execute` to define a step that takes some input and returns that same input.  
+Use `embed` to define a step that uses another `Plumbing::Chain` class to generate the output.  
+
+If you have [dry-validation](https://dry-rb.org/gems/dry-validation/1.10/) installed, you can validate your input using a `Dry::Validation::Contract`.  
+
+If you don't want to use dry-validation, you can instead define a `pre_condition` - there's nothing to stop you defining a contract as well as pre_conditions (with the contract being verified first).  
+
+You can also verify that the output generated is as expected by defining a `post_condition`.  
 
 ### Usage:
 
@@ -107,11 +115,12 @@ You can define pre-conditions (which validate the inputs supplied) or post-condi
 require "plumbing"
 class BuildSequence < Plumbing::Chain 
   pre_condition :must_be_an_array do |input| 
+    # you could replace this with a `validate` definition (using a Dry::Validation::Contract) if you prefer
     input.is_a? Array 
   end
 
   post_condition :must_have_three_elements do |output|
-    # yes, this is a stupid post-condition but it shows how you can ensure your outputs are valid
+    # yes, this is a stupid post-condition but 🤷🏾‍♂️
     output.length == 3
   end
 

data/lib/plumbing/chain/contracts.rb

@@ -0,0 +1,46 @@
+module Plumbing
+  class Chain
+    module Contracts
+      def pre_condition name, &validator
+        pre_conditions[name.to_sym] = validator
+      end
+
+      def validate_with contract_class
+        @validation_contract = contract_class
+      end
+
+      def post_condition name, &validator
+        post_conditions[name.to_sym] = validator
+      end
+
+      private
+
+      def pre_conditions
+        @pre_conditions ||= {}
+      end
+
+      def post_conditions
+        @post_conditions ||= {}
+      end
+
+      def validate_contract_for input
+        return true if @validation_contract.nil?
+        result = const_get(@validation_contract).new.call(input)
+        raise PreConditionError, result.errors.to_h.to_yaml unless result.success?
+        input
+      end
+
+      def validate_preconditions_for input
+        failed_preconditions = pre_conditions.select { |name, validator| !validator.call(input) }
+        raise PreConditionError, failed_preconditions.keys.join(", ") if failed_preconditions.any?
+        input
+      end
+
+      def validate_postconditions_for output
+        failed_postconditions = post_conditions.select { |name, validator| !validator.call(output) }
+        raise PostConditionError, failed_postconditions.keys.join(", ") if failed_postconditions.any?
+        output
+      end
+    end
+  end
+end

data/lib/plumbing/chain/operations.rb

@@ -0,0 +1,40 @@
+module Plumbing
+  class Chain
+    module Operations
+      def perform method, &implementation
+        implementation ||= ->(input, instance) { instance.send(method, input) }
+        operations << implementation
+      end
+
+      def embed method, class_name
+        implementation = ->(input, instance) { const_get(class_name).new.call(input) }
+        operations << implementation
+      end
+
+      def execute method
+        implementation ||= ->(input, instance) do
+          instance.send(method, input)
+          input
+        end
+        operations << implementation
+      end
+
+      def _call input, instance
+        validate_contract_for input
+        validate_preconditions_for input
+        result = input
+        operations.each do |operation|
+          result = operation.call(result, instance)
+        end
+        validate_postconditions_for result
+        result
+      end
+
+      private
+
+      def operations
+        @operations ||= []
+      end
+    end
+  end
+end

data/lib/plumbing/chain.rb

@@ -1,59 +1,14 @@
+require_relative "chain/contracts"
+require_relative "chain/operations"
+
 module Plumbing
   # A chain of operations that are executed in sequence
   class Chain
-    def call params
-      self.class._call params, self
-    end
-
-    class << self
-      def pre_condition name, &validator
-        pre_conditions[name.to_sym] = validator
-      end
-
-      def perform method, &implementation
-        implementation ||= ->(params, instance) { instance.send(method, params) }
-        operations << implementation
-      end
-
-      def post_condition name, &validator
-        post_conditions[name.to_sym] = validator
-      end
-
-      def _call params, instance
-        validate_preconditions_for params
-        result = params
-        operations.each do |operation|
-          result = operation.call(result, instance)
-        end
-        validate_postconditions_for result
-        result
-      end
-
-      private
-
-      def operations
-        @operations ||= []
-      end
-
-      def pre_conditions
-        @pre_conditions ||= {}
-      end
-
-      def post_conditions
-        @post_conditions ||= {}
-      end
-
-      def validate_preconditions_for input
-        failed_preconditions = pre_conditions.select { |name, validator| !validator.call(input) }
-        raise PreConditionError, failed_preconditions.keys.join(", ") if failed_preconditions.any?
-        input
-      end
+    extend Plumbing::Chain::Contracts
+    extend Plumbing::Chain::Operations
 
-      def validate_postconditions_for output
-        failed_postconditions = post_conditions.select { |name, validator| !validator.call(output) }
-        raise PostConditionError, failed_postconditions.keys.join(", ") if failed_postconditions.any?
-        output
-      end
+    def call input
+      self.class._call input, self
     end
   end
 end

data/lib/plumbing/fiber/pipe.rb

@@ -0,0 +1,36 @@
+require "async/task"
+require "async/semaphore"
+
+module Plumbing
+  module Fiber
+    # An implementation of a pipe that uses Fibers
+    class Pipe < Plumbing::Pipe
+      attr_reader :active
+
+      def initialize limit: 4
+        super()
+        @limit = 4
+        @semaphore = Async::Semaphore.new(@limit)
+      end
+
+      def << event
+        raise Plumbing::InvalidEvent.new "event is not a Plumbing::Event" unless event.is_a? Plumbing::Event
+        @semaphore.async do |task|
+          dispatch event, task
+        end
+      end
+
+      protected
+
+      def dispatch event, task
+        @observers.collect do |observer|
+          task.async do
+            observer.call event
+          rescue => ex
+            puts "Error: #{ex}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/plumbing/filter.rb

@@ -1,29 +1,26 @@
-require_relative "blocked_pipe"
-
 module Plumbing
   # A pipe that filters events from a source pipe
-  class Filter < BlockedPipe
+  class Filter < Pipe
     class InvalidFilter < Error; end
 
     # Chain this pipe to the source pipe
-    # @param source [Plumbing::BlockedPipe]
+    # @param source [Plumbing::Pipe]
     # @param accepts [Array[String]] event types that this filter will allow through (or pass [] to allow all)
     # @param rejects [Array[String]] event types that this filter will not allow through
     def initialize source:, accepts: [], rejects: []
       super()
-      raise InvalidFilter.new "source must be a Plumbing::BlockedPipe descendant" unless source.is_a? Plumbing::BlockedPipe
+      raise InvalidFilter.new "source must be a Plumbing::Pipe descendant" unless source.is_a? Plumbing::Pipe
       raise InvalidFilter.new "accepts and rejects must be arrays" unless accepts.is_a?(Array) && rejects.is_a?(Array)
       @accepted_event_types = accepts
       @rejected_event_types = rejects
       source.add_observer do |event|
-        filter_and_republish(event)
+        filter_and_republish event
       end
     end
 
     private
 
     def filter_and_republish event
-      raise InvalidEvent.new "event is not a Plumbing::Event" unless event.is_a? Plumbing::Event
       return nil if @accepted_event_types.any? && !@accepted_event_types.include?(event.type)
       return nil if @rejected_event_types.include? event.type
       dispatch event

data/lib/plumbing/pipe.rb

@@ -1,29 +1,79 @@
-require_relative "blocked_pipe"
-
 module Plumbing
-  # An implementation of a pipe that uses Fibers
-  class Pipe < BlockedPipe
+  # A basic pipe
+  class Pipe
+    # Subclasses should call `super()` to ensure the pipe is initialised corrected
     def initialize
-      super
-      @fiber = Fiber.new do |initial_event|
-        start_run_loop initial_event
-      end
+      @observers = []
     end
 
+    # Push an event into the pipe
+    # @param event [Plumbing::Event] the event to push into the pipe
     def << event
-      raise Plumbing::InvalidEvent.new "event is not a Plumbing::Event" unless event.is_a? Plumbing::Event
-      @fiber.resume event
+      raise Plumbing::InvalidEvent.new event unless event.is_a? Plumbing::Event
+      dispatch event
+    end
+
+    # A shortcut to creating and then pushing an event
+    # @param event_type [String] representing the type of event this is
+    # @param data [Hash] representing the event-specific data to be passed to the observers
+    def notify event_type, data = nil
+      Event.new(type: event_type, data: data).tap do |event|
+        self << event
+      end
+    end
+
+    # Add an observer to this pipe
+    # @param callable [Proc] (optional)
+    # @param &block [Block] (optional)
+    # @return an object representing this observer (dependent upon the implementation of the pipe itself)
+    # Either a `callable` or a `block` must be supplied.  If the latter, it is converted to a [Proc]
+    def add_observer observer = nil, &block
+      observer ||= block.to_proc
+      raise Plumbing::InvalidObserver.new "observer_does_not_respond_to_call" unless observer.respond_to? :call
+      @observers << observer
     end
 
+    # Remove an observer from this pipe
+    # @param observer
+    # This removes the given observer from this pipe.  The observer should have previously been returned by #add_observer and is implementation-specific
+    def remove_observer observer
+      @observers.delete observer
+    end
+
+    # Test whether the given observer is observing this pipe
+    # @param observer
+    # @return [boolean]
+    def is_observer? observer
+      @observers.include? observer
+    end
+
+    # Close this pipe and perform any cleanup.
+    # Subclasses should override this to perform their own shutdown routines and call `super` to ensure everything is tidied up
     def shutdown
-      super
-      @fiber.resume :shutdown
+      # clean up and release any observers, just in case
+      @observers = []
+    end
+
+    # Start this pipe
+    # Subclasses may override this method to add any implementation specific details.
+    # By default any supplied parameters are called to the subclass' `initialize` method
+    def self.start(**params)
+      new(**params)
     end
 
     protected
 
-    def get_next_event
-      Fiber.yield
+    # Dispatch an event to all observers
+    # @param event [Plumbing::Event]
+    # Enumerates all observers and `calls` them with this event
+    # Discards any errors raised by the observer so that all observers will be successfully notified
+    def dispatch event
+      @observers.collect do |observer|
+        observer.call event
+      rescue => ex
+        puts ex
+        ex
+      end
     end
   end
 end

data/lib/plumbing/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Plumbing
-  VERSION = "0.1.2"
+  VERSION = "0.2.0"
 end

data/lib/plumbing.rb

@@ -1,10 +1,12 @@
 # frozen_string_literal: true
 
-module Plumbing
-  require_relative "plumbing/version"
+require_relative "plumbing/version"
+
+require_relative "plumbing/error"
+require_relative "plumbing/event"
+require_relative "plumbing/pipe"
+require_relative "plumbing/filter"
+require_relative "plumbing/chain"
 
-  require_relative "plumbing/error"
-  require_relative "plumbing/event"
-  require_relative "plumbing/pipe"
-  require_relative "plumbing/chain"
+module Plumbing
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard-procedure-plumbing
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Rahoul Baruah
@@ -29,19 +29,21 @@ files:
 - checksums/standard-procedure-plumbing-0.1.1.gem.sha512
 - checksums/standard-procedure-plumbing-0.1.2.gem.sha512
 - lib/plumbing.rb
-- lib/plumbing/blocked_pipe.rb
 - lib/plumbing/chain.rb
+- lib/plumbing/chain/contracts.rb
+- lib/plumbing/chain/operations.rb
 - lib/plumbing/error.rb
 - lib/plumbing/event.rb
+- lib/plumbing/fiber/pipe.rb
 - lib/plumbing/filter.rb
 - lib/plumbing/pipe.rb
 - lib/plumbing/version.rb
 - sig/plumbing.rbs
-homepage: https://theartandscienceofruby.com
+homepage: https://github.com/standard-procedure/plumbing
 licenses: []
 metadata:
   allowed_push_host: https://rubygems.org
-  homepage_uri: https://theartandscienceofruby.com
+  homepage_uri: https://github.com/standard-procedure/plumbing
   source_code_uri: https://github.com/standard-procedure/plumbing
   changelog_uri: https://github.com/standard-procedure/plumbing/blob/main/CHANGELOG.md
 post_install_message:

data/lib/plumbing/blocked_pipe.rb

@@ -1,105 +0,0 @@
-require_relative "error"
-require_relative "event"
-
-module Plumbing
-  # The "plumbing" for a Pipe.
-  # This class is "blocked", in that it won't push any events to registered observers.
-  # Instead, this is the basis for subclasses like [Plumbing::Pipe] which actually allow events to flow through them.
-  class BlockedPipe
-    # Create a new BlockedPipe
-    # Subclasses should call `super()` to ensure the pipe is initialised corrected
-    def initialize
-      @observers = []
-    end
-
-    # Push an event into the pipe
-    # @param event [Plumbing::Event] the event to push into the pipe
-    # Subclasses should implement this method
-    def << event
-      raise Plumbing::PipeIsBlocked
-    end
-
-    # A shortcut to creating and then pushing an event
-    # @param event_type [String] representing the type of event this is
-    # @param data [Hash] representing the event-specific data to be passed to the observers
-    def notify event_type, data = nil
-      Event.new(type: event_type, data: data).tap do |event|
-        self << event
-      end
-    end
-
-    # Add an observer to this pipe
-    # @param callable [Proc] (optional)
-    # @param &block [Block] (optional)
-    # @return an object representing this observer (dependent upon the implementation of the pipe itself)
-    # Either a `callable` or a `block` must be supplied.  If the latter, it is converted to a [Proc]
-    def add_observer observer = nil, &block
-      observer ||= block.to_proc
-      raise Plumbing::InvalidObserver.new "observer_does_not_respond_to_call" unless observer.respond_to? :call
-      @observers << observer
-    end
-
-    # Remove an observer from this pipe
-    # @param observer
-    # This removes the given observer from this pipe.  The observer should have previously been returned by #add_observer and is implementation-specific
-    def remove_observer observer
-      @observers.delete observer
-    end
-
-    # Test whether the given observer is observing this pipe
-    # @param observer
-    # @return [boolean]
-    def is_observer? observer
-      @observers.include? observer
-    end
-
-    # Close this pipe and perform any cleanup.
-    # Subclasses should override this to perform their own shutdown routines and call `super` to ensure everything is tidied up
-    def shutdown
-      # clean up and release any observers, just in case
-      @observers = []
-    end
-
-    # Start this pipe
-    # Subclasses may override this method to add any implementation specific details.
-    # By default any supplied parameters are called to the subclass' `initialize` method
-    def self.start(**params)
-      new(**params)
-    end
-
-    protected
-
-    # Get the next event from the queue
-    # @return [Plumbing::Event]
-    # Subclasses should implement this method
-    def get_next_event
-      raise Plumbing::PipeIsBlocked
-    end
-
-    # Start the event loop
-    # This loop keeps running until `shutdown` is called
-    # Some subclasses may need to replace this method to deal with their own specific implementations
-    # @param initial_event [Plumbing::Event] optional; the first event in the queue
-    def start_run_loop initial_event = nil
-      loop do
-        event = initial_event || get_next_event
-        break if event == :shutdown
-        dispatch event
-        initial_event = nil
-      end
-    end
-
-    # Dispatch an event to all observers
-    # @param event [Plumbing::Event]
-    # Enumerates all observers and `calls` them with this event
-    # Discards any errors raised by the observer so that all observers will be successfully notified
-    def dispatch event
-      @observers.collect do |observer|
-        observer.call event
-      rescue => ex
-        puts ex
-        ex
-      end
-    end
-  end
-end