dry-monads 0.4.0 → 1.0.0.beta1

data/lib/dry/monads/result.rb

@@ -13,15 +13,25 @@ module Dry
     class Result
       include Transformer
 
-      attr_reader :success, :failure
+      # @return [Object] Successful result
+      attr_reader :success
+
+      # @return [Object] Error
+      attr_reader :failure
 
       class << self
-        # Wraps the given value with Success
+        # Wraps the given value with Success.
         #
-        # @param value [Object] the value to be stored inside Success
-        # @return [Result::Success]
-        def pure(value)
-          Success.new(value)
+        # @overload pure(value)
+        #   @param value [Object]
+        #   @return [Result::Success]
+        #
+        # @overload pure(&block)
+        #   @param block [Proc] a block to be wrapped with Success
+        #   @return [Result::Success]
+        #
+        def pure(value = Undefined, &block)
+          Success.new(Undefined.default(value, block))
         end
       end
 
@@ -31,7 +41,13 @@ module Dry
       def to_result
         self
       end
-      alias_method :to_either, :to_result
+
+      # Returns self.
+      #
+      # @return [Result::Success, Result::Failure]
+      def to_monad
+        self
+      end
 
       # Returns the Result monad.
       # This is how we're doing polymorphism in Ruby 😕
@@ -66,13 +82,11 @@ module Dry
         def failure?
           false
         end
-        alias_method :left?, :failure?
 
         # Returns true
         def success?
           true
         end
-        alias_method :right?, :success?
 
         # Does the same thing as #bind except it also wraps the value
         # in an instance of Result::Success monad. This allows for easier
@@ -99,11 +113,18 @@ module Dry
           Dry::Monads::Maybe(@value)
         end
 
-        # Transform to a Failure instance
+        # Transforms to a Failure instance
         #
         # @return [Result::Failure]
         def flip
-          Failure.new(@value)
+          Failure.new(@value, RightBiased::Left.trace_caller)
+        end
+
+        # Transforms to Validated
+        #
+        # @return [Validated::Valid]
+        def to_validated
+          Validated::Valid.new(value!)
         end
       end
 
@@ -114,15 +135,22 @@ module Dry
         include RightBiased::Left
         include Dry::Equalizer(:failure)
 
-        # @api private
-        def failure
-          @value
-        end
-        alias_method :left, :failure
+        # Line where the value was constructed
+        #
+        # @return [String]
+        # @api public
+        attr_reader :trace
 
-        # @param value [Object] a value in an error state
-        def initialize(value)
+        # @param value [Object] failure value
+        # @param trace [String] caller line
+        def initialize(value, trace = RightBiased::Left.trace_caller)
           @value = value
+          @trace = trace
+        end
+
+        # @private
+        def failure
+          @value
         end
 
         # Apply the first function to value.
@@ -136,13 +164,11 @@ module Dry
         def failure?
           true
         end
-        alias_method :left?, :failure?
 
         # Returns false
         def success?
           false
         end
-        alias_method :right?, :success?
 
         # If a block is given passes internal value to it and returns the result,
         # otherwise simply returns the first argument.
@@ -182,7 +208,7 @@ module Dry
 
         # @return [Maybe::None]
         def to_maybe
-          Maybe::None.instance
+          Maybe::None.new(trace)
         end
 
         # Transform to a Success instance
@@ -192,7 +218,7 @@ module Dry
           Success.new(@value)
         end
 
-        # @see Dry::Monads::RightBiased::Left#value_or
+        # @see RightBiased::Left#value_or
         def value_or(val = nil)
           if block_given?
             yield(@value)
@@ -206,45 +232,63 @@ module Dry
         def ===(other)
           Failure === other && failure === other.failure
         end
+
+        # Transforms to Validated
+        #
+        # @return [Validated::Valid]
+        def to_validated
+          Validated::Invalid.new(failure, trace)
+        end
       end
 
       # A module that can be included for easier access to Result monads.
+      #
+      # @api public
       module Mixin
-        Success = Dry::Monads::Result::Success
-        Failure = Dry::Monads::Result::Failure
+        # @see Result::Success
+        Success = Result::Success
+        # @see Result::Failure
+        Failure = Result::Failure
 
+        # Value constructors
+        #
         module Constructors
-          # @param value [Object] the value to be stored in the monad
-          # @return [Result::Success]
-          def Success(value = Dry::Core::Constants::Undefined, &block)
-            if value.equal?(Dry::Core::Constants::Undefined)
-              raise ArgumentError, 'No value given' if block.nil?
-              Success.new(block)
-            else
-              Success.new(value)
-            end
+
+          # Success constructor
+          #
+          # @overload Success(value)
+          #   @param value [Object]
+          #   @return [Result::Success]
+          #
+          # @overload Success(&block)
+          #   @param block [Proc] a block to be wrapped with Success
+          #   @return [Result::Success]
+          #
+          def Success(value = Undefined, &block)
+            v = Undefined.default(value, block)
+            raise ArgumentError, 'No value given' if !value.nil? && v.nil?
+            Success.new(v)
           end
-          alias_method :Right, :Success
-
-          # @param value [Object] the value to be stored in the monad
-          # @return [Result::Failure]
-          def Failure(value = Dry::Core::Constants::Undefined, &block)
-            if value.equal?(Dry::Core::Constants::Undefined)
-              raise ArgumentError, 'No value given' if block.nil?
-              Failure.new(block)
-            else
-              Failure.new(value)
-            end
+
+          # Failure constructor
+          #
+          # @overload Success(value)
+          #   @param value [Object]
+          #   @return [Result::Failure]
+          #
+          # @overload Success(&block)
+          #   @param block [Proc] a block to be wrapped with Failure
+          #   @return [Result::Failure]
+          #
+          def Failure(value = Undefined, &block)
+            v = Undefined.default(value, block)
+            raise ArgumentError, 'No value given' if !value.nil? && v.nil?
+            Failure.new(v, RightBiased::Left.trace_caller)
           end
-          alias_method :Left, :Failure
         end
 
         include Constructors
       end
     end
-
-    Either = Result
-    Result::Right = Result::Success
-    Result::Left = Result::Failure
   end
 end

data/lib/dry/monads/result/fixed.rb

@@ -1,7 +1,7 @@
 module Dry::Monads
   class Result
     # @see Monads#Result
-    # @api private
+    # @private
     class Fixed < Module
       def self.[](error, **options)
         new(error, **options)
@@ -11,7 +11,7 @@ module Dry::Monads
         @mod = Module.new do
           define_method(:Failure) do |value|
             if error === value
-              Failure.new(value)
+              Failure.new(value, RightBiased::Left.trace_caller)
             else
               raise InvalidFailureTypeError.new(value)
             end

data/lib/dry/monads/right_biased.rb

@@ -1,17 +1,18 @@
 require 'dry/core/constants'
-require 'dry/core/deprecations'
 
+require 'dry/monads/curry'
 require 'dry/monads/errors'
 
 module Dry
   module Monads
+    # A common module for right-biased monads, such as Result/Either, Maybe, and Try.
     module RightBiased
+      # Right part
+      #
       # @api public
       module Right
         include Dry::Core::Constants
 
-        extend Dry::Core::Deprecations[:'dry-monads']
-
         # Unwraps the underlying value
         #
         # @return [Object]
@@ -19,8 +20,6 @@ module Dry
           @value
         end
 
-        deprecate :value, :value!
-
         # Calls the passed in Proc object with value stored in self
         # and returns the result.
         #
@@ -65,8 +64,8 @@ module Dry
           bind(*args, &block).bind { self }
         end
 
-        # Abstract method for lifting a block over the monad type
-        # Must be implemented for a right-biased monad
+        # Abstract method for lifting a block over the monad type.
+        # Must be implemented for a right-biased monad.
         #
         # @return [RightBiased::Right]
         def fmap(*)
@@ -97,7 +96,7 @@ module Dry
         end
 
         # Applies the stored value to the given argument if the argument has type of Right,
-        # otherwise returns the argument
+        # otherwise returns the argument.
         #
         # @example happy path
         #   create_user = Dry::Monads::Right(CreateUser.new)
@@ -109,11 +108,12 @@ module Dry
         #   create_user.apply(name) # => Left(:name_missing)
         #
         # @return [RightBiased::Left,RightBiased::Right]
-        def apply(val)
+        def apply(val = Undefined)
           unless @value.respond_to?(:call)
             raise TypeError, "Cannot apply #{ val.inspect } to #{ @value.inspect }"
           end
-          val.fmap { |unwrapped| curry.(unwrapped) }
+
+          Undefined.default(val) { yield }.fmap { |unwrapped| curry.(unwrapped) }
         end
 
         # @param other [RightBiased]
@@ -131,28 +131,19 @@ module Dry
 
         # @api private
         def curry
-          @curried ||=
-            begin
-              func = @value.is_a?(Proc) ? @value : @value.method(:call)
-              seq_args = func.parameters.count { |type, _| type == :req }
-              seq_args += 1 if func.parameters.any? { |type, _| type == :keyreq }
-
-              if seq_args > 1
-                func.curry
-              else
-                func
-              end
-            end
+          @curried ||= Curry.(@value)
         end
       end
 
+      # Left/wrong/erroneous part
+      #
       # @api public
       module Left
-        extend Dry::Core::Deprecations[:'dry-monads']
-
-        attr_reader :value
-
-        deprecate :value, message: '.value is deprecated, use .value! instead'
+        # @private
+        # @return [String] Caller location
+        def self.trace_caller
+          caller_locations(2, 2)[0].to_s
+        end
 
         # Raises an error on accessing internal value
         def value!

data/lib/dry/monads/task.rb

@@ -0,0 +1,309 @@
+require 'concurrent/promise'
+
+require 'dry/monads/curry'
+
+module Dry
+  module Monads
+    # The Task monad represents an async computation. The implementation
+    # is a rather thin wrapper of Concurrent::Promise from the concurrent-ruby.
+    # The API supports setting a custom executor from concurrent-ruby.
+    #
+    # @api public
+    class Task
+      # @api private
+      class Promise < Concurrent::Promise
+        public :on_fulfill, :on_reject
+      end
+      private_constant :Promise
+
+      class << self
+        # Creates a Task from a block
+        #
+        # @overload new(promise)
+        #   @param promise [Promise]
+        #   @return [Task]
+        #
+        # @overload new(&block)
+        #   @param block [Proc] a task to run
+        #   @return [Task]
+        #
+        def new(promise = nil, &block)
+          if promise
+            super(promise)
+          else
+            super(Promise.execute(&block))
+          end
+        end
+
+        # Creates a Task with the given executor
+        #
+        # @example providing an executor instance, using Ruby 2.5+ syntax
+        #   IO = Concurrent::ThreadPoolExecutor.new
+        #   Task[IO] { do_http_request }
+        #
+        # @example using a predefined executor
+        #    Task[:fast] { do_quick_task }
+        #
+        # @param executor [Concurrent::AbstractExecutorService,Symbol] Either an executor instance
+        #                                                              or a name of predefined global
+        #                                                              from concurrent-ruby
+        # @return [Task]
+        def [](executor, &block)
+          new(Promise.execute(executor: executor, &block))
+        end
+
+        # Returns a complete task from the given value
+        #
+        # @overload pure(value)
+        #   @param value [Object]
+        #   @return [Task]
+        #
+        # @overload pure(&block)
+        #   @param block [Proc]
+        #   @return [Task]
+        #
+        def pure(value = Undefined, &block)
+          v = Undefined.default(value, block)
+          new(Promise.fulfill(v))
+        end
+      end
+
+      # @api private
+      attr_reader :promise
+      protected :promise
+
+      # @api private
+      def initialize(promise)
+        @promise = promise
+      end
+
+      # Retrieves the value of the computation.
+      # Blocks current thread if the underlying promise
+      # hasn't been complete yet.
+      # Throws an error if the computation failed.
+      #
+      # @return [Object]
+      # @api public
+      def value!
+        if promise.wait.fulfilled?
+          promise.value
+        else
+          raise promise.reason
+        end
+      end
+
+      # Lifts a block over the Task monad.
+      #
+      # @param block [Proc]
+      # @return [Task]
+      # @api public
+      def fmap(&block)
+        self.class.new(promise.then(&block))
+      end
+
+      # Composes two tasks to run one after another.
+      # A more common name is `then` exists as an alias.
+      #
+      # @param block [Proc] A block that yields the result of the current task
+      #                     and returns another task
+      # @return [Task]
+      def bind(&block)
+        self.class.new(promise.flat_map { |value| block.(value).promise })
+      end
+      alias_method :then, :bind
+
+      # Converts to Result. Blocks the current thread if required.
+      #
+      # @return [Result]
+      def to_result
+        if promise.wait.fulfilled?
+          Result::Success.new(promise.value)
+        else
+          Result::Failure.new(promise.reason, RightBiased::Left.trace_caller)
+        end
+      end
+
+      # Converts to Maybe. Blocks the current thread if required.
+      #
+      # @return [Maybe]
+      def to_maybe
+        if promise.wait.fulfilled?
+          Maybe::Some.new(promise.value)
+        else
+          Maybe::None.new(RightBiased::Left.trace_caller)
+        end
+      end
+
+      # @return [String]
+      def to_s
+        state = case promise.state
+                when :fulfilled
+                  "value=#{ value!.inspect }"
+                when :rejected
+                  "error=#{ promise.reason.inspect }"
+                else
+                  '?'
+                end
+
+        "Task(#{ state })"
+      end
+      alias_method :inspect, :to_s
+
+      # Tranforms the error if the computation wasn't successful.
+      #
+      # @param block [Proc]
+      # @return [Task]
+      def or_fmap(&block)
+        self.class.new(promise.rescue(&block))
+      end
+
+      # Rescues the error with a block that returns another task.
+      #
+      # @param block [Proc]
+      # @return [Object]
+      def or(&block)
+        child = Promise.new(
+          parent: promise,
+          executor: Concurrent::ImmediateExecutor.new
+        )
+
+        promise.on_error do |v|
+          begin
+            inner = block.(v).promise
+            inner.execute
+            inner.on_success { |r| child.on_fulfill(r) }
+            inner.on_error { |e| child.on_reject(e) }
+          rescue => e
+            child.on_reject(e)
+          end
+        end
+        promise.on_success  { |v| child.on_fulfill(v) }
+
+        self.class.new(child)
+      end
+
+      # Extracts the resulting value if the computation was successful
+      # otherwise yields the block and returns its result.
+      #
+      # @param block [Proc]
+      # @return [Object]
+      def value_or(&block)
+        promise.rescue(&block).wait.value
+      end
+
+      # Blocks the current thread until the task is complete.
+      #
+      # @return [Task]
+      def wait(timeout = nil)
+        promise.wait(timeout)
+        self
+      end
+
+      # Compares two tasks. Note, it works
+      # good enough only for complete tasks.
+      #
+      # @return [Boolean]
+      def ==(other)
+        return true if equal?(other)
+        return false unless self.class == other.class
+        compare_promises(promise, other.promise)
+      end
+
+      # Whether the computation is complete.
+      #
+      # @return [Boolean]
+      def complete?
+        promise.complete?
+      end
+
+      # @return [Class]
+      def monad
+        Task
+      end
+
+      # Returns self.
+      #
+      # @return [Maybe::Some, Maybe::None]
+      def to_monad
+        self
+      end
+
+      # Applies the stored value to the given argument.
+      #
+      # @example
+      #   Task.
+      #     pure { |x, y| x ** y }.
+      #     apply(Task { 2 }).
+      #     apply(Task { 3 }).
+      #     to_maybe # => Some(8)
+      #
+      # @param val [Task]
+      # @return [Task]
+      def apply(val = Undefined)
+        arg = Undefined.default(val) { yield }
+        bind { |f| arg.fmap { |v| curry(f).(v) } }
+      end
+
+      private
+
+      # @api private
+      def curry(value)
+        if defined?(@curried)
+          if @curried[0].equal?(value)
+            @curried[1]
+          else
+            Curry.(value)
+          end
+        else
+          @curried = [value, Curry.(value)]
+          @curried[1]
+        end
+      end
+
+      # @api private
+      def compare_promises(x, y)
+        x.equal?(y) ||
+          x.fulfilled? && y.fulfilled? && x.value == y.value ||
+          x.rejected? && y.rejected? && x.reason == y.reason
+      end
+
+      # Task constructors.
+      #
+      # @api public
+      module Mixin
+        Task = Task # @private
+
+        # Created a mixin with the given executor injected.
+        #
+        # @param executor [Concurrent::AbstractExecutorService,Symbol]
+        # @return [Module]
+        def self.[](executor)
+          Module.new do
+            include Mixin
+
+            # Created a new Task with an injected executor.
+            #
+            # @param block [Proc]
+            # @return [Task]
+            define_method(:Task) do |&block|
+              Task[executor, &block]
+            end
+          end
+        end
+
+        # Task constructors
+        module Constructors
+          # Builds a new Task instance.
+          #
+          # @param block [Proc]
+          # @return Task
+          def Task(&block)
+            Task.new(&block)
+          end
+        end
+
+        include Constructors
+      end
+    end
+  end
+end