teckel 0.1.0 → 0.2.0

data/lib/teckel/config.rb

@@ -2,10 +2,22 @@
 
 module Teckel
   class Config
-    class FrozenConfigError < Teckel::Error; end
-
     @default_constructor = :[]
     class << self
+      # @!attribute [r] default_constructor()
+      # The default constructor method for +input+, +output+ and +error+ class (default: +:[]+)
+      # @return [Class] The Output class
+
+      # @!method default_constructor(sym_or_proc)
+      # Set the default constructor method for +input+, +output+ and +error+ class
+      #
+      # defaults to +:[]+
+      #
+      # @param sym_or_proc [Symbol,#call] The method name on the +input+,
+      #   +output+ and +error+ class or a callable which accepts the
+      #   +input+, +output+ or +error+
+      #
+      # @return [Symbol,#call]
       def default_constructor(sym_or_proc = nil)
         return @default_constructor if sym_or_proc.nil?
 
@@ -13,57 +25,37 @@ module Teckel
       end
     end
 
+    # @!visibility private
     def initialize
-      @input_class = nil
-      @input_constructor = nil
-
-      @output_class = nil
-      @output_constructor = nil
-
-      @error_class = nil
-      @error_constructor = nil
-    end
-
-    def input(klass = nil)
-      return @input_class if klass.nil?
-      raise FrozenConfigError unless @input_class.nil?
-
-      @input_class = klass
-    end
-
-    def input_constructor(sym_or_proc = nil)
-      return (@input_constructor || self.class.default_constructor) if sym_or_proc.nil?
-      raise FrozenConfigError unless @input_constructor.nil?
-
-      @input_constructor = sym_or_proc
-    end
-
-    def output(klass = nil)
-      return @output_class if klass.nil?
-      raise FrozenConfigError unless @output_class.nil?
-
-      @output_class = klass
-    end
-
-    def output_constructor(sym_or_proc = nil)
-      return (@output_constructor || self.class.default_constructor) if sym_or_proc.nil?
-      raise FrozenConfigError unless @output_constructor.nil?
-
-      @output_constructor = sym_or_proc
+      @config = {}
+    end
+
+    # @!visibility private
+    def for(key, value = nil, &block)
+      if value.nil?
+        if block
+          @config[key] ||= @config.fetch(key, &block)
+        else
+          @config[key]
+        end
+      elsif @config.key?(key)
+        raise FrozenConfigError, "Configuration #{key} is already set"
+      else
+        @config[key] = value
+      end
     end
 
-    def error(klass = nil)
-      return @error_class if klass.nil?
-      raise FrozenConfigError unless @error_class.nil?
-
-      @error_class = klass
+    # @!visibility private
+    def freeze
+      @config.freeze
+      super
     end
 
-    def error_constructor(sym_or_proc = nil)
-      return (@error_constructor || self.class.default_constructor) if sym_or_proc.nil?
-      raise FrozenConfigError unless @error_constructor.nil?
-
-      @error_constructor = sym_or_proc
+    # @!visibility private
+    def dup
+      super.tap do |copy|
+        copy.instance_variable_set(:@config, @config.dup)
+      end
     end
   end
 end

data/lib/teckel/none.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Teckel
+  # Simple type object for enforcing +input+, +output+ or +error+ data to be
+  # not set (or +nil+)
+  class None
+    class << self
+      # Always return nil
+      # @return nil
+      # @raise [ArgumentError] when called with any non-nil arguments
+      def [](*args)
+        raise ArgumentError, "None called with arguments" if args.any?(&:itself)
+      end
+
+      alias :new :[]
+    end
+  end
+end

data/lib/teckel/operation.rb

@@ -9,10 +9,14 @@ module Teckel
   # the constants +Input+, +Output+ and +Error+, the second way is to use the
   # +input+. +output+ and +error+ methods to point them to anonymous classes.
   #
-  # If you like "traditional" result objects (to ask +successful?+ or +failure?+ on)
-  # see +Teckel::Operation::Results+
+  # If you like "traditional" result objects to ask +successful?+ or +failure?+ on,
+  # see {Teckel::Operation::Results Teckel::Operation::Results}
   #
-  # @see Teckel::Operation::Results
+  # 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.
   #
   # @example class definitions via constants
   #   class CreateUserViaConstants
@@ -38,13 +42,13 @@ module Teckel
   #     error_constructor :new
   #
   #     # @param [CreateUser::Input]
-  #     # @return [User | CreateUser::Error]
+  #     # @return [User,CreateUser::Error]
   #     def call(input)
   #       user = ::User.new(name: input.name, age: input.age)
-  #       if user.safe
+  #       if user.save
   #         user
   #       else
-  #         fail!(message: "Could not safe User", errors: user.errors)
+  #         fail!(message: "Could not save User", errors: user.errors)
   #       end
   #     end
   #   end
@@ -60,14 +64,13 @@ module Teckel
   #     error  Types::Hash.schema(message: Types::String, errors: Types::Array.of(Types::Hash))
   #
   #     # @param [Hash<name: String, age: Integer>]
-  #     # @return [User | Hash<message: String, errors: [Hash]>]
+  #     # @return [User,Hash<message: String, errors: [Hash]>]
   #     def call(input)
   #       user = User.new(name: input[:name], age: input[:age])
-  #       if user.safe
-  #         # exits early with success, prevents any further execution
-  #         success!(user)
+  #       if user.save
+  #         success!(user) # exits early with success, prevents any further execution
   #       else
-  #         fail!(message: "Could not safe User", errors: user.errors)
+  #         fail!(message: "Could not save User", errors: user.errors)
   #       end
   #     end
   #   end
@@ -76,7 +79,7 @@ module Teckel
   #   CreateUserViaMethods.call(name: "Bob", age: 23).is_a?(User) #=> true
   #
   #   # A failure call:
-  #   CreateUserViaMethods.call(name: "Bob", age: 10).eql?(message: "Could not safe User", errors: [{age: "underage"}]) #=> true
+  #   CreateUserViaMethods.call(name: "Bob", age: 10).eql?(message: "Could not save User", errors: [{age: "underage"}]) #=> true
   #
   #   # Build your Input, Output and Error classes in a way that let you know:
   #   begin; CreateUserViaMethods.call(unwanted: "input"); rescue => e; e end.is_a?(::Dry::Types::MissingKeyError) #=> true
@@ -84,8 +87,54 @@ module Teckel
   #   # Feed an instance of the input class directly to call:
   #   CreateUserViaMethods.call(CreateUserViaMethods.input[name: "Bob", age: 23]).is_a?(User) #=> true
   #
-  # @api public
+  # @!visibility public
   module Operation
+    # The default implementation for executing a single {Operation}
+    #
+    # @!visibility protected
+    class Runner
+      # @!visibility private
+      UNDEFINED = Object.new.freeze
+
+      def initialize(operation)
+        @operation = operation
+      end
+      attr_reader :operation
+
+      def call(input)
+        err = catch(:failure) do
+          simple_return = UNDEFINED
+          out = catch(:success) do
+            simple_return = @operation.new.call(build_input(input))
+          end
+          return simple_return == UNDEFINED ? build_output(*out) : build_output(simple_return)
+        end
+        build_error(*err)
+      end
+
+      private
+
+      def build_input(input)
+        operation.input_constructor.call(input)
+      end
+
+      def build_output(*args)
+        if args.size == 1 && operation.output === args.first # rubocop:disable Style/CaseEquality
+          args.first
+        else
+          operation.output_constructor.call(*args)
+        end
+      end
+
+      def build_error(*args)
+        if args.size == 1 && operation.error === args.first # rubocop:disable Style/CaseEquality
+          args.first
+        else
+          operation.error_constructor.call(*args)
+        end
+      end
+    end
+
     module ClassMethods
       # @!attribute [r] input()
       # Get the configured class wrapping the input data structure.
@@ -96,11 +145,8 @@ module Teckel
       # @param  klass [Class] The +input+ class
       # @return [Class] The +input+ class
       def input(klass = nil)
-        return @input_class if @input_class
-
-        @input_class = @config.input(klass)
-        @input_class ||= self::Input if const_defined?(:Input)
-        @input_class
+        @config.for(:input, klass) { self::Input if const_defined?(:Input) } ||
+          raise(Teckel::MissingConfigError, "Missing input config for #{self}")
       end
 
       # @!attribute [r] input_constructor()
@@ -109,9 +155,9 @@ module Teckel
 
       # @!method input_constructor(sym_or_proc)
       # Define how to build the +input+.
-      # @param  sym_or_proc [Symbol|#call]
+      # @param  sym_or_proc [Symbol, #call]
       #   - Either a +Symbol+ representing the _public_ method to call on the +input+ class.
-      #   - Or a callable (like a +Proc+).
+      #   - Or anything that response to +#call+ (like a +Proc+).
       # @return [#call] The callable constructor
       #
       # @example simple symbol to method constructor
@@ -119,7 +165,7 @@ module Teckel
       #     include Teckel::Operation
       #
       #     class Input
-      #       # ...
+      #       def initialize(name:, age:); end
       #     end
       #
       #     # If you need more control over how to build a new +Input+ instance
@@ -134,7 +180,7 @@ module Teckel
       #     include Teckel::Operation
       #
       #     class Input
-      #       # ...
+      #       def initialize(*args, **opts); end
       #     end
       #
       #     # If you need more control over how to build a new +Input+ instance
@@ -143,16 +189,9 @@ module Teckel
       #   end
       #
       #   MyOperation.input_constructor.is_a?(Proc) #=> true
-      def input_constructor(sym_or_proc = nil)
-        return @input_constructor if @input_constructor
-
-        constructor = @config.input_constructor(sym_or_proc)
-        @input_constructor =
-          if constructor.is_a?(Symbol) && input.respond_to?(constructor)
-            input.public_method(constructor)
-          elsif sym_or_proc.respond_to?(:call)
-            sym_or_proc
-          end
+      def input_constructor(sym_or_proc = Config.default_constructor)
+        @config.for(:input_constructor) { build_counstructor(input, sym_or_proc) } ||
+          raise(MissingConfigError, "Missing input_constructor config for #{self}")
       end
 
       # @!attribute [r] output()
@@ -164,11 +203,8 @@ module Teckel
       # @param  klass [Class] The +output+ class
       # @return [Class] The +output+ class
       def output(klass = nil)
-        return @output_class if @output_class
-
-        @output_class = @config.output(klass)
-        @output_class ||= self::Output if const_defined?(:Output)
-        @output_class
+        @config.for(:output, klass) { self::Output if const_defined?(:Output) } ||
+          raise(Teckel::MissingConfigError, "Missing output config for #{self}")
       end
 
       # @!attribute [r] output_constructor()
@@ -177,9 +213,9 @@ module Teckel
 
       # @!method output_constructor(sym_or_proc)
       # Define how to build the +output+.
-      # @param  sym_or_proc [Symbol|#call]
+      # @param  sym_or_proc [Symbol, #call]
       #   - Either a +Symbol+ representing the _public_ method to call on the +output+ class.
-      #   - Or a callable (like a +Proc+).
+      #   - Or anything that response to +#call+ (like a +Proc+).
       # @return [#call] The callable constructor
       #
       # @example
@@ -187,7 +223,7 @@ module Teckel
       #     include Teckel::Operation
       #
       #     class Output
-      #       # ....
+      #       def initialize(*args, **opts); end
       #     end
       #
       #     # MyOperation.call("foo", "bar") # -> Output.new("foo", "bar")
@@ -197,16 +233,9 @@ module Teckel
       #     # 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)
-        return @output_constructor if @output_constructor
-
-        constructor = @config.output_constructor(sym_or_proc)
-        @output_constructor =
-          if constructor.is_a?(Symbol) && output.respond_to?(constructor)
-            output.public_method(constructor)
-          elsif sym_or_proc.respond_to?(:call)
-            sym_or_proc
-          end
+      def output_constructor(sym_or_proc = Config.default_constructor)
+        @config.for(:output_constructor) { build_counstructor(output, sym_or_proc) } ||
+          raise(MissingConfigError, "Missing output_constructor config for #{self}")
       end
 
       # @!attribute [r] error()
@@ -216,13 +245,10 @@ module Teckel
       # @!method error(klass)
       # Set the class wrapping the error data structure.
       # @param  klass [Class] The +error+ class
-      # @return [Class] The +error+ class
+      # @return [Class,nil] The +error+ class or +nil+ if it does not error
       def error(klass = nil)
-        return @error_class if @error_class
-
-        @error_class = @config.error(klass)
-        @error_class ||= self::Error if const_defined?(:Error)
-        @error_class
+        @config.for(:error, klass) { self::Error if const_defined?(:Error) } ||
+          raise(Teckel::MissingConfigError, "Missing error config for #{self}")
       end
 
       # @!attribute [r] error_constructor()
@@ -231,9 +257,9 @@ module Teckel
 
       # @!method error_constructor(sym_or_proc)
       # Define how to build the +error+.
-      # @param  sym_or_proc [Symbol|#call]
+      # @param  sym_or_proc [Symbol, #call]
       #   - Either a +Symbol+ representing the _public_ method to call on the +error+ class.
-      #   - Or a callable (like a +Proc+).
+      #   - Or anything that response to +#call+ (like a +Proc+).
       # @return [#call] The callable constructor
       #
       # @example
@@ -241,7 +267,7 @@ module Teckel
       #     include Teckel::Operation
       #
       #     class Error
-      #       # ....
+      #       def initialize(*args, **opts); end
       #     end
       #
       #     # MyOperation.call("foo", "bar") # -> Error.new("foo", "bar")
@@ -251,72 +277,126 @@ module Teckel
       #     # 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)
-        return @error_constructor if @error_constructor
-
-        constructor = @config.error_constructor(sym_or_proc)
-        @error_constructor =
-          if constructor.is_a?(Symbol) && error.respond_to?(constructor)
-            error.public_method(constructor)
-          elsif sym_or_proc.respond_to?(:call)
-            sym_or_proc
-          end
+      def error_constructor(sym_or_proc = Config.default_constructor)
+        @config.for(:error_constructor) { build_counstructor(error, sym_or_proc) } ||
+          raise(MissingConfigError, "Missing error_constructor config for #{self}")
       end
 
-      # Invoke the Operation
+      # Convenience method for setting {#input}, {#output} or {#error} to the {None} value.
+      # @return [None]
+      # @example Enforcing nil input, output or error
+      #   class MyOperation
+      #     include Teckel::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
-      def call(input)
-        new.call!(input)
+      #     input none
+      #
+      #     # same as
+      #     output Teckel::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
+        None
       end
-    end
 
-    module InstanceMethods
+      # @!attribute [r] runner()
+      # @return [Class] The Runner class
       # @!visibility protected
-      def call!(input)
-        catch(:failure) do
-          out = catch(:success) do
-            simple_ret = call(build_input(input))
-            build_output(simple_ret)
-          end
-          return out
-        end
-      end
 
+      # Overwrite the default runner
+      # @param klass [Class] A class like the {Runner}
       # @!visibility protected
-      def success!(*args)
-        throw :success, build_output(*args)
+      def runner(klass = nil)
+        @config.for(:runner, klass) { Runner }
       end
 
-      # @!visibility protected
-      def fail!(*args)
-        throw :failure, build_error(*args)
+      # 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
+      # @!visibility public
+      def call(input = nil)
+        runner.new(self).call(input)
       end
 
-      private
+      # @!visibility private
+      # @return [nil]
+      def define!
+        %i[input input_constructor output output_constructor error error_constructor runner].each { |e|
+          public_send(e)
+        }
+        nil
+      end
 
-      def build_input(input)
-        self.class.input_constructor.call(input)
+      # Disallow any further changes to this Operation.
+      # Make sure all configurations are set.
+      #
+      # @raise [MissingConfigError]
+      # @return [self] Frozen self
+      # @!visibility public
+      def finalize!
+        define!
+        freeze
+        @config.freeze
+        self
       end
 
-      def build_output(*args)
-        if args.size == 1 && self.class.output === args.first # rubocop:disable Style/CaseEquality
-          args.first
-        else
-          self.class.output_constructor.call(*args)
+      # @!visibility public
+      def dup
+        super.tap do |copy|
+          copy.instance_variable_set(:@config, @config.dup)
         end
       end
 
-      def build_error(*args)
-        if args.size == 1 && self.class.error === args.first # rubocop:disable Style/CaseEquality
-          args.first
+      # @!visibility public
+      def clone
+        if frozen?
+          super
         else
-          self.class.error_constructor.call(*args)
+          super.tap do |copy|
+            copy.instance_variable_set(:@config, @config.dup)
+          end
+        end
+      end
+
+      private
+
+      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
       end
     end
 
+    module InstanceMethods
+      # Halt any further execution with a +output+ value
+      # @!visibility protected
+      def success!(*args)
+        throw :success, args
+      end
+
+      # Halt any further execution with an +error+ value
+      # @!visibility protected
+      def fail!(*args)
+        throw :failure, args
+      end
+    end
+
     def self.included(receiver)
       receiver.extend         ClassMethods
       receiver.send :include, InstanceMethods
@@ -324,14 +404,7 @@ module Teckel
       receiver.class_eval do
         @config = Config.new
 
-        @input_class = nil
-        @input_constructor = nil
-
-        @output_class = nil
-        @output_constructor = nil
-
-        @error_class = nil
-        @error_constructor = nil
+        @runner = Runner
 
         protected :success!, :fail!
       end