teckel 0.1.0 → 0.6.0

data/lib/teckel/contracts.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Teckel
+  module Contracts
+    # Simple contract for enforcing data to be not set or +nil+
+    module 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
+end

data/lib/teckel/operation.rb

@@ -1,5 +1,9 @@
 # frozen_string_literal: true
 
+require_relative "operation/config"
+require_relative "operation/result"
+require_relative "operation/runner"
+
 module Teckel
   # The main operation Mixin
   #
@@ -9,47 +13,15 @@ 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+
-  #
-  # @see Teckel::Operation::Results
-  #
-  # @example class definitions via constants
-  #   class CreateUserViaConstants
-  #     include Teckel::Operation
-  #
-  #     class Input
-  #       def initialize(name:, age:)
-  #         @name, @age = name, age
-  #       end
-  #       attr_reader :name, :age
-  #     end
-  #
-  #     Output = ::User
-  #
-  #     class Error
-  #       def initialize(message, errors)
-  #         @message, @errors = message, errors
-  #       end
-  #       attr_reader :message, :errors
-  #     end
-  #
-  #     input_constructor :new
-  #     error_constructor :new
+  # If you like "traditional" result objects to ask +successful?+ or +failure?+ on,
+  # use {Teckel::Operation::Config#result! result!} and get {Teckel::Operation::Result}
   #
-  #     # @param [CreateUser::Input]
-  #     # @return [User | CreateUser::Error]
-  #     def call(input)
-  #       user = ::User.new(name: input.name, age: input.age)
-  #       if user.safe
-  #         user
-  #       else
-  #         fail!(message: "Could not safe User", errors: user.errors)
-  #       end
-  #     end
-  #   end
+  # By default, +input+. +output+ and +error+ classes are build using +:[]+
+  # (eg: +Input[some: :param]+).
   #
-  #   CreateUserViaConstants.call(name: "Bob", age: 23).is_a?(User) #=> true
+  # 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
@@ -60,14 +32,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 +47,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,257 +55,141 @@ 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
     module ClassMethods
-      # @!attribute [r] input()
-      # Get the configured class wrapping the input data structure.
-      # @return [Class] The +input+ class
-
-      # @!method 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)
-        return @input_class if @input_class
+      # Invoke the Operation
+      #
+      # @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)
+        default_settings = self.default_settings
 
-        @input_class = @config.input(klass)
-        @input_class ||= self::Input if const_defined?(:Input)
-        @input_class
+        if default_settings
+          runner.new(self, default_settings.call)
+        else
+          runner.new(self)
+        end.call(input)
       end
 
-      # @!attribute [r] input_constructor()
-      # The callable constructor to build an instance of the +input+ class.
-      # @return [Class] The Input class
-
-      # @!method 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 a callable (like a +Proc+).
-      # @return [#call] The callable constructor
-      #
-      # @example simple symbol to method constructor
-      #   class MyOperation
-      #     include Teckel::Operation
+      # Provide {InstanceMethods#settings() settings} to the running operation.
       #
-      #     class Input
-      #       # ...
-      #     end
+      # This method is intended to be called on the operation class outside of
+      # it's definition, prior to running {#call}.
       #
-      #     # 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
+      # @param input Any form of input 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
       #
-      #   MyOperation.input_constructor.is_a?(Method) #=> true
+      # @example Inject settings for an operation call
+      #   LOG = []
       #
-      # @example Custom Proc constructor
       #   class MyOperation
-      #     include Teckel::Operation
+      #     include ::Teckel::Operation
       #
-      #     class Input
-      #       # ...
-      #     end
+      #     settings Struct.new(:log)
+      #
+      #     input none
+      #     output none
+      #     error none
       #
-      #     # 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) }
+      #     def call(_input)
+      #       settings.log << "called" if settings&.log
+      #       nil
+      #     end
       #   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
-      end
-
-      # @!attribute [r] output()
-      # Get the configured class wrapping the output data structure.
-      # @return [Class] The +output+ class
-
-      # @!method 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)
-        return @output_class if @output_class
-
-        @output_class = @config.output(klass)
-        @output_class ||= self::Output if const_defined?(:Output)
-        @output_class
+      #   MyOperation.with(LOG).call
+      #   LOG #=> ["called"]
+      #
+      #   LOG.clear
+      #
+      #   MyOperation.with(false).call
+      #   MyOperation.call
+      #   LOG #=> []
+      def with(input)
+        runner.new(self, settings_constructor.call(input))
       end
+      alias :set :with
 
-      # @!attribute [r] output_constructor()
-      # The callable constructor to build an instance of the +output+ class.
-      # @return [Class] The Output class
-
-      # @!method 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 a callable (like a +Proc+).
-      # @return [#call] The callable constructor
+      # 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.
       #
-      # @example
+      # @return [Object] The {Teckel::Contracts::None} class.
+      #
+      # @example Enforcing nil input, output or error
       #   class MyOperation
       #     include Teckel::Operation
       #
-      #     class Output
-      #       # ....
-      #     end
+      #     input none
       #
-      #     # MyOperation.call("foo", "bar") # -> Output.new("foo", "bar")
-      #     output_constructor :new
+      #     # same as
+      #     output Teckel::Contracts::None
       #
-      #     # 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)
-        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
-      end
-
-      # @!attribute [r] error()
-      # Get the configured class wrapping the error data structure.
-      # @return [Class] The +error+ class
-
-      # @!method error(klass)
-      # Set the class wrapping the error data structure.
-      # @param  klass [Class] The +error+ class
-      # @return [Class] The +error+ class
-      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
-      end
-
-      # @!attribute [r] error_constructor()
-      # The callable constructor to build an instance of the +error+ class.
-      # @return [Class] The Error class
-
-      # @!method 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 a callable (like a +Proc+).
-      # @return [#call] The callable constructor
+      #     error none
       #
-      # @example
-      #   class MyOperation
-      #     include Teckel::Operation
+      #     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
       #
-      #     class Error
-      #       # ....
+      #       # when using `output none`:
+      #       # `success!` works, but `success!("data")` raises an error
       #     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)
-        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
-      end
-
-      # 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
-      def call(input)
-        new.call!(input)
+      #   MyOperation.call #=> nil
+      def none
+        Teckel::Contracts::None
       end
     end
 
     module InstanceMethods
-      # @!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
-
+      # @!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
+
+      # Delegates to the configured Runner.
+      # The default behavior is to halt any further execution with a output value.
+      #
+      # @see Teckel::Operation::Runner#success!
       # @!visibility protected
       def success!(*args)
-        throw :success, build_output(*args)
+        runner.success!(*args)
       end
 
+      # Delegates to the configured Runner.
+      # The default behavior is to halt any further execution with an error value.
+      #
+      # @see Teckel::Operation::Runner#fail!
       # @!visibility protected
       def fail!(*args)
-        throw :failure, build_error(*args)
-      end
-
-      private
-
-      def build_input(input)
-        self.class.input_constructor.call(input)
-      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)
-        end
-      end
-
-      def build_error(*args)
-        if args.size == 1 && self.class.error === args.first # rubocop:disable Style/CaseEquality
-          args.first
-        else
-          self.class.error_constructor.call(*args)
-        end
+        runner.fail!(*args)
       end
     end
 
     def self.included(receiver)
+      receiver.extend         Config
       receiver.extend         ClassMethods
       receiver.send :include, InstanceMethods
-
-      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
-
-        protected :success!, :fail!
-      end
     end
   end
 end