dry-monads 1.7.1 → 1.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 71e72f068689b13c930f32796d5d235638fbc8f685b4274070b6e418d1bb1ec3
-  data.tar.gz: 81523f64fc36c7ddfe4f9b90490f7477ad94d43abb52d9b594b9b0bb8b1f4c1f
+  metadata.gz: 43619ae6aa239741e9730b8f824dafb848f999daea83491a78a0c3d8b4fec9f9
+  data.tar.gz: 3d2fcf419ad5b71ef88058db953b44f81d4f661796e87c88e410549b4f4340ab
 SHA512:
-  metadata.gz: f9164e029f4482abaaa3bae2111607417ba3c3867ffc44f10a6626697ffa8793d291cc96518563d2eec8950f0594814167cf04f242f6354f581873256862b672
-  data.tar.gz: 8c915830df01f6461efe56db8c38ec248cb9778270a6b5f5f1b0c2464e0cb6794806d031a62c9e47ed770f0f964b38ba461599afa40d2ac2f35ecc71904961cd
+  metadata.gz: 8991316ee0e95c6ca866b5fa7005e060af38501891080f0184c060dcf5ef81603b30816f55e1dda77e5a086e1f6ba667e313ade3be81a62db0a9a022e2aab334
+  data.tar.gz: 111db3521d27e89567df5f63862bfc7d6b07edf55ffa928583d09cba2a1a1d94278cc309cd3c254f9d1ce754c97cf3f760aea835dbd18d997bc2cac342cabf3c

data/CHANGELOG.md

@@ -1,5 +1,105 @@
 <!--- DO NOT EDIT THIS FILE - IT'S AUTOMATICALLY GENERATED VIA DEVTOOLS --->
 
+## 1.8.0 unreleased
+
+
+### Added
+
+- New extension for RSpec (@flash-gordon in #183):
+  One of the pain points of testing monads is referencing class constants from specs.
+  This extension catches missing class constants, analyzes the call site and
+  returns a matching constant.
+
+  Before, this code would raise a `NameError` because `Failure` is a constant
+  that is missing in `Object`:
+
+  ```ruby
+  example "missing constant" do
+    expect(call_operation).to eql(Failure[:some_error, "some message"])
+  end
+  ```
+
+  Now, after enabling the extension, it will return the correct constant:
+
+  ```ruby
+  Dry::Monads.load_extensions(:rspec)
+
+  example "missing constant" do
+    Failure[:some_error, "some message"] # => Failure[:some_error, "some message"]
+  end
+  ```
+
+  Out of the box, the extension will check if `Success`, `Failure`, `Some`, and
+  `None` are referenced from a file ending with `_spec.rb`.
+
+  More involved analysis is possible if you add `debug_inspector` to your Gemfile:
+
+  ```ruby
+  group :test do
+    gem "debug_inspector"
+  end
+  ```
+
+  This will allow referencing constants from other modules, such as rspec helpers.
+
+  The extension also adds new matchers for `Success`, `Failure`, `Some`, and
+  `None` values.
+
+  ```ruby
+  expect(Success(1)).to be_success
+  expect(Success(1)).to be_success(1)
+  expect(Success(1)).to be_success { |x| x > 0 }
+  expect(Success(1)).to be_a_success { |x| x > 0 }
+
+  expect(Failure(1)).to be_failure(1)
+
+  expect(Some(1)).to be_some
+  expect(Some(1)).to be_success
+
+  expect(None()).to be_none
+  expect(None()).to be_failure
+  ```
+- New extension for super_diff (@flash-gordon in #184):
+
+  Adds support for improved diff output in specs when using the super_diff gem.
+  This makes it easier to understand the differences between monad values in test failures.
+
+  To use this extension:
+  1. Add super_diff to your Gemfile's test group:
+     ```ruby
+     group :test do
+       gem "super_diff"
+     end
+     ```
+  2. Load the extension:
+     ```ruby
+     require "dry/monads"
+     Dry::Monads.load_extensions(:super_diff)
+     ```
+
+  This will change the diff output for monad values to be more readable.
+
+  Before:
+
+  ```
+  -Success({a: 2, c: 2})
+  +Success({a: 1, b: 2})
+  ```
+
+  After:
+
+  ```
+  Success(
+  -   a: 2,
+  +   a: 1,
+  -   c: 2
+  +   b: 2
+  )
+  ```
+
+
+[Compare v1.7.1...v1.8.0](https://github.com/dry-rb/dry-monads/compare/v1.7.1...v1.8.0)
+
 ## 1.7.1 2025-01-21
 
 

data/lib/dry/monads/extensions/rspec.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+require "rspec/matchers"
+
+debug_inspector_available =
+  begin
+    require "debug_inspector"
+    defined?(DebugInspector)
+  rescue LoadError
+    false
+  end
+
+module Dry
+  module Monads
+    module RSpec
+      module Matchers
+        extend ::RSpec::Matchers::DSL
+
+        {
+          failure: {
+            expected_classes: [
+              ::Dry::Monads::Result::Failure,
+              ::Dry::Monads::Maybe::None,
+              ::Dry::Monads::Try::Error
+            ],
+            extract_value: :failure.to_proc
+          },
+          success: {
+            expected_classes: [
+              ::Dry::Monads::Result::Success,
+              ::Dry::Monads::Maybe::Some,
+              ::Dry::Monads::Try::Value
+            ],
+            extract_value: :value!.to_proc
+          },
+          some: {
+            expected_classes: [
+              ::Dry::Monads::Maybe::Some
+            ],
+            extract_value: :value!.to_proc
+          }
+        }.each do |name, args|
+          args => { expected_classes:, extract_value: }
+          expected_constructors = expected_classes.map(&:name).map do |c|
+            c.split("::").last
+          end
+
+          matcher :"be_#{name}" do |expected = Undefined|
+            match do |actual|
+              if expected_classes.any? { |klass| actual.is_a?(klass) }
+                exact_match = actual.is_a?(expected_classes[0])
+
+                if exact_match && block_arg
+                  block_arg.call(extract_value.call(actual))
+                elsif Undefined.equal?(expected)
+                  true
+                elsif exact_match
+                  extract_value.call(actual) == expected
+                else
+                  false
+                end
+              else
+                false
+              end
+            end
+
+            failure_message do |actual|
+              if expected_classes.none? { |klass| actual.is_a?(klass) }
+                if expected_classes.size > 1
+                  "expected #{actual.inspect} to be one of the following values: " \
+                    "#{expected_constructors.join(", ")}, but it's #{actual.class}"
+                else
+                  "expected #{actual.inspect} to be a #{expected_constructors[0]} value, " \
+                    "but it's #{actual.class}"
+                end
+              elsif actual.is_a?(expected_classes[0]) && block_arg
+                "expected #{actual.inspect} to have a value satisfying the given block"
+              else
+                "expected #{actual.inspect} to have value #{expected.inspect}, " \
+                  "but it was #{extract_value.call(actual).inspect}"
+              end
+            end
+
+            failure_message_when_negated do |actual|
+              if expected_classes.size > 1
+                "expected #{actual.inspect} to not be one of the following values: " \
+                  "#{expected_constructors.join(", ")}, but it is"
+              else
+                "expected #{actual.inspect} to not be a #{expected_constructors[0]} value, " \
+                  "but it is"
+              end
+            end
+          end
+
+          alias_matcher :"be_a_#{name}", :"be_#{name}"
+        end
+
+        matcher :be_none do
+          match do |actual|
+            actual.is_a?(::Dry::Monads::Maybe::None)
+          end
+
+          failure_message do |actual|
+            "expected #{actual.inspect} to be none"
+          end
+
+          failure_message_when_negated do |actual|
+            "expected #{actual.inspect} to not be none"
+          end
+        end
+      end
+
+      Constructors = Monads[:result, :maybe]
+
+      CONSTANTS = %i[Success Failure Some None List].to_set
+
+      NESTED_CONSTANTS = CONSTANTS.to_set { |c| "::#{c}" }
+
+      class << self
+        def resolve_constant_name(name)
+          if CONSTANTS.include?(name)
+            name
+          elsif NESTED_CONSTANTS.any? { |c| name.to_s.end_with?(c) }
+            name[/::(\w+)$/, 1].to_sym
+          else
+            nil
+          end
+        end
+
+        def name_to_const(name)
+          case name
+          in :Success
+            ::Dry::Monads::Result::Success
+          in :Failure
+            ::Dry::Monads::Result::Failure
+          in :Some
+            ::Dry::Monads::Maybe::Some
+          in :None
+            ::Dry::Monads::Maybe::None
+          in :List
+            ::Dry::Monads::List
+          end
+        end
+      end
+    end
+  end
+end
+
+catch_missing_const = Module.new do
+  if debug_inspector_available
+    def const_missing(name)
+      const_name = Dry::Monads::RSpec.resolve_constant_name(name)
+
+      if const_name
+        DebugInspector.open do |dc|
+          if dc.frame_binding(2).receiver.is_a?(RSpec::Core::ExampleGroup)
+            Dry::Monads::RSpec.name_to_const(const_name)
+          else
+            super
+          end
+        end
+      else
+        super
+      end
+    end
+  else
+    def const_missing(name)
+      const_name = Dry::Monads::RSpec.resolve_constant_name(name)
+
+      if const_name && caller_locations(1, 1).first.path.end_with?("_spec.rb")
+        Dry::Monads::RSpec.name_to_const(const_name)
+      else
+        super
+      end
+    end
+  end
+
+  define_method(:include) do |*modules|
+    super(*modules).tap do
+      modules.each do |m|
+        m.extend(catch_missing_const) unless m.frozen?
+      end
+    end
+  end
+end
+
+Object.extend(catch_missing_const)
+
+RSpec.configure do |config|
+  config.include Dry::Monads::RSpec::Matchers
+  config.include Dry::Monads::RSpec::Constructors
+  config.extend(catch_missing_const)
+end

data/lib/dry/monads/extensions/super_diff.rb

@@ -0,0 +1,361 @@
+# frozen_string_literal: true
+
+require "delegate"
+require "super_diff"
+require "super_diff/rspec"
+
+if Gem::Version.new("0.15.0") > SuperDiff::VERSION
+  raise "SuperDiff version must be >= 0.15.0"
+end
+
+module Dry
+  module Monads
+    module SuperDiff
+      VALUES = [
+        Result::Success,
+        Result::Failure,
+        Maybe::Some,
+        Maybe::None,
+        Try::Value
+      ].freeze
+
+      EXTRACT_VALUE_MAP = {
+        Result::Success => lambda(&:value!),
+        Result::Failure => lambda(&:failure),
+        Maybe::Some => lambda(&:value!),
+        Maybe::None => lambda { |_| Unit },
+        Try::Value => lambda(&:value!)
+      }.freeze
+
+      EXTRACT_VALUE = lambda do |v|
+        EXTRACT_VALUE_MAP[v.class].(v)
+      end
+
+      IS_ARRAY = lambda do |v|
+        EXTRACT_VALUE.(v).is_a?(::Array)
+      end
+
+      IS_HASH = lambda do |v|
+        EXTRACT_VALUE.(v).is_a?(::Hash)
+      end
+
+      TOKEN_MAP = {
+        Result::Success => "Success",
+        Result::Failure => "Failure",
+        Maybe::Some => "Some",
+        Maybe::None => "None",
+        Try::Value => "Value"
+      }.freeze
+
+      class Tuple < ::SimpleDelegator
+        def is_a?(klass) = klass <= Tuple
+      end
+
+      class Dict < ::SimpleDelegator
+        def is_a?(klass) = klass <= Dict
+      end
+
+      module OTFlatteners
+        module MonasAsCollectionConstructor
+          def call = tiered_lines
+
+          protected
+
+          def build_tiered_lines = inner_lines
+
+          # prevent super_diff from adding a newline after the open token
+          # for arrays
+          def build_lines_for_non_change_operation(*)
+            @indentation_level -= 1
+            super
+          ensure
+            @indentation_level += 1
+          end
+
+          def open_token = ""
+
+          def close_token = ""
+        end
+
+        class RegularConstructor < ::SuperDiff::Basic::OperationTreeFlatteners::CustomObject
+          private
+
+          def initialize(...)
+            super
+
+            @klass = operation_tree.underlying_object.class
+          end
+
+          def open_token = "#{TOKEN_MAP[@klass]}("
+
+          def close_token = ")"
+
+          def item_prefix_for(_) = ""
+        end
+
+        class TupleConstructor < RegularConstructor
+          private
+
+          def open_token = "#{TOKEN_MAP[@klass]}["
+
+          def close_token = "]"
+        end
+
+        class Tuple < ::SuperDiff::Basic::OperationTreeFlatteners::Array
+          include MonasAsCollectionConstructor
+        end
+
+        class Dict < ::SuperDiff::Basic::OperationTreeFlatteners::Hash
+          include MonasAsCollectionConstructor
+        end
+      end
+
+      module OT
+        class RegularConstructor < ::SuperDiff::Basic::OperationTrees::CustomObject
+          def self.applies_to?(value) = VALUES.include?(value.class)
+
+          def operation_tree_flattener_class = OTFlatteners::RegularConstructor
+        end
+
+        class TupleConstructor < RegularConstructor
+          def self.applies_to?(value) = super && IS_ARRAY.call(value)
+
+          def operation_tree_flattener_class = OTFlatteners::TupleConstructor
+        end
+
+        class Tuple < ::SuperDiff::Basic::OperationTrees::Array
+          def self.applies_to?(value) = value.is_a?(::Dry::Monads::SuperDiff::Tuple)
+
+          def operation_tree_flattener_class = OTFlatteners::Tuple
+        end
+
+        class Dict < ::SuperDiff::Basic::OperationTrees::Hash
+          def self.applies_to?(value) = value.is_a?(::Dry::Monads::SuperDiff::Dict)
+
+          def operation_tree_flattener_class = OTFlatteners::Dict
+        end
+      end
+
+      module OTBuilders
+        class CompareDefault < ::SuperDiff::Basic::OperationTreeBuilders::CustomObject
+          def self.applies_to?(expected, actual)
+            VALUES.include?(expected.class) &&
+              actual.instance_of?(expected.class)
+          end
+
+          protected
+
+          def build_operation_tree
+            OT::RegularConstructor.new([], underlying_object: actual)
+          end
+
+          def attribute_names = [:value]
+
+          private
+
+          def establish_expected_and_actual_attributes
+            @expected_attributes = get_value(expected)
+            @actual_attributes = get_value(actual)
+          end
+
+          def get_value(object)
+            v = EXTRACT_VALUE.(object)
+
+            if Unit.equal?(v)
+              EMPTY_HASH
+            else
+              {value: v}
+            end
+          end
+        end
+
+        class Tuple < ::SuperDiff::Basic::OperationTreeBuilders::Array
+          def self.applies_to?(expected, actual)
+            expected.is_a?(::Dry::Monads::SuperDiff::Tuple) &&
+              actual.instance_of?(expected.class)
+          end
+
+          private
+
+          def operation_tree
+            @operation_tree ||= OT::Tuple.new([])
+          end
+        end
+
+        class Dict < ::SuperDiff::Basic::OperationTreeBuilders::Hash
+          def self.applies_to?(expected, actual)
+            expected.is_a?(::Dry::Monads::SuperDiff::Dict) &&
+              actual.instance_of?(expected.class)
+          end
+
+          private
+
+          def build_operation_tree = OT::Dict.new([])
+        end
+
+        class CompareTuples < CompareDefault
+          def self.applies_to?(expected, actual)
+            super && IS_ARRAY.call(expected) && IS_ARRAY.call(actual)
+          end
+
+          private
+
+          def get_value(object)
+            v = EXTRACT_VALUE.(object)
+
+            {value: ::Dry::Monads::SuperDiff::Tuple.new(v)}
+          end
+
+          def build_operation_tree
+            OT::TupleConstructor.new([], underlying_object: actual)
+          end
+        end
+
+        class CompareDicts < CompareDefault
+          def self.applies_to?(expected, actual)
+            super && IS_HASH.call(expected) && IS_HASH.call(actual)
+          end
+
+          private
+
+          def get_value(object)
+            v = EXTRACT_VALUE.(object)
+
+            {value: ::Dry::Monads::SuperDiff::Dict.new(v)}
+          end
+        end
+      end
+
+      module Differs
+        class CompareDefault < ::SuperDiff::Basic::Differs::CustomObject
+          def self.applies_to?(expected, actual)
+            VALUES.include?(expected.class) &&
+              expected.instance_of?(actual.class)
+          end
+
+          def operation_tree_builder_class = OTBuilders::CompareDefault
+        end
+
+        class CompareTuples < CompareDefault
+          def self.applies_to?(expected, actual)
+            super && IS_ARRAY.call(expected) && IS_ARRAY.call(actual)
+          end
+
+          def operation_tree_builder_class = OTBuilders::CompareTuples
+        end
+
+        class CompareDicts < CompareDefault
+          def self.applies_to?(expected, actual)
+            super && IS_HASH.call(expected) && IS_HASH.call(actual)
+          end
+
+          def operation_tree_builder_class = OTBuilders::CompareDicts
+        end
+      end
+
+      module ITBuilders
+        class RegularConstructor < ::SuperDiff::Basic::InspectionTreeBuilders::CustomObject
+          def self.applies_to?(object)
+            VALUES.include?(object.class)
+          end
+
+          def call
+            build_tree do |t2|
+              t2.add_text("#{TOKEN_MAP[object.class]}(")
+
+              v = EXTRACT_VALUE.(object)
+
+              unless Unit.equal?(v)
+                t2.nested do |t3|
+                  t3.add_inspection_of v
+                end
+              end
+
+              t2.add_text(")")
+            end
+          end
+
+          private
+
+          def build_tree(&block)
+            ::SuperDiff::Core::InspectionTree.new do |t1|
+              t1.as_lines_when_rendering_to_lines(
+                collection_bookend: :open, &block
+              )
+            end
+          end
+        end
+
+        class TupleConstructor < RegularConstructor
+          def self.applies_to?(object) = super && IS_ARRAY.call(object)
+
+          def call
+            build_tree do |t2|
+              t2.add_text(TOKEN_MAP[object.class])
+
+              t2.nested do |t3|
+                t3.add_inspection_of EXTRACT_VALUE.(object)
+              end
+            end
+          end
+        end
+
+        class DictConstructor < RegularConstructor
+          def self.applies_to?(object) = super && IS_HASH.call(object)
+
+          def call
+            build_tree do |t2|
+              t2.add_text("#{TOKEN_MAP[object.class]}(")
+
+              t2.nested do |t3|
+                t3.add_inspection_of ::Dry::Monads::SuperDiff::Dict.new(
+                  EXTRACT_VALUE.(object)
+                )
+              end
+
+              t2.add_text(")")
+            end
+          end
+        end
+
+        class Dict < ::SuperDiff::Basic::InspectionTreeBuilders::Hash
+          def self.applies_to?(object) = object.is_a?(::Dry::Monads::SuperDiff::Dict)
+
+          def call
+            ::SuperDiff::Core::InspectionTree.new do |t1|
+              t1.only_when empty do |t2|
+                t2.as_lines_when_rendering_to_lines do |t3|
+                  t3.add_text "{}"
+                end
+              end
+
+              t1.only_when nonempty do |t2|
+                t2.nested do |t3|
+                  t3.insert_hash_inspection_of(object)
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end
+
+SuperDiff.configuration.tap do |config|
+  config.prepend_extra_differ_classes(
+    Dry::Monads::SuperDiff::Differs::CompareTuples,
+    Dry::Monads::SuperDiff::Differs::CompareDicts,
+    Dry::Monads::SuperDiff::Differs::CompareDefault
+  )
+  config.prepend_extra_inspection_tree_builder_classes(
+    Dry::Monads::SuperDiff::ITBuilders::TupleConstructor,
+    Dry::Monads::SuperDiff::ITBuilders::DictConstructor,
+    Dry::Monads::SuperDiff::ITBuilders::RegularConstructor,
+    Dry::Monads::SuperDiff::ITBuilders::Dict
+  )
+  config.prepend_extra_operation_tree_builder_classes(
+    Dry::Monads::SuperDiff::OTBuilders::Tuple,
+    Dry::Monads::SuperDiff::OTBuilders::Dict
+  )
+end

data/lib/dry/monads/extensions.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+Dry::Monads.extend(Dry::Core::Extensions)
+
+Dry::Monads.register_extension(:rspec) do
+  require "dry/monads/extensions/rspec"
+end
+
+Dry::Monads.register_extension(:super_diff) do
+  require "dry/monads/extensions/super_diff"
+end

data/lib/dry/monads/version.rb

@@ -3,6 +3,6 @@
 module Dry
   module Monads
     # Gem version
-    VERSION = "1.7.1"
+    VERSION = "1.8.0"
   end
 end

data/lib/dry/monads.rb

@@ -6,6 +6,7 @@ require "dry/core"
 require "dry/monads/constants"
 require "dry/monads/errors"
 require "dry/monads/registry"
+require "dry/monads/extensions"
 
 module Dry
   # Common, idiomatic monads for Ruby

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dry-monads
 version: !ruby/object:Gem::Version
-  version: 1.7.1
+  version: 1.8.0
 platform: ruby
 authors:
 - Nikita Shilnikov
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-01-21 00:00:00.000000000 Z
+date: 2025-03-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -73,6 +73,9 @@ files:
 - lib/dry/monads/do/all.rb
 - lib/dry/monads/do/mixin.rb
 - lib/dry/monads/errors.rb
+- lib/dry/monads/extensions.rb
+- lib/dry/monads/extensions/rspec.rb
+- lib/dry/monads/extensions/super_diff.rb
 - lib/dry/monads/lazy.rb
 - lib/dry/monads/list.rb
 - lib/dry/monads/maybe.rb