Bump version to 1.2.0 with fold method and specs

- Add fold method to Either (Right, Left, LeftException)
- Add fold method to Maybe (Just, Nothing)
- Add comprehensive specs for fold on all types
- Fix parameter name warnings across Either, Maybe, and List

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: alex-lairan

shard.yml

@@ -1,5 +1,5 @@
 name: monads
-version: 1.1.0
+version: 1.2.0
 
 authors:
   - Alexandre Lairan <alexandrelairan+github@gmail.com>

spec/monads/either/left_exception_spec.cr

@@ -176,4 +176,14 @@ describe Monads::LeftException do
       value.should eq('a')
     end
   end
+
+  describe "#fold" do
+    it "#fold with two procs applies left_fn to exception" do
+      result = Monads::LeftException(Int32).new(DivisionByZeroError.new).fold(
+        ->(x : Int32) { "success: #{x}" },
+        ->(e : Exception) { "error: #{e.class.name}" }
+      )
+      result.should eq("error: DivisionByZeroError")
+    end
+  end
 end

spec/monads/either/left_spec.cr

@@ -219,4 +219,20 @@ describe Monads::Left do
       value.should eq('a')
     end
   end
+
+  describe "#fold" do
+    it "#fold with two procs applies left_fn to error value" do
+      result = Monads::Left(String, Int32).new("error message").fold(
+        ->(x : Int32) { "success: #{x}" },
+        ->(e : String) { "error: #{e}" }
+      )
+      result.should eq("error: error message")
+    end
+
+    it "#fold with block raises error" do
+      expect_raises(Exception, "Called fold on Left") do
+        Monads::Left(String, Int32).new("error").fold { |x| x * 2 }
+      end
+    end
+  end
 end

spec/monads/either/right_spec.cr

@@ -234,4 +234,19 @@ describe Monads::Right do
       value.should eq('a')
     end
   end
+
+  describe "#fold" do
+    it "#fold with two procs applies right_fn to value" do
+      result = Monads::Right(String, Int32).new(42).fold(
+        ->(x : Int32) { "success: #{x}" },
+        ->(e : String) { "error: #{e}" }
+      )
+      result.should eq("success: 42")
+    end
+
+    it "#fold with block applies block to value" do
+      result = Monads::Right(String, Int32).new(42).fold { |x| x * 2 }
+      result.should eq(84)
+    end
+  end
 end

spec/monads/maybe/just_spec.cr

@@ -214,4 +214,19 @@ describe Monads::Just do
       monad.should eq(Monads::Just.new(1))
     end
   end
+
+  describe "#fold" do
+    it "#fold with two procs applies just_fn to value" do
+      result = Monads::Just.new(42).fold(
+        ->(x : Int32) { "value: #{x}" },
+        ->{ "nothing" }
+      )
+      result.should eq("value: 42")
+    end
+
+    it "#fold with block applies block to value" do
+      result = Monads::Just.new(42).fold { |x| x * 2 }
+      result.should eq(84)
+    end
+  end
 end

spec/monads/maybe/nothing_spec.cr

@@ -194,4 +194,20 @@ describe Monads::Nothing do
       boolean.should be_falsey
     end
   end
+
+  describe "#fold" do
+    it "#fold with two procs applies nothing_fn" do
+      result = Monads::Nothing(Int32).new.fold(
+        ->(x : Int32) { "value: #{x}" },
+        ->{ "nothing" }
+      )
+      result.should eq("nothing")
+    end
+
+    it "#fold with block raises error" do
+      expect_raises(Exception, "Called fold on Nothing") do
+        Monads::Nothing(Int32).new.fold { |x| x * 2 }
+      end
+    end
+  end
 end

spec/monads_spec.cr

@@ -3,6 +3,6 @@ require "./monads/**"
 
 describe Monads do
   it "should have version" do
-    Monads::VERSION.should eq("1.1.0")
+    Monads::VERSION.should eq("1.2.0")
   end
 end

src/monads.cr

@@ -1,5 +1,5 @@
 require "./monads/*"
 
 module Monads
-  VERSION = "1.1.0"
+  VERSION = "1.2.0"
 end

src/monads/either.cr

@@ -26,10 +26,25 @@ module Monads
       Right(Nil, T).new(value)
     end
 
-    abstract def value_or(element : U) forall U
-    abstract def value_or(lambda : E -> U) forall U
-    abstract def or(monad : Either)
-    abstract def or(lambda : E -> U) forall U
+    # Fold/match the Either: applies right_fn if Right, left_fn if Left
+    # Returns the result of whichever function was applied
+    #
+    # Example:
+    #   result.fold(
+    #     ->(account : Account) { json_response(account) },
+    #     ->(error : AuthError) { error_response(error) }
+    #   )
+    abstract def fold(right_fn : T -> U, left_fn : E -> U) forall U
+
+    # Block version of fold
+    def fold(&block : T -> U) forall U
+      fold(block, ->(e : E) { raise "Called fold on Left" })
+    end
+
+    abstract def value_or(other : U) forall U
+    abstract def value_or(other : E -> U) forall U
+    abstract def or(other : Either)
+    abstract def or(other : E -> U) forall U
     abstract def <=>(other : Right)
     abstract def <=>(other : Left)
     abstract def map_or(default : U, lambda : T -> U) forall U
@@ -51,6 +66,10 @@ module Monads
       @data
     end
 
+    def fold(right_fn : T -> U, left_fn : E -> U) forall U
+      right_fn.call(@data)
+    end
+
     def fmap(lambda : T -> U) : Right(E, U) forall U
       Right(E, U).new(lambda.call(@data))
     end
@@ -67,15 +86,19 @@ module Monads
       1
     end
 
-    def value_or(element : _)
+    def value_or(other : _)
+      value!
+    end
+
+    def value_or(other : E -> _)
       value!
     end
 
-    def or(monad : Either)
+    def or(other : Either)
       self
     end
 
-    def or(lambda : _ -> _) : Right(E, T)
+    def or(other : _ -> _) : Right(E, T)
       self
     end
 
@@ -97,20 +120,20 @@ module Monads
       self.as(Leftable(E, U))
     end
 
-    def value_or(lambda : E -> _)
-      lambda.call(@data)
+    def value_or(other : E -> _)
+      other.call(@data)
     end
 
-    def value_or(element : U) forall U
-      element
+    def value_or(other : U) forall U
+      other
     end
 
-    def or(monad : Either)
-      monad
+    def or(other : Either)
+      other
     end
 
-    def or(lambda : E -> _)
-      lambda.call(@data)
+    def or(other : E -> _)
+      other.call(@data)
     end
 
     def bind(lambda : T -> _) : Leftable(E, T)
@@ -132,6 +155,10 @@ module Monads
       @data
     end
 
+    def fold(right_fn : T -> U, left_fn : E -> U) forall U
+      left_fn.call(@data)
+    end
+
     def <=>(other : LeftException)
       1
     end
@@ -152,20 +179,20 @@ module Monads
       Left(E, U).new(@data)
     end
 
-    def value_or(lambda : E -> _)
-      lambda.call(@data)
+    def value_or(other : E -> _)
+      other.call(@data)
     end
 
-    def value_or(element : U) forall U
-      element
+    def value_or(other : U) forall U
+      other
     end
 
-    def or(monad : Either)
-      monad
+    def or(other : Either)
+      other
     end
 
-    def or(lambda : E -> _)
-      lambda.call(@data)
+    def or(other : E -> _)
+      other.call(@data)
     end
 
     def bind(lambda : T -> _) : Left(E, T)
@@ -191,6 +218,10 @@ module Monads
       @data
     end
 
+    def fold(right_fn : T -> U, left_fn : Exception -> U) forall U
+      left_fn.call(@data)
+    end
+
     def <=>(other : LeftException)
       if @data.class == other.value!.class
         0
@@ -215,20 +246,20 @@ module Monads
       LeftException(U).new(@data)
     end
 
-    def value_or(lambda : Exception -> _)
-      lambda.call(@data)
+    def value_or(other : Exception -> _)
+      other.call(@data)
     end
 
-    def value_or(element : U) forall U
-      element
+    def value_or(other : U) forall U
+      other
     end
 
-    def or(monad : Either)
-      monad
+    def or(other : Either)
+      other
     end
 
-    def or(lambda : Exception -> _)
-      lambda.call(@data)
+    def or(other : Exception -> _)
+      other.call(@data)
     end
 
     def bind(lambda : T -> _) : LeftException(T)

src/monads/list.cr

@@ -30,8 +30,8 @@ module Monads
       end
     end
 
-    def <=>(rhs : List)
-      @value <=> rhs.to_a
+    def <=>(other : List)
+      @value <=> other.to_a
     end
 
     def unsafe_fetch(index : Int)