sorbet-result 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4eb8fb4c04fad76f6947a6c888e741ebc9154abb224edb87d5a8f3461aaabfc1
-  data.tar.gz: 3de9d634bec586f32a6d7151d826e78f125dabc6ae93423137bcc1c3985e8ef3
+  metadata.gz: 4721bbbd3c051fd826ebc2721567a032a6f64ffb7545c990cef2d5b82fd78305
+  data.tar.gz: bd1cf4a0d186f3ef0be4f8e8aba11908fe4e4546198a647e10140901f4c16069
 SHA512:
-  metadata.gz: ab3a1deeae77642c99de930d1d9ad7d772b0401bbdcedfc8e2b49c36839b1d6868a3a4b5643cc024304403a6b967855be0c0754c8079e84adc079d0792d9a350
-  data.tar.gz: 556bdd555bcb02e7976c09097fde14c06a9cbc7fa7bbf20aefa95610ea5d3d3b897ae1e8cb5700f6234ddd0a89f6293f874a3767c762e6321789e3909ecb5ee7
+  metadata.gz: d767cc69f61e9de10862ff3ceca4a9fbf880eb748cb7fb12c58f992b6a573a566ea15b6d5867bd47b42eac6a890195d29bd79731de56ef7b1bee90c51d31691d
+  data.tar.gz: 52577942ef7db2a668b3d505263507758c6a720271ed9e883a346e962c48e53ba3b4850f3fffd590f4580ff2bfb352c08dc2f2d1e503c4c790b58f896ff84a3a

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,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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.0)
       sorbet-runtime (~> 0.5)
       zeitwerk (~> 2.6)
 
@@ -14,7 +14,7 @@ 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)
@@ -30,10 +30,10 @@ GEM
       sorbet-runtime (>= 0.5.9204)
       unparser
     regexp_parser (2.8.0)
-    reline (0.3.3)
+    reline (0.3.5)
       io-console (~> 0.5)
     rexml (3.2.5)
-    rubocop (1.51.0)
+    rubocop (1.52.0)
       json (~> 2.3)
       parallel (~> 1.10)
       parser (>= 3.2.0.0)
@@ -43,7 +43,7 @@ GEM
       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 +52,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.10864)
+      sorbet-static (= 0.5.10864)
+    sorbet-runtime (0.5.10864)
+    sorbet-static (0.5.10864-universal-darwin-22)
+    sorbet-static (0.5.10864-x86_64-linux)
+    sorbet-static-and-runtime (0.5.10864)
+      sorbet (= 0.5.10864)
+      sorbet-runtime (= 0.5.10864)
     spoom (1.2.1)
       sorbet (>= 0.5.10187)
       sorbet-runtime (>= 0.5.9204)

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
 ```
 
@@ -64,17 +78,42 @@ result = call_api(1)
 
 result.success? # => true if success, false if failure
 result.failure? # => true if failure, false if success
+result.payload # => nil on failure, payload type on failure
+result.error # => nil on success, error type 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
+```
 
-result.error # => nil on success, nil or error type on failure
+### Chaining
 
-result.payload # => nil on failure, nil or payload type on failure
+`Typed::Result` supports chaining, so you can chain together methods that return `Typed::Result`s using.
 
-result.payload! # => payload type or raises NilPayloadError on success, raises NoPayloadOnFailureError 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.
 
-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.
+```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
+```
 
-### 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 +141,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,19 @@ 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
   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,18 @@ 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
   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,19 @@ 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
   end
 end

data/sorbet/config

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