standard-procedure-plumbing 0.4.3 → 0.4.5

data/lib/plumbing/actor.rb

@@ -8,7 +8,7 @@ module Plumbing
       nil
     end
 
-    def within_actor? = proxy.within_actor?
+    def in_context? = proxy.in_context?
 
     def stop = proxy.stop
 

data/lib/plumbing/config.rb

@@ -1,6 +1,6 @@
 # Pipes, pipelines, actors and rubber ducks
 module Plumbing
-  Config = Data.define :mode, :actor_proxy_classes, :timeout do
+  Config = Data.define :mode, :actor_proxy_classes, :timeout, :debug do
     def actor_proxy_class_for target_class
       actor_proxy_classes[target_class]
     end
@@ -45,7 +45,7 @@ module Plumbing
   private_class_method :set_configuration_and_yield
 
   def self.configs
-    @configs ||= [Config.new(mode: :inline, timeout: 30, actor_proxy_classes: {})]
+    @configs ||= [Config.new(mode: :inline, timeout: 30, actor_proxy_classes: {}, debug: false)]
   end
   private_class_method :configs
 end

data/lib/plumbing/spec/become_matchers.rb

@@ -0,0 +1,121 @@
+require "rspec/expectations"
+
+# Custom matcher that repeatedly evaluates the block until it matches the expected value or the timeout has elapsed
+#
+# This allows asynchronous operations to be tested in a synchronous manner with a timeout
+#
+# Example:
+#     expect{ subject.greeting }.to become "Hello Alice"
+#
+RSpec::Matchers.define :become do |expected|
+  match do |block|
+    wait_for do
+      (@result = block.call) == expected
+    end
+    true
+  rescue Timeout::Error
+    false
+  end
+
+  def supports_block_expectations? = true
+
+  failure_message do |expected|
+    "expected #{expected} but, after timeout, the result was #{@result}"
+  end
+end
+
+# Custom matcher that repeatedly evaluates the block until it becomes true or the timeout has elapsed
+#
+# This allows asynchronous operations to be tested in a synchronous manner with a timeout
+#
+# Example:
+#     expect { @object.valid? }.to become_true
+#
+RSpec::Matchers.define :become_true do
+  match do |block|
+    wait_for do
+      block.call == true
+    end
+    true
+  rescue Timeout::Error
+    false
+  end
+
+  def supports_block_expectations? = true
+
+  failure_message do |expected|
+    "expected true but timeout expired"
+  end
+end
+
+# Custom matcher that repeatedly evaluates the block until it becomes truthy or the timeout has elapsed
+#
+# This allows asynchronous operations to be tested in a synchronous manner with a timeout
+#
+# Example:
+#     expect { @object.message }.to become_truthy
+#
+RSpec::Matchers.define :become_truthy do
+  match do |block|
+    wait_for do
+      block.call
+    end
+    true
+  rescue Timeout::Error
+    false
+  end
+
+  def supports_block_expectations? = true
+
+  failure_message do |expected|
+    "expected truthy value but timeout expired"
+  end
+end
+
+# Custom matcher that repeatedly evaluates the block until it becomes false or the timeout has elapsed
+#
+# This allows asynchronous operations to be tested in a synchronous manner with a timeout
+#
+# Example:
+#     expect { @object.in_progress? }.to become_false
+#
+RSpec::Matchers.define :become_false do
+  match do |block|
+    wait_for do
+      block.call == false
+    end
+    true
+  rescue Timeout::Error
+    false
+  end
+
+  def supports_block_expectations? = true
+
+  failure_message do |expected|
+    "expected false but timeout expired"
+  end
+end
+
+# Custom matcher that repeatedly evaluates the block until it becomes falsey or the timeout has elapsed
+#
+# This allows asynchronous operations to be tested in a synchronous manner with a timeout
+#
+# Example:
+#     expect { @object.background_task }.to become_falsey
+#
+RSpec::Matchers.define :become_falsey do
+  match do |block|
+    wait_for do
+      !block.call
+    end
+    true
+  rescue Timeout::Error
+    false
+  end
+
+  def supports_block_expectations? = true
+
+  failure_message do |expected|
+    "expected falsey but timeout expired"
+  end
+end

data/lib/plumbing/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: standard-procedure-plumbing
 version: !ruby/object:Gem::Version
-  version: 0.4.3
+  version: 0.4.5
 platform: ruby
 authors:
 - Rahoul Baruah
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-09-17 00:00:00.000000000 Z
+date: 2024-09-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: globalid
@@ -31,6 +31,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- LICENSE
 - README.md
 - Rakefile
 - lib/plumbing.rb
@@ -55,25 +56,9 @@ files:
 - lib/plumbing/rubber_duck/module.rb
 - lib/plumbing/rubber_duck/object.rb
 - lib/plumbing/rubber_duck/proxy.rb
+- lib/plumbing/spec/become_matchers.rb
 - lib/plumbing/types.rb
 - lib/plumbing/version.rb
-- spec/become_equal_to_matcher.rb
-- spec/examples/actor_spec.rb
-- spec/examples/await_spec.rb
-- spec/examples/pipe_spec.rb
-- spec/examples/pipeline_spec.rb
-- spec/examples/rubber_duck_spec.rb
-- spec/plumbing/a_pipe.rb
-- spec/plumbing/actor/transporter_spec.rb
-- spec/plumbing/actor_spec.rb
-- spec/plumbing/custom_filter_spec.rb
-- spec/plumbing/filter_spec.rb
-- spec/plumbing/junction_spec.rb
-- spec/plumbing/pipe_spec.rb
-- spec/plumbing/pipeline_spec.rb
-- spec/plumbing/rubber_duck_spec.rb
-- spec/plumbing_spec.rb
-- spec/spec_helper.rb
 homepage: https://github.com/standard-procedure/plumbing
 licenses: []
 metadata:
@@ -96,7 +81,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.12
+rubygems_version: 3.5.17
 signing_key:
 specification_version: 4
 summary: Plumbing - various pipelines for your ruby application

data/spec/become_equal_to_matcher.rb

@@ -1,26 +0,0 @@
-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|
-    max = Plumbing.config.timeout * 10
-    counter = 0
-    matched = false
-    while (counter < max) && (matched == false)
-      sleep 0.1
-      counter += 1
-      matched = true if (@result = block_arg.call) == expected
-    end
-    matched
-  end
-
-  failure_message do |expected|
-    "expected block to return #{expected} but was #{@result} after timeout expired"
-  end
-end

data/spec/examples/actor_spec.rb

@@ -1,86 +0,0 @@
-require "spec_helper"
-require "plumbing/actor/async"
-require "plumbing/actor/threaded"
-
-RSpec.shared_examples "an example actor" do |runs_in_background|
-  # standard:disable Lint/ConstantDefinitionInBlock
-  class Employee
-    include Plumbing::Actor
-    async :name, :job_title, :greet_slowly, :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
-
-  it "queries an object" do
-    @person = Employee.start "Alice"
-
-    expect(await { @person.name }).to eq "Alice"
-    expect(await { @person.job_title }).to eq "Sales assistant"
-
-    @time = Time.now
-    # `greet_slowly` is a query so will block until a response is received
-    expect(await { @person.greet_slowly }).to eq "H E L L O"
-    expect(Time.now - @time).to be > 0.1
-
-    @time = Time.now
-    # we're not awaiting the result, so this should run in the background (unless we're using inline mode)
-    @person.greet_slowly
-
-    expect(Time.now - @time).to be < 0.1 if runs_in_background
-    expect(Time.now - @time).to be > 0.1 if !runs_in_background
-  ensure
-    @person.stop
-  end
-
-  it "commands an object" do
-    @person = Employee.start "Alice"
-    @person.promote
-    expect(@person.job_title.value).to eq "Sales manager"
-  ensure
-    @person.stop
-  end
-end
-
-RSpec.describe "Actor example: " do
-  context "inline mode" do
-    around :example do |example|
-      Plumbing.configure mode: :inline, &example
-    end
-
-    it_behaves_like "an example actor", 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 actor", true
-  end
-
-  context "threaded mode" do
-    around :example do |example|
-      Plumbing.configure mode: :threaded, &example
-    end
-
-    it_behaves_like "an example actor", true
-  end
-end

data/spec/examples/await_spec.rb

@@ -1,43 +0,0 @@
-require "spec_helper"
-require "plumbing/actor/async"
-require "plumbing/actor/threaded"
-
-RSpec.describe "await" do
-  # standard:disable Lint/ConstantDefinitionInBlock
-  class Person
-    include Plumbing::Actor
-    async :name
-    def initialize name
-      @name = name
-    end
-    attr_reader :name
-  end
-  # standard:enable Lint/ConstantDefinitionInBlock
-
-  [:inline, :async, :threaded].each do |mode|
-    context "#{mode} mode" do
-      around :example do |example|
-        Sync do
-          Plumbing.configure mode: mode, &example
-        end
-      end
-
-      it "awaits a result from the actor directly" do
-        @person = Person.start "Alice"
-
-        expect(@person.name.value).to eq "Alice"
-      end
-
-      it "uses a block to await the result from the actor" do
-        @person = Person.start "Alice"
-
-        expect(await { @person.name }).to eq "Alice"
-      end
-
-      it "uses a block to immediately access non-actor objects" do
-        @person = "Bob"
-        expect(await { @person }).to eq "Bob"
-      end
-    end
-  end
-end

data/spec/examples/pipe_spec.rb

@@ -1,145 +0,0 @@
-require "spec_helper"
-require "async"
-require "plumbing/actor/async"
-require "plumbing/actor/threaded"
-
-RSpec.describe "Pipe examples" do
-  it "observes events" do
-    @source = Plumbing::Pipe.start
-
-    @result = []
-    @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 = []
-    @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
-        safely do
-          @events << event
-          if @events.count >= 3
-            @events.clear
-            self << event
-          end
-        end
-      end
-    end
-    # standard:enable Lint/ConstantDefinitionInBlock
-
-    @source = Plumbing::Pipe.start
-    @filter = EveryThirdEvent.start(source: @source)
-
-    @result = []
-    @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 = []
-    @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 async" 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
-
-  it "dispatches events asynchronously using threads" do
-    Plumbing.configure mode: :threaded do
-      @result = []
-
-      @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
-      await do
-        @filter.add_observer do |event|
-          puts "observing #{event.type}"
-          @result << event.type
-        end
-      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.sort }
-    ensure
-      @first_source.shutdown
-      @second_source.shutdown
-      @junction.shutdown
-      @filter.shutdown
-    end
-  end
-end

data/spec/examples/pipeline_spec.rb

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