teckel 0.1.0 → 0.6.0

data/lib/teckel/operation/runner.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Teckel
+  module Operation
+    # The default implementation for executing a single {Operation}
+    # @note You shouldn't need to call this explicitly.
+    #   Use {ClassMethods#with MyOperation.with()} or {ClassMethods#with MyOperation.call()} instead.
+    # @!visibility protected
+    class Runner
+      # @!visibility private
+      UNDEFINED = Object.new.freeze
+
+      def initialize(operation, settings = UNDEFINED)
+        @operation, @settings = operation, settings
+      end
+      attr_reader :operation, :settings
+
+      def call(input = nil)
+        catch(:failure) do
+          out = catch(:success) do
+            run operation.input_constructor.call(input)
+            return nil # :sic!: return values need to go through +success!+
+          end
+
+          return out
+        end
+      end
+
+      # This is just here to raise a meaningful error.
+      # @!visibility private
+      def with(*)
+        raise Teckel::Error, "Operation already has settings assigned."
+      end
+
+      # Halt any further execution with a output value
+      #
+      # @return a thing matching your {Teckel::Operation::Config#output output} definition
+      # @!visibility protected
+      def success!(*args)
+        value =
+          if args.size == 1 && operation.output === args.first # rubocop:disable Style/CaseEquality
+            args.first
+          else
+            operation.output_constructor.call(*args)
+          end
+
+        throw :success, operation.result_constructor.call(value, true)
+      end
+
+      # Halt any further execution with an error value
+      #
+      # @return a thing matching your {Teckel::Operation::Config#error error} definition
+      # @!visibility protected
+      def fail!(*args)
+        value =
+          if args.size == 1 && operation.error === args.first # rubocop:disable Style/CaseEquality
+            args.first
+          else
+            operation.error_constructor.call(*args)
+          end
+
+        throw :failure, operation.result_constructor.call(value, false)
+      end
+
+      private
+
+      def run(input)
+        op = @operation.new
+        op.runner = self
+        op.settings = settings if settings != UNDEFINED
+        op.call(input)
+      end
+    end
+  end
+end

data/lib/teckel/result.rb

@@ -1,63 +1,62 @@
 # frozen_string_literal: true
 
 module Teckel
-  # Wrapper for +output+ and +error+ return values of Operations
-  #
-  # @example asking for status
-  #
-  #   Teckel::Result.new("some output", true).successful? #=> true
-  #   Teckel::Result.new("some output", true).failure? #=> false
-  #
-  #   Teckel::Result.new("some error", false).successful? #=> false
-  #   Teckel::Result.new("some error", false).failure? #=> true
-  #
-  # @example Use +.value+ to get the wrapped value regardless of success state
-  #
-  #   Teckel::Result.new("some output", true).value #=> "some output"
-  #   Teckel::Result.new("some error", false).value #=> "some error"
-  #
-  # @example Use +.success+ to get the wrapped value of a successful result
-  #
-  #  # Note: The +.failure+ method works just the same for successful results
-  #  Teckel::Result.new("some output", true).success #=> "some output"
-  #  Teckel::Result.new("some error", false).success #=> nil
-  #  Teckel::Result.new("some error", false).success("other default") #=> "other default"
-  #  Teckel::Result.new("some error", false).success { |value| "Failed: #{value}" } #=> "Failed: some error"
-  #
-  # @api public
-  class Result
-    # @param value [Mixed] the value/payload of the result.
-    # @param success [Bool] whether this is a successful result
-    def initialize(value, success)
-      @value = value
-      @success = success
+  # @abstract The interface an {Operation}s result object needs to adopt.
+  #
+  # @example
+  #   class MyResult
+  #     include Teckel::Result
+  #
+  #     def initialize(value, success)
+  #       @value = value
+  #       @success = (!!success).freeze
+  #     end
+  #
+  #     def successful?; @success end
+  #
+  #     def value; @value end
+  #   end
+  module Result
+    module ClassMethods
+      def [](value, success)
+        new(value, success)
+      end
     end
 
-    # @!attribute [r] value
-    # @return [Mixed] the value/payload
-    attr_reader :value
-
-    def successful?
-      @success
-    end
-
-    def failure?
-      !@success
-    end
-
-    def failure(default = nil, &block)
-      return @value if !@success
-      return yield(@value) if block
-
-      default
+    module InstanceMethods
+      # Whether this is a success result
+      # @return [Boolean]
+      def successful?
+        raise NotImplementedError, "Result object does not implement `successful?`"
+      end
+
+      # Whether this is a error/failure result
+      # @return [Boolean]
+      def failure?
+        !successful?
+      end
+
+      # @!attribute [r] value
+      # @return [Mixed] the value/payload
+      def value
+        raise NotImplementedError, "Result object does not implement `value`"
+      end
+
+      def deconstruct
+        [successful?, value]
+      end
+
+      def deconstruct_keys(keys)
+        e = {}
+        e[:success] = successful? if keys.include?(:success)
+        e[:value] = value if keys.include?(:value)
+        e
+      end
     end
 
-    def success(default = nil, &block)
-      return @value if @success
-
-      return yield(@value) if block
-
-      default
+    def self.included(receiver)
+      receiver.extend         ClassMethods
+      receiver.send :include, InstanceMethods
     end
   end
 end

data/lib/teckel/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Teckel
-  VERSION = "0.1.0"
+  VERSION = "0.6.0"
 end

data/spec/chain/default_settings_spec.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module TeckelChainDefaultSettingsTest
+  class MyOperation
+    include Teckel::Operation
+    result!
+
+    settings Struct.new(:say, :other)
+    settings_constructor ->(data) { settings.new(*data.values_at(*settings.members)) } # ruby 2.4 way for `keyword_init: true`
+
+    input none
+    output Hash
+    error none
+
+    def call(_)
+      success! settings.to_h
+    end
+  end
+
+  class Chain
+    include Teckel::Chain
+
+    default_settings!(a: { say: "Chain Default" })
+
+    step :a, MyOperation
+  end
+end
+
+RSpec.describe Teckel::Chain do
+  specify "call chain without settings, uses default settings" do
+    result = TeckelChainDefaultSettingsTest::Chain.call
+    expect(result.success).to eq(say: "Chain Default", other: nil)
+  end
+
+  specify "call chain with explicit settings, overwrites defaults" do
+    result = TeckelChainDefaultSettingsTest::Chain.with(a: { other: "What" }).call
+    expect(result.success).to eq(say: nil, other: "What")
+  end
+end

data/spec/chain/inheritance_spec.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require 'support/dry_base'
+require 'support/fake_models'
+
+module TeckelChainDefaultsViaBaseClass
+  LOG = [] # rubocop:disable Style/MutableConstant
+
+  class LoggingChain
+    include Teckel::Chain
+
+    around do |chain, input|
+      require 'benchmark'
+      result = nil
+      LOG << Benchmark.measure { result = chain.call(input) }
+      result
+    end
+
+    freeze
+  end
+
+  class OperationA
+    include Teckel::Operation
+
+    result!
+
+    input none
+    output Types::Integer
+    error none
+
+    def call(_)
+      success! rand(1000)
+    end
+
+    finalize!
+  end
+
+  class OperationB
+    include Teckel::Operation
+
+    result!
+
+    input none
+    output Types::String
+    error none
+
+    def call(_)
+      success! ("a".."z").to_a.sample
+    end
+
+    finalize!
+  end
+
+  class ChainA < LoggingChain
+    step :roll, OperationA
+
+    finalize!
+  end
+
+  class ChainB < LoggingChain
+    step :say, OperationB
+
+    finalize!
+  end
+
+  class ChainC < ChainB
+    finalize!
+  end
+end
+
+RSpec.describe Teckel::Chain do
+  before do
+    TeckelChainDefaultsViaBaseClass::LOG.clear
+  end
+
+  let(:base_chain) { TeckelChainDefaultsViaBaseClass::LoggingChain }
+  let(:chain_a) { TeckelChainDefaultsViaBaseClass::ChainA }
+  let(:chain_b) { TeckelChainDefaultsViaBaseClass::ChainB }
+  let(:chain_c) { TeckelChainDefaultsViaBaseClass::ChainC }
+
+  it "inherits config" do
+    expect(chain_a.around)
+    expect(chain_b.around)
+
+    expect(base_chain.steps).to eq([])
+    expect(chain_a.steps.size).to eq(1)
+    expect(chain_b.steps.size).to eq(1)
+  end
+
+  it "runs chain a" do
+    expect {
+      result = chain_a.call
+      expect(result.success).to be_a(Integer)
+    }.to change {
+      TeckelChainDefaultsViaBaseClass::LOG.size
+    }.from(0).to(1)
+  end
+
+  it "runs chain b" do
+    expect {
+      result = chain_b.call
+      expect(result.success).to be_a(String)
+    }.to change {
+      TeckelChainDefaultsViaBaseClass::LOG.size
+    }.from(0).to(1)
+  end
+
+  it "inherits steps" do
+    expect {
+      result = chain_c.call
+      expect(result.success).to be_a(String)
+    }.to change {
+      TeckelChainDefaultsViaBaseClass::LOG.size
+    }.from(0).to(1)
+  end
+end

data/spec/chain/none_input_spec.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module TeckelChainNoneInputTest
+  class MyOperation
+    include Teckel::Operation
+    result!
+
+    settings Struct.new(:say)
+
+    input none
+    output String
+    error none
+
+    def call(_)
+      success!(settings&.say || "Called")
+    end
+  end
+
+  class Chain
+    include Teckel::Chain
+
+    step :a, MyOperation
+  end
+end
+
+RSpec.describe Teckel::Chain do
+  specify "call chain without input value" do
+    result = TeckelChainNoneInputTest::Chain.call
+    expect(result.success).to eq("Called")
+  end
+
+  specify "call chain runner without input value" do
+    result = TeckelChainNoneInputTest::Chain.with(a: "What").call
+    expect(result.success).to eq("What")
+  end
+end

data/spec/chain/results_spec.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require 'support/dry_base'
+require 'support/fake_models'
+
+module TeckelChainResultTest
+  class Message
+    include ::Teckel::Operation
+
+    result!
+
+    input Types::Hash.schema(message: Types::String)
+    error none
+    output Types::String
+
+    def call(input)
+      success! input[:message].upcase
+    end
+  end
+
+  class Chain
+    include Teckel::Chain
+
+    step :message, Message
+
+    class Result < Teckel::Operation::Result
+      def initialize(value, success, step, opts = {})
+        super(value, success)
+        @step = step
+        @opts = opts
+      end
+
+      class << self
+        alias :[] :new # Alias the default constructor to :new
+      end
+
+      attr_reader :opts, :step
+    end
+
+    result_constructor ->(value, success, step) {
+      result.new(value, success, step, time: Time.now.to_i)
+    }
+  end
+end
+
+RSpec.describe Teckel::Chain do
+  specify do
+    result = TeckelChainResultTest::Chain.call(message: "Hello World!")
+    expect(result).to be_successful
+    expect(result.success).to eq("HELLO WORLD!")
+    expect(result.opts).to include(time: kind_of(Integer))
+  end
+end