dry-monads 1.3.0 → 1.3.5

data/docsite/source/unit.html.md

@@ -0,0 +1,36 @@
+---
+title: Unit
+layout: gem-single
+name: dry-monads
+---
+
+Some constructors do not require you to pass a value. As a default they use `Unit`, a special singleton value:
+
+```ruby
+extend Dry::Monads[:result]
+
+Success().value! # => Unit
+```
+
+`Unit` doesn't have any special properties or methods, it's similar to `nil` except for it is not i.e. `if Unit` passes.
+
+`Unit` is usually excluded from the output:
+
+```ruby
+extend Dry::Monads[:result]
+
+# Outputs as "Success()" but technically it's "Success(Unit)"
+Success()
+```
+
+### Discarding values
+
+When the outcome of an operation is not a caller's concern, call `.discard`, it will map the wrapped value to `Unit`:
+
+```ruby
+extend Dry::Monads[:result]
+
+result = create_user # returns Success(#<User...>) or Failure(...)
+
+result.discard # => Maps Success(#<User ...>) to Success() but lefts Failure(...) intact
+```

data/docsite/source/validated.html.md

@@ -0,0 +1,88 @@
+---
+title: Validated
+layout: gem-single
+name: dry-monads
+---
+
+Suppose you've got a form to validate. If you are using `Result` combined with `Do` your code might look like this:
+
+```ruby
+require 'dry/monads'
+
+class CreateAccount
+  include Dry::Monads[:result, :do]
+
+  def call(form)
+    name = yield validate_name(form)
+    email = yield validate_email(form)
+    password = yield validate_password(form)
+
+    user = repo.create_user(
+      name: name,
+      email: email,
+      password: password
+    )
+
+    Success(user)
+  end
+
+  def validate_name(form)
+    # Success(name) or Failure(:invalid_name)
+  end
+
+  def validate_email(form)
+    # Success(email) or Failure(:invalid_email)
+  end
+
+  def validate_password(form)
+    # Success(password) or Failure(:invalid_password)
+  end
+end
+```
+
+If any of the validation steps fails the user will see an error. The problem is if `name` is not valid the user won't see errors about invalid `email` and `password`, if any. `Validated` circumvents this particular problem.
+
+`Validated` is actually not a monad but an applicative functor. This means you can't call `bind` on it. Instead, it can accumulate values in combination with `List`:
+
+```ruby
+require 'dry/monads'
+
+class CreateAccount
+  include Dry::Monads[:list, :result, :validated, :do]
+
+  def call(form)
+    name, email, password = yield List::Validated[
+      validate_name(form),
+      validate_email(form),
+      validate_password(form)
+    ].traverse.to_result
+
+    user = repo.create_user(
+      name: name,
+      email: email,
+      password: password
+    )
+
+    Success(user)
+  end
+
+  def validate_name(form)
+    # Valid(name) or Invalid(:invalid_name)
+  end
+
+  def validate_email(form)
+    # Valid(email) or Invalid(:invalid_email)
+  end
+
+  def validate_password(form)
+    # Valid(password) or Invalid(:invalid_password)
+  end
+end
+```
+
+Here all validations will be processed at once, if any of them fails the result will be converted to a `Failure` wrapping the `List` of errors:
+
+```ruby
+create_account.(form)
+# => Failure(List[:invalid_name, :invalid_email])
+```

data/dry-monads.gemspec

@@ -1,4 +1,6 @@
-lib = File.expand_path('../lib', __FILE__)
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'dry/monads/version'
 
@@ -25,13 +27,13 @@ Gem::Specification.new do |spec|
   spec.bindir        = 'exe'
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
-  spec.required_ruby_version = ">= 2.4.0"
-  spec.add_dependency 'dry-equalizer'
-  spec.add_dependency 'dry-core', '~> 0.4', '>= 0.4.4'
+  spec.required_ruby_version = '>= 2.4.0'
   spec.add_dependency 'concurrent-ruby', '~> 1.0'
+  spec.add_dependency 'dry-core', '~> 0.4', '>= 0.4.4'
+  spec.add_dependency 'dry-equalizer'
 
   spec.add_development_dependency 'bundler'
+  spec.add_development_dependency 'dry-types', '>= 0.12'
   spec.add_development_dependency 'rake'
   spec.add_development_dependency 'rspec'
-  spec.add_development_dependency 'dry-types', '>= 0.12'
 end

data/lib/dry-monads.rb

@@ -1 +1,3 @@
+# frozen_string_literal: true
+
 require 'dry/monads'

data/lib/dry/monads.rb

@@ -1,3 +1,6 @@
+# frozen_string_literal: true
+
+require 'dry/core/constants'
 require 'dry/monads/registry'
 
 module Dry

data/lib/dry/monads/all.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'dry/monads'
 require 'dry/monads/registry'
 

data/lib/dry/monads/{undefined.rb → constants.rb}

@@ -1,8 +1,10 @@
+# frozen_string_literal: true
+
 require 'dry/core/constants'
 
 module Dry
   module Monads
     # @private
-    Undefined = Dry::Core::Constants::Undefined
+    include Core::Constants
   end
 end

data/lib/dry/monads/conversion_stubs.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Dry
   module Monads
     module ConversionStubs

data/lib/dry/monads/curry.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Dry
   module Monads
     # @private

data/lib/dry/monads/do.rb

@@ -1,5 +1,8 @@
+# frozen_string_literal: true
+
 require 'dry/monads/list'
 require 'dry/monads/do/mixin'
+require 'dry/monads/constants'
 
 module Dry
   module Monads
@@ -9,6 +12,8 @@ module Dry
     module Do
       extend Mixin
 
+      DELEGATE = ::RUBY_VERSION < '2.7' ? '*' : '...'
+
       # @api private
       class Halt < StandardError
         # @api private
@@ -102,7 +107,7 @@ module Dry
         # @api private
         def wrap_method(target, method_name)
           target.module_eval(<<-RUBY, __FILE__, __LINE__ + 1)
-            def #{method_name}(*)
+            def #{method_name}(#{DELEGATE})
               if block_given?
                 super
               else
@@ -130,7 +135,7 @@ module Dry
 
         # @api private
         def halt(result)
-          raise Halt.new(result)
+          raise Halt.new(result), EMPTY_STRING, []
         end
       end
     end

data/lib/dry/monads/do/all.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'dry/monads/do'
 
 module Dry
@@ -56,7 +58,7 @@ module Dry
       #
       module All
         # @private
-        class MethodTracker < Module
+        class MethodTracker < ::Module
           attr_reader :wrappers
 
           def initialize(wrappers)
@@ -80,7 +82,7 @@ module Dry
 
               def included(base)
                 super
-                Dry::Monads::Do::All.included(base)
+                All.included(base)
               end
             end
           end
@@ -119,6 +121,7 @@ module Dry
               super(method)
 
               next if method.equal?(:singleton_method_added)
+
               Do.wrap_method(wrapper, method)
             end
             object.singleton_class.instance_methods(false).each do |m|

data/lib/dry/monads/do/mixin.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Dry
   module Monads
     module Do
@@ -43,14 +45,13 @@ module Dry
         # @api public
         def bind(monads)
           monads = Do.coerce_to_monad(Array(monads))
-          unwrapped = monads.map { |result|
+          unwrapped = monads.map do |result|
             monad = result.to_monad
             monad.or { Do.halt(monad) }.value!
-          }
+          end
           monads.size == 1 ? unwrapped[0] : unwrapped
         end
       end
     end
   end
 end
-

data/lib/dry/monads/either.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'dry/core/deprecations'
 
 Dry::Core::Deprecations.warn('Either monad was renamed to Result', tag: :'dry-monads')

data/lib/dry/monads/errors.rb

@@ -1,16 +1,18 @@
+# frozen_string_literal: true
+
 module Dry
   module Monads
     # An unsuccessful result of extracting a value from a monad.
     class UnwrapError < StandardError
       def initialize(ctx)
-        super("value! was called on #{ ctx.inspect }")
+        super("value! was called on #{ctx.inspect}")
       end
     end
 
     # An error thrown on returning a Failure of unknown type.
     class InvalidFailureTypeError < StandardError
       def initialize(failure)
-        super("Cannot create Failure from #{ failure.inspect }, it doesn't meet the constraints")
+        super("Cannot create Failure from #{failure.inspect}, it doesn't meet the constraints")
       end
     end
 

data/lib/dry/monads/lazy.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'concurrent/promise'
 
 require 'dry/monads/task'
@@ -45,12 +47,12 @@ module Dry
                 when :fulfilled
                   value!.inspect
                 when :rejected
-                  "!#{ promise.reason.inspect }"
+                  "!#{promise.reason.inspect}"
                 else
                   '?'
                 end
 
-        "Lazy(#{ state })"
+        "Lazy(#{state})"
       end
       alias_method :inspect, :to_s
 

data/lib/dry/monads/list.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'dry/equalizer'
 
 require 'dry/monads/maybe'
@@ -163,8 +165,8 @@ module Dry
       #
       # @return [String]
       def inspect
-        type_ann = typed? ? "<#{ type.name.split('::').last }>" : ''
-        "List#{ type_ann }#{ value.inspect }"
+        type_ann = typed? ? "<#{type.name.split('::').last}>" : ''
+        "List#{type_ann}#{value.inspect}"
       end
       alias_method :to_s, :inspect
 
@@ -263,10 +265,10 @@ module Dry
       def typed(type = nil)
         if type.nil?
           if size.zero?
-            raise ArgumentError, "Cannot infer a monad for an empty list"
+            raise ArgumentError, 'Cannot infer a monad for an empty list'
           else
             self.class.warn(
-              "Automatic monad inference is deprecated, pass a type explicitly "\
+              'Automatic monad inference is deprecated, pass a type explicitly '\
               "or use a predefined constant, e.g. List::Result\n"\
               "#{caller.find { |l| l !~ %r{(lib/dry/monads)|(gems)} }}"
             )
@@ -296,16 +298,16 @@ module Dry
       # @return [Monad] Result is a monadic value
       def traverse(proc = nil, &block)
         unless typed?
-          raise StandardError, "Cannot traverse an untyped list"
+          raise StandardError, 'Cannot traverse an untyped list'
         end
 
         cons = type.pure { |list, i| list + List.pure(i) }
         with = proc || block || Traverse[type]
 
         foldl(type.pure(EMPTY)) do |acc, el|
-          cons.
-            apply(acc).
-            apply { with.(el) }
+          cons
+            .apply(acc)
+            .apply { with.(el) }
         end
       end
 
@@ -433,7 +435,6 @@ module Dry
       #
       # @api public
       module Mixin
-
         # @see Dry::Monads::List
         List = List
 

data/lib/dry/monads/maybe.rb

@@ -1,11 +1,12 @@
+# frozen_string_literal: true
+
 require 'dry/equalizer'
-require 'dry/core/constants'
 require 'dry/core/deprecations'
 
 require 'dry/monads/right_biased'
 require 'dry/monads/transformer'
 require 'dry/monads/unit'
-require 'dry/monads/undefined'
+require 'dry/monads/constants'
 
 module Dry
   module Monads
@@ -16,7 +17,7 @@ module Dry
       include Transformer
 
       class << self
-        extend Dry::Core::Deprecations[:'dry-monads']
+        extend Core::Deprecations[:'dry-monads']
 
         # Wraps the given value with into a Maybe object.
         #
@@ -105,6 +106,7 @@ module Dry
 
         def initialize(value = Undefined)
           raise ArgumentError, 'nil cannot be some' if value.nil?
+
           @value = Undefined.default(value, Unit)
         end
 
@@ -139,7 +141,6 @@ module Dry
       # @api public
       class None < Maybe
         include RightBiased::Left
-        include Core::Constants
 
         @instance = new.freeze
         singleton_class.send(:attr_reader, :instance)
@@ -163,6 +164,10 @@ module Dry
           @trace = trace
         end
 
+        # @!method maybe(*args, &block)
+        #   Alias of fmap, returns self back
+        alias_method :maybe, :fmap
+
         # If a block is given passes internal value to it and returns the result,
         # otherwise simply returns the parameter val.
         #

data/lib/dry/monads/registry.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'concurrent/map'
 
 module Dry
@@ -36,8 +38,9 @@ module Dry
       # @private
       def register_mixin(name, mod)
         if registry.key?(name)
-          raise ArgumentError, "#{ name.inspect } is already registered"
+          raise ArgumentError, "#{name.inspect} is already registered"
         end
+
         self.registry = registry.merge(name => mod)
       end
 
@@ -49,7 +52,7 @@ module Dry
       # @private
       def load_monad(name)
         path = @paths.fetch(name) {
-          raise ArgumentError, "#{ name.inspect } is not a known monad"
+          raise ArgumentError, "#{name.inspect} is not a known monad"
         }
         Array(path).each { |p| require p }
       end