standard-procedure-plumbing 0.3.1 → 0.3.3

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,109 @@
+require "spec_helper"
+
+RSpec.describe "Rubber Duck examples" do
+  it "casts objects into duck types" do
+    # standard:disable Lint/ConstantDefinitionInBlock
+    module DuckExample
+      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)
+    end
+
+    # standard:enable Lint/ConstantDefinitionInBlock
+
+    @porsche_911 = DuckExample::CarData.new "Porsche", "911", "black"
+    expect { @porsche_911.as DuckExample::Person }.to raise_error(TypeError)
+
+    @alice = DuckExample::PersonData.new "Alice", "Aardvark", "alice@example.com", "Ice cream"
+
+    @person = @alice.as DuckExample::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 DuckExample::LikesFood
+    expect(@hungry.favourite_food).to eq "Ice cream"
+  end
+
+  it "casts objects into modules" do
+    # standard:disable Lint/ConstantDefinitionInBlock
+    module ModuleExample
+      module Person
+        def first_name = @first_name
+
+        def last_name = @last_name
+
+        def email = @email
+      end
+
+      module LikesFood
+        def favourite_food = @favourite_food
+      end
+
+      PersonData = Struct.new(:first_name, :last_name, :email, :favourite_food)
+      CarData = Struct.new(:make, :model, :colour)
+    end
+    # standard:enable Lint/ConstantDefinitionInBlock
+    @porsche_911 = ModuleExample::CarData.new "Porsche", "911", "black"
+    expect { @porsche_911.as ModuleExample::Person }.to raise_error(TypeError)
+
+    @alice = ModuleExample::PersonData.new "Alice", "Aardvark", "alice@example.com", "Ice cream"
+
+    @person = @alice.as ModuleExample::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 ModuleExample::LikesFood
+    expect(@hungry.favourite_food).to eq "Ice cream"
+  end
+
+  it "casts objects into clases" do
+    # standard:disable Lint/ConstantDefinitionInBlock
+    module ClassExample
+      class Person
+        def initialize first_name, last_name, email
+          @first_name = first_name
+          @last_name = last_name
+          @email = email
+        end
+
+        attr_reader :first_name
+        attr_reader :last_name
+        attr_reader :email
+      end
+
+      class PersonWhoLikesFood < Person
+        def initialize first_name, last_name, email, favourite_food
+          super(first_name, last_name, email)
+          @favourite_food = favourite_food
+        end
+
+        attr_reader :favourite_food
+      end
+
+      class CarData
+        def initialize make, model, colour
+          @make = make
+          @model = model
+          @colour = colour
+        end
+      end
+    end
+    # standard:enable Lint/ConstantDefinitionInBlock
+    @porsche_911 = ClassExample::CarData.new "Porsche", "911", "black"
+    expect { @porsche_911.as ClassExample::Person }.to raise_error(TypeError)
+
+    @alice = ClassExample::PersonWhoLikesFood.new "Alice", "Aardvark", "alice@example.com", "Ice cream"
+
+    @person = @alice.as ClassExample::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 ClassExample::PersonWhoLikesFood
+    expect(@hungry.favourite_food).to eq "Ice cream"
+  end
+end

data/spec/examples/valve_spec.rb

@@ -0,0 +1,81 @@
+require "spec_helper"
+
+RSpec.shared_examples "an example valve" do |runs_in_background|
+  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
+    # `greet_slowly` is a query so will block until a response is received
+    expect(@person.greet_slowly).to eq "H E L L O"
+    expect(Time.now - @time).to be > 0.1
+
+    @time = Time.now
+    # we're ignoring the result so this will not block (except :inline mode which does not run in the background)
+    expect(@person.greet_slowly(ignore_result: true)).to be_nil
+    expect(Time.now - @time).to be < 0.1 if runs_in_background
+    expect(Time.now - @time).to be > 0.1 if !runs_in_background
+  end
+
+  it "commands an object" do
+    @person = Employee.start "Alice"
+    @person.promote
+    @job_title = @person.job_title
+    expect(@job_title).to eq "Sales manager"
+  end
+end
+
+RSpec.describe "Valve example: " 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 mode" do
+    around :example do |example|
+      Plumbing.configure mode: :inline, &example
+    end
+
+    it_behaves_like "an example valve", false
+  end
+
+  context "async mode" do
+    around :example do |example|
+      Plumbing.configure mode: :async do
+        Kernel::Async(&example)
+      end
+    end
+
+    it_behaves_like "an example valve", true
+  end
+
+  context "threaded mode" do
+    around :example do |example|
+      Plumbing.configure mode: :threaded, &example
+    end
+
+    it_behaves_like "an example valve", true
+  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,31 @@
+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
+
+  context "threaded" do
+    around :example do |example|
+      Plumbing.configure mode: :threaded, &example
+    end
+
+    it_behaves_like "a pipe"
+  end
+end