flows 0.2.0 → 0.6.0

data/lib/flows/flow/router/simple.rb

@@ -0,0 +1,25 @@
+module Flows
+  class Flow
+    class Router
+      # Router with static paths for successful and failure results.
+      class Simple < Router
+        # @param success_route [Symbol] route for any successful results.
+        # @param failure_route [Symbol] route for any failure results.
+        def initialize(success_route, failure_route)
+          @success_route = success_route
+          @failure_route = failure_route
+        end
+
+        # @see Flows::Flow::Router#call
+        def call(result)
+          result.ok? ? @success_route : @failure_route
+        end
+
+        # @see Flows::Flow::Router#destinations
+        def destinations
+          [@success_route, @failure_route]
+        end
+      end
+    end
+  end
+end

data/lib/flows/plugin.rb

@@ -0,0 +1,15 @@
+module Flows
+  # Namespace for class behaviour extensions.
+  #
+  # Feel free to use it to empower your abstractions.
+  #
+  # @since 0.4.0
+  module Plugin
+  end
+end
+
+require_relative 'plugin/dependency_injector'
+require_relative 'plugin/implicit_init'
+require_relative 'plugin/output_contract'
+require_relative 'plugin/profiler'
+require_relative 'plugin/interface'

data/lib/flows/plugin/dependency_injector.rb

@@ -0,0 +1,170 @@
+require_relative 'dependency_injector/errors'
+require_relative 'dependency_injector/dependency'
+require_relative 'dependency_injector/dependency_definition'
+require_relative 'dependency_injector/dependency_list'
+
+module Flows
+  module Plugin
+    # Allows to inject dependencies on the initialization step.
+    #
+    # After including this module you inject dependencies by providing `:dependencies` key
+    # to your initializer:
+    #
+    #     x = MyClass.new(dependencies: { my_dep: -> { 'Hi' } })
+    #     x.my_dep
+    #     # => 'Hi'
+    #
+    # Keys are dependency names. Dependency will be injected as
+    # a public method with dependency name. Values are dependencies itself.
+    #
+    # You can also require some dependencies to be present.
+    # If required dependency is missed - {MissingDependencyError} will be raised.
+    #
+    # If an optional dependency has no default - {MissingDependencyDefaultError} will be raised.
+    #
+    # For an optional dependency default value must be provided.
+    #
+    # You can provide a type for the dependency.
+    # Type check uses case equality (`===`).
+    # So, it works like Ruby's `case`.
+    # In case of type mismatch {UnexpectedDependencyTypeError} will be raised.
+    #
+    #     dependency :name, type: String # name should be a string
+    #
+    #     # by the way, you can use lambdas like in Ruby's `case`
+    #     dependency :age, type: ->(x) { x.is_a?(Number) && x > 0 && x < 100 }
+    #
+    # If you're trying to inject undeclared dependency - {UnexpectedDependencyError} will be raised.
+    #
+    # Inheritance is supported and dependency definitions will be inherited into child classes.
+    #
+    # @example
+    #
+    #     class MyClass
+    #       include Flows::Plugin::DependencyInjector
+    #
+    #       dependency :logger, required: true
+    #       dependency :name, default: 'Boris', type: String # by default dependency is optional.
+    #
+    #       attr_reader :data
+    #
+    #       def initializer(data)
+    #         @data = data
+    #       end
+    #
+    #       def log_the_name
+    #         logger.call(name)
+    #       end
+    #     end
+    #
+    #     class Logger
+    #       def self.call(msg)
+    #         puts msg
+    #       end
+    #     end
+    #
+    #     x = MyClass.new('DATA', dependencies: {
+    #       logger: Logger
+    #     })
+    #
+    #     x.data
+    #     # => 'DATA'
+    #
+    #     x.name
+    #     # => 'Boris'
+    #
+    #     x.logger.call('Hello')
+    #     # prints 'Hello'
+    #
+    #     x.log_the_name
+    #     # prints 'Boris'
+    module DependencyInjector
+      # Placeholder for empty type. We cannot use `nil` because value can be `nil`.
+      NO_TYPE = :__no_type__
+
+      # Placeholder for empty default. We cannot use `nil` because value can be `nil`.
+      NO_DEFAULT = :__no_default__
+
+      # Placeholder for empty value. We cannot use `nil` because value can be `nil`.
+      NO_VALUE = :__no_value__
+
+      SingletonVarsSetup = Flows::Util::InheritableSingletonVars::DupStrategy.make_module(
+        '@dependencies' => {}
+      )
+
+      include SingletonVarsSetup
+
+      # @api private
+      module DSL
+        attr_reader :dependencies
+
+        # `:reek:BooleanParameter` disabled here because it's not applicable for DSLs
+        def dependency(name, required: false, default: NO_DEFAULT, type: NO_TYPE)
+          dependencies[name] = DependencyDefinition.new(
+            name: name,
+            required: required,
+            default: default,
+            type: type,
+            klass: self
+          )
+        end
+      end
+
+      # @api private
+      #
+      # `:reek:UtilityFunction` and `:reek:FeatureEnvy` are disabled here because Reek does not
+      # know about inheritance callback stuff.
+      module InheritanceCallback
+        def included(mod)
+          mod.extend(DSL)
+
+          mod.singleton_class.prepend(InheritanceCallback) if mod.class == Module
+
+          super
+        end
+
+        def extended(mod)
+          mod.extend(DSL)
+
+          mod.singleton_class.prepend(InheritanceCallback) if mod.class == Module
+
+          super
+        end
+      end
+
+      singleton_class.prepend InheritanceCallback
+
+      InitializerWrapper = Util::PrependToClass.make_module do
+        def initialize(*args, **kwargs, &block) # rubocop:disable Metrics/MethodLength
+          if @__dependencies_injected__
+            if kwargs.empty? # https://bugs.ruby-lang.org/issues/14415
+              super(*args, &block)
+            else
+              super(*args, **kwargs, &block)
+            end
+
+            return
+          end
+          @__dependencies_injected__ = true
+
+          klass = self.class
+          DependencyList.new(
+            klass: klass,
+            definitions: klass.dependencies,
+            provided_values: kwargs[:dependencies].dup || {}
+          ).inject_to(self)
+
+          filtered_kwargs = kwargs.reject { |key, _| key == :dependencies }
+
+          if filtered_kwargs.empty? # https://bugs.ruby-lang.org/issues/14415
+            super(*args, &block)
+          else
+            super(*args, **filtered_kwargs, &block)
+          end
+        end
+      end
+
+      include InitializerWrapper
+    end
+  end
+end

data/lib/flows/plugin/dependency_injector/dependency.rb

@@ -0,0 +1,24 @@
+module Flows
+  module Plugin
+    module DependencyInjector
+      # Resolves dependency on initialization and can inject it into class instance.
+      #
+      # @api private
+      Dependency = Struct.new(:name, :definition, :provided_value, :value, :klass, keyword_init: true) do
+        def initialize(*)
+          super
+
+          self.value = provided_value == NO_VALUE ? definition.default : provided_value
+          type = definition.type
+
+          raise UnexpectedDependencyTypeError.new(klass, name, value, type) if type != NO_TYPE && !(type === value) # rubocop:disable Style/CaseEquality
+        end
+
+        def inject_to(instance)
+          value = self.value
+          instance.define_singleton_method(name) { value }
+        end
+      end
+    end
+  end
+end

data/lib/flows/plugin/dependency_injector/dependency_definition.rb

@@ -0,0 +1,16 @@
+module Flows
+  module Plugin
+    module DependencyInjector
+      # Struct for storing dependency definitions.
+      #
+      # @api private
+      DependencyDefinition = Struct.new(:name, :required, :default, :type, :klass, keyword_init: true) do
+        def initialize(*)
+          super
+
+          raise MissingDependencyDefaultError.new(klass, name) if !required && (default == NO_DEFAULT)
+        end
+      end
+    end
+  end
+end

data/lib/flows/plugin/dependency_injector/dependency_list.rb

@@ -0,0 +1,55 @@
+module Flows
+  module Plugin
+    module DependencyInjector
+      # Resolves dependencies on initialization and can inject it into class instance.
+      #
+      # @api private
+      class DependencyList
+        attr_reader :definitions, :provided_values, :dependencies
+
+        def initialize(klass:, definitions:, provided_values:)
+          @klass = klass
+          @definitions = definitions
+          @provided_values = provided_values.dup.tap { |pv| pv.default = NO_VALUE }
+
+          check_missing_dependencies
+          check_unexpected_dependencies
+          resolve_dependencies
+        end
+
+        def inject_to(instance)
+          dependencies.each { |dep| dep.inject_to(instance) }
+        end
+
+        private
+
+        def required_dependencies
+          definitions.select { |_, definition| definition.required }.keys
+        end
+
+        def check_missing_dependencies
+          missing = required_dependencies - provided_values.keys
+
+          raise MissingDependencyError.new(@klass, missing) if missing.any?
+        end
+
+        def check_unexpected_dependencies
+          unexpected = provided_values.keys - definitions.keys
+
+          raise UnexpectedDependencyError.new(@klass, unexpected) if unexpected.any?
+        end
+
+        def resolve_dependencies
+          @dependencies = definitions.map do |name, definition|
+            Dependency.new(
+              klass: @klass,
+              name: name,
+              definition: definition,
+              provided_value: provided_values[name]
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/flows/plugin/dependency_injector/errors.rb

@@ -0,0 +1,58 @@
+module Flows
+  module Plugin
+    module DependencyInjector
+      # Base error class for dependency injection errors.
+      class Error < ::Flows::Error; end
+
+      # Raised when you're missed some dependency.
+      class MissingDependencyError < Error
+        def initialize(klass, names)
+          @klass = klass
+          @names = names
+        end
+
+        def message
+          "Missing dependency(ies) for #{@klass}: #{@names.map(&:to_s).join(', ')}"
+        end
+      end
+
+      # Raised when you're providing undeclared dependency.
+      class UnexpectedDependencyError < Error
+        def initialize(klass, names)
+          @klass = klass
+          @names = names
+        end
+
+        def message
+          "Unexpected dependency(ies) for #{@klass}: #{@names.map(&:to_s).join(', ')}"
+        end
+      end
+
+      # Raised when dependency has unexpected type.
+      class UnexpectedDependencyTypeError < Error
+        def initialize(klass, name, value, type)
+          @klass = klass
+          @_name = name
+          @value = value
+          @_type = type
+        end
+
+        def message
+          "#{@_name} dependency for #{@klass} has wrong type, must conform `#{@_type.inspect}`: `#{@value.inspect}`"
+        end
+      end
+
+      # Raised when an optional dependency has no default value.
+      class MissingDependencyDefaultError < Error
+        def initialize(klass, name)
+          @klass = klass
+          @_name = name
+        end
+
+        def message
+          "Optional dependency #{@_name} for #{@klass} has no default value"
+        end
+      end
+    end
+  end
+end

data/lib/flows/plugin/implicit_init.rb

@@ -0,0 +1,45 @@
+module Flows
+  module Plugin
+    # Class extension with method `MyClass.call` which works like `MyClass.new.call`.
+    #
+    # @note This module must be injected into target class using `extend`, not `include`.
+    #
+    # @note Class inheritance is supported: each child class will inherit behaviour, but not data.
+    #
+    # @example Extending a class
+    #   class SomeClass
+    #     extend Flows::Plugin::ImplicitInit
+    #
+    #     def initialize(param: 'default')
+    #       @param = param
+    #     end
+    #
+    #     def call
+    #       @param
+    #     end
+    #   end
+    #
+    #   SomeClass.call
+    #   # => 'default'
+    #
+    #   SomeClass.default_instance.call
+    #   # => 'default'
+    # @since 0.4.0
+    module ImplicitInit
+      # Contains memoized instance of a host class or `nil`.
+      attr_reader :default_instance
+
+      # Creates an instance of a host class by calling `new` without arguments and
+      # calls `#call` method on the instance with provided parameters and block.
+      #
+      # After first invocation the instance will be memoized in {.default_instance}.
+      #
+      # Child classes have separate default instances.
+      def call(*args, **kwargs, &block)
+        @default_instance ||= new
+
+        default_instance.call(*args, **kwargs, &block)
+      end
+    end
+  end
+end

data/lib/flows/plugin/interface.rb

@@ -0,0 +1,84 @@
+module Flows
+  module Plugin
+    # Class extension to define Java/C#-like interfaces in Ruby.
+    #
+    # On target class initialization will check defined methods for existence.
+    #
+    # **Currently interface composition is not supported.** You cannot define
+    # 2 interface modules and include it into one class.
+    #
+    # @example Simple interface
+    #   class MyAction
+    #     extend Flows::Plugin::Interface
+    #
+    #     defmethod :perform
+    #   end
+    #
+    #   class InvalidAction < MyAction; end
+    #   InvalidAction.new
+    #   # will raise an error
+    #
+    #   class ValidAction < MyAction
+    #     def perfrom
+    #       puts 'Hello!'
+    #     end
+    #   end
+    #   ValidAction.new.perform
+    #   # => Hello!
+    #
+    # @example Interface as module
+    #   module MyBehavior
+    #     extend Flows::Plugin::Interface
+    #
+    #     defmethod :my_method
+    #   end
+    #
+    #   class MyImplementation
+    #     include MyBehaviour
+    #
+    #     def my_method; end
+    #   end
+    module Interface
+      # Base error class for interface errors.
+      class Error < ::Flows::Error; end
+
+      # Raised when you're missed some dependency.
+      class MissingMethodsError < Error
+        def initialize(klass, names)
+          @klass = klass
+          @names = names
+        end
+
+        def message
+          "Methods required by interface for #{@klass} are missing: #{@names.map(&:to_s).join(', ')}"
+        end
+      end
+
+      SingletonVarsSetup = Flows::Util::InheritableSingletonVars::DupStrategy.make_module(
+        '@interface_methods' => {}
+      )
+
+      include SingletonVarsSetup
+
+      InitializePatch = Flows::Util::PrependToClass.make_module do
+        def initialize(*)
+          klass = self.class
+
+          required_methods = klass.instance_variable_get(:@interface_methods).keys
+          missing_methods = required_methods - methods
+
+          raise MissingMethodsError.new(klass, missing_methods) if missing_methods.any?
+
+          super
+        end
+      end
+
+      include InitializePatch
+
+      def defmethod(method_name)
+        method_list = instance_variable_get(:@interface_methods)
+        method_list[method_name.to_sym] = { required_by: self }
+      end
+    end
+  end
+end