standard-procedure-plumbing 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 71e621c375dc0a17f928884eee2718fc7ed89a2f113374e90a5e6532914d71ea
-  data.tar.gz: 6632624c924bdee49e9dc4b273da36792916c434d12b867d874bcd1ddb880b8b
+  metadata.gz: 00f89cef3ca3db2daf437446af1788755906434de2ec2d4e6e81130b26190f84
+  data.tar.gz: 44d27c6f52de7bbc24c488f741035d0a9fe4341036c423e51b5031896ca9f50a
 SHA512:
-  metadata.gz: aa02b3cc5688ebeed1ec98f22142077d9c26e952bc34772d9395d6d120f2a5103efc67a5cc0e3f7508c937f6392a294f3d6088d8adca9d7415cf81cb2e7f28e6
-  data.tar.gz: d2a164087e839fc3cd48d9b0c22cee9765541a388e4ffc48f5f614faa4690b69d7aa17a6bfc6d77d03ce2ed91e2af49cb8a02fa98e094117194414d7dbd49470
+  metadata.gz: 6785c35e5596df5718a8ce458ced0713abbe3d18516a90b6353c806da8f867d3bf4d48d70b8b31b15b7c23a491fa2c855c091250aa96bdf97595f813b53e8e18
+  data.tar.gz: 22169d08af47f789dd5a950635ad46598c6a77f402a2221ed719f369df00b065185b402f14ba2dd2dd82b54cac8774d67d1adc2c07524307a644be11707d7956

data/.vscode/tasks.json

@@ -0,0 +1,11 @@
+{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "rspec",
+      "type": "shell",
+      "command": "rspec",
+      "problemMatcher": []
+    }
+  ]
+}

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.2.1] - 2024-08-25
+
+ - Split the Pipe implementation between the Pipe and EventDispatcher
+ - Use different EventDispatchers to handle fibers or inline pipes
+ - Renamed Chain to Pipeline
+
 ## [0.2.0] - 2024-08-14
 
  - Added optional Dry::Validation support

data/README.md

@@ -1,5 +1,63 @@
 # Plumbing
 
+## Plumbing::Pipeline - transform data through a pipeline
+
+Define a sequence of operations that proceed in order, passing their output from one operation as the input to another.
+
+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` (although 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:
+
+```ruby
+require "plumbing"
+class BuildSequence < Plumbing::Pipeline 
+  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|
+    # this is a stupid post-condition but 🤷🏾‍♂️, this is just an example
+    output.length == 3
+  end
+
+  perform :add_first
+  perform :add_second
+  perform :add_third
+
+  private 
+
+  def add_first input 
+    input << "first"
+  end
+
+  def add_second input 
+    input << "second" 
+  end
+
+  def add_third input 
+    input << "third"
+  end
+end
+
+BuildSequence.new.call []
+# => ["first", "second", "third"]
+
+BuildSequence.new.call 1
+# => Plumbing::PreconditionError("must_be_an_array")
+
+BuildSequence.new.call ["extra element"]
+# => Plumbing::PostconditionError("must_have_three_elements")
+```
+
 ## Plumbing::Pipe - a composable observer
 
 [Observers](https://ruby-doc.org/3.3.0/stdlibs/observer/Observable.html) in Ruby are a pattern where objects (observers) register their interest in another object (the observable).  This pattern is common throughout programming languages (event listeners in Javascript, the dependency protocol in [Smalltalk](https://en.wikipedia.org/wiki/Smalltalk)).
@@ -28,7 +86,9 @@ require "plumbing"
 
 @source = Plumbing::Pipe.start
 
-@filter = Plumbing::Filter.start source: @source, accepts: %w[important urgent]
+@filter = Plumbing::Filter.start source: @source do |event|
+  %w[important urgent].include? event.type 
+end
 
 @observer = @filter.add_observer do |event|
   puts event.type
@@ -83,9 +143,9 @@ require "plumbing"
 @first_source = Plumbing::Pipe.start
 @second_source = Plumbing::Pipe.start
 
-@join = Plumbing::Junction.start @first_source, @second_source
+@junction = Plumbing::Junction.start @first_source, @second_source
 
-@observer = @join.add_observer do |event|
+@observer = @junction.add_observer do |event|
   puts event.type
 end
 
@@ -95,64 +155,31 @@ end
 # => "two"
 ```
 
-## Plumbing::Chain - a chain of operations that occur in sequence
-
-Define a sequence of operations that proceed in order, passing their output from one operation as the input to another.
-
-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:
-
+Dispatching events asynchronously (using Fibers)
 ```ruby
 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
+require "plumbing/event_dispatcher/fiber"
+require "async"
 
-  post_condition :must_have_three_elements do |output|
-    # yes, this is a stupid post-condition but 🤷🏾‍♂️
-    output.length == 3
-  end
+# `limit` controls how many fibers can dispatch events concurrently - the default is 4
+@first_source = Plumbing::Pipe.start dispatcher: Plumbing::EventDispatcher::Fiber.new limit: 8
+@second_source = Plumbing::Pipe.start dispatcher: Plumbing::EventDispatcher::Fiber.new limit: 2
 
-  perform :add_first
-  perform :add_second
-  perform :add_third
-
-  private 
+@junction = Plumbing::Junction.start @first_source, @second_source, dispatcher: Plumbing::EventDispatcher::Fiber.new
 
-  def add_first input 
-    input << "first"
-  end
-
-  def add_second input 
-    input << "second" 
-  end
-
-  def add_third input 
-    input << "third"
-  end
+@filter = Plumbing::Filter.start source: @junction, dispatcher: Plumbing::EventDispatcher::Fibernew do |event|
+  %w[one-one two-two].include? event.type 
 end
 
-BuildSequence.new.call []
-# => ["first", "second", "third"]
-
-BuildSequence.new.call 1
-# => Plumbing::PreconditionError("must_be_an_array")
-
-BuildSequence.new.call ["extra element"]
-# => Plumbing::PostconditionError("must_have_three_elements")
+Sync do 
+  @first_source.notify "one-one"
+  @first_source.notify "one-two"
+  @second_source.notify "two-one"
+  @second_source.notify "two-two"
+end
 ```
 
+
 ## Installation
 
 Install the gem and add to the application's Gemfile by executing:

data/checksums/standard-procedure-plumbing-0.2.0.gem.sha512

@@ -0,0 +1 @@
+f8972f9d59a7a040262dd738514a53e38300604b524f67a16bfc465d69335838fd6861a429c164764f72a4172d54462c8816eeb43d4bafe8099c97eb9fe7b156

data/checksums/standard-procedure-plumbing-0.2.1.gem.sha512

@@ -0,0 +1 @@
+92f63ff4b002a27778854ba86d2bb4b60e4ce7eae93592d3c3e3f90aa03045d961b6dfea86901a7290485d4953df548c521ae49efd7d53547939208515aa392e

data/lib/plumbing/error.rb

@@ -14,6 +14,6 @@ module Plumbing
   # Error raised because an invalid observer was registered
   class InvalidObserver < Error; end
 
-  # Error raised because a BlockedPipe was used instead of an actual implementation of a Pipe
-  class PipeIsBlocked < Plumbing::Error; end
+  # Error raised because a Pipe was connected to a non-Pipe
+  class InvalidSource < Plumbing::Error; end
 end

data/lib/plumbing/event_dispatcher/fiber.rb

@@ -0,0 +1,61 @@
+require "async/task"
+require "async/semaphore"
+
+module Plumbing
+  class EventDispatcher
+    class Fiber < EventDispatcher
+      def initialize limit: 4
+        super()
+        @semaphore = Async::Semaphore.new(limit)
+        @queue = Set.new
+        @paused = false
+      end
+
+      def dispatch event
+        @queue << event
+        dispatch_events unless @paused
+      end
+
+      def pause
+        @paused = true
+      end
+
+      def resume
+        @paused = false
+        dispatch_events
+      end
+
+      def queue_size
+        @queue.size
+      end
+
+      def shutdown
+        super
+        @queue.clear
+      end
+
+      private
+
+      def dispatch_events
+        @semaphore.async do |task|
+          events = @queue.dup
+          @queue.clear
+          events.each do |event|
+            dispatch_event event, task
+          end
+        end
+      end
+
+      def dispatch_event event, task
+        @observers.collect do |observer|
+          task.async do
+            observer.call event
+          rescue => ex
+            puts ex
+            ex
+          end
+        end
+      end
+    end
+  end
+end

data/lib/plumbing/event_dispatcher.rb

@@ -0,0 +1,35 @@
+module Plumbing
+  class EventDispatcher
+    def initialize observers: []
+      @observers = observers
+    end
+
+    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
+      observer
+    end
+
+    def remove_observer observer
+      @observers.delete observer
+    end
+
+    def is_observer? observer
+      @observers.include? observer
+    end
+
+    def dispatch event
+      @observers.collect do |observer|
+        observer.call event
+      rescue => ex
+        puts ex
+        ex
+      end
+    end
+
+    def shutdown
+      @observers = []
+    end
+  end
+end

data/lib/plumbing/filter.rb

@@ -1,18 +1,13 @@
 module Plumbing
   # A pipe that filters events from a source pipe
   class Filter < Pipe
-    class InvalidFilter < Error; end
-
     # Chain this pipe to the source pipe
     # @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::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
+    # @param &accepts [Block] a block that returns a boolean value - true to accept the event, false to reject it
+    def initialize source:, dispatcher: nil, &accepts
+      super(dispatcher: dispatcher)
+      raise InvalidSource.new "#{source} must be a Plumbing::Pipe descendant" unless source.is_a? Plumbing::Pipe
+      @accepts = accepts
       source.add_observer do |event|
         filter_and_republish event
       end
@@ -21,8 +16,7 @@ module Plumbing
     private
 
     def filter_and_republish event
-      return nil if @accepted_event_types.any? && !@accepted_event_types.include?(event.type)
-      return nil if @rejected_event_types.include? event.type
+      return nil unless @accepts.call event
       dispatch event
     end
   end

data/lib/plumbing/junction.rb

@@ -0,0 +1,21 @@
+module Plumbing
+  # A pipe that filters events from a source pipe
+  class Junction < Pipe
+    # Chain multiple sources to this pipe
+    # @param [Array<Plumbing::Pipe>]
+    def initialize *sources, dispatcher: nil
+      super(dispatcher: dispatcher)
+      @sources = sources.collect { |source| add(source) }
+    end
+
+    private
+
+    def add source
+      raise InvalidSource.new "#{source} must be a Plumbing::Pipe descendant" unless source.is_a? Plumbing::Pipe
+      source.add_observer do |event|
+        dispatch event
+      end
+      source
+    end
+  end
+end

data/lib/plumbing/pipe.rb

@@ -1,9 +1,11 @@
 module Plumbing
   # A basic pipe
   class Pipe
+    require_relative "event_dispatcher"
+
     # Subclasses should call `super()` to ensure the pipe is initialised corrected
-    def initialize
-      @observers = []
+    def initialize dispatcher: nil
+      @dispatcher = dispatcher || EventDispatcher.new
     end
 
     # Push an event into the pipe
@@ -27,38 +29,36 @@ module Plumbing
     # @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
+    def add_observer(observer = nil, &)
+      @dispatcher.add_observer(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
+      @dispatcher.remove_observer observer
     end
 
     # Test whether the given observer is observing this pipe
     # @param observer
     # @return [boolean]
     def is_observer? observer
-      @observers.include? observer
+      @dispatcher.is_observer? 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 = []
+      @dispatcher.shutdown
     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)
+    def self.start(*, **, &)
+      new(*, **, &)
     end
 
     protected
@@ -68,12 +68,7 @@ module Plumbing
     # 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
+      @dispatcher.dispatch event
     end
   end
 end

data/lib/plumbing/{chain → pipeline}/contracts.rb

@@ -1,5 +1,5 @@
 module Plumbing
-  class Chain
+  class Pipeline
     module Contracts
       def pre_condition name, &validator
         pre_conditions[name.to_sym] = validator

data/lib/plumbing/{chain → pipeline}/operations.rb

@@ -1,14 +1,8 @@
 module Plumbing
-  class Chain
+  class Pipeline
     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
+      def perform method, using: nil, &implementation
+        using.nil? ? perform_internal(method, &implementation) : perform_external(method, using)
       end
 
       def execute method
@@ -35,6 +29,17 @@ module Plumbing
       def operations
         @operations ||= []
       end
+
+      def perform_internal method, &implementation
+        implementation ||= ->(input, instance) { instance.send(method, input) }
+        operations << implementation
+      end
+
+      def perform_external method, class_or_class_name
+        external_class = class_or_class_name.is_a?(String) ? const_get(class_or_class_name) : class_or_class_name
+        implementation = ->(input, instance) { external_class.new.call(input) }
+        operations << implementation
+      end
     end
   end
 end

data/lib/plumbing/pipeline.rb

@@ -0,0 +1,14 @@
+require_relative "pipeline/contracts"
+require_relative "pipeline/operations"
+
+module Plumbing
+  # A chain of operations that are executed in sequence
+  class Pipeline
+    extend Plumbing::Pipeline::Contracts
+    extend Plumbing::Pipeline::Operations
+
+    def call input
+      self.class._call input, self
+    end
+  end
+end

data/lib/plumbing/version.rb

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

data/lib/plumbing.rb

@@ -6,7 +6,8 @@ require_relative "plumbing/error"
 require_relative "plumbing/event"
 require_relative "plumbing/pipe"
 require_relative "plumbing/filter"
-require_relative "plumbing/chain"
+require_relative "plumbing/junction"
+require_relative "plumbing/pipeline"
 
 module Plumbing
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: standard-procedure-plumbing
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Rahoul Baruah
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-08-14 00:00:00.000000000 Z
+date: 2024-08-25 00:00:00.000000000 Z
 dependencies: []
 description: A composable event pipeline and sequential pipelines of operations
 email:
@@ -21,6 +21,7 @@ files:
 - ".rubocop.yml"
 - ".solargraph.yml"
 - ".standard.yml"
+- ".vscode/tasks.json"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - LICENSE
@@ -28,15 +29,19 @@ files:
 - Rakefile
 - checksums/standard-procedure-plumbing-0.1.1.gem.sha512
 - checksums/standard-procedure-plumbing-0.1.2.gem.sha512
+- checksums/standard-procedure-plumbing-0.2.0.gem.sha512
+- checksums/standard-procedure-plumbing-0.2.1.gem.sha512
 - lib/plumbing.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/event_dispatcher.rb
+- lib/plumbing/event_dispatcher/fiber.rb
 - lib/plumbing/filter.rb
+- lib/plumbing/junction.rb
 - lib/plumbing/pipe.rb
+- lib/plumbing/pipeline.rb
+- lib/plumbing/pipeline/contracts.rb
+- lib/plumbing/pipeline/operations.rb
 - lib/plumbing/version.rb
 - sig/plumbing.rbs
 homepage: https://github.com/standard-procedure/plumbing
@@ -61,7 +66,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.9
+rubygems_version: 3.5.17
 signing_key:
 specification_version: 4
 summary: Plumbing - various pipelines for your ruby application

data/lib/plumbing/chain.rb

@@ -1,14 +0,0 @@
-require_relative "chain/contracts"
-require_relative "chain/operations"
-
-module Plumbing
-  # A chain of operations that are executed in sequence
-  class Chain
-    extend Plumbing::Chain::Contracts
-    extend Plumbing::Chain::Operations
-
-    def call input
-      self.class._call input, self
-    end
-  end
-end

data/lib/plumbing/fiber/pipe.rb

@@ -1,36 +0,0 @@
-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