mona-result 0.1.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 74a4d1f256317d8a2675c58dc8c5b52822987f3d7f05473042ce617828c9a78d
-  data.tar.gz: 278922b075a71ab08d07756e8b46c8cdafa2b11c390e489c9875d482039664d9
+  metadata.gz: b53dbabf6036e587ba320df3ffde82737a8d692a354d38ea2093d5c1046eedd8
+  data.tar.gz: ffd6a0f736e3407fb4c1cbab320572b399bc4091de6c90644520695162d382d7
 SHA512:
-  metadata.gz: 8319264ee1391c3244626af638c33b575156b17db884984214d140069cf3ae1f5f28bcbf20b5e222537d24b895a36b75b65e656d74645999d01a6b16153e52d2
-  data.tar.gz: 8457dbf1772ac1b536b1026cb1cb241456a2fdb27fbbf22e178937d01816921289e825cb1a0f4172629c305ce23ec4f1c89dcbb16f0d9e71fcaf39d0d85588af
+  metadata.gz: cd2b54c044638818a3359239c43adeb631b19254bf94153a99127008c58774d2813ce4aa1363dc92aa107a269585d8fee1739ae98ff53643afdbd446fa5c0549
+  data.tar.gz: d9947684fd66ee1394811c1bf2160215699dd51650ed0b91fd04f22415155fd1af48e85ed35a9a68bfc4283a258172fcd0689929613f574a30afb28e0081703f

data/CHANGELOG.md

@@ -1,3 +1,19 @@
+## [0.3.0] - 2022-08-25
+
+- Bring utility methods into Mona namespace
+- Reorganisation to make Result and DictResult interface modules
+
+## [0.2.0] - 2022-08-23
+
+- Adds Mona::Resultable module which implements the Result interface
+- Simplify and improve RBS
+- Steep checks tests in a stricter fashion
+- Improve docs, tests, and rubocop
+
+## [0.1.3] - 2022-08-09
+
+- Fix CHANGELOG rubygems link
+
 ## [0.1.2] - 2022-08-09
 
 - Fix gemspec links

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    mona-result (0.1.2)
+    mona-result (0.3.0)
 
 GEM
   remote: https://rubygems.org/
@@ -21,7 +21,7 @@ GEM
     listen (3.7.1)
       rb-fsevent (~> 0.10, >= 0.10.3)
       rb-inotify (~> 0.9, >= 0.9.10)
-    minitest (5.16.2)
+    minitest (5.16.3)
     parallel (1.22.1)
     parser (3.1.2.1)
       ast (~> 2.4.1)
@@ -33,14 +33,14 @@ GEM
     rbs (2.6.0)
     regexp_parser (2.5.0)
     rexml (3.2.5)
-    rubocop (1.34.0)
+    rubocop (1.35.1)
       json (~> 2.3)
       parallel (~> 1.10)
       parser (>= 3.1.2.1)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 1.8, < 3.0)
       rexml (>= 3.2.5, < 4.0)
-      rubocop-ast (>= 1.20.0, < 2.0)
+      rubocop-ast (>= 1.20.1, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 1.4.0, < 3.0)
     rubocop-ast (1.21.0)

data/README.md

@@ -24,7 +24,10 @@ success = Result.ok(1) # => #<OK 1>
 success.ok? # => true
 success.err? # => false
 success.value # => 1
-success.and_tap { puts "it is #{_1}" }.and_then { _1 * 5 }.value_or { :nope }
+
+success.and_tap { puts "it is #{_1}" }
+       .and_then { _1 * 5 }
+       .value_or { :nope }
 # OUT: it is 1
 # => 5
 
@@ -34,7 +37,11 @@ failure.ok? # => false
 failure.err? # => true
 failure.failure # => 4
 failure.reason # => :not_prime
-failure.and_tap { puts "it is #{_1}" }.and_then { _1 * 5 }.value_or { :nope } # => :nope
+
+failure.and_tap { puts "it is #{_1}" }
+       .and_then { _1 * 5 }
+       .value_or { :nope }
+# => :nope
 
 # Dict with sequence, example using a fictional repository.
 # #set can take a [Symbol, Symbol] key argument where left is OK key, right is Err key

data/Steepfile

@@ -6,18 +6,15 @@ target :lib do
   signature "sig"
 
   check "lib"
-
-  configure_code_diagnostics(D::Ruby.default)
 end
 
 target :test do
-  signature "sig"
+  signature "sig", "test/sig"
 
   check "test"
 
   library "minitest", "mutex_m"
 
-  configure_code_diagnostics(D::Ruby.strict)
   configure_code_diagnostics do |h|
     h[D::Ruby::UnsupportedSyntax] = :information
   end

data/lib/mona/dict_result/err.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Mona
+  module DictResult
+    # Err DictResult
+    class Err < Mona::Err
+      include DictResult
+
+      def set(_key, _val) = raise(Error, "cannot #set on #{self}")
+
+      def to_h = @failure
+    end
+  end
+end

data/lib/mona/dict_result/ok.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Mona
+  module DictResult
+    # OK DictResult
+    class OK < Mona::OK
+      include DictResult
+
+      def set(key, val)
+        key, failure_key = key if key.is_a?(Array)
+        failure_key ||= key
+
+        # @type var meta: Hash[Symbol, untyped]
+        Result[val].either \
+          ->(value) { OK.new to_h.merge(key => value) },
+          ->(failure, reason, **meta) { Err.new to_h.merge(failure_key => failure), reason, **meta, key: failure_key }
+      end
+
+      def to_h = @value
+    end
+  end
+end

data/lib/mona/dict_result/sequence.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Mona
+  module DictResult
+    # Sequence.call { ... } allows monadic 'do' notation for DictResult, where #set-ing the first failure skips the
+    # remainder of the block and returns the DictResult
+    class Sequence
+      def self.call(result = DictResult::EMPTY, &) = new(result).call(&)
+
+      def initialize(result = DictResult::EMPTY)
+        @result = result
+        @throw = Object.new
+      end
+
+      def call
+        catch(@throw) do
+          yield self
+          @result
+        end
+      end
+
+      def set(key, value)
+        @result = @result.set(key, value)
+      ensure
+        throw @throw, @result if @result.err?
+      end
+
+      def get(key) = @result.get(key)
+
+      def key?(key) = @result.key?(key)
+    end
+  end
+end

data/lib/mona/dict_result.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "dict_result/ok"
+require_relative "dict_result/err"
+require_relative "dict_result/sequence"
+
+module Mona
+  # Represents a dictionary of results, it is successful if all results are successful, and a failure if one
+  # is a failure. A DictResult can only contain one failure.
+  module DictResult
+    include Result
+
+    # factory method that returns DictResult::OK or DictResult::Err
+    def self.[](initial = {}, &block)
+      result = EMPTY
+      initial.each { |k, v| result = result.set(k, v) }
+      result = result.sequence(&block) if block
+      result
+    end
+
+    def key?(key) = to_h.key?(key)
+
+    def get(key) = to_h.fetch(key)
+
+    def set(_key, _val) = raise(NotImplementedError, "implement #to_h")
+
+    def to_h = raise(NotImplementedError, "implement #to_h")
+
+    def sequence(&) = Sequence.new(self).call(&)
+
+    EMPTY = DictResult::OK.new({}).freeze
+  end
+end

data/lib/mona/err.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Mona
+  # An Err (failure) result, with optional reason, and metadata
+  class Err
+    include Result
+
+    def self.[](failure, reason = nil, **meta) = new(failure, reason, **meta)
+
+    def initialize(failure, reason, **meta)
+      raise ArgumentError, "meta can't contain :reason or err: key" if meta.key?(:reason) || meta.key?(:err)
+
+      @failure = failure
+      @reason  = reason
+      @meta    = meta
+    end
+
+    # @dynamic failure, reason, meta
+    attr_reader :failure, :reason, :meta
+
+    def either(_ok, err) = err.call(@failure, @reason, **@meta)
+
+    def inspect = "Err(#{[failure, *reason, *meta.map { "#{_1}: #{_2}" }].join(", ")})"
+
+    # @dynamic to_s
+    alias to_s inspect
+  end
+end

data/lib/mona/no_match_error.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Mona
+  # raised by ResultMatch.call when no match is found
+  class NoMatchError < Mona::Error
+    # @dynamic result
+    attr_reader :result
+
+    def initialize(result)
+      @result = result
+      super("No match found for #{@result}")
+    end
+  end
+end

data/lib/mona/ok.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Mona
+  # A Successful (OK) result
+  class OK
+    include Result
+
+    def self.[](value) = new(value)
+
+    def initialize(value)
+      @value = value
+    end
+
+    # @dynamic value
+    attr_reader :value
+
+    def either(ok, _err) = ok.call(@value)
+
+    def inspect = "OK(#{@value})"
+
+    # @dynamic to_s
+    alias to_s inspect
+  end
+end

data/lib/mona/result.rb

@@ -1,37 +1,45 @@
 # frozen_string_literal: true
 
-require_relative "result/version"
-require_relative "result/error"
+require_relative "../mona"
 
 module Mona
-  # Monadic result
-  #
-  # @author Ian White
-  # @since 0.1.0
+  # Provides the result interface, including class must implement #either(on_ok, on_err)
   module Result
-    autoload :OK,       "mona/result/ok.rb"
-    autoload :Err,      "mona/result/err.rb"
-    autoload :Match,    "mona/result/match.rb"
-    autoload :Dict,     "mona/result/dict.rb"
-    autoload :Sequence, "mona/result/sequence.rb"
-    autoload :Action,   "mona/result/action.rb"
+    VERSION = "0.3.0"
 
-    def self.[](obj) = obj.respond_to?(:to_result) ? obj.to_result : OK.new(obj)
+    def self.[](obj) = obj.is_a?(Result) ? obj : OK[obj]
 
-    module_function
+    def either(_ok, _err) = raise(NotImplementedError, "implement #either")
 
-    def to_result(obj) = Result[obj]
+    def value_or(&block) = either -> { _1 }, ->(*_args) { block.call }
 
-    def ok(value) = OK.new(value)
+    def ok? = either ->(_) { true }, ->(*_args) { false }
 
-    def err(failure, reason = nil, **meta) = Err.new(failure, reason, **meta)
+    def err? = either ->(_) { false }, ->(*_args) { true }
 
-    def on_result(result, &) = Match.call(result, &)
+    def ok(&block) = either block, ->(*_args) {}
 
-    def on_ok(result, &) = Match.call(result) { _1.ok(&) }
+    def err(&block) = either ->(_) {}, block
 
-    def dict(initial = {}, &) = Dict.new(initial, &)
+    def and_tap(&block) = tap { either block, ->(*_args) {} }
 
-    def action(&) = Action::Ephemeral.new(&)
+    def and_then(&block) = either -> { Result[block.call _1] }, ->(*_args) { self }
+
+    def or_else(&block)
+      # @type var meta: Hash[Symbol, untyped]
+      either ->(_) { self }, ->(failure, reason, **meta) { Result[block.call failure, reason, **meta] }
+    end
+
+    def deconstruct
+      # @type var meta: Hash[Symbol, untyped]
+      either ->(value) { [:ok, value] }, ->(failure, reason, **meta) { [:err, failure, reason, meta] }
+    end
+
+    def deconstruct_keys(_keys = nil)
+      # @type var meta: Hash[Symbol, untyped]
+      either ->(ok) { { ok: } }, ->(err, reason, **meta) { meta.merge(err:, reason:) }
+    end
+
+    def ==(other) = deconstruct == other.deconstruct
   end
 end

data/lib/mona/result_action.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Mona
+  # mixin for objects that return Result::Dict results
+  #
+  # define #perform to do the work, use #set to add results to the Result::Dict, the first failure will abort the
+  # rest of the #perform method and the result will be returned.  This works like monadic 'do' notation.
+  #
+  # After a result is set at a key, it can be accessed via its key name as a method.
+  #
+  # use the Action with #call
+  #
+  # example:
+  #
+  #   class UpdateUser
+  #     inlcude Mona::ResultAction
+  #     include Auditing # for example, adds #audit(model, input) method
+  #
+  #     def perform(user_id, attributes)
+  #       set :user, UserRepo.find(user_id) # if find is Err, the block exits with failure of :user
+  #       set :input, UserInput.valid(attributes) # likewise if valid is Err, the block exits
+  #       set [:user, :input], UserRepo.update(user.id, input) # note that #input and #user are available methods
+  #                                                            # if update is Err it is set on the :input key
+  #       audit(user, input) # this only runs if all of the above set successful results
+  #     end
+  #   end
+  #
+  #   UpdateUser.new.call(user_id, attributes) # => Result
+  module ResultAction
+    # You can create an Ephemeral Action as follows:
+    #
+    # Example:
+    #   compute = Mona::ResultAction::Ephemeral.new do |x, y|
+    #     set :numerator, x
+    #     puts "set numerator: #{numerator}"
+    #     set :denominator, y.zero? ? Result.failure(y, :zero) : y
+    #     puts "set denominator: #{denominator}"
+    #     set :answer, numerator / denominator
+    #     puts "answer: #{answer}"
+    #   end
+    #
+    #   > compute.call(10,2)
+    #   set numerator: 10
+    #   set denominator: 2
+    #   answer: 5
+    #   => #<Result success: {:numerator=>10, :denominator=>2, :answer=>5}>
+    #
+    #   > compute.call(10,0)
+    #   set numerator: 10
+    #   => #<Result failure: {:numerator=>10, :denominator=>0}, error: {:error=>:zero, :on=>:denominator}>
+    #
+    # Mona::ResultAction() is a shortcut for this
+    class Ephemeral
+      include ResultAction
+
+      def initialize(&perform)
+        @perform = perform
+      end
+
+      def perform(*args, **kwargs) = instance_exec(*args, **kwargs, &@perform)
+    end
+
+    def call(*args, **kwargs)
+      @sequence = DictResult::Sequence.new
+      @sequence.call { |_sequence| perform(*args, **kwargs) }
+    ensure
+      remove_instance_variable :@sequence
+    end
+
+    def perform(*args, **kwargs) = raise(NotImplementedError, "implement `perform'")
+
+    private
+
+    def get(key) = @sequence.get(key)
+
+    def set(key, value) = @sequence.set(key, value)
+
+    def key?(key) = @sequence.key?(key)
+
+    def respond_to_missing?(key, _include_private = false) = key?(key)
+
+    def method_missing(key, *args)
+      return get(key) if args.empty? && key?(key)
+
+      raise NoMethodError, "no method `#{key}' for #{self}"
+    end
+  end
+end

data/lib/mona/result_match.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Mona
+  # Use ResultMatch.call to respond to result success or failure
+  #
+  # ResultMatch.call(result) do |r|
+  #   r.ok                  { |value| ... }
+  #   r.err(reason, **meta) { |failure, reason, **meta| ... }
+  #   r.err(**meta)         { |failure, reason, **meta| ... }
+  #   r.err(reason)         { |failure, reason, **meta| ... }
+  #   r.err                 { |failure, reason, **meta| ... }
+  # end
+  class ResultMatch
+    def self.call(result, &) = new(result).call(&)
+
+    def initialize(result)
+      @throw = Object.new
+      @result = result
+    end
+
+    def call
+      catch @throw do
+        yield self
+        raise NoMatchError, @result
+      end
+    end
+
+    def ok
+      @result.and_then do |value|
+        throw @throw, yield(value)
+      end
+    end
+
+    def err(match_reason = nil, **match_meta)
+      @result.or_else do |failure, reason, **meta|
+        # @type var meta: Hash[Symbol, untyped]
+        if match_reason?(match_reason, reason) && match_meta?(match_meta, meta)
+          throw @throw, yield(failure, reason, **meta)
+        end
+      end
+    end
+
+    private
+
+    def match_reason?(match_reason, reason)
+      match_reason.nil? || match_reason === reason # rubocop:disable Style/CaseEquality
+    end
+
+    def match_meta?(match_meta, meta)
+      match_meta.all? { |key, val| val.nil? || val === meta[key] } # rubocop:disable Style/CaseEquality
+    end
+  end
+end

data/lib/mona.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# Mona top level module contains utility methods
+module Mona
+  autoload :OK,           "mona/ok.rb"
+  autoload :Err,          "mona/err.rb"
+  autoload :DictResult,   "mona/dict_result.rb"
+  autoload :ResultMatch,  "mona/result_match.rb"
+  autoload :ResultAction, "mona/result_action.rb"
+  autoload :NoMatchError, "mona/no_match_error.rb"
+
+  class Error < StandardError; end
+
+  module_function
+
+  # @dynamic self.result, self.ok, self.err, self.dict_result, self.on_result, self.on_ok, self.result_action
+
+  def result(obj) = obj.is_a?(Result) ? obj : OK[obj]
+
+  def ok(value) = OK[value]
+
+  def err(failure, reason = nil, **meta) = Err[failure, reason, **meta]
+
+  def dict_result(initial = {}, &) = DictResult[initial, &]
+
+  def on_result(result, &) = ResultMatch.call(result, &)
+
+  def on_ok(result, &) = ResultMatch.call(result) { _1.ok(&) }
+
+  def result_action(&) = ResultAction::Ephemeral.new(&)
+end

data/sig/mona.rbs

@@ -0,0 +1,141 @@
+module Mona
+  Result::VERSION: String
+
+  type dict        = Hash[Symbol, untyped]
+  type result      = Result[untyped, untyped]
+  type dict_result = DictResult[untyped]
+
+  def self?.result: (untyped) -> result
+  def self?.ok: [T] (T) -> OK[T]
+  def self?.err: [T, ReasonT] (T, ?ReasonT?, **untyped) -> Err[T, ReasonT?]
+  def self?.dict_result: (?dict) ?{ (DictResult::Sequence) -> void } -> dict_result
+  def self?.on_result: (result) { (ResultMatch) -> void } -> untyped
+  def self?.on_ok: (result) { (untyped) -> void } -> untyped
+  def self?.result_action: { (*untyped) -> void } -> ResultAction::Ephemeral
+
+  module Result[T, ReasonT]
+    def self.[]: (untyped) -> result
+
+    def either: [OKR, ErrR] (^(T) -> OKR, ^(T, ?ReasonT?, **untyped) -> ErrR) -> (OKR | ErrR)
+    def ok?: -> bool
+    def err?: -> bool
+    def ok: [R] () { (T) -> R } -> (R | nil)
+    def err: [R] () { (T, ?ReasonT?, **untyped) -> R } -> (R | nil)
+    def value_or: [R] { () -> R } -> (R | T)
+    def and_then: [R] () { (T) -> R } -> result
+    def and_tap: () { (T) -> void } -> self
+    def or_else: [R] () { (T, ?ReasonT?, **untyped) -> R } -> result
+    def deconstruct: -> Array[untyped]
+    def deconstruct_keys: (?Array[Symbol]?) -> dict
+  end
+
+  class OK[T]
+    include Result[T, nil]
+
+    attr_reader value: T
+
+    def self.[]: [T] (T) -> OK[T]
+
+    def initialize: (T) -> void
+    def either: [OKR] (^(T) -> OKR, ^(T, ?untyped?, **untyped) -> void) -> OKR
+    def inspect: -> String
+    alias to_s inspect
+  end
+
+  class Err[T, ReasonT]
+    include Result[T, ReasonT]
+
+    attr_reader failure: T
+    attr_reader reason: ReasonT
+    attr_reader meta: dict
+
+    def self.[]: [T, ReasonT] (T, ?ReasonT?, **untyped) -> Err[T, ReasonT?]
+
+    def initialize: (T, ReasonT, **untyped) -> void
+    def either: [ErrR] (^(T) -> void, ^(T, ?ReasonT?, **untyped) -> ErrR) -> ErrR
+    def inspect: -> String
+    alias to_s inspect
+  end
+
+  module DictResult[ReasonT]
+    include Result[dict, ReasonT]
+
+    EMPTY: dict_result
+
+    def self.[]: (?dict) ?{ (Sequence) -> void } -> dict_result
+
+    def key? : (Symbol) -> bool
+    def get : (Symbol) -> untyped
+    def set: (Symbol | [Symbol, Symbol], untyped) -> dict_result
+    def sequence: () { (Sequence) -> void } -> dict_result
+    def to_h: -> dict
+
+    class OK < Mona::OK[dict]
+      include DictResult[nil]
+    end
+
+    class Err[ReasonT] < Mona::Err[dict, ReasonT]
+      include DictResult[ReasonT]
+    end
+
+    class Sequence
+      @throw: Object
+      @result: dict_result
+
+      def self.call: (?dict_result) { (Sequence) -> void } -> dict_result
+      def initialize: (?dict_result) -> void
+      def call: () { (Sequence) -> void } -> dict_result
+      def set: (Symbol | [Symbol,Symbol], untyped) -> void
+      def get: (Symbol) -> untyped
+      def key?: (Symbol) -> bool
+    end
+  end
+
+  class Error < StandardError
+  end
+
+  class NoMatchError < Error
+    attr_reader result: result
+    def initialize: (result) -> void
+  end
+
+  class ResultMatch
+    @throw: Object
+    @result: result
+
+    def self.call: (result) { (ResultMatch) -> void } -> untyped
+    def initialize: (result) -> void
+    def call: () { (ResultMatch) -> void } -> untyped
+    def ok: () { (untyped) -> void } -> void
+    def err: (?untyped, **untyped) { (untyped, ?untyped, **untyped) -> void } -> void
+
+    private
+
+    def match_reason?: (untyped, untyped) -> bool
+    def match_meta?: (untyped, untyped) -> bool
+  end
+
+  module ResultAction
+    class Ephemeral
+      include ResultAction
+
+      @perform: ^(*untyped, **untyped) -> void
+
+      def initialize: () { (*untyped, **untyped) -> void } -> void
+      def perform: (*untyped, **untyped) -> void
+    end
+
+    @sequence: DictResult::Sequence
+
+    def call: (*untyped, **untyped) -> dict_result
+    def perform: (*untyped, **untyped) -> void
+
+    private
+
+    def get: (Symbol) -> untyped
+    def set: (Symbol | [Symbol,Symbol], untyped) -> void
+    def key?: (Symbol) -> bool
+    def respond_to_missing?: (Symbol, ?bool) -> bool
+    def method_missing: (Symbol, *untyped) -> untyped
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mona-result
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.3.0
 platform: ruby
 authors:
 - Ian White
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-08-09 00:00:00.000000000 Z
+date: 2022-08-25 00:00:00.000000000 Z
 dependencies: []
 description: Mona::Result provides a result monad, and dict result monad with do-notation
 email:
@@ -25,16 +25,18 @@ files:
 - README.md
 - Rakefile
 - Steepfile
+- lib/mona.rb
+- lib/mona/dict_result.rb
+- lib/mona/dict_result/err.rb
+- lib/mona/dict_result/ok.rb
+- lib/mona/dict_result/sequence.rb
+- lib/mona/err.rb
+- lib/mona/no_match_error.rb
+- lib/mona/ok.rb
 - lib/mona/result.rb
-- lib/mona/result/action.rb
-- lib/mona/result/dict.rb
-- lib/mona/result/err.rb
-- lib/mona/result/error.rb
-- lib/mona/result/match.rb
-- lib/mona/result/ok.rb
-- lib/mona/result/sequence.rb
-- lib/mona/result/version.rb
-- sig/mona/result.rbs
+- lib/mona/result_action.rb
+- lib/mona/result_match.rb
+- sig/mona.rbs
 homepage: https://github.com/mona-rb/mona-result
 licenses:
 - MIT
@@ -42,7 +44,7 @@ metadata:
   rubygems_mfa_required: 'true'
   homepage_uri: https://github.com/mona-rb/mona-result
   source_code_uri: https://github.com/mona-rb/mona-result
-  changelog_uri: https://github.com/mona-rb/mona-result/CHANGELOG.md
+  changelog_uri: https://github.com/mona-rb/mona-result/blob/main/CHANGELOG.md
 post_install_message:
 rdoc_options: []
 require_paths:

data/lib/mona/result/action.rb

@@ -1,84 +0,0 @@
-# frozen_string_literal: true
-
-module Mona
-  module Result
-    # mixin for objects that return Result::Dict results
-    #
-    # define #perform to do the work, use #set to add results to the Result::Dict, the first failure will abort the
-    # rest of the #perform method and the result will be returned.  This works like monadic 'do' notation.
-    #
-    # After a result is set at a key, it can be accessed via its key name as a method.
-    #
-    # use the Action with #call
-    #
-    # example:
-    #
-    #   class UpdateUser
-    #     inlcude Mona::Result::Action
-    #     include Auditing # for example, adds #audit(model, input) method
-    #
-    #     def perform(user_id, attributes)
-    #       set :user, UserRepo.find(user_id) # if find is Err, the block exits with failure of :user
-    #       set :input, UserInput.valid(attributes) # likewise if valid is Err, the block exits
-    #       set [:user, :input], UserRepo.update(user.id, input) # note that #input and #user are available methods
-    #                                                            # if update is Err it is set on the :input key
-    #       audit(user, input) # this only runs if all of the above set successful results
-    #     end
-    #   end
-    #
-    #   UpdateUser.new.call(user_id, attributes) # => Result
-    module Action
-      # You can create an Ephemeral Action as follows:
-      #
-      # Example:
-      #   compute = Mona::Result::Action::Ephemeral.new do |x, y|
-      #     set :numerator, x
-      #     puts "set numerator: #{numerator}"
-      #     set :denominator, y.zero? ? Result.failure(y, :zero) : y
-      #     puts "set denominator: #{denominator}"
-      #     set :answer, numerator / denominator
-      #     puts "answer: #{answer}"
-      #   end
-      #
-      #   > compute.call(10,2)
-      #   set numerator: 10
-      #   set denominator: 2
-      #   answer: 5
-      #   => #<Result success: {:numerator=>10, :denominator=>2, :answer=>5}>
-      #
-      #   > compute.call(10,0)
-      #   set numerator: 10
-      #   => #<Result failure: {:numerator=>10, :denominator=>0}, error: {:error=>:zero, :on=>:denominator}>
-      #
-      # Mona::Result.action is a shortcut for this
-      class Ephemeral
-        include Action
-
-        def initialize(&perform)
-          @perform = perform
-        end
-
-        def perform(*args, **kwargs) = instance_exec(*args, **kwargs, &@perform)
-      end
-
-      def call(*args, **kwargs)
-        @sequence = Sequence.new
-        @sequence.call { |_sequence| perform(*args, **kwargs) }
-      ensure
-        remove_instance_variable :@sequence
-      end
-
-      private
-
-      def set(key, value) = @sequence.set(key, value)
-
-      def respond_to_missing?(key, _include_private = false) = @sequence.key?(key)
-
-      def method_missing(key, *args)
-        return @sequence.fetch(key) if args.empty? && @sequence.key?(key)
-
-        raise NoMethodError, "no method `#{key}' for #{self}"
-      end
-    end
-  end
-end

data/lib/mona/result/dict.rb

@@ -1,57 +0,0 @@
-# frozen_string_literal: true
-
-module Mona
-  module Result
-    # Represents a dictionary of results, it is successful if all results are successful, and a failure if one
-    # is a failure. A Result::Dict can only contain one failure.
-    class Dict
-      # factory method that returns {Dict::Success} or {Dict::Failure}
-      def self.new(initial = {}, &block)
-        result = Dict::EMPTY
-        initial.each { |k, v| result = result.set(k, v) }
-        result = result.sequence(&block) if block
-        result
-      end
-
-      # Dict read interface
-      module ReadInterface
-        def [](key) = to_h[key]
-
-        def key?(key) = to_h.key?(key)
-
-        def fetch(key) = to_h.fetch(key)
-      end
-
-      # OK dict result
-      class OK < Result::OK
-        include ReadInterface
-
-        def set(key, to_result)
-          key, failure_key = key if key.is_a?(Array)
-          failure_key ||= key
-
-          Result[to_result].either \
-            ->(value)                { OK.new to_h.merge(key => value) },
-            ->(failure, reason, **m) { Err.new to_h.merge(failure_key => failure), reason, **m, key: failure_key }
-        end
-
-        def sequence(&) = Sequence.new(self).call(&)
-
-        def to_h = @value
-      end
-
-      # Err dict result
-      class Err < Result::Err
-        include ReadInterface
-
-        def set(_key, _val) = raise(Error, "cannot #set on #{self}")
-
-        def sequence(&) = self
-
-        def to_h = @failure
-      end
-
-      EMPTY = OK.new({}).freeze
-    end
-  end
-end

data/lib/mona/result/err.rb

@@ -1,48 +0,0 @@
-# frozen_string_literal: true
-
-module Mona
-  module Result
-    # A Error or failure result, with optional reason, and metadata
-    class Err
-      def initialize(failure, reason = nil, **meta)
-        raise ArgumentError, "meta can't contain :reason key" if meta.key?(:reason)
-
-        @failure = failure.freeze
-        @reason = reason
-        @meta = meta
-      end
-
-      attr_reader :failure, :reason, :meta
-
-      def ok? = false
-
-      def err? = true
-
-      def value_or(&) = yield
-
-      def ok(&) = nil
-
-      def err(&) = yield @failure, @reason, **@meta
-
-      def either(_ok, err) = err.call(@failure, @reason, **@meta)
-
-      def and_then(&) = self
-
-      def and_tap(&) = self
-
-      def or_else(&) = Result[yield @failure, @reason, **@meta]
-
-      def deconstruct = [:err, @failure, @reason, @meta]
-
-      def deconstruct_keys(_keys = nil) = { err: @failure, reason: @reason, **@meta }
-
-      def to_result = self
-
-      def to_s
-        "#<Err #{@failure.inspect} #{{ reason: @reason, **@meta }.map{ "#{_1}: #{_2.inspect}" }.join(", ")}>"
-      end
-
-      alias inspect to_s
-    end
-  end
-end

data/lib/mona/result/error.rb

@@ -1,18 +0,0 @@
-# frozen_string_literal: true
-
-module Mona
-  module Result
-    # Base error for Result
-    class Error < StandardError; end
-
-    # raised when Result::Match does not match the result
-    class NoMatchError < Error
-      attr_reader :result
-
-      def initialize(result)
-        @result = result
-        super("No match found for #{result}")
-      end
-    end
-  end
-end

data/lib/mona/result/match.rb

@@ -1,53 +0,0 @@
-# frozen_string_literal: true
-
-module Mona
-  module Result
-    # Use Match.call to respond to result success or failure
-    #
-    # Result::Match.call(result) do |r|
-    #   r.ok                 { |value| ... }
-    #   r.err(error, **meta) { |failure, reason, **meta| ... }
-    #   r.err(error)         { |failure, reason, **meta| ... }
-    #   r.err                { |failure, reason, **meta| ... }
-    # end
-    class Match
-      def self.call(result, &) = new(result).call(&)
-
-      def initialize(result)
-        @throw = Object.new
-        @result = result
-      end
-
-      def call
-        catch @throw do
-          yield self
-          raise NoMatchError, @result
-        end
-      end
-
-      def ok
-        @result.and_then do |value|
-          throw @throw, yield(value)
-        end
-      end
-
-      def err(match_reason = nil, **match_meta)
-        @result.or_else do |failure, reason, **meta|
-          if match_reason?(match_reason, reason) && match_meta?(match_meta, meta)
-            throw @throw, yield(failure, reason, **meta)
-          end
-        end
-      end
-
-      private
-
-      def match_reason?(match_reason, reason)
-        match_reason.nil? || match_reason === reason # rubocop:disable Style/CaseEquality
-      end
-
-      def match_meta?(match_meta, meta)
-        match_meta.all? { |key, val| val.nil? || val === meta[key] } # rubocop:disable Style/CaseEquality
-      end
-    end
-  end
-end

data/lib/mona/result/ok.rb

@@ -1,42 +0,0 @@
-# frozen_string_literal: true
-
-module Mona
-  module Result
-    # A Successful (OK) result
-    class OK
-      def initialize(value)
-        @value = value.freeze
-      end
-
-      attr_reader :value
-
-      def value_or(&) = @value
-
-      def ok? = true
-
-      def err? = false
-
-      def ok(&) = yield @value
-
-      def err(&) = nil
-
-      def either(ok, _err) = ok.call(@value)
-
-      def and_then(&) = Result[yield @value]
-
-      def and_tap(&) = tap { yield @value }
-
-      def or_else(&) = self
-
-      def deconstruct = [:ok, @value]
-
-      def deconstruct_keys(_keys = nil) = { ok: @value }
-
-      def to_result = self
-
-      def to_s = "#<OK #{@value.inspect}>"
-
-      alias inspect to_s
-    end
-  end
-end

data/lib/mona/result/sequence.rb

@@ -1,33 +0,0 @@
-# frozen_string_literal: true
-
-module Mona
-  module Result
-    # Sequence.call { ... } allows monadic 'do' notation for Result::Dict, where #set-ing the first failure skips the
-    # remainder of the block and returns the Result::Dict
-    class Sequence
-      include Dict::ReadInterface
-
-      def self.call(result = Dict::EMPTY, &) = new(result).call(&)
-
-      def initialize(result = Dict::EMPTY)
-        @result = result
-        @throw = Object.new
-      end
-
-      def call
-        catch(@throw) do
-          yield self
-          @result
-        end
-      end
-
-      def set(key, value)
-        @result = @result.set(key, value)
-      ensure
-        throw @throw, @result if @result.err?
-      end
-
-      def to_h = @result.to_h
-    end
-  end
-end

data/lib/mona/result/version.rb

@@ -1,7 +0,0 @@
-# frozen_string_literal: true
-
-module Mona
-  module Result
-    VERSION = "0.1.2"
-  end
-end

data/sig/mona/result.rbs

@@ -1,177 +0,0 @@
-module Mona
-  module Result
-    VERSION: String
-
-    type dict        = Hash[Symbol, untyped]
-    type keys        = Array[Symbol]
-    type result[T]   = (_OK[T] | _Err[T])
-    type dict_result = result[dict] & _Dict
-    type set_key     = (Symbol | [Symbol, Symbol])
-
-    def self.[]: (untyped) -> result[untyped]
-    def self?.to_result: (untyped) -> result[untyped]
-    def self?.ok: [T] (T) -> _OK[T]
-    def self?.err: [T] (T, ?untyped, **untyped) -> _Err[T]
-    def self?.dict: (?dict) ?{ (Sequence) -> void } -> dict_result
-    def self?.on_result: (result[untyped]) { (Match) -> void } -> untyped
-    def self?.on_ok: (result[untyped]) { (untyped) -> void } -> untyped
-    def self?.action: () { (*untyped) -> void } -> Action::Ephemeral
-
-    interface _OK[T]
-      def initialize: (T) -> void
-      def value: -> T
-      def ok?: -> true
-      def err?: -> false
-      def ok: [R] () { (T) -> R } -> R
-      def err: () { (T, untyped, **untyped) -> void } -> nil
-      def either: [R] (^(T) -> R, ^(T, untyped, **untyped) -> void) -> R
-      def value_or: () { -> void } -> T
-      def and_then: () { (T) -> untyped } -> result[untyped]
-      def and_tap: () { (T) -> void } -> self
-      def or_else: () { (T, ?untyped, **untyped) -> untyped } -> self
-      def deconstruct: -> [:ok, T]
-      def deconstruct_keys: (?keys?) -> { ok: T }
-    end
-
-    interface _Err[T]
-      def initialize: (T, ?untyped, **untyped) -> void
-      def failure: -> T
-      def reason: -> untyped
-      def meta: -> dict
-      def ok?: -> false
-      def err?: -> true
-      def ok: () { (untyped) -> void } -> nil
-      def err: [R] () { (T, untyped, **untyped) -> R } -> R
-      def either: [R] (^(T) -> void, ^(T, untyped, **untyped) -> R) -> R
-      def value_or: [R] () { -> R } -> R
-      def and_then: () { (T) -> untyped } -> self
-      def and_tap: () { (T) -> void } -> self
-      def or_else: () { (T, ?untyped, **untyped) -> untyped } -> result[untyped]
-      def deconstruct: -> [:err, T, untyped, dict]
-      def deconstruct_keys: (?keys?) -> dict
-    end
-
-    interface _ToH
-      def to_h: -> dict
-    end
-
-    interface _DictRead
-      def key? : (Symbol) -> bool
-      def fetch : (Symbol) -> untyped
-      def [] : (Symbol) -> untyped
-    end
-
-    interface _Dict
-      include _DictRead
-      def set: (set_key, untyped) -> dict_result
-      def sequence: () { (Sequence) -> void } -> dict_result
-      def to_h: -> dict
-    end
-
-    interface _Perform
-      def perform: (*untyped, **untyped) -> void
-    end
-
-    class Error < StandardError
-    end
-
-    class NoMatchError < Error
-      attr_reader result: _Err[untyped]
-      def initialize: (_Err[untyped]) -> void
-    end
-
-    class OK
-      include _OK[untyped]
-
-      @value: untyped
-    end
-
-    class Err
-      include _Err[untyped]
-
-      @failure: untyped
-      @reason: untyped
-      @meta: dict
-    end
-
-    class Dict
-      EMPTY: dict_result
-
-      module ReadInterface : _ToH
-        include _DictRead
-      end
-
-      class OK < Result::OK
-        include ReadInterface
-
-        include _OK[dict]
-        include _Dict
-
-        @value: dict
-      end
-
-      class Err < Result::Err
-        include ReadInterface
-
-        include _Err[dict]
-        include _Dict
-
-        @failure: dict
-        @reason: untyped
-        @meta: dict
-      end
-
-      def self.new: (?dict) ?{ (Sequence) -> void } -> dict_result
-    end
-
-    class Match
-      @throw: Object
-      @result: result[untyped]
-
-      def self.call: (result[untyped]) { (Match) -> void } -> untyped
-      def initialize: (result[untyped]) -> void
-      def call: () { (Match) -> void } -> untyped
-      def ok: () { (untyped) -> void } -> void
-      def err: (?untyped, **untyped) { (untyped, ?untyped, **untyped) -> void } -> void
-
-      private
-
-      def match_reason?: (untyped, untyped) -> bool
-      def match_meta?: (untyped, untyped) -> bool
-    end
-
-    class Sequence
-      include Dict::ReadInterface
-
-      @throw: Object
-      @result: dict_result
-
-      def self.call: (?dict_result) { (Sequence) -> void } -> dict_result
-      def initialize: (?dict_result) -> void
-      def call: () { (Sequence) -> void } -> dict_result
-      def set: (set_key, untyped) -> void
-      def to_h: -> dict
-    end
-
-    module Action : _Perform
-      class Ephemeral
-        include Action
-
-        @perform: ^(*untyped, **untyped) -> void
-
-        def initialize: () { (*untyped, **untyped) -> void } -> void
-        def perform: (*untyped, **untyped) -> void
-      end
-
-      @sequence: Sequence
-
-      def call: (*untyped, **untyped) -> dict_result
-
-      private
-
-      def set: (set_key, untyped) -> void
-      def respond_to_missing?: (Symbol, ?bool) -> bool
-      def method_missing: (Symbol, *untyped) -> untyped
-    end
-  end
-end