standard-procedure-plumbing 0.3.1 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9a111ce599942b5e33b6928cede476b75e56fd6574625bf50ca82d6d75f3e718
-  data.tar.gz: b1b4c48062aec9d77ec3b917c25723fae8ff2cc4075d9f91c699da3f165b7c84
+  metadata.gz: 54681502a7df050136406e706c4fd6b9d9bffea81e44c151e969379e6803c532
+  data.tar.gz: ed03cbc9476d43822792fd6a4788b0c2e6c629545056063342f15c0861dc7dd0
 SHA512:
-  metadata.gz: 6d2de706d57ef380e67fcd9d79b3d202ca0741f7ed24552ad62bc63944f1c0a82cdd6123560a6d79a85099218db5c9c966ee602a0ef281ea7d5b0305e1f5a707
-  data.tar.gz: 47de86307b817c0d0399bc06bcac5f78eea3629b93725b785f1dc6a442a300a03ceadde6627f2d198ea296524f584f29a90fa3ec52e5e635507c024241fec5da
+  metadata.gz: 1387fdd83a547157541f444ccf2dcb9465c261616f424dc530ef4c9c13dda52214c21c4d50c99eb825e4827268f4892d62a29d212af9be21bc5bd65dd83422a4
+  data.tar.gz: c0dcbde3271e4d34cd41d16bda9c488ee40bd838ac0f006fd46bd23eb2c0c1cc4ea18d86236de1d8e87f6b5b97fc5dc728bedbd5a3e354fa09886094866404c9

data/lib/plumbing/version.rb

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

data/spec/become_equal_to_matcher.rb

@@ -0,0 +1,25 @@
+require "rspec/expectations"
+
+# Custom matcher that repeatedly evaluates the block until it matches the expected value or 5 seconds have elapsed
+#
+# This allows asynchronous operations to be tested in a synchronous manner with a timeout
+#
+# Example:
+#     expect("Hello").to become_equal_to { subject.greeting }
+#
+RSpec::Matchers.define :become_equal_to do
+  match do |expected|
+    counter = 0
+    matched = false
+    while (counter < 50) && (matched == false)
+      matched = true if (@result = block_arg.call) == expected
+      sleep 0.1
+      counter += 1
+    end
+    matched
+  end
+
+  failure_message do |expected|
+    "expected block to return #{expected} but was #{@result} after timeout expired"
+  end
+end

data/spec/examples/pipe_spec.rb

@@ -0,0 +1,109 @@
+require "spec_helper"
+require "async"
+
+RSpec.describe "Pipe examples" do
+  it "observes events" do
+    @source = Plumbing::Pipe.start
+
+    @result = []
+    @observer = @source.add_observer do |event|
+      @result << event.type
+    end
+
+    @source.notify "something_happened", message: "But what was it?"
+    expect(@result).to eq ["something_happened"]
+  end
+
+  it "filters events" do
+    @source = Plumbing::Pipe.start
+
+    @filter = Plumbing::Filter.start source: @source do |event|
+      %w[important urgent].include? event.type
+    end
+
+    @result = []
+    @observer = @filter.add_observer do |event|
+      @result << event.type
+    end
+
+    @source.notify "important", message: "ALERT! ALERT!"
+    expect(@result).to eq ["important"]
+
+    @source.notify "unimportant", message: "Nothing to see here"
+    expect(@result).to eq ["important"]
+  end
+
+  it "allows for custom filters" do
+    # standard:disable Lint/ConstantDefinitionInBlock
+    class EveryThirdEvent < Plumbing::CustomFilter
+      def initialize source:
+        super
+        @events = []
+      end
+
+      def received event
+        @events << event
+        if @events.count >= 3
+          @events.clear
+          self << event
+        end
+      end
+    end
+    # standard:enable Lint/ConstantDefinitionInBlock
+
+    @source = Plumbing::Pipe.start
+    @filter = EveryThirdEvent.new(source: @source)
+
+    @result = []
+    @observer = @filter.add_observer do |event|
+      @result << event.type
+    end
+
+    1.upto 10 do |i|
+      @source.notify i.to_s
+    end
+
+    expect(@result).to eq ["3", "6", "9"]
+  end
+
+  it "joins multiple source pipes" do
+    @first_source = Plumbing::Pipe.start
+    @second_source = Plumbing::Pipe.start
+
+    @junction = Plumbing::Junction.start @first_source, @second_source
+
+    @result = []
+    @observer = @junction.add_observer do |event|
+      @result << event.type
+    end
+
+    @first_source.notify "one"
+    expect(@result).to eq ["one"]
+    @second_source.notify "two"
+    expect(@result).to eq ["one", "two"]
+  end
+
+  it "dispatches events asynchronously using fibers" do
+    Plumbing.configure mode: :async do
+      Sync do
+        @first_source = Plumbing::Pipe.start
+        @second_source = Plumbing::Pipe.start
+        @junction = Plumbing::Junction.start @first_source, @second_source
+        @filter = Plumbing::Filter.start source: @junction do |event|
+          %w[one-one two-two].include? event.type
+        end
+        @result = []
+        @filter.add_observer do |event|
+          @result << event.type
+        end
+
+        @first_source.notify "one-one"
+        @first_source.notify "one-two"
+        @second_source.notify "two-one"
+        @second_source.notify "two-two"
+
+        expect(["one-one", "two-two"]).to become_equal_to { @result }
+      end
+    end
+  end
+end

data/spec/examples/pipeline_spec.rb

@@ -0,0 +1,89 @@
+require "spec_helper"
+require "dry/validation"
+
+RSpec.describe "Pipeline examples" do
+  it "builds a simple pipeline of operations adding to an array with pre-conditions and post-conditions" do
+    # standard:disable Lint/ConstantDefinitionInBlock
+    class BuildArray < Plumbing::Pipeline
+      perform :add_first
+      perform :add_second
+      perform :add_third
+
+      pre_condition :must_be_an_array do |input|
+        input.is_a? Array
+      end
+
+      post_condition :must_have_three_elements do |output|
+        output.length == 3
+      end
+
+      private
+
+      def add_first(input) = input << "first"
+
+      def add_second(input) = input << "second"
+
+      def add_third(input) = input << "third"
+    end
+    # standard:enable Lint/ConstantDefinitionInBlock
+
+    expect(BuildArray.new.call([])).to eq ["first", "second", "third"]
+    expect { BuildArray.new.call(1) }.to raise_error(Plumbing::PreConditionError)
+    expect { BuildArray.new.call(["extra element"]) }.to raise_error(Plumbing::PostConditionError)
+  end
+
+  it "builds a simple pipeline of operations using an external class to implement one of the steps" do
+    # standard:disable Lint/ConstantDefinitionInBlock
+    class ExternalStep < Plumbing::Pipeline
+      perform :add_item_to_array
+
+      private
+
+      def add_item_to_array(input) = input << "external"
+    end
+
+    class BuildSequenceWithExternalStep < Plumbing::Pipeline
+      perform :add_first
+      perform :add_second, using: "ExternalStep"
+      perform :add_third
+
+      private
+
+      def add_first(input) = input << "first"
+
+      def add_third(input) = input << "third"
+    end
+    # standard:enable Lint/ConstantDefinitionInBlock
+
+    expect(BuildSequenceWithExternalStep.new.call([])).to eq ["first", "external", "third"]
+  end
+
+  it "uses a dry-validation contract to test the input parameters" do
+    # standard:disable Lint/ConstantDefinitionInBlock
+    class SayHello < Plumbing::Pipeline
+      validate_with "SayHello::Input"
+      perform :say_hello
+
+      private
+
+      def say_hello input
+        "Hello #{input[:name]} - I will now send a load of annoying marketing messages to #{input[:email]}"
+      end
+
+      class Input < Dry::Validation::Contract
+        params do
+          required(:name).filled(:string)
+          required(:email).filled(:string)
+        end
+        rule :email do
+          key.failure("must be a valid email") unless /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i.match? value
+        end
+      end
+    end
+    # standard:enable Lint/ConstantDefinitionInBlock
+
+    SayHello.new.call(name: "Alice", email: "alice@example.com")
+
+    expect { SayHello.new.call(some: "other data") }.to raise_error(Plumbing::PreConditionError)
+  end
+end

data/spec/examples/rubber_duck_spec.rb

@@ -0,0 +1,26 @@
+require "spec_helper"
+
+RSpec.describe "Rubber Duck examples" do
+  it "casts objects as duck types" do
+    # standard:disable Lint/ConstantDefinitionInBlock
+    Person = Plumbing::RubberDuck.define :first_name, :last_name, :email
+    LikesFood = Plumbing::RubberDuck.define :favourite_food
+
+    PersonData = Struct.new(:first_name, :last_name, :email, :favourite_food)
+    CarData = Struct.new(:make, :model, :colour)
+    # standard:enable Lint/ConstantDefinitionInBlock
+
+    @porsche_911 = CarData.new "Porsche", "911", "black"
+    expect { @porsche_911.as Person }.to raise_error(TypeError)
+
+    @alice = PersonData.new "Alice", "Aardvark", "alice@example.com", "Ice cream"
+
+    @person = @alice.as Person
+    expect(@person.first_name).to eq "Alice"
+    expect(@person.email).to eq "alice@example.com"
+    expect { @person.favourite_food }.to raise_error(NoMethodError)
+
+    @hungry = @person.as LikesFood
+    expect(@hungry.favourite_food).to eq "Ice cream"
+  end
+end

data/spec/examples/valve_spec.rb

@@ -0,0 +1,88 @@
+require "spec_helper"
+
+RSpec.describe "Valve examples" do
+  # standard:disable Lint/ConstantDefinitionInBlock
+  class Employee
+    include Plumbing::Valve
+    query :name, :job_title, :greet_slowly
+    command :promote
+
+    def initialize(name)
+      @name = name
+      @job_title = "Sales assistant"
+    end
+
+    attr_reader :name, :job_title
+
+    def promote
+      sleep 0.5
+      @job_title = "Sales manager"
+    end
+
+    def greet_slowly
+      sleep 0.2
+      "H E L L O"
+    end
+  end
+  # standard:enable Lint/ConstantDefinitionInBlock
+
+  context "inline" do
+    it "queries an object" do
+      Plumbing.configure mode: :inline do
+        @person = Employee.start "Alice"
+
+        expect(@person.name).to eq "Alice"
+        expect(@person.job_title).to eq "Sales assistant"
+
+        @time = Time.now
+        expect(@person.greet_slowly).to eq "H E L L O"
+        expect(Time.now - @time).to be > 0.1
+
+        @time = Time.now
+        expect(@person.greet_slowly(ignore_result: true)).to be_nil
+        expect(Time.now - @time).to be > 0.1
+      end
+    end
+
+    it "commands an object" do
+      Plumbing.configure mode: :inline do
+        @person = Employee.start "Alice"
+
+        @person.promote
+
+        expect(@person.job_title).to eq "Sales manager"
+      end
+    end
+  end
+
+  context "async" do
+    around :example do |example|
+      Plumbing.configure mode: :async do
+        Kernel::Async(&example)
+      end
+    end
+
+    it "queries an object" do
+      @person = Employee.start "Alice"
+
+      expect(@person.name).to eq "Alice"
+      expect(@person.job_title).to eq "Sales assistant"
+
+      @time = Time.now
+      expect(@person.greet_slowly).to eq "H E L L O"
+      expect(Time.now - @time).to be > 0.1
+
+      @time = Time.now
+      expect(@person.greet_slowly(ignore_result: true)).to be_nil
+      expect(Time.now - @time).to be < 0.1
+    end
+
+    it "commands an object" do
+      @person = Employee.start "Alice"
+
+      @person.promote
+
+      expect(@person.job_title).to eq "Sales manager"
+    end
+  end
+end

data/spec/plumbing/a_pipe.rb

@@ -0,0 +1,106 @@
+RSpec.shared_examples "a pipe" do
+  it "adds a block observer" do
+    @pipe = described_class.start
+    @observer = @pipe.add_observer do |event|
+      puts event.type
+    end
+    expect(@pipe.is_observer?(@observer)).to eq true
+  end
+
+  it "adds a callable observer" do
+    @pipe = described_class.start
+    @proc = ->(event) { puts event.type }
+
+    @pipe.add_observer @proc
+
+    expect(@pipe.is_observer?(@proc)).to eq true
+  end
+
+  it "does not allow an observer without a #call method" do
+    @pipe = described_class.start
+
+    expect { @pipe.add_observer(Object.new) }.to raise_error(TypeError)
+  end
+
+  it "removes an observer" do
+    @pipe = described_class.start
+    @proc = ->(event) { puts event.type }
+
+    @pipe.remove_observer @proc
+
+    expect(@pipe.is_observer?(@proc)).to eq false
+  end
+
+  it "does not send notifications for objects  which are not events" do
+    @pipe = described_class.start
+    @results = []
+    @observer = @pipe.add_observer do |event|
+      @results << event
+    end
+
+    @pipe << Object.new
+
+    sleep 0.5
+    expect(@results).to eq []
+  end
+
+  it "notifies block observers" do
+    @pipe = described_class.start
+    @results = []
+    @observer = @pipe.add_observer do |event|
+      @results << event
+    end
+
+    @first_event = Plumbing::Event.new type: "first_event", data: {test: "event"}
+    @second_event = Plumbing::Event.new type: "second_event", data: {test: "event"}
+
+    @pipe << @first_event
+    expect([@first_event]).to become_equal_to { @results }
+
+    @pipe << @second_event
+    expect([@first_event, @second_event]).to become_equal_to { @results }
+  end
+
+  it "notifies callable observers" do
+    @pipe = described_class.start
+    @results = []
+    @observer = ->(event) { @results << event }
+    @pipe.add_observer @observer
+
+    @first_event = Plumbing::Event.new type: "first_event", data: {test: "event"}
+    @second_event = Plumbing::Event.new type: "second_event", data: {test: "event"}
+
+    @pipe << @first_event
+    expect([@first_event]).to become_equal_to { @results }
+
+    @pipe << @second_event
+    expect([@first_event, @second_event]).to become_equal_to { @results }
+  end
+
+  it "ensures all observers are notified even if an observer raises an exception" do
+    @pipe = described_class.start
+    @results = []
+    @failing_observer = @pipe.add_observer do |event|
+      raise "Failed processing #{event.type}"
+    end
+    @working_observer = @pipe.add_observer do |event|
+      @results << event
+    end
+
+    @event = Plumbing::Event.new type: "event", data: {test: "event"}
+
+    @pipe << @event
+
+    expect([@event]).to become_equal_to { @results }
+  end
+
+  it "shuts down the pipe" do
+    @pipe = described_class.start
+    @observer = ->(event) { @results << event }
+    @pipe.add_observer @observer
+
+    @pipe.shutdown
+
+    expect(@pipe.is_observer?(@observer)).to eq false
+  end
+end

data/spec/plumbing/custom_filter_spec.rb

@@ -0,0 +1,29 @@
+require "spec_helper"
+
+RSpec.describe Plumbing::CustomFilter do
+  it "raises a TypeError if it is connected to a non-Pipe" do
+    @invalid_source = Object.new
+
+    expect { described_class.start source: @invalid_source }.to raise_error(TypeError)
+  end
+
+  it "defines a custom filter" do
+    # standard:disable Lint/ConstantDefinitionInBlock
+    class ReversingFilter < Plumbing::CustomFilter
+      def received(event) = notify event.type.reverse, event.data
+    end
+    # standard:enable Lint/ConstantDefinitionInBlock
+
+    @pipe = Plumbing::Pipe.start
+    @filter = ReversingFilter.new(source: @pipe)
+    @result = []
+    @filter.add_observer do |event|
+      @result << event.type
+    end
+
+    @pipe.notify "hello"
+    @pipe.notify "world"
+
+    expect(@result).to eq ["olleh", "dlrow"]
+  end
+end

data/spec/plumbing/filter_spec.rb

@@ -0,0 +1,32 @@
+require "spec_helper"
+
+RSpec.describe Plumbing::Filter do
+  it "raises a TypeError if it is connected to a non-Pipe" do
+    @invalid_source = Object.new
+
+    expect { described_class.start source: @invalid_source }.to raise_error(TypeError)
+  end
+
+  it "accepts event types" do
+    @pipe = Plumbing::Pipe.start
+
+    @filter = described_class.start source: @pipe do |event|
+      %w[first_type third_type].include? event.type.to_s
+    end
+
+    @results = []
+    @filter.add_observer do |event|
+      @results << event
+    end
+
+    @pipe << Plumbing::Event.new(type: "first_type", data: nil)
+    expect(@results.count).to eq 1
+
+    @pipe << Plumbing::Event.new(type: "second_type", data: nil)
+    expect(@results.count).to eq 1
+
+    # Use the alternative syntax
+    @pipe.notify "third_type"
+    expect(@results.count).to eq 2
+  end
+end

data/spec/plumbing/junction_spec.rb

@@ -0,0 +1,67 @@
+require "spec_helper"
+
+RSpec.describe Plumbing::Junction do
+  it "raises a TypeError if it is connected to a non-Pipe" do
+    @sources = [Plumbing::Pipe.start, Object.new, Plumbing::Pipe.start]
+
+    expect { described_class.start(*@sources) }.to raise_error(TypeError)
+  end
+
+  it "publishes events from a single source" do
+    @source = Plumbing::Pipe.start
+    @junction = described_class.start @source
+
+    @results = []
+    @junction.add_observer do |event|
+      @results << event
+    end
+
+    @event = Plumbing::Event.new type: "test_event", data: {test: "event"}
+    @source << @event
+
+    expect([@event]).to become_equal_to { @results }
+  end
+
+  it "publishes events from two sources" do
+    @first_source = Plumbing::Pipe.start
+    @second_source = Plumbing::Pipe.start
+    @junction = described_class.start @first_source, @second_source
+
+    @results = []
+    @junction.add_observer do |event|
+      @results << event
+    end
+
+    @first_event = Plumbing::Event.new type: "test_event", data: {test: "one"}
+    @first_source << @first_event
+    expect([@first_event]).to become_equal_to { @results }
+
+    @second_event = Plumbing::Event.new type: "test_event", data: {test: "two"}
+    @second_source << @second_event
+    expect([@first_event, @second_event]).to become_equal_to { @results }
+  end
+
+  it "publishes events from multiple sources" do
+    @first_source = Plumbing::Pipe.start
+    @second_source = Plumbing::Pipe.start
+    @third_source = Plumbing::Pipe.start
+    @junction = described_class.start @first_source, @second_source, @third_source
+
+    @results = []
+    @junction.add_observer do |event|
+      @results << event
+    end
+
+    @first_event = Plumbing::Event.new type: "test_event", data: {test: "one"}
+    @first_source << @first_event
+    expect([@first_event]).to become_equal_to { @results }
+
+    @second_event = Plumbing::Event.new type: "test_event", data: {test: "two"}
+    @second_source << @second_event
+    expect([@first_event, @second_event]).to become_equal_to { @results }
+
+    @third_event = Plumbing::Event.new type: "test_event", data: {test: "three"}
+    @third_source << @third_event
+    expect([@first_event, @second_event, @third_event]).to become_equal_to { @results }
+  end
+end

data/spec/plumbing/pipe_spec.rb

@@ -0,0 +1,23 @@
+require "spec_helper"
+require_relative "a_pipe"
+require "async"
+
+RSpec.describe Plumbing::Pipe do
+  context "inline" do
+    around :example do |example|
+      Plumbing.configure mode: :inline, &example
+    end
+
+    it_behaves_like "a pipe"
+  end
+
+  context "async" do
+    around :example do |example|
+      Sync do
+        Plumbing.configure mode: :async, &example
+      end
+    end
+
+    it_behaves_like "a pipe"
+  end
+end