feat!: Enrich #value_or API

CHANGES.md

@@ -11,6 +11,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Support Ruby-3.4.X.
 - Add `Success#inspect` and `Failure#inspect` methods.
+- Support default value literal in `Failure#value_or`.
+
+### Changed
+
+- (BREAKING) `Success#value_or` requries default value or block to keep it
+  consistent with `Failure#value_or`.
 
 
 ## [0.5.2] - 2024-08-30

lib/amazing_activist/outcome/failure.rb

@@ -2,6 +2,7 @@
 
 require_relative "../polyglot"
 require_relative "../unwrap_error"
+require_relative "../undefined"
 
 module AmazingActivist
   module Outcome
@@ -22,13 +23,13 @@ class Failure
       # @param activity [AmazingActivist::Activity]
       # @param message [#to_s, nil]
       # @param exception [Exception, nil]
-      # @param context [Hash]
+      # @param context [#to_h]
       def initialize(code, activity:, message:, exception:, context:)
         @code      = code.to_sym
         @activity  = activity
         @message   = message&.to_s
         @exception = exception
-        @context   = context
+        @context   = context.to_h
       end
 
       def inspect
@@ -62,8 +63,22 @@ def deconstruct_keys(keys)
         deconstructed
       end
 
-      # @yieldparam self [self]
-      def value_or
+      # @overload value_or(default)
+      #   @param default [Object]
+      #   @return [Object] default value
+      # @overload value_or(&block)
+      #   @yieldparam self [self]
+      #   @yieldreturn [Object] result of the block
+      # @raise [ArgumentError] if neither default value, nor block given
+      def value_or(default = UNDEFINED)
+        raise ArgumentError, "either default value, or block must be given" if default == UNDEFINED && !block_given?
+
+        unless default == UNDEFINED
+          return default unless block_given?
+
+          warn "block supersedes default value argument"
+        end
+
         yield self
       end
 

lib/amazing_activist/outcome/success.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../undefined"
+
 module AmazingActivist
   module Outcome
     class Success
@@ -41,8 +43,21 @@ def deconstruct_keys(_)
         { success: @value, activity: @activity }
       end
 
-      # @return [Object]
-      def value_or
+      # @note Method requires default value or block (even though neither will
+      #   be used) to keep it consistent with {Failure#value_or}, and avoid
+      #   unpleasant surprises when code is not testing all possible outcomes.
+      #
+      # @raise [ArgumentError] if neither default value, nor block given
+      # @return [Object] unwrapped value
+      def value_or(default = UNDEFINED)
+        raise ArgumentError, "either default value, or block must be given" if default == UNDEFINED && !block_given?
+
+        unless default == UNDEFINED
+          return @value unless block_given?
+
+          warn "block supersedes default value argument"
+        end
+
         @value
       end
 

lib/amazing_activist/undefined.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module AmazingActivist
+  UNDEFINED = Object.new.freeze
+end

spec/amazing_activist/outcome/failure_spec.rb

@@ -67,12 +67,39 @@
   end
 
   describe "#value_or" do
-    it "returns result of the given block" do
-      expect(outcome.value_or { :result_of_block }).to be :result_of_block
+    it "requires either default value or a block" do
+      expect { outcome.value_or }.to raise_error(ArgumentError)
     end
 
-    it "yields control to the given block with self as a sole argument" do
-      expect { |b| outcome.value_or(&b) }.to yield_with_args(outcome)
+    context "when default value given" do
+      it "returns provided value" do
+        expect(outcome.value_or(:literal)).to be :literal
+      end
+    end
+
+    context "when block given" do
+      it "returns result of the given block" do
+        expect(outcome.value_or { :result_of_block }).to be :result_of_block
+      end
+
+      it "yields control to the given block with self as a sole argument" do
+        expect { |b| outcome.value_or(&b) }.to yield_with_args(outcome)
+      end
+    end
+
+    context "when both block, and literal given" do
+      it "returns result of the given block" do
+        expect(outcome.value_or(:literal) { :result_of_block }).to be :result_of_block
+      end
+
+      it "yields control to the given block with self as a sole argument" do
+        expect { |b| outcome.value_or(:literal, &b) }.to yield_with_args(outcome)
+      end
+
+      it "warns that block supersedes argument" do
+        expect { outcome.value_or(:literal) { :result_of_block } }
+          .to output(%r{block supersedes}).to_stderr
+      end
     end
   end
 

spec/amazing_activist/outcome/success_spec.rb

@@ -49,12 +49,39 @@
   end
 
   describe "#value_or" do
-    it "returns wrapped value" do
-      expect(outcome.value_or { Object.new }).to be value
+    it "requires either default value or a block" do
+      expect { outcome.value_or }.to raise_error(ArgumentError)
     end
 
-    it "ignores given block" do
-      expect { |b| outcome.value_or(&b) }.not_to yield_control
+    context "when default value given" do
+      it "returns actual value" do
+        expect(outcome.value_or(:literal)).to be value
+      end
+    end
+
+    context "when block given" do
+      it "returns actual value" do
+        expect(outcome.value_or { :result_of_block }).to be value
+      end
+
+      it "does not actually call it" do
+        expect { |b| outcome.value_or(&b) }.not_to yield_control
+      end
+    end
+
+    context "when both block, and literal given" do
+      it "returns actual value" do
+        expect(outcome.value_or { :result_of_block }).to be value
+      end
+
+      it "does not actually call it" do
+        expect { |b| outcome.value_or(&b) }.not_to yield_control
+      end
+
+      it "warns that block supersedes argument" do
+        expect { outcome.value_or(:literal) { :result_of_block } }
+          .to output(%r{block supersedes}).to_stderr
+      end
     end
   end
 end