djk_monads 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 351088f4c8de33dd072afb7fa93ef5cdbeb4bed569dde6bc1c8e4ef147f3d1d6
+  data.tar.gz: ba3766f358d52203f3de0fca4571804b5bfa0923572a896c0259147f7f2929c7
+SHA512:
+  metadata.gz: 100910e5eeb79c53b5c21fac1eb9d645848b49524c80447ed7530b437b7a1b6f80c4d7c4e83dbeb2751414217ece7718304002a2583bd5fc440b88c412be1ac5
+  data.tar.gz: 0c7eef839bba5d57f6d4cb233de7a8503de1fb3faadebda36646ce1294be648cca1f77b8f658c4735c16773e5267502b7a3071d27d5aca2b791554460421b458

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-09-25
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+DJK Monads follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behavior within this project, please contact me at ["dan@dankotowski.dev"](mailto:"dan@dankotowski.dev").

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Dan Kotowski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,157 @@
+# DJK Monads [![Tests](https://github.com/djkotowski/djk_monads/actions/workflows/ci.yml/badge.svg)](https://github.com/djkotowski/djk_monads/actions/workflows/ci.yml)
+
+Rust-style `Result` and `Option` monads for Ruby.
+
+- **`Result`**: the outcome of an operation that either succeeds with a value (`Ok`) or fails with an error (`Err`).
+- **`Option`**: a value that is either present (Some) or absent (None).
+
+Both support chaining (`map`, `flat_map`), unwrapping with fallbacks, and pattern matching.
+
+## Requirements
+
+Ruby 4.0 or newer.
+
+## Installation
+
+The gem hasn't been published to RubyGems yet. Install it from GitHub by adding it to your Gemfile:
+
+```ruby
+gem "djk_monads", github: "djkotowski/djk_monads"
+```
+
+Then require it:
+
+```ruby
+require "djk"
+
+include DJK::Monads # optional, lets you write Result and Option unqualified
+```
+
+To use the types without the namespace everywhere, define them as top-level constants instead:
+
+```ruby
+DJK::Monads.apply_aliases!
+# => [:ReturnError, :Err, :Ok, :Option, :Result]
+```
+
+This defines `ReturnError`, `Err`, `Ok`, `Option` and `Result` at the top level. Any of those names that's already defined is left alone and left out of the returned list, and a warning naming it is printed to stderr.
+
+## Usage
+
+### Result
+
+Build results with `Result.ok`, `Result.err` or `Result.from`. Don't instantiate `Ok` or `Err` directly.
+
+```ruby
+Result.ok(1).map { it + 1 }
+# => Ok<2>
+
+Result.err("boom").unwrap_or(0)
+# => 0
+
+# Result.from runs the block and wraps any StandardError it raises in an Err
+Result.from { Integer("oops") }.map_err(&:message)
+# => Err<"invalid value for Integer(): \"oops\"">
+```
+
+Chain operations that can fail with `flat_map`. The block must return a `Result`, or a `DJK::Monads::ReturnError` is raised:
+
+```ruby
+Result.ok(2).flat_map { |n| n.even? ? Result.ok(n / 2) : Result.err("odd") }
+# => Ok<1>
+```
+
+Pattern match on the variant:
+
+```ruby
+case Result.from { Integer("42") }
+in Ok[value] then value
+in Err[error] then error.message
+end
+# => 42
+```
+
+Hash patterns work too, with `in Ok[value:]` and `in Err[error:]`.
+
+#### Instance methods
+
+| Method | `Ok` | `Err` |
+| --- | --- | --- |
+| `ok?` / `err?` | `true` / `false` | `false` / `true` |
+| `map { }` | wraps the block's return value in `Ok` | returns `self` |
+| `map_err { }` | returns `self` | wraps the block's return value in `Err` |
+| `flat_map { }` | returns the block's `Result` | returns `self` |
+| `flat_map_err { }` | returns `self` | returns the block's `Result` |
+| `on_ok { }` / `on_err { }` | runs the block for side effects, returns `self` | same |
+| `flatten` | returns the innermost nested `Result` | same |
+| `unwrap!` | returns the value | raises the wrapped error |
+| `unwrap_err!` | raises `ReturnError` | returns the error |
+| `unwrap_or(default)` | returns the value | returns `default` |
+| `unwrap_or_else { \|error\| }` | returns the value | returns the block's return value |
+| `to_h` | `{ variant: :ok, value: }` | `{ variant: :err, error: }` |
+
+`map` does not flatten: if its block returns a `Result`, you get a nested result. Use `flat_map`, or call `flatten`.
+
+`Err#unwrap!` raises the wrapped error as is, so it works best when the error is an exception or a message string.
+
+#### Working with collections
+
+```ruby
+# Split results into their values and their errors
+Result.partition([Result.ok(1), Result.err("boom"), Result.ok(2)])
+# => [[1, 2], ["boom"]]
+
+# Map each element to a Result and collect the values, stopping at the first Err
+Result.traverse(%w[1 2 3]) { |s| Result.from { Integer(s) } }
+# => Ok<[1, 2, 3]>
+
+Result.traverse(%w[1 x 3]) { |s| Result.from { Integer(s) } }.map_err(&:message)
+# => Err<"invalid value for Integer(): \"x\"">
+
+# Remove every Ok wrapping nil
+Result.compact([Result.ok(nil), Result.ok(1), Result.err(nil)])
+# => [Ok<1>, Err<nil>]
+```
+
+### Option
+
+Build options with `Option.some`, `Option.none` or `Option.from`. None is a single shared instance, and a Some can never wrap `nil`. `Option.some(nil)` raises `ArgumentError`.
+
+```ruby
+Option.from(nil).map { it + 1 }.unwrap_or(0)
+# => 0
+
+Option.from({ a: 1 }[:a]).map { it * 10 }.unwrap!
+# => 10
+
+Option.none.or_else { Option.some(5) }.unwrap!
+# => 5
+
+# Convert to a Result
+Option.from(nil).ok_or("missing")
+# => Err<"missing">
+
+# Raise your own error instead of Option::NoneError
+Option.none.expect(KeyError.new("no key"))
+# raises KeyError: no key
+```
+
+`Option#map` returns None when the block returns `nil`. `flat_map` and `or_else` blocks must return an `Option`, or a `DJK::Monads::ReturnError` is raised.
+
+Other methods: `some?`, `none?`, `unwrap_or_else { }` and `to_a` (`[value]` for a Some, `[]` for None).
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then run `bundle exec rake` to run the specs and RuboCop. CI also checks formatting with `bin/stree check`. `bin/console` opens an interactive prompt with the gem loaded.
+
+Formatting uses [Syntax Tree](https://github.com/ruby-syntax-tree/syntax_tree) (`bin/stree write`) and [RuboCop](https://rubocop.org) (`bin/rubocop -a`). A [lefthook](https://github.com/evilmartians/lefthook) pre-commit hook runs both on staged files. Run `bundle exec lefthook install` to enable it.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `lib/djk/monads/version.rb`, then run `bundle exec rake release`. That creates a git tag for the version, pushes the commits and the tag, and pushes the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/djkotowski/djk_monads. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/djkotowski/djk_monads/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/djk/monads/err.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require_relative "result"
+
+module DJK
+  module Monads
+    # The failed variant of a Result, wrapping an error.
+    #
+    # The error can be any object. Calling +unwrap!+ raises it, so an exception or a message string works best.
+    #
+    # @example
+    #   Result.err("boom").unwrap_or(0)
+    #   # => 0
+    class Err < Result
+      # @param error [Object] the error to wrap
+      def initialize(error)
+        super()
+        @error = error
+      end
+
+      # @param other [Object] the object to compare against
+      # @return [Boolean] true if +other+ is an Err wrapping an error equal to this one
+      def ==(other)
+        return false unless other.is_a?(Result) && other.err?
+
+        error == other.unwrap_err!
+      end
+
+      # @return [Array(Object)] the wrapped error in a single element array
+      def deconstruct
+        [error]
+      end
+
+      # @param _keys [Array<Symbol>, nil] ignored, every key is always returned
+      # @return [Hash{Symbol => Object}] the wrapped error under +:error+
+      def deconstruct_keys(_keys)
+        { error: }
+      end
+
+      # @return [Boolean] always true
+      def err?
+        true
+      end
+
+      # Collapses nested results, returning the innermost one.
+      #
+      # @return [Result] the innermost result when the error is a Result, otherwise +self+
+      def flatten
+        return self unless error.is_a?(Result)
+
+        error.flatten
+      end
+
+      # Does nothing, since there is no value to chain from.
+      #
+      # @return [Err] +self+, without calling the block
+      def flat_map(&)
+        self
+      end
+
+      # Chains another result producing operation onto the wrapped error.
+      #
+      # @yieldparam error [Object] the wrapped error
+      # @yieldreturn [Result] must return a Result
+      # @raise [ReturnError] when the block does not return a Result
+      # @return [Result] the result returned by the block
+      def flat_map_err
+        yield(error).tap { raise ReturnError, "block must return a Result" unless it.is_a?(Result) }
+      end
+
+      # @return [String] the inspected error wrapped in <tt>Err<></tt>, such as <tt>Err<"boom"></tt>
+      def inspect
+        "Err<#{error.inspect}>"
+      end
+
+      # Does nothing, since there is no value to transform.
+      #
+      # @return [Err] +self+, without calling the block
+      def map
+        self
+      end
+
+      # Transforms the wrapped error.
+      #
+      # @yieldparam error [Object] the wrapped error
+      # @return [Err] an Err wrapping the block's return value, which is not flattened when it is itself a Result
+      def map_err
+        Result.err(yield(error))
+      end
+
+      # @return [Boolean] always false
+      def ok?
+        false
+      end
+
+      # Runs the block with the wrapped error for its side effects.
+      #
+      # @yieldparam error [Object] the wrapped error
+      # @return [Err] +self+, ignoring the block's return value
+      def on_err
+        yield error
+        self
+      end
+
+      # Does nothing, since there is no value.
+      #
+      # @return [Err] +self+, without calling the block
+      def on_ok
+        self
+      end
+
+      # @return [Hash{Symbol => Object}] the +:err+ variant along with the wrapped error
+      def to_h
+        { variant: :err, error: }
+      end
+
+      # Always raises the wrapped error, since there is no value to unwrap.
+      #
+      # An exception is raised as is, and a string is raised as a RuntimeError with that message. Any other object
+      # makes +raise+ fail with a TypeError.
+      #
+      # @raise [Exception] the wrapped error
+      def unwrap!
+        raise error
+      end
+
+      # @return [Object] the wrapped error
+      def unwrap_err!
+        error
+      end
+
+      # @param default [Object] the value to return
+      # @return [Object] +default+
+      def unwrap_or(default)
+        default
+      end
+
+      # @yieldparam error [Object] the wrapped error
+      # @return [Object] the block's return value
+      def unwrap_or_else
+        yield error
+      end
+
+      private
+
+      attr_reader :error
+    end
+  end
+end

data/lib/djk/monads/ok.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require_relative "result"
+
+module DJK
+  module Monads
+    # The successful variant of a Result, wrapping a value.
+    #
+    # @example
+    #   Result.ok(1).unwrap!
+    #   # => 1
+    class Ok < Result
+      # @param value [Object] the value to wrap
+      def initialize(value)
+        super()
+        @value = value
+      end
+
+      # @param other [Object] the object to compare against
+      # @return [Boolean] true if +other+ is an Ok wrapping a value equal to this one
+      def ==(other)
+        return false unless other.is_a?(Result) && other.ok?
+
+        value == other.unwrap!
+      end
+
+      # @return [Array(Object)] the wrapped value in a single element array
+      def deconstruct
+        [value]
+      end
+
+      # @param _keys [Array<Symbol>, nil] ignored, every key is always returned
+      # @return [Hash{Symbol => Object}] the wrapped value under +:value+
+      def deconstruct_keys(_keys)
+        { value: }
+      end
+
+      # @return [Boolean] always false
+      def err?
+        false
+      end
+
+      # Collapses nested results, returning the innermost one.
+      #
+      # @return [Result] the innermost result when the value is a Result, otherwise +self+
+      def flatten
+        return self unless value.is_a?(Result)
+
+        value.flatten
+      end
+
+      # Chains another result producing operation onto the wrapped value.
+      #
+      # @yieldparam value [Object] the wrapped value
+      # @yieldreturn [Result] must return a Result
+      # @raise [ReturnError] when the block does not return a Result
+      # @return [Result] the result returned by the block
+      def flat_map
+        yield(value).tap { raise ReturnError, "block must return a Result" unless it.is_a?(Result) }
+      end
+
+      # Does nothing, since there is no error to chain from.
+      #
+      # @return [Ok] +self+, without calling the block
+      def flat_map_err
+        self
+      end
+
+      # @return [String] the inspected value wrapped in <tt>Ok<></tt>, such as <tt>Ok<1></tt>
+      def inspect
+        "Ok<#{value.inspect}>"
+      end
+
+      # Transforms the wrapped value.
+      #
+      # @yieldparam value [Object] the wrapped value
+      # @return [Ok] an Ok wrapping the block's return value, which is not flattened when it is itself a Result
+      def map
+        Result.ok(yield(value))
+      end
+
+      # Does nothing, since there is no error to transform.
+      #
+      # @return [Ok] +self+, without calling the block
+      def map_err
+        self
+      end
+
+      # @return [Boolean] always true
+      def ok?
+        true
+      end
+
+      # Does nothing, since there is no error.
+      #
+      # @return [Ok] +self+, without calling the block
+      def on_err(&)
+        self
+      end
+
+      # Runs the block with the wrapped value for its side effects.
+      #
+      # @yieldparam value [Object] the wrapped value
+      # @return [Ok] +self+, ignoring the block's return value
+      def on_ok
+        yield(value)
+        self
+      end
+
+      # @return [Hash{Symbol => Object}] the +:ok+ variant along with the wrapped value
+      def to_h
+        { variant: :ok, value: }
+      end
+
+      # @return [Object] the wrapped value
+      def unwrap!
+        value
+      end
+
+      # Always raises, since there is no error to unwrap.
+      #
+      # @raise [ReturnError] always
+      def unwrap_err!
+        raise ReturnError, "cannot unwrap_err! on Ok"
+      end
+
+      # @param _default [Object] ignored
+      # @return [Object] the wrapped value
+      def unwrap_or(_default)
+        value
+      end
+
+      # @return [Object] the wrapped value, without calling the block
+      def unwrap_or_else(&)
+        value
+      end
+
+      private
+
+      attr_reader :value
+    end
+  end
+end

data/lib/djk/monads/option.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require "singleton"
+
+module DJK
+  module Monads
+    # An optional value that is either present (Some) or absent (None).
+    #
+    # Build options with Option.some, Option.none, or Option.from. None is a single shared instance, and a Some can
+    # never wrap +nil+.
+    #
+    # @example
+    #   Option.from(1).map { it + 1 }.unwrap_or(0)
+    #   # => 2
+    #
+    #   Option.from(nil).map { it + 1 }.unwrap_or(0)
+    #   # => 0
+    class Option
+      include Singleton
+
+      # Raised by +unwrap!+ when called on None.
+      class NoneError < StandardError
+      end
+
+      # @api private
+      # @param value [Object, nil] the value to wrap, or +nil+ for None
+      def initialize(value: nil)
+        @value = value
+      end
+
+      # @param other [Object] the object to compare against
+      # @return [Boolean] true if both are None, or both are a Some wrapping equal values
+      def ==(other)
+        return false unless other.is_a?(Option)
+        return false if some? && other.none?
+        return true if none? && other.none?
+
+        value == other.unwrap!
+      end
+
+      # Returns the wrapped value, raising +error+ instead of a NoneError when the option is None.
+      #
+      # @param error [Exception, String] the error to raise for None
+      # @raise [Exception] +error+ when the option is None
+      # @return [Object] the wrapped value
+      def expect(error)
+        unwrap!
+      rescue NoneError
+        raise error
+      end
+
+      # Chains another option producing operation onto a Some, passing through None untouched.
+      #
+      # @yieldparam value [Object] the wrapped value, only for a Some
+      # @yieldreturn [Option] must return an Option
+      # @raise [ReturnError] when the block does not return an Option
+      # @return [Option] the option returned by the block, or +self+ when the receiver is None
+      def flat_map
+        return self if none?
+
+        yield(value).tap { raise ReturnError, "block must return an Option" unless it.is_a?(Option) }
+      end
+
+      # Transforms the value of a Some, passing through None untouched.
+      #
+      # @yieldparam value [Object] the wrapped value, only for a Some
+      # @return [Option] a Some wrapping the block's return value, None when the block returns +nil+, or +self+ when
+      #   the receiver is None
+      def map
+        return self if none?
+
+        Option.from(yield(value))
+      end
+
+      # Converts the option into a Result.
+      #
+      # @param error [Object] the error to wrap when the option is None
+      # @return [Ok, Err] an Ok wrapping the value of a Some, or an Err wrapping +error+ for None
+      def ok_or(error)
+        some? ? Result.ok(value) : Result.err(error)
+      end
+
+      # Falls back to another option when the receiver is None.
+      #
+      # @yieldreturn [Option] must return an Option, only called for None
+      # @raise [ReturnError] when the block does not return an Option
+      # @return [Option] +self+ for a Some, or the option returned by the block for None
+      def or_else
+        some? ? self : yield.tap { raise ReturnError, "block must return an Option" unless it.is_a?(Option) }
+      end
+
+      # @return [Boolean] true if the option is None
+      def none?
+        value.nil?
+      end
+
+      # @return [Boolean] true if the option is a Some
+      def some?
+        !none?
+      end
+
+      # Returns the wrapped value, raising when the option is None.
+      #
+      # @raise [NoneError] when the option is None
+      # @return [Object] the wrapped value
+      def unwrap!
+        raise NoneError, "unwrap! called on None" if none?
+
+        value
+      end
+
+      # Returns the wrapped value, falling back to +default+ when the option is None.
+      #
+      # @param default [Object] the value to return for None
+      # @return [Object] the wrapped value or +default+
+      def unwrap_or(default)
+        none? ? default : value
+      end
+
+      # Returns the wrapped value, falling back to the block's return value when the option is None.
+      #
+      # @yieldreturn [Object] the value to return, only called for None
+      # @return [Object] the wrapped value or the block's return value
+      def unwrap_or_else
+        none? ? yield : value
+      end
+
+      # @return [Array] the wrapped value in a single element array for a Some, or an empty array for None
+      def to_a
+        some? ? [value] : []
+      end
+
+      # Wraps a value that may be +nil+.
+      #
+      # @param value [Object, nil] the value to wrap
+      # @return [Option] None when +value+ is +nil+, otherwise a Some wrapping +value+
+      def self.from(value)
+        value.nil? ? none : some(value)
+      end
+
+      # @return [Option] the shared None instance
+      def self.none = instance
+
+      # Wraps a value that must not be +nil+.
+      #
+      # @param value [Object] the value to wrap
+      # @raise [ArgumentError] when +value+ is +nil+
+      # @return [Option] a Some wrapping +value+
+      def self.some(value)
+        raise ArgumentError, "value cannot be nil" if value.nil?
+
+        new(value:)
+      end
+
+      private
+
+      attr_reader :value
+    end
+  end
+end

data/lib/djk/monads/result.rb

@@ -0,0 +1,237 @@
+# frozen_string_literal: true
+
+module DJK
+  module Monads
+    # The outcome of an operation that can either succeed with a value (Ok) or fail with an error (Err).
+    #
+    # Build results with Result.ok, Result.err, or Result.from rather than instantiating the subclasses directly.
+    #
+    # @abstract Subclassed by Ok and Err, which implement every instance method.
+    # @example
+    #   Result.ok(1).map { it + 1 }
+    #   # => Ok<2>
+    #
+    #   case Result.from { Integer("oops") }
+    #   in Ok[value] then value
+    #   in Err[error] then error.message
+    #   end
+    #   # => "invalid value for Integer(): \"oops\""
+    class Result
+      # Compares this result with another object.
+      #
+      # @abstract
+      # @param other [Object] the object to compare against
+      # @return [Boolean] true if +other+ is a Result of the same variant wrapping an equal value
+      def ==(other)
+      end
+
+      # Destructures the result for array patterns, exposing the wrapped value or error.
+      #
+      # @abstract
+      # @return [Array] a single element array holding the value (Ok) or the error (Err)
+      def deconstruct
+      end
+
+      # Destructures the result for hash patterns.
+      #
+      # @abstract
+      # @param keys [Array<Symbol>, nil] the keys requested by the pattern
+      # @return [Hash] the wrapped value or error keyed by variant
+      def deconstruct_keys(keys)
+      end
+
+      # @abstract
+      # @return [Boolean] true if the result is an Err
+      def err?
+      end
+
+      # Collapses a result wrapping another result into a single result.
+      #
+      # @abstract
+      # @return [Result] the innermost result, or +self+ when nothing is nested
+      def flatten
+      end
+
+      # Chains another result producing operation onto an Ok, passing through an Err untouched.
+      #
+      # @abstract
+      # @yieldparam value [Object] the wrapped value, only for an Ok
+      # @yieldreturn [Result] must return a Result
+      # @return [Result] the result returned by the block, or +self+ when the receiver is an Err
+      def flat_map
+      end
+
+      # Chains another result producing operation onto an Err, passing through an Ok untouched.
+      #
+      # @abstract
+      # @yieldparam error [Object] the wrapped error, only for an Err
+      # @yieldreturn [Result] must return a Result
+      # @return [Result] the result returned by the block, or +self+ when the receiver is an Ok
+      def flat_map_err
+      end
+
+      # @abstract
+      # @return [String] a human readable representation of the result
+      def inspect
+      end
+
+      # Transforms the value of an Ok, passing through an Err untouched.
+      #
+      # @abstract
+      # @yieldparam value [Object] the wrapped value, only for an Ok
+      # @return [Result] an Ok wrapping the block's return value, or +self+ when the receiver is an Err
+      def map
+      end
+
+      # Transforms the error of an Err, passing through an Ok untouched.
+      #
+      # @abstract
+      # @yieldparam error [Object] the wrapped error, only for an Err
+      # @return [Result] an Err wrapping the block's return value, or +self+ when the receiver is an Ok
+      def map_err
+      end
+
+      # @abstract
+      # @return [Boolean] true if the result is an Ok
+      def ok?
+      end
+
+      # Runs the block for its side effects when the result is an Err.
+      #
+      # @abstract
+      # @yieldparam error [Object] the wrapped error, only for an Err
+      # @return [Result] +self+
+      def on_err
+      end
+
+      # Runs the block for its side effects when the result is an Ok.
+      #
+      # @abstract
+      # @yieldparam value [Object] the wrapped value, only for an Ok
+      # @return [Result] +self+
+      def on_ok
+      end
+
+      # @abstract
+      # @return [Hash] the result's variant along with its value or error
+      def to_h
+      end
+
+      # Returns the wrapped value, raising when the result is an Err.
+      #
+      # @abstract
+      # @raise [Object] the wrapped error when the result is an Err
+      # @return [Object] the wrapped value
+      def unwrap!
+      end
+
+      # Returns the wrapped error, raising when the result is an Ok.
+      #
+      # @abstract
+      # @raise [ReturnError] when the result is an Ok
+      # @return [Object] the wrapped error
+      def unwrap_err!
+      end
+
+      # Returns the wrapped value, falling back to +default+ when the result is an Err.
+      #
+      # @abstract
+      # @param default [Object] the value to return for an Err
+      # @return [Object] the wrapped value or +default+
+      def unwrap_or(default)
+      end
+
+      # Returns the wrapped value, falling back to the block's return value when the result is an Err.
+      #
+      # @abstract
+      # @yieldparam error [Object] the wrapped error, only for an Err
+      # @return [Object] the wrapped value or the block's return value
+      def unwrap_or_else
+      end
+
+      # Implicit hash conversion, which lets a result be splatted into a hash with <tt>**result</tt>.
+      #
+      # @return [Hash] the same hash as +to_h+
+      def to_hash = to_h
+
+      # @return [String] the same string as +inspect+
+      def to_s = inspect
+
+      # Removes all instances of <tt>Ok<nil></tt> from +results+, preserving the order of the remaining results.
+      #
+      # @param results [Array<Result>] the results to compact
+      # @return [Array<Result>] +results+ without any Ok wrapping +nil+
+      def self.compact(results)
+        results.reject { it.ok? && it.unwrap!.nil? }
+      end
+
+      # Creates a new Err.
+      #
+      # @param error [Object] the error to wrap
+      # @return [Err] an Err wrapping +error+
+      def self.err(error)
+        Err.new(error)
+      end
+
+      # Runs the provided block, wrapping the returned value in Ok. If an exception is raised, returns an Err with
+      # that exception instead.
+      #
+      # Only StandardError and its subclasses are rescued, so exceptions such as NotImplementedError still propagate.
+      #
+      # @yieldreturn [Object] the value to wrap in an Ok
+      # @return [Ok, Err] an Ok wrapping the block's return value, or an Err wrapping the exception it raised
+      def self.from
+        Result.ok(yield)
+      rescue StandardError => e
+        Result.err(e)
+      end
+
+      # Creates a new Ok.
+      #
+      # @param value [Object] the value to wrap
+      # @return [Ok] an Ok wrapping +value+
+      def self.ok(value)
+        Ok.new(value)
+      end
+
+      # Splits results into their unwrapped values and unwrapped errors, preserving their order.
+      #
+      # @param results [Array<Result>] the results to split
+      # @raise [ArgumentError] when any element of +results+ is not a Result
+      # @return [Array(Array, Array)] the unwrapped values of every Ok, followed by the unwrapped errors of every Err
+      # @example
+      #   Result.partition([Result.ok(1), Result.err("boom"), Result.ok(2)])
+      #   # => [[1, 2], ["boom"]]
+      def self.partition(results)
+        raise ArgumentError, "results must all be Result" unless results.all?(Result)
+
+        results.each_with_object([[], []]) do |result, (ok, err)|
+          result.on_ok { |value| ok << value }.on_err { |error| err << error }
+        end
+      end
+
+      # Maps each value in +values+ through a block, collecting the unwrapped values into an <tt>Ok<Array></tt>.
+      # Short-circuits on the first Err.
+      #
+      # @param values [Enumerable] the values to map to results
+      # @yieldparam value [Object] each element of +values+
+      # @yieldreturn [Result] must return a Result
+      # @return [Ok<Array>, Err] all unwrapped values if all block calls returned Ok or the first Err encountered
+      # @example
+      #   Result.traverse([1, 2, 3]) { |n| Result.ok(n * 2) }
+      #   # => Ok<[2, 4, 6]>
+      #
+      #   Result.traverse([1, 2, 3]) { |n| n == 2 ? Result.err("bad") : Result.ok(n) }
+      #   # => Err<"bad">
+      def self.traverse(values)
+        values.reduce(Result.ok([])) do |result, value|
+          result.flat_map do |outputs|
+            yield(value)
+              .tap { raise ReturnError, "block must return a Result" unless it.is_a?(Result) }
+              .map { |output| [*outputs, output] }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/djk/monads/return_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module DJK
+  module Monads
+    # Raised when a method or block does not return an expected value.
+    class ReturnError < StandardError
+    end
+  end
+end

data/lib/djk/monads/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module DJK
+  module Monads
+    VERSION = "0.1.0"
+  end
+end

data/lib/djk/monads.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "monads/version"
+require_relative "monads/return_error"
+require_relative "monads/result"
+require_relative "monads/ok"
+require_relative "monads/err"
+require_relative "monads/option"
+
+module DJK
+  # Rust-style Result and Option monads.
+  module Monads
+    class Error < StandardError
+    end
+
+    ALIASES = %i[ReturnError Err Ok Option Result].freeze
+    private_constant :ALIASES
+
+    # Defines ReturnError, Err, Ok, Option, and Result as top level constants, so they can be used without the
+    # DJK::Monads namespace.
+    #
+    # A constant that is already defined at the top level is left untouched, and a warning naming it is printed to
+    # stderr. Constants that already point to the matching DJK::Monads class, such as from an earlier call, are skipped
+    # without a warning.
+    #
+    # @return [Array<Symbol>] the names of the constants that were defined by this call
+    # @example
+    #   DJK::Monads.apply_aliases!
+    #   # => [:ReturnError, :Err, :Ok, :Option, :Result]
+    #
+    #   Result.ok(1)
+    #   # => Ok<1>
+    def self.apply_aliases!
+      defined, undefined = ALIASES.partition { Object.const_defined?(it, false) }
+      conflicts = defined.reject { Object.const_get(it, false).equal?(const_get(it)) }
+      unless conflicts.empty?
+        warn "DJK::Monads.apply_aliases! skipped already defined constants: #{conflicts.join(", ")}", uplevel: 1
+      end
+
+      undefined.each { Object.const_set(it, const_get(it)) }
+    end
+  end
+end

data/lib/djk.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative "djk/monads"
+
+module DJK # rubocop:disable Style/Documentation
+end

metadata

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification
+name: djk_monads
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Dan Kotowski
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: A collection of Rust-like monads for Ruby that I'm using in my personal
+  projects.
+email:
+- dan@dankotowski.dev
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- lib/djk.rb
+- lib/djk/monads.rb
+- lib/djk/monads/err.rb
+- lib/djk/monads/ok.rb
+- lib/djk/monads/option.rb
+- lib/djk/monads/result.rb
+- lib/djk/monads/return_error.rb
+- lib/djk/monads/version.rb
+homepage: https://github.com/djkotowski/djk_monads
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/djkotowski/djk_monads
+  changelog_uri: https://github.com/djkotowski/djk_monads/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 4.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.21
+specification_version: 4
+summary: Rust-style monads for Ruby
+test_files: []