flows 0.3.0 → 0.4.0

data/lib/flows/plugin.rb

@@ -0,0 +1,13 @@
+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'

data/lib/flows/plugin/dependency_injector.rb

@@ -0,0 +1,159 @@
+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__
+
+      Flows::Util::InheritableSingletonVars::DupStrategy.call(
+        self,
+        '@dependencies' => {}
+      )
+
+      # @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
+
+      # @api private
+      module InitializePatch
+        def initialize(*args, **kwargs, &block) # rubocop:disable Metrics/MethodLength
+          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
+
+      Flows::Util::PrependToClass.call(self, InitializePatch)
+    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,57 @@
+module Flows
+  module Plugin
+    module DependencyInjector
+      # Resolves dependencies on initialization and can inject it into class instance.
+      #
+      # @api private
+      class DependencyList
+        attr_reader :definitions
+        attr_reader :provided_values
+        attr_reader :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/output_contract.rb

@@ -0,0 +1,84 @@
+require_relative 'output_contract/errors'
+require_relative 'output_contract/dsl'
+require_relative 'output_contract/wrapper'
+
+module Flows
+  module Plugin
+    # Allows to make a contract check and transformation for `#call` method execution in any class.
+    #
+    # Plugin applies a wrapper to a `#call` instance method.
+    # This wrapper will do the following:
+    #
+    # * check that {Result} instance is returned by `#call`
+    # * check that returned {Result#status} is expected
+    # * check that returned result data conforms {Contract} assigned
+    #   to a particular result type and status
+    # * applies contract transform to the returned data
+    # * returns {Result} with the same status and type,
+    #   wraps transformed data inside.
+    #
+    # Plugin provides DSL to express expected result statuses and assigned contracts.
+    # Contracts definition reuses {Contract.make} to execute block and get a contract.
+    #
+    # * `success_with(status, &block)` - defines contract for a successful result with status `status`.
+    # * `failure_with(status, &block)` - defines contract for a failure result with status `status`.
+    #
+    # @example with one possible output contract
+    #     class DoJob
+    #       include Flows::Result::Helpers
+    #       include Flows::Plugin::OutputContract
+    #
+    #       success_with :ok do
+    #         Integer
+    #       end
+    #
+    #       def call(a, b)
+    #         ok_data(a + b)
+    #       end
+    #     end
+    #
+    #     DoJob.new.call(1, 2).unwrap
+    #     # => 3
+    #
+    #     DoJob.new.call('a', 'b')
+    #     # Flows::Contract::Error exception raised
+    #
+    # @example with multiple contracts
+    #     class DoJob
+    #       include Flows::Result::Helpers
+    #       include Flows::Plugin::OutputContract
+    #
+    #       success_with :int_sum do
+    #         Integer
+    #       end
+    #
+    #       success_with :float_sum do
+    #         Float
+    #       end
+    #
+    #       failure_with :err do
+    #         hash_of(
+    #           key: Symbol,
+    #           msg: String
+    #         )
+    #       end
+    #
+    #       def call(a, b)
+    #         if a.is_a?(Float) || b.is_a?(Float)
+    #           ok_data(a + b, status: :float_sum)
+    #         elsif a.is_a?(Integer) && b.is_a?(Integer)
+    #           ok_data(a + b, status: :int_sum)
+    #         else
+    #           err(key: :unexpected_type, msg: "Unexpected argument types")
+    #         end
+    #       end
+    #     end
+    module OutputContract
+      # @api private
+      def self.included(mod)
+        mod.extend(DSL)
+        mod.prepend(Wrapper)
+      end
+    end
+  end
+end