sorbet-result 0.2.1 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4eb8fb4c04fad76f6947a6c888e741ebc9154abb224edb87d5a8f3461aaabfc1
-  data.tar.gz: 3de9d634bec586f32a6d7151d826e78f125dabc6ae93423137bcc1c3985e8ef3
+  metadata.gz: 55fcf298c304ef8f0101c1a6461c7ded68f9bfb87fead9d12ad23760b4d2268b
+  data.tar.gz: 96ee6aaac4f115f97065977d0cd21f510c9dcdab08b73f14855760171c3e5053
 SHA512:
-  metadata.gz: ab3a1deeae77642c99de930d1d9ad7d772b0401bbdcedfc8e2b49c36839b1d6868a3a4b5643cc024304403a6b967855be0c0754c8079e84adc079d0792d9a350
-  data.tar.gz: 556bdd555bcb02e7976c09097fde14c06a9cbc7fa7bbf20aefa95610ea5d3d3b897ae1e8cb5700f6234ddd0a89f6293f874a3767c762e6321789e3909ecb5ee7
+  metadata.gz: 9a0e1ed605028d5d98109173d11a530a7f7025c33462a918ced64bf240e06e740f78371d5a249bc0866cfd4ac1ebeb4cfef2fe58e17a0cad2a8cfd6a646a5796
+  data.tar.gz: 454f9d376b8a1066aaa2cbbd350f20b43fc71c1ffece65cee72dc8299118260d2dfb0b5b38e73eb2427d9df6c6ce69e222e21243c32292d1a5859c6fcad3cfb9

data/.rubocop.yml

@@ -26,3 +26,8 @@ Style/StringLiteralsInInterpolation:
 
 Layout/LineLength:
   Max: 120
+
+Lint/UselessMethodDefinition:
+  Exclude:
+    - lib/typed/failure.rb
+    - lib/typed/success.rb

data/CHANGELOG.md

@@ -6,6 +6,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.1] - 2023-06-20
+
+### Added
+
+- Add `#on_error` to `Typed::Result` to allow behavior when an error is encountered during chaining.
+- Add `#payload_or` to `Typed::Result` to allow callers to specify a default value if `Failure` is returned.
+
+## [0.3.0] - 2023-06-06
+
+### Added
+
+- Add `.blank` to create a `Typed::Success` with a `nil` payload or a `Typed::Failure` with a `nil` error.
+- Add `#and_then` to `Typed::Result` to allow chaining of results. See #14 for more details.
+
+### Changed
+
+- *Breaking* Make `Typed::Success#Error` and `Typed::Failure#Payload` fixed to `T.noreturn`. This allows to specify the other type_member only when using generics. See #8 for more details
+- *Breaking* Remove `T.nilable` from `Payload` and `Error` parameters in `Typed::Success.new` and `Typed::Failure.new`. Nilability will now need to be specified in the generic type. This also means that you'll need to use the new `.blank` instead of `.new` when you want to create a `Typed::Success` or `Typed::Failure` with a `nil` payload or error.
+- *Breaking* Change `Typed::Success` and `Typed::Failure` initialize arguments from keyword to positional.
+- Improve `Typed::Success.new` and `Typed::Failure.new` to make them generic methods and automatically infer the type of the `payload` and `error` arguments. See #8 for more details
+
 ## [0.2.1] - 2023-05-18
 
 ### Added

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    sorbet-result (0.2.1)
+    sorbet-result (0.3.1)
       sorbet-runtime (~> 0.5)
       zeitwerk (~> 2.6)
 
@@ -14,14 +14,16 @@ GEM
       reline (>= 0.3.1)
     diff-lcs (1.5.0)
     io-console (0.6.0)
-    irb (1.6.4)
+    irb (1.7.0)
       reline (>= 0.3.0)
     json (2.6.3)
-    minitest (5.18.0)
+    minitest (5.18.1)
     netrc (0.11.0)
     parallel (1.23.0)
-    parser (3.2.2.1)
+    parser (3.2.2.3)
       ast (~> 2.4.1)
+      racc
+    racc (1.7.1)
     rainbow (3.1.1)
     rake (13.0.6)
     rbi (0.0.16)
@@ -29,21 +31,21 @@ GEM
       parser (>= 2.6.4.0)
       sorbet-runtime (>= 0.5.9204)
       unparser
-    regexp_parser (2.8.0)
-    reline (0.3.3)
+    regexp_parser (2.8.1)
+    reline (0.3.5)
       io-console (~> 0.5)
     rexml (3.2.5)
-    rubocop (1.51.0)
+    rubocop (1.52.1)
       json (~> 2.3)
       parallel (~> 1.10)
-      parser (>= 3.2.0.0)
+      parser (>= 3.2.2.3)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 1.8, < 3.0)
       rexml (>= 3.2.5, < 4.0)
       rubocop-ast (>= 1.28.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 3.0)
-    rubocop-ast (1.28.1)
+    rubocop-ast (1.29.0)
       parser (>= 3.2.1.0)
     rubocop-minitest (0.31.0)
       rubocop (>= 1.39, < 2.0)
@@ -52,14 +54,14 @@ GEM
     rubocop-sorbet (0.7.0)
       rubocop (>= 0.90.0)
     ruby-progressbar (1.13.0)
-    sorbet (0.5.10832)
-      sorbet-static (= 0.5.10832)
-    sorbet-runtime (0.5.10832)
-    sorbet-static (0.5.10832-universal-darwin-22)
-    sorbet-static (0.5.10832-x86_64-linux)
-    sorbet-static-and-runtime (0.5.10832)
-      sorbet (= 0.5.10832)
-      sorbet-runtime (= 0.5.10832)
+    sorbet (0.5.10880)
+      sorbet-static (= 0.5.10880)
+    sorbet-runtime (0.5.10880)
+    sorbet-static (0.5.10880-universal-darwin-22)
+    sorbet-static (0.5.10880-x86_64-linux)
+    sorbet-static-and-runtime (0.5.10880)
+      sorbet (= 0.5.10880)
+      sorbet-runtime (= 0.5.10880)
     spoom (1.2.1)
       sorbet (>= 0.5.10187)
       sorbet-runtime (>= 0.5.9204)
@@ -75,7 +77,7 @@ GEM
       yard-sorbet
     thor (1.2.2)
     unicode-display_width (2.4.2)
-    unparser (0.6.7)
+    unparser (0.6.8)
       diff-lcs (~> 1.3)
       parser (>= 3.2.0)
     yard (0.9.34)

data/README.md

@@ -14,35 +14,49 @@ If bundler is not being used to manage dependencies, install the gem by executin
 
 ## Usage
 
+### Getting Started
+
 Using a basic Result in your methods is as simple as indicating something could return a `Typed::Result`.
 
+In practice though, you won't return instances of `Typed::Result`, but rather `Typed::Success` or `Typed::Failure`.
+
+`Typed::Success` can hold a payload, and `Typed::Failure` can hold an error, but if you don't have such information to provide you can simply use `Typed::Success.blank` or `Typed::Failure.blank`.
+
+`Typed::Result` is powered by Sorbet's Generics, so you'll need to specify it as `Typed::Result[Success, Error]`, where `Success` represents the type of `payload` in case of a success, while `Error` represents the type of `error` in case of an error.
+
 ```ruby
-sig { params(resource_id: Integer).returns(Typed::Result) }
+sig { params(resource_id: Integer).returns(Typed::Result[NilClass, NilClass]) }
 def call_api(resource_id)
   # something bad happened
-  return Typed::Failure.new
+  return Typed::Failure.blank
 
   # something other bad thing happened
-  return Typed::Failure.new
+  return Typed::Failure.blank
 
   # Success!
-  Typed::Success.new
+  Typed::Success.blank
 end
 ```
 
 Generally, it's nice to have a payload with results, and it's nice to have more information on failures. We can indicate what types these are in our signatures for better static checks. Note that payloads and errors can be _any_ type.
 
+`Typed::Result`, `Typed::Success` and `Typed::Failure` are all generic types, so you can specify the payload and error types when you use them.
+
+`Typed::Result` will need both the success and the error types to be specified, while `Typed::Success` and `Typed::Failure` will only need the success or error type respectively.
+
+`Typed::Success.new` and `Typed::Failure.new` are generic methods, so the payload or error type will be inferred by the parameter type.
+
 ```ruby
 sig { params(resource_id: Integer).returns(Typed::Result[Float, String]) }
 def call_api(resource_id)
-  # something bad happened
-  return Typed::Failure.new(error: "I couldn't do it!")
+  # Something bad happened
+  return Typed::Failure.new("I couldn't do it!") # => Typed::Failure[String]
 
-  # something other bad thing happened
-  return Typed::Failure.new(error: "I couldn't do it for another reason!")
+  # Some other bad thing happened
+  return Typed::Failure.new("I couldn't do it for another reason!") # => Typed::Failure[String]
 
   # Success!
-  Typed::Success.new(payload: 1.12)
+  Typed::Success.new(1.12) # => Typed::Success[Float]
 end
 ```
 
@@ -51,9 +65,9 @@ end
 Further, if another part of your program needs the Result, it can depend on _only_ `Typed::Success`es (or `Typed::Failure`s if you're doing something with those results).
 
 ```ruby
-sig { params(success_result: Typed::Success).void }
+sig { params(success_result: Typed::Success[String]).void }
 def do_something_with_resource(success_result)
-  ...
+  success_result.payload # => String
 end
 ```
 
@@ -62,19 +76,58 @@ Finally, there are a few methods you can use on both `Typed::Result` types.
 ```ruby
 result = call_api(1)
 
-result.success? # => true if success, false if failure
-result.failure? # => true if failure, false if success
+result.success? # => true on success, false on failure
+result.failure? # => true on failure, false on success
+result.payload # => nil on failure, payload type on failure
+result.error # => nil on success, error type on failure
+result.payload_or("fallback") # => returns payload on success, given value on failure
+
+# You can combine all the above to write flow-sensitive type-checked code
+if result.success?
+  T.assert_type!(result.payload, Float)
+else
+  T.assert_type!(result.error, String)
+end
+```
+
+### Chaining
 
-result.error # => nil on success, nil or error type on failure
+`Typed::Result` supports chaining, so you can chain together methods that return `Typed::Result`s using.
 
-result.payload # => nil on failure, nil or payload type on failure
+To do so, use the `#and_then` method to transform the payload of a `Typed::Success` into another `Typed::Result`, or return a `Typed::Failure` as is.
 
-result.payload! # => payload type or raises NilPayloadError on success, raises NoPayloadOnFailureError on failure
+```ruby
+# In this example, retrieve_user and send_notification both return a Typed::Result
+#  retrieve_user: Typed::Result[User, RetrieveUserError
+#  send_notification: Typed::Result[T::Boolean, SendNotificationError]
+res = retrieve_user(user_id)
+  .and_then { |user| send_notification(user.email) } # this block will only run if retrieve_user returns a Typed::Success
+
+# The actual type of `res` is Typed::Result[T::Boolean, T.any(RetrieveUserError, SendNotificationError)]
+# because only the last operation can return a success, but any operation can return a failure.
+if res.success?
+  # Notification sent successfully, we can do something with res.payload coming from send_notification.
+  res.payload # => T::Boolean
+else
+  # Something went wrong, res.error could be either from retrieve_user or send_notification
+  res.error # => T.any(RetrieveUserError, SendNotificationError)
+end
+```
+
+You can also use the `#on_error` chain to take an action only on failure, such as logging or capturing error information in an error monitoring service.
+
+```ruby
+# In this example, retrieve_user and send_notification both return a Typed::Result
+#  retrieve_user: Typed::Result[User, RetrieveUserError
+#  send_notification: Typed::Result[T::Boolean, SendNotificationError]
+res = retrieve_user(user_id)
+  .and_then { |user| send_notification(user.email) } # this block will only run if retrieve_user returns a Typed::Success
+  .on_error { |error| puts "Encountered this error: #{error}"}
 ```
 
-The `payload!` method is useful if you don't want to do a `T.must` escape hatch, since the payload _could_ always be `nil`. If you're writing Railway inspired code, you should do the `success?` check before calling `payload!` and know that you've returned a payload on the Result.
+If the above chain does not fail, the `puts` statement is never run. If the chain does yield a `Failure`, the `puts` block is executed and the `Failure` is ultimately returned.
 
-### Why use Results?
+## Why use Results?
 
 Let's say you're working on a method that reaches out to an API and fetches a resource. We hope to get a successful response and continue on in our program, but you can imagine several scenarios where we don't get that response: our authentication could fail, the server could return a 5XX response code, or the resource we were querying could have moved or not exist any more.
 
@@ -102,13 +155,13 @@ Railway Oriented Programming, which comes from the functional programming commun
 sig { params(resource_id: Integer).returns(Typed::Result[Float, String]) }
 def call_api(resource_id)
   # something bad happened
-  return Typed::Failure.new(error: "I couldn't do it!")
+  return Typed::Failure.new("I couldn't do it!")
 
   # something other bad thing happened
-  return Typed::Failure.new(error: "I couldn't do it for another reason!")
+  return Typed::Failure.new("I couldn't do it for another reason!")
 
   # Success!
-  Typed::Success.new(payload: 1.12)
+  Typed::Success.new(1.12)
 end
 ```
 

data/Rakefile

@@ -7,6 +7,11 @@ Minitest::TestTask.create do |t|
   t.test_globs = ["test/**/*_test.rb"]
 end
 
+desc "Test Compiler output"
+task :compiler do
+  sh "./test/test_type_checker.sh"
+end
+
 require "rubocop/rake_task"
 
 RuboCop::RakeTask.new
@@ -21,4 +26,4 @@ task :sorbet do
   sh "bundle exec srb tc"
 end
 
-task default: %i[rubocop:autocorrect_all sorbet test]
+task default: %i[rubocop:autocorrect_all sorbet test compiler]

data/lib/typed/failure.rb

@@ -7,14 +7,28 @@ module Typed
     extend T::Sig
     extend T::Generic
 
-    Payload = type_member
+    Payload = type_member { { fixed: T.noreturn } }
     Error = type_member
 
-    sig { override.returns(T.nilable(Error)) }
+    sig { override.returns(Error) }
     attr_reader :error
 
-    sig { params(error: T.nilable(Error)).void }
-    def initialize(error: nil)
+    sig do
+      type_parameters(:T)
+        .params(error: T.type_parameter(:T))
+        .returns(Typed::Failure[T.type_parameter(:T)])
+    end
+    def self.new(error)
+      super(error)
+    end
+
+    sig { returns(Typed::Failure[NilClass]) }
+    def self.blank
+      new(nil)
+    end
+
+    sig { params(error: Error).void }
+    def initialize(error)
       @error = error
       super()
     end
@@ -29,14 +43,39 @@ module Typed
       true
     end
 
-    sig { override.returns(T.nilable(Payload)) }
+    sig { override.returns(T.noreturn) }
     def payload
-      nil
+      raise NoPayloadOnFailureError
     end
 
-    sig { override.returns(Payload) }
-    def payload!
-      raise NoPayloadOnFailureError
+    sig do
+      override
+        .type_parameters(:U, :T)
+        .params(_block: T.proc.params(arg0: Payload).returns(Result[T.type_parameter(:U), T.type_parameter(:T)]))
+        .returns(Result[T.type_parameter(:U), Error])
+    end
+    def and_then(&_block)
+      self
+    end
+
+    sig do
+      override
+        .params(block: T.proc.params(arg0: Error).void)
+        .returns(T.self_type)
+    end
+    def on_error(&block)
+      block.call(error)
+      self
+    end
+
+    sig do
+      override
+        .type_parameters(:Fallback)
+        .params(value: T.type_parameter(:Fallback))
+        .returns(T.any(Payload, T.type_parameter(:Fallback)))
+    end
+    def payload_or(value)
+      value
     end
   end
 end

data/lib/typed/no_error_on_success_error.rb

@@ -0,0 +1,14 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Typed
+  # Error when user attempts to access payload from a Failure Result.
+  class NoErrorOnSuccessError < StandardError
+    extend T::Sig
+
+    sig { void }
+    def initialize
+      super("Attempted to access `error` from a Success Result. You were probably expecting a Failure Result. Check the result with `#success?` or `#failure?` before attempting to access `error`.") # rubocop:disable Layout/LineLength
+    end
+  end
+end

data/lib/typed/no_payload_on_failure_error.rb

@@ -8,7 +8,7 @@ module Typed
 
     sig { void }
     def initialize
-      super("Attempted to access a payload from a Failure Result. You were probably expecting a Success Result. Check the result with #success? or #failure? before attempting to access the payload.") # rubocop:disable Layout/LineLength
+      super("Attempted to access `payload` from a Failure Result. You were probably expecting a Success Result. Check the result with `#success?` or `#failure?` before attempting to access `payload`.") # rubocop:disable Layout/LineLength
     end
   end
 end

data/lib/typed/result.rb

@@ -10,8 +10,8 @@ module Typed
 
     abstract!
 
-    Payload = type_member
-    Error = type_member
+    Payload = type_member(:out)
+    Error = type_member(:out)
 
     sig { abstract.returns(T::Boolean) }
     def success?; end
@@ -19,13 +19,33 @@ module Typed
     sig { abstract.returns(T::Boolean) }
     def failure?; end
 
-    sig { abstract.returns(T.nilable(Payload)) }
+    sig { abstract.returns(Payload) }
     def payload; end
 
-    sig { abstract.returns(T.nilable(Error)) }
+    sig { abstract.returns(Error) }
     def error; end
 
-    sig { abstract.returns(Payload) }
-    def payload!; end
+    sig do
+      abstract
+        .type_parameters(:U, :T)
+        .params(_block: T.proc.params(arg0: Payload).returns(Result[T.type_parameter(:U), T.type_parameter(:T)]))
+        .returns(T.any(Result[T.type_parameter(:U), T.type_parameter(:T)], Result[T.type_parameter(:U), Error]))
+    end
+    def and_then(&_block); end
+
+    sig do
+      abstract
+        .params(block: T.proc.params(arg0: Error).void)
+        .returns(T.self_type)
+    end
+    def on_error(&block); end
+
+    sig do
+      abstract
+        .type_parameters(:Fallback)
+        .params(value: T.type_parameter(:Fallback))
+        .returns(T.any(Payload, T.type_parameter(:Fallback)))
+    end
+    def payload_or(value); end
   end
 end

data/lib/typed/success.rb

@@ -8,13 +8,27 @@ module Typed
     extend T::Generic
 
     Payload = type_member
-    Error = type_member
+    Error = type_member { { fixed: T.noreturn } }
 
-    sig { override.returns(T.nilable(Payload)) }
+    sig { override.returns(Payload) }
     attr_reader :payload
 
-    sig { params(payload: T.nilable(Payload)).void }
-    def initialize(payload: nil)
+    sig do
+      type_parameters(:T)
+        .params(payload: T.type_parameter(:T))
+        .returns(Typed::Success[T.type_parameter(:T)])
+    end
+    def self.new(payload)
+      super(payload)
+    end
+
+    sig { returns(Typed::Success[NilClass]) }
+    def self.blank
+      new(nil)
+    end
+
+    sig { params(payload: Payload).void }
+    def initialize(payload)
       @payload = payload
       super()
     end
@@ -29,19 +43,38 @@ module Typed
       false
     end
 
-    sig { override.returns(NilClass) }
+    sig { override.returns(T.noreturn) }
     def error
-      nil
+      raise NoErrorOnSuccessError
     end
 
-    sig { override.returns(Payload) }
-    def payload!
-      case @payload
-      when nil
-        raise NilPayloadError
-      else
-        @payload
-      end
+    sig do
+      override
+        .type_parameters(:U, :T)
+        .params(block: T.proc.params(arg0: Payload).returns(Result[T.type_parameter(:U), T.type_parameter(:T)]))
+        .returns(Result[T.type_parameter(:U), T.type_parameter(:T)])
+    end
+    def and_then(&block)
+      block.call(payload)
+    end
+
+    sig do
+      override
+        .params(_block: T.proc.params(arg0: Error).void)
+        .returns(T.self_type)
+    end
+    def on_error(&_block)
+      self
+    end
+
+    sig do
+      override
+        .type_parameters(:Fallback)
+        .params(_value: T.type_parameter(:Fallback))
+        .returns(T.any(Payload, T.type_parameter(:Fallback)))
+    end
+    def payload_or(_value)
+      payload
     end
   end
 end

data/sorbet/config

@@ -2,3 +2,4 @@
 .
 --ignore=tmp/
 --ignore=vendor/
+--ignore=test/test_data/