codequest_pipes 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 5de4743e4f4364742d5f485f244167f604394777
+  data.tar.gz: 76c3e6315db9137dac15c76a0263b177855295c3
+SHA512:
+  metadata.gz: f5059e69133b70d4c618334e1fef64eb603e54b90e86df911ed22aa4b7f05a61542089d85f86d42f22789ece92ff0ccf9e83ddcb69cc94af27da479fe2bc4660
+  data.tar.gz: b3589d64194030087e2df1a7115e65956683a4b55e4dfcfde8b144aa320c27139baaa897efce8743c38b30c399d1598759f7db9e41d9e8852db0da8c9da5a07d

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format documentation

data/.travis.yml

@@ -0,0 +1,5 @@
+language: ruby
+rvm:
+  - 2.2.0
+  - 2.1.0
+  - 2.0.0

data/Gemfile

@@ -0,0 +1,7 @@
+source 'https://rubygems.org'
+
+gemspec
+
+group :test do
+  gem 'rspec', '~> 3.1'
+end

data/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 code quest
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

data/README.md

@@ -0,0 +1,57 @@
+# Pipes [![Build Status](https://travis-ci.org/codequest-eu/codequest_pipes.svg?branch=master)](https://travis-ci.org/codequest-eu/codequest_pipes) [![codebeat badge](https://codebeat.co/badges/73f1bb7f-516f-4fc5-b241-daea42c7badd)](https://codebeat.co/projects/codequest_pipes-master-ab1a7c5f-ad5f-425a-a0f0-e56e13a04876)
+
+Pipes provide a Unix-like way to chain business objects (interactors) in Ruby.
+
+## Installation
+
+To start using Pipes, add the library to your Gemfile. This project is currently
+not available on RubyGems.
+
+```ruby
+gem "codequest_pipes", github: "codequest-eu/codequest_pipes"
+```
+
+## High-level usage example
+
+```ruby
+FLOW = Projects::Match         | # NOTE: each of the elements must inherit from
+       Projects::Validate      | # Pipes::Pipe!
+       Projects::UpdatePayment |
+       Projects::SaveWithReport
+context = Pipes::Context.new(project: p)
+FLOW.call(context)
+```
+
+## Pipe
+
+Pipes provide a way to describe business transactions in a stateless
+and reusable way. Let's create a few pipes from plain Ruby classes.
+
+```ruby
+class PaymentPipe < Pipes::Pipe
+  require_context :user        # flow will fail if precondition not met
+  provide_context :transaction # flow will fail if postcondition not met
+
+  def call
+    result = PaymentService.create_transaction(user)
+    add(transaction: result.transaction)
+  end
+end
+```
+
+Note how we've only had to implement the `call` method for the magic to start happening. When calling these objects you'd be using the class method `call` instead and passing a `Pipes::Context` objects to it. All unknown messages (like `user`) in two examples above are passed to the `context` which is an instance variable of every object inheriting from `Pipes::Pipe`.
+
+## Context
+
+Each Pipe requires an instance `Pipes::Context` to be passed on `.call` invokation. It provides append-only data container for Pipes: you can add data to a context at any time using the `add` method but the same call will raise an error if you try to modify an existing key.
+
+Made with <3 by [code quest](http://www.codequest.com)
+
+
+
+
+
+
+
+
+

data/Rakefile

@@ -0,0 +1,9 @@
+begin
+  require 'rspec/core/rake_task'
+
+  RSpec::Core::RakeTask.new(:spec)
+
+  task :default => :spec
+rescue LoadError
+  # no rspec available
+end

data/codequest_pipes.gemspec

@@ -0,0 +1,19 @@
+# encoding: utf-8
+
+Gem::Specification.new do |spec|
+  spec.name    = 'codequest_pipes'
+  spec.version = '0.2.0'
+
+  spec.author      = 'codequest'
+  spec.email       = 'hello@codequest.com'
+  spec.description = 'Pipes provides a Unix-like way to chain business objects'
+  spec.summary     = 'Unix-like way to chain business objects (interactors)'
+  spec.homepage    = 'https://github.com/codequest-eu/codequest_pipes'
+  spec.license     = 'MIT'
+
+  spec.files      = `git ls-files`.split($RS)
+  spec.test_files = spec.files.grep(/^spec/)
+
+  spec.add_development_dependency 'bundler', '>= 1.6.9'
+  spec.add_development_dependency 'rake', '~> 10.3'
+end

data/lib/codequest_pipes/closure.rb

@@ -0,0 +1,9 @@
+module Pipes
+  # Closure provides a quick and dirty way of turning a block into an example of
+  # Pipes::Pipe.
+  class Closure
+    def self.define(&block)
+      Class.new(Pipe) { define_method(:call, block) }
+    end
+  end # class Closure
+end # module Pipes

data/lib/codequest_pipes/context.rb

@@ -0,0 +1,61 @@
+module Pipes
+  # Context is an object used to pass data between Pipes. It behaves like an
+  # OpenStruct except you can write a value only once - this way we prevent
+  # context keys from being overwritten.
+  class Context
+    attr_reader :error
+
+    # Override is an exception raised when an attempt is made to override an
+    # existing Context property.
+    class Override < ::StandardError; end
+
+    # ExecutionTerminated is an exception raised when the `fail` method is
+    # explicitly called on the Context. This terminates the flow of a pipe.
+    class ExecutionTerminated < ::StandardError; end
+
+    # Context constructor.
+    #
+    # @param values [Hash]
+    def initialize(values = {})
+      add(values)
+      @error = nil
+    end
+
+    # Method `add` allows adding new properties (as a Hash) to the Context.
+    #
+    # @param values [Hash]
+    def add(values)
+      values.each do |key, val|
+        k_sym = key.to_sym
+        fail Override, "Property :#{key} already present" if respond_to?(k_sym)
+        define_singleton_method(k_sym) { val }
+      end
+    end
+
+    # Explicitly fail the pipe, allowing the error to be saved and accessed from
+    # the Context.
+    #
+    # @param error [Any] Error to be set.
+    #
+    # @raise [ExecutionTerminated]
+    def terminate(error)
+      @error = error
+      fail ExecutionTerminated, error
+    end
+
+    # Check if the Context finished successfully.
+    # This method smells of :reek:NilCheck
+    #
+    # @return [Boolean] Success status.
+    def success?
+      @error.nil?
+    end
+
+    # Check if the Context failed.
+    #
+    # @return [Boolean] Failure status.
+    def failure?
+      !success?
+    end
+  end # class Context
+end # module Pipes

data/lib/codequest_pipes/pipe.rb

@@ -0,0 +1,76 @@
+module Pipes
+  # Pipe is a mix-in which turns a class into a Pipes building block (Pipe).
+  # A Pipe can only have class methods since it can't be instantiated.
+  class Pipe
+    attr_reader :context
+
+    def initialize(ctx)
+      @context = ctx
+    end
+
+    def call
+      fail MissingCallMethod
+    end
+
+    def self.|(other)
+      this = self
+      Class.new(Pipe) do
+        _combine(this, other)
+      end
+    end
+
+    def self.call(ctx)
+      _validate_ctx(_required_context_elements, ctx)
+      new(ctx).call
+      _validate_ctx(_provided_context_elements, ctx)
+      ctx
+    end
+
+    def self.require_context(*args)
+      _required_context_elements.push(*args)
+    end
+
+    def self.provide_context(*args)
+      _provided_context_elements.push(*args)
+    end
+
+    def self._combine(first, second)
+      _check_interface(first)
+      _check_interface(second)
+      define_singleton_method(:call) do |ctx|
+        first.call(ctx)
+        second.call(ctx)
+      end
+    end
+    private_class_method :_combine
+
+    def self._check_interface(klass)
+      fail MissingCallMethod unless klass.instance_methods.include?(:call)
+    end
+    private_class_method :_check_interface
+
+    def self._required_context_elements
+      @required_context_elements ||= []
+    end
+    private_class_method :_required_context_elements
+
+    def self._provided_context_elements
+      @provided_context_elements ||= []
+    end
+    private_class_method :_provided_context_elements
+
+    def self._validate_ctx(collection, ctx)
+      collection.each do |element|
+        next if ctx.respond_to?(element)
+        fail MissingContext, "context does not respond to '#{element}'"
+      end
+    end
+    private_class_method :_validate_ctx
+
+    private
+
+    def method_missing(name, *args, &block)
+      context.send(name, *args, &block)
+    end
+  end # class Pipe
+end # module Pipes

data/lib/codequest_pipes.rb

@@ -0,0 +1,8 @@
+require 'codequest_pipes/closure'
+require 'codequest_pipes/context'
+require 'codequest_pipes/pipe'
+
+module Pipes
+  class MissingCallMethod < ::Exception; end
+  class MissingContext < ::Exception; end
+end # module Pipes

data/spec/context_spec.rb

@@ -0,0 +1,18 @@
+require 'spec_helper'
+
+describe Pipes::Context do
+  let(:ctx) { Pipes::Context.new }
+
+  describe '#add' do
+    it 'allows adding new fields' do
+      ctx.add(key: 'val')
+      expect(ctx.key).to eq('val')
+    end
+
+    it 'does not allow rewriting existing fields' do
+      ctx.add(key: 'val')
+      expect { ctx.add(key: 'other_val') }
+        .to raise_error(Pipes::Context::Override)
+    end
+  end
+end # describe Context

data/spec/pipe_spec.rb

@@ -0,0 +1,127 @@
+require 'spec_helper'
+
+# Parent is a dummy test class.
+class Parent < Pipes::Pipe
+  require_context :flow
+
+  def call
+    flow.push(self.class.name)
+  end
+end # class Parent
+
+class Child < Parent; end
+class Grandchild < Parent; end
+class GrandGrandchild < Parent; end
+
+# BadApple will break.
+class BadApple < Pipes::Pipe
+  def call
+    fail StandardError
+  end
+end
+
+# NoMethodPipe will break with NoMethodError.
+class NoMethodPipe < Pipes::Pipe; end
+
+describe Pipes::Pipe do
+  let(:ctx) { Pipes::Context.new(flow: []) }
+
+  subject { pipe.call(ctx) }
+
+  describe 'normal flow' do
+    let(:pipe) { Parent | Child | Grandchild }
+
+    it 'executes the pipe left to right' do
+      expect { subject }.to change { ctx.flow }
+        .from([]).to %w(Parent Child Grandchild)
+    end
+  end # describe 'normal flow'
+
+  describe 'pipe raising an exception' do
+    let(:pipe) { Parent | BadApple | Child }
+
+    it 'raises StandardError' do
+      expect { pipe.call(ctx) }.to raise_error StandardError
+    end
+
+    it 'stores the result of execution so far in the context' do
+      # rubocop:disable Style/RescueModifier
+      expect { pipe.call(ctx) rescue nil }
+        .to change { ctx.flow }
+        .from([]).to(['Parent'])
+      # rubocop:enable Style/RescueModifier
+    end
+  end # describe 'pipe raising an exception'
+
+  describe '.provide_context' do
+    context 'when context element provided' do
+      class ProvidingChild < Parent
+        provide_context :bacon
+
+        def call
+          super
+          add(bacon: true)
+        end
+      end # class ProvideChild
+
+      let(:pipe) { Parent | ProvidingChild }
+
+      it 'does not raise' do
+        expect { subject }.to_not raise_error
+      end
+    end # context 'when context element provided'
+
+    context 'when context element not provided' do
+      class NotProvidingChild < Parent
+        provide_context :bacon
+      end
+
+      let(:pipe) { Parent | NotProvidingChild }
+
+      it 'raises MissingContext' do
+        expect { subject }.to raise_error Pipes::MissingContext
+      end
+    end # context 'when context element not provided'
+  end # describe '.provide_context'
+
+  describe 'pipes declared using Pipe::Closure' do
+    let(:dynamic_grandchild) do
+      Pipes::Closure.define { context.flow << 'bacon' }
+    end
+    let(:pipe) { Parent | dynamic_grandchild | Child }
+
+    it 'behaves as with normal pipes' do
+      expect { subject }
+        .to change { ctx.flow }
+        .from([]).to %w(Parent bacon Child)
+    end
+  end # describe 'pipes declared using Pipe::Closure'
+
+  describe 'pipe with a missing `call` method' do
+    let(:pipe) { Parent | Child | NoMethodPipe }
+
+    it 'raises a Pipes::MissingCallMethod error' do
+      expect { subject }.to raise_error Pipes::MissingCallMethod
+    end
+  end # describe 'pipe with a missing `call` method'
+
+  describe 'combined pipes' do
+    let(:first)  { Parent | Child }
+    let(:second) { Grandchild | GrandGrandchild }
+    let(:pipe)   { first | second }
+
+    it 'behaves as with normal pipes' do
+      expect { subject }
+        .to change { ctx.flow }
+        .from([]).to %w(Parent Child Grandchild GrandGrandchild)
+    end
+
+    describe 'broken combination' do
+      let(:second) { NoMethodPipe | Grandchild }
+
+      it 'raises error from a broken pipe' do
+        expect { subject }.to raise_error Pipes::MissingCallMethod
+      end
+    end # describe 'broken combination'
+  end # describe 'combined pipes'
+end # describe Pipes::Pipe

data/spec/spec_helper.rb

@@ -0,0 +1,4 @@
+require 'bundler/setup'
+Bundler.setup
+
+require 'codequest_pipes'

metadata

@@ -0,0 +1,89 @@
+--- !ruby/object:Gem::Specification
+name: codequest_pipes
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- codequest
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-02-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.6.9
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.6.9
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.3'
+description: Pipes provides a Unix-like way to chain business objects
+email: hello@codequest.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- codequest_pipes.gemspec
+- lib/codequest_pipes.rb
+- lib/codequest_pipes/closure.rb
+- lib/codequest_pipes/context.rb
+- lib/codequest_pipes/pipe.rb
+- spec/context_spec.rb
+- spec/pipe_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/codequest-eu/codequest_pipes
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.1
+signing_key: 
+specification_version: 4
+summary: Unix-like way to chain business objects (interactors)
+test_files:
+- spec/context_spec.rb
+- spec/pipe_spec.rb
+- spec/spec_helper.rb