teckel 0.4.0 → 0.8.0

data/lib/teckel/operation/result.rb

@@ -38,16 +38,16 @@ module Teckel
       include Teckel::Result
 
       # @param value [Object] The result value
-      # @param success [Boolean] whether this is a successful result
-      def initialize(value, success)
+      # @param successful [Boolean] whether this is a successful result
+      def initialize(value, successful)
         @value = value
-        @success = (!!success).freeze
+        @successful = successful
       end
 
       # Whether this is a success result
       # @return [Boolean]
       def successful?
-        @success
+        @successful
       end
 
       # @!attribute [r] value
@@ -59,8 +59,8 @@ module Teckel
       # @param  default [Mixed] return this default value if it's not a failure result
       # @return [Mixed] the value/payload
       def failure(default = nil, &block)
-        return @value unless @success
-        return yield(@value) if block
+        return value unless @successful
+        return yield(value) if block
 
         default
       end
@@ -70,8 +70,8 @@ module Teckel
       # @param  default [Mixed] return this default value if it's not a success result
       # @return [Mixed] the value/payload
       def success(default = nil, &block)
-        return @value if @success
-        return yield(@value) if block
+        return value if @successful
+        return yield(value) if block
 
         default
       end

data/lib/teckel/operation/runner.rb

@@ -16,54 +16,58 @@ module Teckel
       attr_reader :operation, :settings
 
       def call(input = nil)
-        err = catch(:failure) do
-          simple_return = UNDEFINED
-          out = catch(:success) do
-            simple_return = call!(build_input(input))
-          end
-          return simple_return == UNDEFINED ? build_output(*out) : build_output(simple_return)
+        catch(:halt) do
+          op = instance
+          op_input = op.instance_exec(input, &operation.input_constructor)
+          op.call(op_input)
+          nil # return values need to go through +success!+ or +fail!+
         end
-        build_error(*err)
       end
 
-      # This is just here to raise a meaningful error.
-      # @!visibility private
-      def with(*)
-        raise Teckel::Error, "Operation already has settings assigned."
-      end
+      def instance
+        return @instance if instance_variable_defined?(:@instance)
 
-      private
+        op = operation.new
+        op.runner = self
+        op.settings = settings unless settings.eql?(UNDEFINED)
 
-      def call!(input)
-        op = @operation.new
-        op.settings = settings if settings != UNDEFINED
-        op.call(input)
+        @instance = op
       end
 
-      def build_input(input)
-        operation.input_constructor.call(input)
+      # This is just here to raise a meaningful error.
+      # @!visibility private
+      def with(*)
+        raise Error, "Operation already has settings assigned."
       end
 
-      def build_output(*args)
+      # 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
+          if args.size.equal?(1) && operation.output === args.first # rubocop:disable Style/CaseEquality
             args.first
           else
             operation.output_constructor.call(*args)
           end
 
-        operation.result_constructor.call(value, true)
+        throw :halt, instance.instance_exec(value, true, &operation.result_constructor)
       end
 
-      def build_error(*args)
+      # 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
+          if args.size.equal?(1) && operation.error === args.first # rubocop:disable Style/CaseEquality
             args.first
           else
             operation.error_constructor.call(*args)
           end
 
-        operation.result_constructor.call(value, false)
+        throw :halt, instance.instance_exec(value, false, &operation.result_constructor)
       end
     end
   end

data/lib/teckel/operation.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "operation/config"
 require_relative "operation/result"
 require_relative "operation/runner"
 
@@ -13,13 +14,14 @@ module Teckel
   # +input+. +output+ and +error+ methods to point them to anonymous classes.
   #
   # If you like "traditional" result objects to ask +successful?+ or +failure?+ on,
-  # use {.result!} and get {Teckel::Operation::Result}
+  # use {Teckel::Operation::Config#result! result!} and get {Teckel::Operation::Result}
   #
   # By default, +input+. +output+ and +error+ classes are build using +:[]+
   # (eg: +Input[some: :param]+).
-  # Use {ClassMethods#input_constructor input_constructor},
-  # {ClassMethods#output_constructor output_constructor} and
-  # {ClassMethods#error_constructor error_constructor} to change them.
+  #
+  # Use {Teckel::Operation::Config#input_constructor input_constructor},
+  # {Teckel::Operation::Config#output_constructor output_constructor} and
+  # {Teckel::Operation::Config#error_constructor error_constructor} to change them.
   #
   # @example class definitions via methods
   #   class CreateUserViaMethods
@@ -56,318 +58,28 @@ module Teckel
   # @!visibility public
   module Operation
     module ClassMethods
-      # @!group Contacts definition
-
-      # @overload input()
-      #   Get the configured class wrapping the input data structure.
-      #   @return [Class] The +input+ class
-      # @overload input(klass)
-      #   Set the class wrapping the input data structure.
-      #   @param  klass [Class] The +input+ class
-      #   @return [Class] The +input+ class
-      def input(klass = nil)
-        @config.for(:input, klass) { self::Input if const_defined?(:Input) } ||
-          raise(Teckel::MissingConfigError, "Missing input config for #{self}")
-      end
-
-      # @overload input_constructor()
-      #   The callable constructor to build an instance of the +input+ class.
-      #   Defaults to {Teckel::DEFAULT_CONSTRUCTOR}
-      #   @return [Proc] A callable that will return an instance of the +input+ class.
-      #
-      # @overload input_constructor(sym_or_proc)
-      #   Define how to build the +input+.
-      #   @param  sym_or_proc [Symbol, #call]
-      #     - Either a +Symbol+ representing the _public_ method to call on the +input+ class.
-      #     - Or anything that response to +#call+ (like a +Proc+).
-      #   @return [#call] The callable constructor
-      #
-      #   @example simple symbol to method constructor
-      #     class MyOperation
-      #       include Teckel::Operation
-      #
-      #       class Input
-      #         def initialize(name:, age:); end
-      #       end
-      #
-      #       # If you need more control over how to build a new +Input+ instance
-      #       # MyOperation.call(name: "Bob", age: 23) # -> Input.new(name: "Bob", age: 23)
-      #       input_constructor :new
-      #     end
-      #
-      #     MyOperation.input_constructor.is_a?(Method) #=> true
-      #
-      #   @example Custom Proc constructor
-      #     class MyOperation
-      #       include Teckel::Operation
-      #
-      #       class Input
-      #         def initialize(*args, **opts); end
-      #       end
-      #
-      #       # If you need more control over how to build a new +Input+ instance
-      #       # MyOperation.call("foo", opt: "bar") # -> Input.new(name: "foo", opt: "bar")
-      #       input_constructor ->(name, options) { Input.new(name: name, **options) }
-      #     end
-      #
-      #     MyOperation.input_constructor.is_a?(Proc) #=> true
-      def input_constructor(sym_or_proc = nil)
-        get_set_counstructor(:input_constructor, input, sym_or_proc) ||
-          raise(MissingConfigError, "Missing input_constructor config for #{self}")
-      end
-
-      # @overload output()
-      #  Get the configured class wrapping the output data structure.
-      #  Defaults to {Teckel::DEFAULT_CONSTRUCTOR}
-      #  @return [Class] The +output+ class
-      #
-      # @overload output(klass)
-      #   Set the class wrapping the output data structure.
-      #   @param  klass [Class] The +output+ class
-      #   @return [Class] The +output+ class
-      def output(klass = nil)
-        @config.for(:output, klass) { self::Output if const_defined?(:Output) } ||
-          raise(Teckel::MissingConfigError, "Missing output config for #{self}")
-      end
-
-      # @overload output_constructor()
-      #  The callable constructor to build an instance of the +output+ class.
-      #  Defaults to {Teckel::DEFAULT_CONSTRUCTOR}
-      #  @return [Proc] A callable that will return an instance of +output+ class.
-      #
-      # @overload output_constructor(sym_or_proc)
-      #   Define how to build the +output+.
-      #   @param sym_or_proc [Symbol, #call]
-      #     - Either a +Symbol+ representing the _public_ method to call on the +output+ class.
-      #     - Or anything that response to +#call+ (like a +Proc+).
-      #   @return [#call] The callable constructor
-      #
-      #   @example
-      #     class MyOperation
-      #       include Teckel::Operation
-      #
-      #       class Output
-      #         def initialize(*args, **opts); end
-      #       end
-      #
-      #       # MyOperation.call("foo", "bar") # -> Output.new("foo", "bar")
-      #       output_constructor :new
-      #
-      #       # If you need more control over how to build a new +Output+ instance
-      #       # MyOperation.call("foo", opt: "bar") # -> Output.new(name: "foo", opt: "bar")
-      #       output_constructor ->(name, options) { Output.new(name: name, **options) }
-      #     end
-      def output_constructor(sym_or_proc = nil)
-        get_set_counstructor(:output_constructor, output, sym_or_proc) ||
-          raise(MissingConfigError, "Missing output_constructor config for #{self}")
-      end
-
-      # @overload error()
-      #   Get the configured class wrapping the error data structure.
-      #   @return [Class] The +error+ class
-      #
-      # @overload error(klass)
-      #   Set the class wrapping the error data structure.
-      #   @param klass [Class] The +error+ class
-      #   @return [Class,nil] The +error+ class or +nil+ if it does not error
-      def error(klass = nil)
-        @config.for(:error, klass) { self::Error if const_defined?(:Error) } ||
-          raise(Teckel::MissingConfigError, "Missing error config for #{self}")
-      end
-
-      # @overload error_constructor()
-      #   The callable constructor to build an instance of the +error+ class.
-      #   Defaults to {Teckel::DEFAULT_CONSTRUCTOR}
-      #   @return [Proc] A callable that will return an instance of +error+ class.
-      #
-      # @overload error_constructor(sym_or_proc)
-      #   Define how to build the +error+.
-      #   @param sym_or_proc [Symbol, #call]
-      #     - Either a +Symbol+ representing the _public_ method to call on the +error+ class.
-      #     - Or anything that response to +#call+ (like a +Proc+).
-      #   @return [#call] The callable constructor
-      #
-      #   @example
-      #     class MyOperation
-      #       include Teckel::Operation
-      #
-      #       class Error
-      #         def initialize(*args, **opts); end
-      #       end
-      #
-      #       # MyOperation.call("foo", "bar") # -> Error.new("foo", "bar")
-      #       error_constructor :new
-      #
-      #       # If you need more control over how to build a new +Error+ instance
-      #       # MyOperation.call("foo", opt: "bar") # -> Error.new(name: "foo", opt: "bar")
-      #       error_constructor ->(name, options) { Error.new(name: name, **options) }
-      #     end
-      def error_constructor(sym_or_proc = nil)
-        get_set_counstructor(:error_constructor, error, sym_or_proc) ||
-          raise(MissingConfigError, "Missing error_constructor config for #{self}")
-      end
-
-      # @!endgroup
-
-      # @overload settings()
-      #  Get the configured class wrapping the settings data structure.
-      #  @return [Class] The +settings+ class, or {Teckel::Contracts::None} as default
-      #
-      # @overload settings(klass)
-      #   Set the class wrapping the settings data structure.
-      #   @param klass [Class] The +settings+ class
-      #   @return [Class] The +settings+ class configured
-      def settings(klass = nil)
-        @config.for(:settings, klass) { const_defined?(:Settings) ? self::Settings : none }
-      end
-
-      # @overload settings_constructor()
-      #   The callable constructor to build an instance of the +settings+ class.
-      #   Defaults to {Teckel::DEFAULT_CONSTRUCTOR}
-      #   @return [Proc] A callable that will return an instance of +settings+ class.
-      #
-      # @overload settings_constructor(sym_or_proc)
-      #  Define how to build the +settings+.
-      #  @param  sym_or_proc [Symbol, #call]
-      #    - Either a +Symbol+ representing the _public_ method to call on the +settings+ class.
-      #    - Or anything that response to +#call+ (like a +Proc+).
-      #  @return [#call] The callable constructor
-      #
-      #  @example
-      #    class MyOperation
-      #      include Teckel::Operation
-      #
-      #      class Settings
-      #        def initialize(*args); end
-      #      end
-      #
-      #      # MyOperation.with("foo", "bar") # -> Settings.new("foo", "bar")
-      #      settings_constructor :new
-      #    end
-      def settings_constructor(sym_or_proc = nil)
-        get_set_counstructor(:settings_constructor, settings, sym_or_proc) ||
-          raise(MissingConfigError, "Missing settings_constructor config for #{self}")
-      end
-
-      # @overload runner()
-      #   @return [Class] The Runner class
-      #   @!visibility protected
-      #
-      # @overload runner(klass)
-      #   Overwrite the default runner
-      #   @param klass [Class] A class like the {Runner}
-      #   @!visibility protected
-      def runner(klass = nil)
-        @config.for(:runner, klass) { Teckel::Operation::Runner }
-      end
-
-      # @overload result()
-      #   Get the configured result object class wrapping {error} or {output}.
-      #   The {ValueResult} default will act as a pass-through and does. Any error
-      #   or output will just returned as-is.
-      #   @return [Class] The +result+ class, or {ValueResult} as default
-      #
-      # @overload result(klass)
-      #   Set the result object class wrapping {error} or {output}.
-      #   @param klass [Class] The +result+ class
-      #   @return [Class] The +result+ class configured
-      def result(klass = nil)
-        @config.for(:result, klass) { const_defined?(:Result, false) ? self::Result : ValueResult }
-      end
-
-      # @overload result_constructor()
-      #   The callable constructor to build an instance of the +result+ class.
-      #   Defaults to {Teckel::DEFAULT_CONSTRUCTOR}
-      #   @return [Proc] A callable that will return an instance of +result+ class.
-      #
-      # @overload result_constructor(sym_or_proc)
-      #  Define how to build the +result+.
-      #  @param  sym_or_proc [Symbol, #call]
-      #    - Either a +Symbol+ representing the _public_ method to call on the +result+ class.
-      #    - Or anything that response to +#call+ (like a +Proc+).
-      #  @return [#call] The callable constructor
-      #
-      #  @example
-      #    class MyOperation
-      #      include Teckel::Operation
-      #
-      #      class Result
-      #        include Teckel::Result
-      #        def initialize(value, success, opts = {}); end
-      #      end
-      #
-      #      # If you need more control over how to build a new +Settings+ instance
-      #      result_constructor ->(value, success) { result.new(value, success, {foo: :bar}) }
-      #    end
-      def result_constructor(sym_or_proc = nil)
-        get_set_counstructor(:result_constructor, result, sym_or_proc) ||
-          raise(MissingConfigError, "Missing result_constructor config for #{self}")
-      end
-
-      # @!group Shortcuts
-
-      # Shortcut to use {Teckel::Operation::Result} as a result object,
-      # wrapping any {error} or {output}.
-      #
-      # @!visibility protected
-      # @note Don't use in conjunction with {result} or {result_constructor}
-      # @return [nil]
-      def result!
-        @config.for(:result, Teckel::Operation::Result)
-        @config.for(:result_constructor, Teckel::Operation::Result.method(:new))
-        nil
-      end
-
-      # Convenience method for setting {#input}, {#output} or {#error} to the
-      # {Teckel::Contracts::None} value.
-      # @return [Object] The {Teckel::Contracts::None} class.
-      #
-      # @example Enforcing nil input, output or error
-      #   class MyOperation
-      #     include Teckel::Operation
-      #
-      #     input none
-      #
-      #     # same as
-      #     output Teckel::Contracts::None
-      #
-      #     error none
-      #
-      #     def call(_) # you still need to take than +nil+ input when using `input none`
-      #       # when using `error none`:
-      #       # `fail!` works, but `fail!("data")` raises an error
-      #
-      #       # when using `output none`:
-      #       # `success!` works, but `success!("data")` raises an error
-      #       # same thing when using simple return values as success:
-      #       # take care to not return anything
-      #       nil
-      #     end
-      #   end
-      #
-      #   MyOperation.call #=> nil
-      def none
-        Teckel::Contracts::None
-      end
-
-      # @endgroup
+      # @!visibility private
+      UNDEFINED = Object.new
 
       # Invoke the Operation
       #
-      # @param input Any form of input your {#input} class can handle via the given {#input_constructor}
-      # @return Either An instance of your defined {#error} class or {#output} class
+      # @param input Any form of input your {Teckel::Operation::Config#input input} class can handle via the given
+      #   {Teckel::Operation::Config#input_constructor input_constructor}
+      # @return Either An instance of your defined {Teckel::Operation::Config#error error} class or
+      #   {Teckel::Operation::Config#output output} class
       # @!visibility public
       def call(input = nil)
-        runner.new(self).call(input)
+        runable.call(input)
       end
 
-      # Provide {InstanceMethods#settings() settings} to the running operation.
+      # Provide {InstanceMethods#settings() settings} to the operation.
       #
       # This method is intended to be called on the operation class outside of
-      # it's definition, prior to running {#call}.
+      # it's definition, prior to invoking {#call}.
       #
-      # @param input Any form of input your {#settings} class can handle via the given {#settings_constructor}
-      # @return [Class] The configured {runner}
+      # @param settings Any form of settings your {Teckel::Operation::Config#settings settings} class can handle via the given
+      #   {Teckel::Operation::Config#settings_constructor settings_constructor}
+      # @return [Class] The configured {Teckel::Operation::Config#runner runner}
       # @!visibility public
       #
       # @example Inject settings for an operation call
@@ -396,120 +108,107 @@ module Teckel
       #   MyOperation.with(false).call
       #   MyOperation.call
       #   LOG #=> []
-      def with(input)
-        runner.new(self, settings_constructor.call(input))
+      def with(settings)
+        runable(settings_constructor.call(settings))
       end
       alias :set :with
 
-      # @!visibility private
-      # @return [void]
-      def define!
-        %i[
-          input input_constructor
-          output output_constructor
-          error error_constructor
-          settings settings_constructor
-          result result_constructor
-          runner
-        ].each { |e| public_send(e) }
-        nil
-      end
-
-      # Disallow any further changes to this Operation.
-      # Make sure all configurations are set.
-      #
-      # @raise [MissingConfigError]
-      # @return [self] Frozen self
-      # @!visibility public
-      def finalize!
-        define!
-        @config.freeze
-        self
-      end
-
-      # Produces a shallow copy of this operation and all it's configuration.
+      # Constructs a Runner instance for {call} and {with}.
       #
-      # @return [self]
-      # @!visibility public
-      def dup
-        super.tap do |copy|
-          copy.instance_variable_set(:@config, @config.dup)
-        end
-      end
-
-      # Produces a clone of this operation and all it's configuration
+      # @note This method is public to make testing, stubbing and mocking easier.
+      #   Your normal application code should use {with} and/or {call}
       #
-      # @return [self]
+      # @param settings Optional. Any form of settings your
+      #   {Teckel::Operation::Config#settings settings} class can handle via the
+      #   given {Teckel::Operation::Config#settings_constructor settings_constructor}
+      # @return [Class] The configured {Teckel::Operation::Config#runner runner}
       # @!visibility public
-      def clone
-        if frozen?
-          super
+      def runable(settings = UNDEFINED)
+        if settings != UNDEFINED
+          runner.new(self, settings)
+        elsif default_settings
+          runner.new(self, default_settings.call)
         else
-          super.tap do |copy|
-            copy.instance_variable_set(:@config, @config.dup)
-          end
+          runner.new(self)
         end
       end
 
-      # @!visibility private
-      def inherited(subclass)
-        subclass.instance_variable_set(:@config, @config.dup)
-      end
-
-      # @!visibility private
-      def self.extended(base)
-        base.instance_exec do
-          @config = Config.new
-          attr_accessor :settings
-        end
-      end
-
-      private
-
-      def get_set_counstructor(name, on, sym_or_proc)
-        constructor = build_counstructor(on, sym_or_proc) unless sym_or_proc.nil?
-
-        @config.for(name, constructor) {
-          build_counstructor(on, Teckel::DEFAULT_CONSTRUCTOR)
-        }
-      end
-
-      def build_counstructor(on, sym_or_proc)
-        if sym_or_proc.is_a?(Symbol) && on.respond_to?(sym_or_proc)
-          on.public_method(sym_or_proc)
-        elsif sym_or_proc.respond_to?(:call)
-          sym_or_proc
-        end
+      # Convenience method for setting {Teckel::Operation::Config#input input},
+      # {Teckel::Operation::Config#output output} or
+      # {Teckel::Operation::Config#error error} to the
+      # {Teckel::Contracts::None} value.
+      #
+      # @return [Object] The {Teckel::Contracts::None} class.
+      #
+      # @example Enforcing nil input, output or error
+      #   class MyOperation
+      #     include Teckel::Operation
+      #
+      #     input none
+      #
+      #     # same as
+      #     output Teckel::Contracts::None
+      #
+      #     error none
+      #
+      #     def call(_) # you still need to take than +nil+ input when using `input none`
+      #       # when using `error none`:
+      #       # `fail!` works, but `fail!("data")` raises an error
+      #
+      #       # when using `output none`:
+      #       # `success!` works, but `success!("data")` raises an error
+      #     end
+      #   end
+      #
+      #   MyOperation.call #=> nil
+      def none
+        Contracts::None
       end
     end
 
     module InstanceMethods
+      # @!method call(input)
+      # @abstract
+      # @see Operation
+      # @see ClassMethods#call
+      #
+      # The entry point for your operation. It needs to always accept an input value, even when
+      # using +input none+.
+      # If your Operation expects to generate success or failure outputs, you need to use either
+      # {.success!} or {.fail!} respectively. Simple return values will get ignored by default. See
+      # {Teckel::Operation::Config#runner} and {Teckel::Operation::Runner} on how to overwrite.
+
       # @!attribute [r] settings()
       # @return [Class,nil] When executed with settings, an instance of the
       #   configured {.settings} class. Otherwise +nil+
       # @see ClassMethods#settings
       # @!visibility public
 
-      # Halt any further execution with a output value
+      # Delegates to the configured Runner.
+      # The default behavior is to halt any further execution with a output value.
       #
-      # @return a thing matching your {Operation::ClassMethods#output Operation#output} definition
+      # @see Teckel::Operation::Runner#success!
       # @!visibility protected
       def success!(*args)
-        throw :success, args
+        runner.success!(*args)
       end
 
-      # Halt any further execution with an error value
+      # Delegates to the configured Runner.
+      # The default behavior is to halt any further execution with an error value.
       #
-      # @return a thing matching your {Operation::ClassMethods#error Operation#error} definition
+      # @see Teckel::Operation::Runner#fail!
       # @!visibility protected
       def fail!(*args)
-        throw :failure, args
+        runner.fail!(*args)
       end
     end
 
     def self.included(receiver)
-      receiver.extend         ClassMethods
-      receiver.send :include, InstanceMethods
+      receiver.class_eval do
+        extend  Config
+        extend  ClassMethods
+        include InstanceMethods
+      end
     end
   end
 end