dry-monads 0.4.0 → 1.0.0.beta1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 90f99efaec5f7f88c8f150a6af7d9f3ee2bc2a64
-  data.tar.gz: 82c6bb698fa47243c44367c14ab182d893c0b59c
+SHA256:
+  metadata.gz: e39ab380c859836fb98aad8bc158eeafb73896472cc703254c0f21490c6cde68
+  data.tar.gz: 749f9cf55040d0cafc8f8f4e3d8c60a8e2486768223069adff7f0b4c55cc9a43
 SHA512:
-  metadata.gz: 559a48263fd284e9c93c1773846b66960653a37ca811b249f5482a1cc518aa83a40e71e7adb5d206c50066293e353317793cb68893935c37f8f12a36654ad854
-  data.tar.gz: 8c06400c56a9b753d83df82cd011477cc29ba492a3383d1df325e9fa7eaafd56bef653590cde58c4b415994c63817eac1574b12a769267cf2060ab8c0eead8d5
+  metadata.gz: 3c66d5ea73e5c781e26acfb1611067a34cc25a9fbbb258a01ad8f5705b33cd569944ae9eab126e18456b4f6eeec0722163e39406e52c332e5224a78b5dae53e9
+  data.tar.gz: 73a8d308f628a5ea630cabdaf240f67627e3310ec3cf64a75cec7140b6c5645853cfcf50ecc463a38f1813c28b78a145d7d40ec45998327c7cbedce1177c60c5

data/.travis.yml

@@ -5,13 +5,16 @@ cache: bundler
 bundler_args: --without benchmarks docs
 script:
   - bundle exec rake spec
+before_install:
+  - gem update --system
 after_success:
   - '[ -d coverage ] && bundle exec codeclimate-test-reporter'
 rvm:
-  - 2.2.8
-  - 2.3.5
-  - 2.4.2
-  - jruby-9.1.13.0
+  - 2.2.9
+  - 2.3.6
+  - 2.4.3
+  - 2.5.0
+  - jruby-9.1.15.0
   - ruby-head
 env:
   global:

data/CHANGELOG.md

@@ -1,3 +1,143 @@
+# v1.0.0 to-be-released
+
+## Added
+
+* `do`-like notation (the idea comes from Haskell of course). This is the biggest and most important addition in the release which greatly increases the ergonomics of using monads in Ruby. Basically, almost everything it does is passing a block to a given method. You call `yield` on monads to extract the values. If any operation fails i.e. no value can be extracted, the whole computation is halted and the failing step becomes a result. With `Do` you don't need to chain monadic values with `fmap/bind` and block, everything can be done on a single level of indentation. Here is a more or less real-life example:
+
+  ```ruby
+  class CreateUser
+    include Dry::Monads
+    include Dry::Monads::Do.for(:call)
+
+    attr_reader :user_repo
+
+    def initialize(:user_repo)
+      @user_repo = user_repo
+    end
+
+    def call(params)
+      json = yield parse_json(params)
+      hash = yield validate(json)
+
+      user_repo.transaction do
+        user = yield create_user(hash[:user])
+        yield create_profile(user, hash[:profile])
+
+        Success(user)
+      end
+    end
+
+    private
+
+    def parse_json(params)
+      Try[JSON::ParserError] {
+        JSON.parse(params)
+      }.to_result
+    end
+
+    def validate(json)
+      UserSchema.(json).to_monad
+    end
+
+    def create_user(user_data)
+      Try[Sequel::Error] { user_repo.create(user_data) }.to_result
+    end
+ 
+    def create_profile(user, profile_data)
+      Try[Sequel::Error] {
+        user_repo.create_profile(user, profile_data)
+      }.to_result
+    end
+  end
+  ```
+
+  In the code above any `yield` can potentially fail and return the failure reason as a result. In other words, `yield None` acts as `return None`. Internally, `Do` uses exceptions, not `return`, this is somewhat slower but allows to detect failed operations in DB-transactions and roll back the changes which far more useful than an unjustifiable speed boost (flash-gordon)
+
+* The `Task` monad based on `Promise` from the [`concurrent-ruby` gem](https://github.com/ruby-concurrency/concurrent-ruby/). `Task` represents an asynchrounos computation which _can be_ (doesn't have to!) run on a seperated thread. `Promise` already offers a good API and implemented in a safe manner so `dry-monads` just adds a monad-compatible interface for it. Out of the box, `concurrent-ruby` has three types of executors for running blocks: `:io`, `:fast`, `:immediate`, check out [the docs](http://ruby-concurrency.github.io/concurrent-ruby/root/Concurrent.html#executor-class_method) for details. You can provide your own executor if needed (flash-gordon)
+
+  ```ruby
+  include Dry::Monads::Task::Mixin
+
+  def call
+    name = Task { get_name_via_http }    # runs a request in the background
+    email = Task { get_email_via_http }  # runs another one request in the background
+  
+    # to_result forces both computations/requests to complete by pausing current thread
+    # returns `Result::Success/Result::Failure`
+    name.bind { |n| email.fmap { |e| create(e, n) } }.to_result
+  end
+  ```
+
+  `Task` works perfectly with `Do`
+
+  ```ruby
+  include Dry::Monads::Do.for(:call)
+
+  def call
+    name, email = yield Task { get_name_via_http }, Task { get_email_via_http }
+    Success(create(e, n))
+  end
+  ```
+
+* `Lazy` is a copy of `Task` that isn't run until you ask for the value _for the first time_. It is guaranteed the evaluation is run at most once as opposed to lazy assignment `||=` which isn't synchronized. `Lazy` is run on the same thread asking for the value (flash-gordon)
+
+* Automatic type inference with `.typed` for lists was deprecated. Instead, typed list builders were added
+
+  ```ruby
+  list = List::Task[Task { get_name }, Task { get_email }]
+  list.traverse # => Task(List['John', 'john@doe.org'])
+  ```
+  
+  The code above runs two tasks in parallel and automatically combines their results with `traverse` (flash-gordon)
+  
+* `Try` got a new call syntax supported in Ruby 2.5+
+
+  ```ruby
+    Try[ArgumentError, TypeError] { unsafe_operation } 
+  ```
+  
+  Prior to 2.5, it wasn't possible to pass a block to `[]`.
+
+* The `Validated` “monad” that represents a result of a validation. Suppose, you want to collect all the errors and return them at once. You can't have it with `Result` because when you `traverse` a `List` of `Result`s it returns the first value and this is the correct behavior from the theoretical point of view. `Validated`, in fact, doesn't have a monad instance but provides a useful variant of applicative which concatenates the errors.
+
+  ```ruby
+    include Dry::Monads
+    include Dry::Monads::Do.for(:call)
+    
+    def call(input)
+      name, email = yield [
+        validate_name(input[:name]),
+        validate_email(input[:email])
+      ]
+      
+      Success(create(name, email))
+    end
+    
+    # can return 
+    # * Success(User(...))
+    # * Invalid(List[:invalid_name])
+    # * Invalid(List[:invalid_email])    
+    # * Invalid(List[:invalid_name, :invalid_email])    
+  ```
+  
+  In the example above an array of `Validated` values is implicitly casted to `List::Validated`. It's supported because it's useful but don't forget it's all about types and don't mix different types of monads in a single array, the consequences are unclear. You always can be explicit with `List::Validated[validate_name(...), ...]`, choose what you like (flash-gordon).
+  
+* `Failure`, `None`, and `Invalid` values now store the line where they were created. On of the biggest downside of dealing wtih monadic code is lack of backtraces. If you have a long list of computations and one of them fails how do you know where did it actually happen? Say, you've got `None` and this tells you nothing about _what variable_ was assigned to `None`. It makes sense to use `Result` instead of `Maybe` and use distinct errors everywhere but it doesn't always look good and forces you to think more. TLDR; call `.trace` to get the line where a fail-case was constructed
+
+  ```ruby
+  Failure(:invalid_name).trace # => app/operations/create_user.rb:43
+  ```
+  
+## Deprecations
+
+* `Either`, the former name of `Result`, is now deprecated
+
+## BREAKING CHANGES
+
+* `Either#value` and `Maybe#value` were both droped, use `value_or` or `value!` when you :100: sure it's safe
+
+[Compare v0.4.0...v1.0.0](https://github.com/dry-rb/dry-monads/compare/v0.4.0...master)
+
 # v0.4.0 2017-11-11
 
 ## Changed
@@ -23,7 +163,7 @@
 
 ## Deprecated
 
-* Direct accessing `value` on right-biased monads has been deprecated, use the `value!` method instead. `value!` will raise an exception if it is called on a Sailure/None/Error instance (flash-gordon)
+* Direct accessing `value` on right-biased monads has been deprecated, use the `value!` method instead. `value!` will raise an exception if it is called on a Failure/None/Error instance (flash-gordon)
 
 [Compare v0.3.1...v0.4.0](https://github.com/dry-rb/dry-monads/compare/v0.3.1...v0.4.0)
 

data/CONTRIBUTING.md

@@ -22,7 +22,7 @@ Other requirements:
 2) Follow the style conventions of the surrounding code. In most cases, this is standard ruby style.
 3) Add API documentation if it's a new feature
 4) Update API documentation if it changes an existing feature
-5) Bonus points for sending a PR to [github.com/dry-rb/dry-rb.org](github.com/dry-rb/dry-rb.org) which updates user documentation and guides
+5) Bonus points for sending a PR to [github.com/dry-rb/dry-rb.org](https://github.com/dry-rb/dry-rb.org) which updates user documentation and guides
 
 # Asking for help
 

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2016 Nikita Shilnikov
+Copyright (c) 2016-2018 Nikita Shilnikov
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -8,8 +8,8 @@
 
 [![Gem Version](https://img.shields.io/gem/v/dry-monads.svg)][gem]
 [![Build Status](https://img.shields.io/travis/dry-rb/dry-monads.svg)][travis]
-[![Code Climate](https://img.shields.io/codeclimate/github/dry-rb/dry-monads.svg)][code_climate]
-[![Test Coverage](https://img.shields.io/codeclimate/coverage/github/dry-rb/dry-monads.svg)][code_climate]
+[![Code Climate](https://api.codeclimate.com/v1/badges/b0ea4d8023d53b7f0f50/maintainability)][code_climate]
+[![Test Coverage](https://api.codeclimate.com/v1/badges/b0ea4d8023d53b7f0f50/test_coverage)][code_climate]
 [![API Documentation Coverage](http://inch-ci.org/github/dry-rb/dry-monads.svg)][inch]
 ![No monkey-patches](https://img.shields.io/badge/monkey--patches-0-brightgreen.svg)
 

data/dry-monads.gemspec

@@ -27,7 +27,8 @@ Gem::Specification.new do |spec|
   spec.require_paths = ['lib']
   spec.required_ruby_version = ">= 2.2.0"
   spec.add_dependency 'dry-equalizer'
-  spec.add_dependency 'dry-core', '~> 0.3', '>= 0.3.3'
+  spec.add_dependency 'dry-core', '~> 0.4', '>= 0.4.4'
+  spec.add_dependency 'concurrent-ruby', '~> 1.0'
 
   spec.add_development_dependency 'bundler'
   spec.add_development_dependency 'rake'

data/lib/dry/monads.rb

@@ -2,26 +2,47 @@ require 'dry/core/constants'
 require 'dry/monads/maybe'
 require 'dry/monads/try'
 require 'dry/monads/list'
+require 'dry/monads/task'
+require 'dry/monads/lazy'
 require 'dry/monads/result'
 require 'dry/monads/result/fixed'
+require 'dry/monads/do'
+require 'dry/monads/validated'
 
 module Dry
+  # Common, idiomatic monads for Ruby
+  #
   # @api public
   module Monads
+    # @private
     Undefined = Dry::Core::Constants::Undefined
 
+    # List of monad constructors
     CONSTRUCTORS = [
       Maybe::Mixin::Constructors,
-      Result::Mixin::Constructors
+      Result::Mixin::Constructors,
+      Validated::Mixin::Constructors,
+      Try::Mixin::Constructors,
+      Task::Mixin::Constructors,
+      Lazy::Mixin::Constructors
     ].freeze
 
+    # @see Maybe::Some
     Some = Maybe::Some
+    # @see Maybe::None
     None = Maybe::None
+    # @see Result::Success
     Success = Result::Success
+    # @see Result::Failure
     Failure = Result::Failure
+    # @see Validated::Valid
+    Valid = Validated::Valid
+    # @see Validated::Invalid
+    Invalid = Validated::Invalid
 
     extend(*CONSTRUCTORS)
 
+    # @private
     def self.included(base)
       super
 

data/lib/dry/monads/curry.rb

@@ -0,0 +1,19 @@
+module Dry
+  module Monads
+    # @private
+    module Curry
+      # @private
+      def self.call(value)
+        func = value.is_a?(Proc) ? value : value.method(:call)
+        seq_args = func.parameters.count { |type, _| type == :req || type == :opt }
+        seq_args += 1 if func.parameters.any? { |type, _| type == :keyreq }
+
+        if seq_args > 1
+          func.curry
+        else
+          func
+        end
+      end
+    end
+  end
+end

data/lib/dry/monads/do.rb

@@ -0,0 +1,119 @@
+module Dry
+  module Monads
+    # An implementation of do-notation.
+    #
+    # @see Do.for
+    module Do
+      # @private
+      class Halt < StandardError
+        # @private
+        attr_reader :result
+
+        def initialize(result)
+          super()
+
+          @result = result
+        end
+      end
+
+      # Generates a module that passes a block to methods
+      # that either unwraps a single-valued monadic value or halts
+      # the execution.
+      #
+      # @example A complete example
+      #
+      #   class CreateUser
+      #     include Dry::Monads::Result::Mixin
+      #     include Dry::Monads::Try::Mixin
+      #     include Dry::Monads::Do.for(:call)
+      #
+      #     attr_reader :user_repo
+      #
+      #     def initialize(:user_repo)
+      #       @user_repo = user_repo
+      #     end
+      #
+      #     def call(params)
+      #       json = yield parse_json(params)
+      #       hash = yield validate(json)
+      #
+      #       user_repo.transaction do
+      #         user = yield create_user(hash[:user])
+      #         yield create_profile(user, hash[:profile])
+      #       end
+      #
+      #       Success(user)
+      #     end
+      #
+      #     private
+      #
+      #     def parse_json(params)
+      #       Try(JSON::ParserError) {
+      #         JSON.parse(params)
+      #       }.to_result
+      #     end
+      #
+      #     def validate(json)
+      #       UserSchema.(json).to_monad
+      #     end
+      #
+      #     def create_user(user_data)
+      #       Try(Sequel::Error) {
+      #         user_repo.create(user_data)
+      #       }.to_result
+      #     end
+      #
+      #     def create_profile(user, profile_data)
+      #       Try(Sequel::Error) {
+      #         user_repo.create_profile(user, profile_data)
+      #       }.to_result
+      #     end
+      #   end
+      #
+      # @param [Array<Symbol>] methods
+      # @return [Module]
+      def self.for(*methods)
+        mod = Module.new do
+          methods.each do |method|
+            class_eval(<<-RUBY, __FILE__, __LINE__ + 1)
+              def #{ method }(*)
+                super do |*ms|
+                  ms = coerce_to_monad(ms)
+                  unwrapped = ms.map { |m| m.to_monad.or { halt(m) }.value! }
+                  ms.size == 1 ? unwrapped[0] : unwrapped
+                end
+              rescue Halt => e
+                e.result
+              end
+            RUBY
+          end
+        end
+
+        Module.new do
+          singleton_class.send(:define_method, :included) do |base|
+            base.prepend(mod)
+          end
+
+          def halt(result)
+            raise Halt.new(result)
+          end
+
+          # @private
+          def coerce_to_monad(ms)
+            return ms if ms.size != 1
+
+            fst = ms[0]
+
+            case fst
+            when Array, List
+              list = fst.is_a?(Array) ? List.coerce(fst) : fst
+              [list.traverse]
+            else
+              ms
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/dry/monads/either.rb

@@ -1 +1,64 @@
+require 'dry/core/deprecations'
+
+Dry::Core::Deprecations.warn('Either monad was renamed to Result', tag: :'dry-monads')
+
 require 'dry/monads/result'
+
+module Dry
+  module Monads
+    Either = Result
+    deprecate_constant :Either
+
+    class Result
+      extend Dry::Core::Deprecations[:'dry-monads']
+
+      deprecate :to_either, :to_result
+
+      Right = Success
+      Left = Failure
+
+      deprecate_constant :Right
+      deprecate_constant :Left
+
+      module Mixin
+        module Constructors
+          extend Dry::Core::Deprecations[:'dry-monads']
+
+          Right = Success
+          Left = Failure
+          deprecate_constant :Right
+          deprecate_constant :Left
+
+          deprecate :Right, :Success
+          deprecate :Left, :Failure
+        end
+      end
+
+      class Success
+        deprecate :left?, :failure?
+        deprecate :right?, :success?
+      end
+
+      class Failure
+        deprecate :left?, :failure?
+        deprecate :right?, :success?
+
+        deprecate :left, :failure
+      end
+    end
+
+    class Try
+      class Value
+        extend Dry::Core::Deprecations[:'dry-monads']
+
+        deprecate :to_either, :to_result
+      end
+
+      class Error
+        extend Dry::Core::Deprecations[:'dry-monads']
+
+        deprecate :to_either, :to_result
+      end
+    end
+  end
+end