standard-procedure-plumbing 0.3.0 → 0.3.2

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

data/spec/plumbing/pipeline_spec.rb

@@ -0,0 +1,208 @@
+require "spec_helper"
+require "dry/validation"
+
+RSpec.describe Plumbing::Pipeline do
+  it "defines a single operation that returns a value based upon the input parameters" do
+    # standard:disable Lint/ConstantDefinitionInBlock
+    class Addition < Plumbing::Pipeline
+      perform :addition
+
+      private
+
+      def addition number
+        number + 1
+      end
+    end
+    # standard:enable Lint/ConstantDefinitionInBlock
+
+    expect(Addition.new.call(5)).to eq 6
+  end
+
+  it "defines a sequence of commands that are executed in order" do
+    # standard:disable Lint/ConstantDefinitionInBlock
+    class Sequence < Plumbing::Pipeline
+      perform :first_step
+      perform :second_step
+      perform :third_step
+
+      private
+
+      def first_step value = []
+        value << "first"
+      end
+
+      def second_step value = []
+        value << "second"
+      end
+
+      def third_step value = []
+        value << "third"
+      end
+    end
+    # standard:enable Lint/ConstantDefinitionInBlock
+
+    expect(Sequence.new.call([])).to eq ["first", "second", "third"]
+  end
+
+  context "embedding an external command" do
+    it "specifies the command with a string" do
+      # standard:disable Lint/ConstantDefinitionInBlock
+      class InnerByName < Plumbing::Pipeline
+        perform :embedded_step
+
+        private
+
+        def embedded_step value = []
+          value << "embedded"
+        end
+      end
+
+      class OuterByName < Plumbing::Pipeline
+        perform :first_step
+        perform :second_step, using: "InnerByName"
+        perform :third_step
+
+        private
+
+        def first_step value = []
+          value << "first"
+        end
+
+        def third_step value = []
+          value << "third"
+        end
+      end
+      # standard:enable Lint/ConstantDefinitionInBlock
+
+      expect(OuterByName.new.call([])).to eq ["first", "embedded", "third"]
+    end
+
+    it "specifies the command with a class" do
+      # standard:disable Lint/ConstantDefinitionInBlock
+      class InnerByClass < Plumbing::Pipeline
+        perform :embedded_step
+
+        private
+
+        def embedded_step value = []
+          value << "embedded"
+        end
+      end
+
+      class OuterByClass < Plumbing::Pipeline
+        perform :first_step
+        perform :second_step, using: InnerByClass
+        perform :third_step
+
+        private
+
+        def first_step value = []
+          value << "first"
+        end
+
+        def third_step value = []
+          value << "third"
+        end
+      end
+      # standard:enable Lint/ConstantDefinitionInBlock
+
+      expect(OuterByClass.new.call([])).to eq ["first", "embedded", "third"]
+    end
+  end
+
+  it "defines an operation that does something but returns the provided input untouched" do
+    # standard:disable Lint/ConstantDefinitionInBlock
+    class Passthrough < Plumbing::Pipeline
+      execute :external_operation
+
+      private
+
+      def external_operation input
+        # SomeApi.do_some_stuff input
+        nil
+      end
+    end
+    # standard:enable Lint/ConstantDefinitionInBlock
+
+    expect(Passthrough.new.call("some parameters")).to eq "some parameters"
+  end
+
+  it "raises a PreConditionError if the input fails the precondition test" do
+    # standard:disable Lint/ConstantDefinitionInBlock
+    class PreConditionCheck < Plumbing::Pipeline
+      pre_condition :has_first_key do |input|
+        input.key?(:first)
+      end
+
+      pre_condition :has_second_key do |input|
+        input.key?(:second)
+      end
+
+      perform :do_something
+
+      private
+
+      def do_something input
+        "#{input[:first]} #{input[:second]}"
+      end
+    end
+    # standard:enable Lint/ConstantDefinitionInBlock
+
+    expect(PreConditionCheck.new.call(first: "First", second: "Second")).to eq "First Second"
+    expect { PreConditionCheck.new.call(first: "First") }.to raise_error(Plumbing::PreConditionError, "has_second_key")
+  end
+
+  it "raises a PreConditionError if the input fails to validate against a Dry::Validation::Contract" do
+    # standard:disable Lint/ConstantDefinitionInBlock
+    class Validated < Plumbing::Pipeline
+      validate_with "Validated::Input"
+      perform :say_hello
+
+      private
+
+      def say_hello input
+        "Hello #{input[:name]} (#{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
+
+    expect(Validated.new.call(name: "Alice", email: "alice@example.com")).to eq "Hello Alice (alice@example.com)"
+    expect { Validated.new.call(email: "alice@example.com") }.to raise_error(Plumbing::PreConditionError, {name: ["is missing"]}.to_yaml)
+    expect { Validated.new.call(name: "Bob", email: "bob-has-fat-fingers-and-cant-type") }.to raise_error(Plumbing::PreConditionError, {email: ["must be a valid email"]}.to_yaml)
+  end
+
+  it "raises a PostConditionError if the outputs fail the postcondition test" do
+    # standard:disable Lint/ConstantDefinitionInBlock
+    class PostConditionCheck < Plumbing::Pipeline
+      post_condition :should_be_integer do |result|
+        result.instance_of? Integer
+      end
+
+      post_condition :should_be_greater_than_zero do |result|
+        result > 0
+      end
+
+      perform :do_something
+
+      private
+
+      def do_something value
+        value.to_i
+      end
+    end
+    # standard:enable Lint/ConstantDefinitionInBlock
+
+    expect(PostConditionCheck.new.call("23")).to eq 23
+    expect { PostConditionCheck.new.call("NOT A NUMBER") }.to raise_error(Plumbing::PostConditionError, "should_be_greater_than_zero")
+  end
+end

data/spec/plumbing/rubber_duck_spec.rb

@@ -0,0 +1,76 @@
+require "spec_helper"
+
+RSpec.describe Plumbing::RubberDuck do
+  # standard:disable Lint/ConstantDefinitionInBlock
+  class Duck
+    def quack = "Quack"
+
+    def swim place
+      "Swim in #{place}"
+    end
+
+    def fly &block
+      "Fly #{block.call}"
+    end
+  end
+  # standard:enable Lint/ConstantDefinitionInBlock
+
+  it "verifies that an object matches the RubberDuck type" do
+    @duck_type = described_class.define :quack, :swim, :fly
+    @duck = Duck.new
+
+    expect(@duck_type.verify(@duck)).to eq @duck
+  end
+
+  it "casts the object to a duck type" do
+    @duck_type = described_class.define :quack, :swim, :fly
+    @duck = Duck.new
+
+    @proxy = @duck.as @duck_type
+
+    expect(@proxy).to be_kind_of Plumbing::RubberDuck::Proxy
+    expect(@proxy).to respond_to :quack
+    expect(@proxy.quack).to eq "Quack"
+    expect(@proxy).to respond_to :swim
+    expect(@proxy.swim("the river")).to eq "Swim in the river"
+    expect(@proxy).to respond_to :fly
+    expect(@proxy.fly { "ducky fly" }).to eq "Fly ducky fly"
+  end
+
+  it "does not forward methods that are not part of the duck type" do
+    @duck_type = described_class.define :swim, :fly
+    @duck = Duck.new
+
+    @proxy = @duck.as @duck_type
+
+    expect(@proxy).to_not respond_to :quack
+  end
+
+  it "does not wrap rubber ducks in a proxy" do
+    @duck_type = described_class.define :swim, :fly
+    @duck = Duck.new
+
+    @proxy = @duck.as @duck_type
+
+    expect(@proxy.as(@duck_type)).to eq @proxy
+  end
+
+  it "allows rubber ducks to be expanded and cast to other types" do
+    @quackers = described_class.define :quack
+    @swimming_bird = described_class.define :swim, :fly
+    @duck = Duck.new
+
+    @swimmer = @duck.as @swimming_bird
+    @quacker = @swimmer.as @quackers
+
+    expect(@swimmer).to respond_to :swim
+    expect(@quacker).to respond_to :quack
+  end
+
+  it "raises a TypeError if the class responds to the given methods" do
+    cow_type = described_class.define :moo, :chew
+    duck = Duck.new
+
+    expect { cow_type.verify(duck) }.to raise_error(TypeError)
+  end
+end

data/spec/plumbing/valve_spec.rb

@@ -0,0 +1,167 @@
+require "spec_helper"
+require "async"
+require_relative "../../lib/plumbing/valve/async"
+
+RSpec.describe Plumbing::Valve do
+  # standard:disable Lint/ConstantDefinitionInBlock
+  class Counter
+    include Plumbing::Valve
+    query :name, :count, :am_i_failing?, :slow_query
+    command "slowly_increment", "raises_error"
+    attr_reader :name, :count
+
+    def initialize name, initial_value: 0
+      @name = name
+      @count = initial_value
+    end
+
+    def slowly_increment
+      sleep 0.5
+      @count += 1
+    end
+
+    def slow_query
+      sleep 0.5
+      @count
+    end
+
+    def am_i_failing? = raise "I'm a failure"
+
+    def raises_error = raise "I'm an error"
+  end
+
+  class StepCounter < Counter
+    query :step_value
+    attr_reader :step_value
+
+    def initialize name, initial_value: 0, step_value: 5
+      super(name, initial_value: initial_value)
+      @step_value = step_value
+    end
+
+    def slowly_increment
+      sleep 0.5
+      @count += @step_value
+    end
+
+    def failing_query
+      raise "I'm a failure"
+    end
+  end
+  # standard:enable Lint/ConstantDefinitionInBlock
+
+  it "knows which queries are defined" do
+    expect(Counter.queries).to eq [:name, :count, :am_i_failing?, :slow_query]
+  end
+
+  it "knows which commands are defined" do
+    expect(Counter.commands).to eq [:slowly_increment, :raises_error]
+  end
+
+  it "raises exceptions from queries" do
+    @counter = Counter.start "failure"
+
+    expect { @counter.am_i_failing? }.to raise_error "I'm a failure"
+  end
+
+  it "does not raise exceptions from commands" do
+    @counter = Counter.start "failure"
+
+    expect { @counter.raises_error }.not_to raise_error
+  end
+
+  it "raises exceptions from queries" do
+    @counter = Counter.start "failure"
+
+    expect { @counter.am_i_failing? }.to raise_error "I'm a failure"
+  end
+
+  it "reuses existing proxy classes" do
+    @counter = Counter.start "inline counter", initial_value: 100
+    @proxy_class = @counter.class
+
+    @counter = Counter.start "another inline counter", initial_value: 200
+    expect(@counter.class).to eq @proxy_class
+  end
+
+  it "includes commands and queries from the superclass" do
+    expect(StepCounter.queries).to eq [:name, :count, :am_i_failing?, :slow_query, :step_value]
+    expect(StepCounter.commands).to eq [:slowly_increment, :raises_error]
+
+    @step_counter = StepCounter.start "step counter", initial_value: 100, step_value: 10
+
+    expect(@step_counter.count).to eq 100
+    expect(@step_counter.step_value).to eq 10
+    @step_counter.slowly_increment
+    expect(@step_counter.count).to eq 110
+  end
+
+  context "inline" do
+    around :example do |example|
+      Plumbing.configure mode: :inline, &example
+    end
+
+    it "sends all queries immediately" do
+      @counter = Counter.start "inline counter", initial_value: 100
+      @time = Time.now
+
+      expect(@counter.name).to eq "inline counter"
+      expect(@counter.count).to eq 100
+      expect(Time.now - @time).to be < 0.1
+
+      expect(@counter.slow_query).to eq 100
+      expect(Time.now - @time).to be > 0.4
+    end
+
+    it "sends all commands immediately" do
+      @counter = Counter.start "inline counter", initial_value: 100
+      @time = Time.now
+
+      @counter.slowly_increment
+
+      expect(@counter.count).to eq 101
+      expect(Time.now - @time).to be > 0.4
+    end
+  end
+
+  context "async" do
+    around :example do |example|
+      Sync do
+        Plumbing.configure mode: :async, &example
+      end
+    end
+
+    it "sends all queries using fibers and waits for the response" do
+      @counter = Counter.start "async counter", initial_value: 100
+      @time = Time.now
+
+      expect(@counter.name).to eq "async counter"
+      expect(@counter.count).to eq 100
+      expect(Time.now - @time).to be < 0.1
+
+      expect(@counter.slow_query).to eq 100
+      expect(Time.now - @time).to be > 0.4
+    end
+
+    it "ignores the response from a query and returns immediately" do
+      @counter = Counter.start "async counter", initial_value: 100
+      @time = Time.now
+
+      expect(@counter.slow_query(ignore_result: true)).to be_nil
+
+      expect(Time.now - @time).to be < 0.1
+    end
+
+    it "sends all commands using fibers without waiting for the response" do
+      @counter = Counter.start "async counter", initial_value: 100
+      @time = Time.now
+
+      @counter.slowly_increment
+      expect(Time.now - @time).to be < 0.1
+
+      # wait for the async task to complete
+      expect(@counter.count).to become_equal_to { 101 }
+      expect(Time.now - @time).to be > 0.4
+    end
+  end
+end

data/spec/plumbing_spec.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+RSpec.describe Plumbing do
+  it "has a version number" do
+    expect(Plumbing::VERSION).not_to be nil
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "plumbing"
+require_relative "become_equal_to_matcher"
+
+RSpec.configure do |config|
+  # Enable flags like --only-failures and --next-failure
+  config.example_status_persistence_file_path = ".rspec_status"
+
+  # Disable RSpec exposing methods globally on `Module` and `main`
+  config.disable_monkey_patching!
+
+  config.expect_with :rspec do |c|
+    c.syntax = :expect
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: standard-procedure-plumbing
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.2
 platform: ruby
 authors:
 - Rahoul Baruah
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-08-28 00:00:00.000000000 Z
+date: 2024-09-13 00:00:00.000000000 Z
 dependencies: []
 description: A composable event pipeline and sequential pipelines of operations
 email:
@@ -17,22 +17,8 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".rspec"
-- ".rubocop.yml"
-- ".solargraph.yml"
-- ".standard.yml"
-- ".vscode/tasks.json"
-- CHANGELOG.md
-- CODE_OF_CONDUCT.md
-- LICENSE
 - README.md
 - 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
-- checksums/standard-procedure-plumbing-0.2.2.gem.sha512
-- checksums/standard-procedure-plumbing-0.3.0.gem.sha512
 - lib/plumbing.rb
 - lib/plumbing/config.rb
 - lib/plumbing/custom_filter.rb
@@ -53,7 +39,21 @@ files:
 - lib/plumbing/valve/inline.rb
 - lib/plumbing/valve/message.rb
 - lib/plumbing/version.rb
-- sig/plumbing.rbs
+- spec/become_equal_to_matcher.rb
+- spec/examples/pipe_spec.rb
+- spec/examples/pipeline_spec.rb
+- spec/examples/rubber_duck_spec.rb
+- spec/examples/valve_spec.rb
+- spec/plumbing/a_pipe.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/valve_spec.rb
+- spec/plumbing_spec.rb
+- spec/spec_helper.rb
 homepage: https://github.com/standard-procedure/plumbing
 licenses: []
 metadata:

data/.rspec

@@ -1,3 +0,0 @@
---format documentation
---color
---require spec_helper

data/.rubocop.yml

@@ -1,24 +0,0 @@
-# We want Exclude directives from different
-# config files to get merged, not overwritten
-inherit_mode:
-  merge:
-    - Exclude
-
-require:
-  # Standard's config uses custom cops,
-  # so it must be loaded along with custom Standard gems
-  - standard
-  - standard-custom
-  - standard-performance
-  # rubocop-performance is required when using Performance cops
-  - rubocop-performance
-
-inherit_gem:
-  standard: config/base.yml
-  standard-performance: config/base.yml
-  standard-custom: config/base.yml
-
-# Global options, like Ruby version
-AllCops:
-  SuggestExtensions: false
-  TargetRubyVersion: 3.2

data/.solargraph.yml

@@ -1,32 +0,0 @@
----
-include:
-  - "**/*.rb"
-exclude:
-  - spec/**/*
-  - test/**/*
-  - vendor/**/*
-  - ".bundle/**/*"
-require:
-  - actioncable
-  - actionmailer
-  - actionpack
-  - actionview
-  - activejob
-  - activemodel
-  - activerecord
-  - activestorage
-  - activesupport  
-domains: []
-reporters:
-  - rubocop
-  - require_not_found
-formatter:
-  rubocop:
-    cops: safe
-    except: []
-    only: []
-    extra_args: []
-require_paths: []
-plugins:
-  - solargraph-rails
-max_files: 5000

data/.standard.yml

@@ -1,9 +0,0 @@
-fix: true               
-parallel: true          
-format: progress        
-default_ignores: true
-
-ignore:           
-  - 'vendor/**/*'
-  - 'Gemfile.lock'
-

data/.vscode/tasks.json

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

data/CHANGELOG.md

@@ -1,36 +0,0 @@
-## [0.3.0] - 2024-08-28
-
- - Added Plumbing::Valve
- - Reimplemented Plumbing::Pipe to use Plumbing::Valve
-
-## [0.2.2] - 2024-08-25
-
- - Added Plumbing::RubberDuck
-
-## [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
- - Use Async for fiber-based pipes
-
-## [0.1.2] - 2024-08-14
-
- - Removed dependencies
- - Removed Ractor-based concurrent pipe (as I don't trust it yet)
-
-## [0.1.1] - 2024-08-14
-
-- Tidied up the code
-- Added Plumbing::Chain
-
-## [0.1.0] - 2024-04-13
-
-- Initial release
-
-## [Unreleased]
-

data/CODE_OF_CONDUCT.md

@@ -1,5 +0,0 @@
-# Contributor Covenant Code of Conduct
-
-**BE NICE**
-
-If people think you're being a dick, you're probably being a dick, so stop it.