mangrove 0.30.1 → 0.34.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 71226a1d7d1fb7eba306e5838de3bb3f0558c5ecaaf765c4f598fbeac1177e5c
-  data.tar.gz: abce827cd50183555927cf71dbd87d04d2e42273ac71c2eeee6e7d14307ba95c
+  metadata.gz: 1dfe08aeea0151d419caef995589fe18b98674aeb78817f651d58eef0b45e552
+  data.tar.gz: 070b2971e1f62072b6e26289fe7e04f0f5527c414db63664cb76ef82c19b9ffd
 SHA512:
-  metadata.gz: 973e7abe2127c628b8fd3172f62d82103c571910269b6a0256bb6f405ae29eefbd4779bcef569369a5ab79b5a8fc1709c6ef5190f9b2af26be04eb9a8a377d39
-  data.tar.gz: 8daf78cf239f11cd7bf83efad79dfe163f42953dc7d9be08e1bf0dc6a5976db6630f5c5b037062bc2acabe69c568737819adeaea158b42b0d91188006399910b
+  metadata.gz: 75bc64b315237e3e0c44ce8245a13e4562daf2ac2444cd3aff98151869f3c3f796259b9f62ab3d3b5fc2a58749033e3839e44d86785c20f0ec1a6b3a51e23474
+  data.tar.gz: 60204fffda1d393f5d1b6b0c893c29757d66c14c149685b0e138d2b1e86926da61784315f789c45dcec549dd564cc87f0c7166f9c5f259ce9de05081d41ddac2

data/README.md

@@ -1,79 +1,124 @@
 # Mangrove
 
-Mangrove is a Ruby Gem designed to be the definitive toolkit for leveraging Sorbet's type system in Ruby applications. It's designed to offer a robust, statically-typed experience, focusing on solid types, a functional programming style, and an interface-driven approach.
+Mangrove is a Ruby toolkit that brings a functional, statically-typed flavor to your Sorbet-enabled projects. Inspired by concepts from languages like Rust and Haskell, Mangrove provides a robust set of tools—primarily `Result` and ADT-like Enums—to help you write safer, more expressive Ruby code.
 
-- [Documentation](https://kazzix14.github.io/mangrove/docs/)
-- [Coverage](https://kazzix14.github.io/mangrove/coverage/index.html#_AllFiles)
+- **[Documentation](https://kazzix14.github.io/mangrove/docs/)**
+- **[Coverage](https://kazzix14.github.io/mangrove/coverage/index.html#_AllFiles)**
 
-## Features
+---
 
-- Option Type
-- Result Type
-- Enums with inner types (ADTs)
+## Highlights
+
+- **Sorbet Integration**
+  Built from the ground up to work smoothly with Sorbet’s type system.
+
+- **Result Type**
+  Model success/failure outcomes with explicit types—no more “return false or nil” for errors!
+
+- **Enums (ADTs)**
+  Define your own sealed enums with typed variants. Each variant can hold distinct inner data.
+
+- **Functional Patterns**
+  Chain transformations or short-circuit error handling with a clean monadic style.
+
+---
 
 ## Installation
 
-```
+```bash
 bundle add mangrove
 ```
 
-## Usage
+---
+
+## Usage Overview
+
+Mangrove revolves around **`Result`** and a sealed “Enum” mechanism for ADTs.
+
+### Result
+
+A `Result` is either `Ok(T)` or `Err(E)`. You can compose them with monadic methods like `and_then` and `or_else`.
+For “early returns” in a functional style, you have two main approaches:
 
-[Documentation is available here](https://kazzix14.github.io/mangrove/docs).
-For more concrete examples, see [`spec/**/**_spec.rb`](https://github.com/kazzix14/mangrove/tree/main/spec).
+1. **A context-based DSL (e.g., `ctx.try!`)**
+2. **An instance method on `Result` itself, `unwrap_in(ctx)`**, which behaves similarly.
+
+Here’s an example of chaining requests and short-circuiting on error:
 
 ```ruby
-Mangrove::Result[OkType, ErrType]
-Mangrove::Result::Ok[OkType, ErrType]
-Mangrove::Result::Err[OkType, ErrType]
-Mangrove::Option[InnerType]
-Mangrove::Option::Some[InnerType]
-Mangrove::Option::None[InnerType]
-
-my_ok = Result::Ok.new("my value")
-my_err = Result::Err.new("my err")
-my_some = Option::Some.new(1234)
-my_none = Option::None.new
-
-##############################
-
-response = MyClient
-  .new
-  .and_then { |client| client.get_response() }
-  .and_then { |response| response.body }
-
-case response
-when Mangrove::Result::Ok
-  puts response.ok_inner
-when Mangrove::Result::Err
-  puts response.err_inner
+class MyClient
+  extend T::Sig
+
+  sig { returns(Mangrove::Result[String, StandardError]) }
+  def connect
+    # ...
+    Mangrove::Result::Ok.new("Connected")
+  end
+
+  sig { params(data: String).returns(Mangrove::Result[String, StandardError]) }
+  def request(data)
+    # ...
+    Mangrove::Result::Ok.new("Response: #{data}")
+  end
+end
+
+# Let's say we have a special DSL context for collecting short-circuits:
+# (Hypothetical usage)
+
+Result.collecting(String, StandardError) do |ctx|
+  final_result = MyClient.new
+    .connect
+    .and_then do |connection|
+      MyClient.new.request("Payload from #{connection}")
+    end
+
+  # Option 1: Call from the context
+  response_data = ctx.try!(final_result)
+  # => If 'final_result' is Err, short-circuits now;
+  #    otherwise returns the Ok(T) value.
+
+  puts response_data  # If no errors, prints "Response: Connected"
+
+  # Option 2: Call via 'unwrap_in(ctx)'
+  # This does the same short-circuit if 'Err', using the context:
+  response_data_alt = final_result.unwrap_in(ctx)
 end
 
-##############################
+# More chaining, etc...
+```
+
+### Enums (ADTs)
+
+Define an enum with typed variants:
 
+```ruby
 class MyEnum
   extend Mangrove::Enum
 
   variants do
-    variant VariantWithInteger, Integer
-    variant VariantWithString, String
-    variant VariantWithException, Exception
-    variant VariantWithTuple, [Integer, String]
-    variant VariantWithShape, { name: String, age: Integer }
+    variant IntVariant, Integer
+    variant StrVariant, String
+    variant ShapeVariant, { name: String, age: Integer }
   end
 end
+
+int_v = MyEnum::IntVariant.new(123)
+puts int_v.inner  # => 123
 ```
 
+For more details on monadic methods, short-circuit contexts, and advanced usage, please visit the [official documentation](https://kazzix14.github.io/mangrove/docs/) or see real-world usages in [`spec/`](https://github.com/kazzix14/mangrove/tree/main/spec).
+
+---
+
 ## Commands for Development
 
-```
+```bash
 git config core.hooksPath hooks
 bundle install
 bundle exec tapioca init
 bundle exec tapioca gems -w `nproc`
 bundle exec tapioca dsl -w `nproc`
 bundle exec tapioca check-shims
-bundle exec tapioca init
 bundle exec rspec -f d
 bundle exec rubocop -DESP
 bundle exec srb typecheck
@@ -85,3 +130,22 @@ bundle exec yard server --reload --plugin yard-sorbet
 rake build
 rake release
 ```
+
+Run these commands to maintain code quality, generate documentation, and verify type safety under Sorbet.
+
+---
+
+## Contributing
+
+We welcome contributions! To get started:
+
+1. Fork & clone the repo
+2. Install dependencies: `bundle install`
+3. Make your changes and add tests
+4. Submit a PR
+
+---
+
+## License
+
+Mangrove is available under the [MIT License](https://opensource.org/licenses/MIT). See the LICENSE file for details.

data/lib/mangrove/result.rb

@@ -42,6 +42,9 @@ module Mangrove
     sig { abstract.returns(OkType) }
     def unwrap_or_raise_inner!; end
 
+    sig { abstract.params(ctx: Result::CollectingContext[OkType, ErrType]).returns(OkType) }
+    def unwrap_in(ctx); end
+
     sig { abstract.params(message: String).returns(OkType) }
     def expect!(message); end
 
@@ -66,6 +69,12 @@ module Mangrove
     sig { abstract.type_parameters(:NewErrType).params(_t_new_err: T::Class[T.type_parameter(:NewErrType)], block: T.proc.params(this: ErrType).returns(T.type_parameter(:NewErrType))).returns(Result[OkType, T.type_parameter(:NewErrType)]) }
     def map_err_wt(_t_new_err, &block); end
 
+    sig { abstract.params(block: T.proc.params(this: OkType).void).returns(Result[OkType, ErrType]) }
+    def tap_ok(&block); end
+
+    sig { abstract.params(block: T.proc.params(this: ErrType).void).returns(Result[OkType, ErrType]) }
+    def tap_err(&block); end
+
     sig { abstract.type_parameters(:NewOkType, :NewErrType).params(other: Result[T.type_parameter(:NewOkType), T.type_parameter(:NewErrType)]).returns(T.any(Result[T.type_parameter(:NewOkType), T.type_parameter(:NewErrType)], Result[T.type_parameter(:NewOkType), ErrType])) }
     def and(other); end
 
@@ -151,6 +160,43 @@ module Mangrove
       def err_wt(_t_ok, inner)
         Result::Err[T.type_parameter(:ErrType)].new(inner)
       end
+
+      sig {
+        type_parameters(:O, :E)
+          .params(
+            _t_ok: T::Class[T.type_parameter(:O)],
+            _t_err: T::Class[T.type_parameter(:E)],
+            block: T.proc.params(
+              do_block: CollectingContext[T.type_parameter(:O), T.type_parameter(:E)]
+            ).returns(Mangrove::Result[T.type_parameter(:O), T.type_parameter(:E)])
+          )
+          .returns(Mangrove::Result[T.type_parameter(:O), T.type_parameter(:E)])
+      }
+      def collecting(_t_ok, _t_err, &block)
+        catch(:__mangrove_result_collecting_context_return) {
+          block.call(CollectingContext[T.type_parameter(:O), T.type_parameter(:E)].new)
+        }
+      end
+    end
+
+    class CollectingContext
+      extend T::Sig
+      extend T::Generic
+
+      O = type_member
+      E = type_member
+
+      sig { params(result: Mangrove::Result[O, E]).returns(O) }
+      def try!(result)
+        case result
+        when Mangrove::Result::Ok
+          result.ok_inner
+        when Mangrove::Result::Err
+          throw :__mangrove_result_collecting_context_return, result
+        else
+          T.absurd(result)
+        end
+      end
     end
 
     class Ok
@@ -206,6 +252,11 @@ module Mangrove
         @inner
       end
 
+      sig { override.params(_ctx: Result::CollectingContext[OkType, ErrType]).returns(OkType) }
+      def unwrap_in(_ctx)
+        @inner
+      end
+
       sig { override.params(_message: String).returns(OkType) }
       def expect!(_message)
         @inner
@@ -256,6 +307,17 @@ module Mangrove
         self
       end
 
+      sig { override.params(block: T.proc.params(this: OkType).void).returns(Result[OkType, ErrType]) }
+      def tap_ok(&block)
+        block.call(@inner)
+        self
+      end
+
+      sig { override.params(_block: T.proc.params(this: ErrType).void).returns(Result[OkType, ErrType]) }
+      def tap_err(&_block)
+        self
+      end
+
       sig { override.type_parameters(:NewOkType, :NewErrType).params(other: Result[T.type_parameter(:NewOkType), T.type_parameter(:NewErrType)]).returns(Result[T.type_parameter(:NewOkType), T.type_parameter(:NewErrType)]) }
       def and(other)
         other
@@ -381,6 +443,11 @@ module Mangrove
         raise T.unsafe(@inner)
       end
 
+      sig { override.params(_ctx: Result::CollectingContext[OkType, ErrType]).returns(T.noreturn) }
+      def unwrap_in(_ctx)
+        throw :__mangrove_result_collecting_context_return, self
+      end
+
       sig { override.params(message: String).returns(OkType) }
       def expect!(message)
         raise Result::ControlSignal, message
@@ -429,6 +496,17 @@ module Mangrove
         Result::Err[T.type_parameter(:NewErrType)].new(block.call(@inner))
       end
 
+      sig { override.params(_block: T.proc.params(this: OkType).void).returns(Result[OkType, ErrType]) }
+      def tap_ok(&_block)
+        self
+      end
+
+      sig { override.params(block: T.proc.params(this: ErrType).void).returns(Result[OkType, ErrType]) }
+      def tap_err(&block)
+        block.call(@inner)
+        self
+      end
+
       sig { override.type_parameters(:NewOkType, :NewErrType).params(_other: Result[T.type_parameter(:NewOkType), T.type_parameter(:NewErrType)]).returns(Result[T.type_parameter(:NewOkType), ErrType]) }
       def and(_other)
         self

data/lib/mangrove/version.rb

@@ -2,5 +2,5 @@
 # frozen_string_literal: true
 
 module Mangrove
-  VERSION = "0.30.1"
+  VERSION = "0.34.0"
 end

data/lib/tapioca/dsl/compilers/mangrove_enum.rb

@@ -48,7 +48,13 @@ module Tapioca
             inner_type
           }
 
-          constant_type.create_method("inner", return_type: "T.any(#{inner_types.join(", ")})")
+          return_type = if inner_types.size == 1
+                          T.must(inner_types.first)
+                        else
+                          "T.any(#{inner_types.join(", ")})"
+                        end
+
+          constant_type.create_method("inner", return_type:)
           constant_type.create_method("as_super", return_type: constant.name.to_s)
           constant_type.sort_nodes!
         }

data/sorbet/config

@@ -3,3 +3,4 @@
 --ignore=tmp/
 --ignore=vendor/
 --enable-experimental-requires-ancestor
+--disable-watchman