sorbet_operation 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: '0654591b2ec0d42146c7942a293437e589d7665bb12cccea68851b7350f91379'
+  data.tar.gz: 90718cfed8a9f9ba88e5074f94fe4d337a31e94a8297ae679c8b0fdfa3bce89a
+SHA512:
+  metadata.gz: e1dd98bdcdd68fbebc21d861892538310ee750fb23e255900cc7eb3eff1964b7d81e43d9675be30fcaa5c44ddc6f10737e2ad5a75d3c20b5fee4b21a0cb7dccd
+  data.tar.gz: e9f3b644e2a89d7482e8a98e1d9e3085e4e5709a89b9c2abb73de39a7478caf3a64ecef3818b0b0e0b964032999fe7b7666962da3d7b84f73f761d3c9673f951

data/.editorconfig

@@ -0,0 +1,12 @@
+# EditorConfig is awesome: https://EditorConfig.org
+
+# top-most EditorConfig file
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true

data/.rubocop.yml

@@ -0,0 +1,20 @@
+# Opinionated cops - see https://ruby-style-guide.shopify.dev/ for explanations
+inherit_gem:
+  rubocop-shopify: rubocop.yml
+
+require:
+  - rubocop-minitest
+  - rubocop-performance
+  - rubocop-rake
+  - rubocop-sorbet
+
+AllCops:
+  NewCops: enable
+  SuggestExtensions: false
+  TargetRubyVersion: 3.0
+
+Minitest/MultipleAssertions:
+  Enabled: false
+
+Sorbet/StrictSigil:
+  Enabled: true

data/.ruby-version

@@ -0,0 +1 @@
+3.0.6

data/.yardopts

@@ -0,0 +1,3 @@
+--markup markdown
+--protected
+--plugin sorbet

data/Gemfile

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in sorbet_operation.gemspec
+gemspec
+
+gem "rake", "~> 13.0"
+
+group :development, :test do
+  gem "pry"
+  gem "pry-byebug"
+end
+
+group :development do
+  gem "sorbet", "~> 0.5.10736"
+  gem "tapioca", require: false
+
+  gem "rubocop", require: false
+  gem "rubocop-minitest", require: false
+  gem "rubocop-performance", require: false
+  gem "rubocop-rake", require: false
+  gem "rubocop-shopify", require: false
+  gem "rubocop-sorbet", require: false
+
+  gem "bundler-audit", require: false
+end
+
+group :test do
+  gem "minitest", "~> 5.0"
+  gem "minitest-reporters", "~> 1.4"
+
+  gem "simplecov", require: false
+end
+
+group :docs do
+  gem "yard"
+  gem "yard-sorbet"
+end

data/Gemfile.lock

@@ -0,0 +1,135 @@
+PATH
+  remote: .
+  specs:
+    sorbet_operation (0.1.0)
+      sorbet-runtime (~> 0.5.10741)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ansi (1.5.0)
+    ast (2.4.2)
+    builder (3.2.4)
+    bundler-audit (0.9.1)
+      bundler (>= 1.2.0, < 3)
+      thor (~> 1.0)
+    byebug (11.1.3)
+    coderay (1.1.3)
+    diff-lcs (1.5.0)
+    docile (1.4.0)
+    json (2.6.3)
+    method_source (1.0.0)
+    minitest (5.18.0)
+    minitest-reporters (1.6.0)
+      ansi
+      builder
+      minitest (>= 5.0)
+      ruby-progressbar
+    netrc (0.11.0)
+    parallel (1.22.1)
+    parser (3.2.2.0)
+      ast (~> 2.4.1)
+    pry (0.14.2)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
+    pry-byebug (3.10.1)
+      byebug (~> 11.0)
+      pry (>= 0.13, < 0.15)
+    rainbow (3.1.1)
+    rake (13.0.6)
+    rbi (0.0.16)
+      ast
+      parser (>= 2.6.4.0)
+      sorbet-runtime (>= 0.5.9204)
+      unparser
+    regexp_parser (2.7.0)
+    rexml (3.2.5)
+    rubocop (1.48.1)
+      json (~> 2.3)
+      parallel (~> 1.10)
+      parser (>= 3.2.0.0)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml (>= 3.2.5, < 4.0)
+      rubocop-ast (>= 1.26.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 3.0)
+    rubocop-ast (1.28.0)
+      parser (>= 3.2.1.0)
+    rubocop-minitest (0.29.0)
+      rubocop (>= 1.39, < 2.0)
+    rubocop-performance (1.16.0)
+      rubocop (>= 1.7.0, < 2.0)
+      rubocop-ast (>= 0.4.0)
+    rubocop-rake (0.6.0)
+      rubocop (~> 1.0)
+    rubocop-shopify (2.12.0)
+      rubocop (~> 1.44)
+    rubocop-sorbet (0.7.0)
+      rubocop (>= 0.90.0)
+    ruby-progressbar (1.13.0)
+    simplecov (0.22.0)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.12.3)
+    simplecov_json_formatter (0.1.4)
+    sorbet (0.5.10741)
+      sorbet-static (= 0.5.10741)
+    sorbet-runtime (0.5.10741)
+    sorbet-static (0.5.10741-universal-darwin-22)
+    sorbet-static (0.5.10741-x86_64-linux)
+    sorbet-static-and-runtime (0.5.10741)
+      sorbet (= 0.5.10741)
+      sorbet-runtime (= 0.5.10741)
+    spoom (1.2.1)
+      sorbet (>= 0.5.10187)
+      sorbet-runtime (>= 0.5.9204)
+      thor (>= 0.19.2)
+    tapioca (0.11.4)
+      bundler (>= 2.2.25)
+      netrc (>= 0.11.0)
+      parallel (>= 1.21.0)
+      rbi (~> 0.0.0, >= 0.0.16)
+      sorbet-static-and-runtime (>= 0.5.10187)
+      spoom (~> 1.2.0, >= 1.2.0)
+      thor (>= 1.2.0)
+      yard-sorbet
+    thor (1.2.1)
+    unicode-display_width (2.4.2)
+    unparser (0.6.7)
+      diff-lcs (~> 1.3)
+      parser (>= 3.2.0)
+    webrick (1.7.0)
+    yard (0.9.28)
+      webrick (~> 1.7.0)
+    yard-sorbet (0.8.0)
+      sorbet-runtime (>= 0.5)
+      yard (>= 0.9)
+
+PLATFORMS
+  arm64-darwin-22
+  x86_64-linux
+
+DEPENDENCIES
+  bundler-audit
+  minitest (~> 5.0)
+  minitest-reporters (~> 1.4)
+  pry
+  pry-byebug
+  rake (~> 13.0)
+  rubocop
+  rubocop-minitest
+  rubocop-performance
+  rubocop-rake
+  rubocop-shopify
+  rubocop-sorbet
+  simplecov
+  sorbet (~> 0.5.10736)
+  sorbet_operation!
+  tapioca
+  yard
+  yard-sorbet
+
+BUNDLED WITH
+   2.4.3

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 Thatch Health, Inc.
+
+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,116 @@
+# sorbet_operation
+
+[![Build Status](https://github.com/thatch-health/sorbet_operation/actions/workflows/main.yml/badge.svg?branch=main)](https://github.com/thatch-health/sorbet_operation/actions?query=branch%3Amain)
+
+sorbet_operation is a minimal operation framework that leverages Sorbet's type system to ensure that operations are well-typed and that their inputs and outputs are well-defined.
+
+An operation is a Ruby class that encapsulates business logic. It is similar to a service class, but whereas service classes often group several related methods, an operation object does one and only one thing.
+
+For example, here is an operation that creates a new user:
+```ruby
+class CreateUser < SorbetOperation::Base
+  ValueType = type_member { { fixed: User } }
+
+  sig { params(user_params: ActiveSupport::Parameters).void }
+  def initialize(user_params)
+    @user_params = user_params
+  end
+
+  protected
+
+  sig { returns(ValueType) }
+  def execute
+    User.create!(@user_params)
+  rescue => e
+    raise SorbetOperation::Failure, "User creation failed: #{e.message}"
+  end
+end
+```
+
+In a Rails controller, this operation could be used as follows:
+```ruby
+class UsersController < ApplicationController
+  def create
+    result = CreateUser.new(user_params).perform
+    if operation.success?
+      user = result.unwrap!
+      T.reveal_type(user) # `User`
+      redirect_to user
+    else
+      error = result.unwrap_error!
+      T.reveal_type(error) # `SorbetOperation::Error`
+      render :new, alert: error.message
+    end
+  end
+
+  private
+
+  def user_params
+    params.require(:user).permit(:name, :email, :password)
+  end
+end
+```
+
+Operations return a result object which indicates whether the operation was successful or not. The result object wraps the return value of the operation if it was successful, or an instance of `SorbetOperation::Error` if it failed.
+
+## Installation
+
+This gem is not yet published to RubyGems.org. For now, you can install it by adding the following to your `Gemfile`:
+```ruby
+gem "sorbet_operation", github: "thatch-health/sorbet_operation", branch: "main"
+```
+
+TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+    $ gem install UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG
+
+## Usage
+
+An operation is a Ruby class that derives from `SorbetOperation::Base`. `SorbetOperation::Base` is an abstract generic class which requires derived classes to do two things:
+1. define the return type using the `ValueType` generic type member
+2. define an `#execute` method that returns a `ValueType`
+
+The `#execute` method should be `protected` or `private`, since it is not meant to be invoked directly; rather, operation callers should use the `#perform` public method to actually perform the operation. (Unfortunately, at this time there is no mechanism to enforce that `#execute` is not a public method on child classes, so it's up to the programmer to be vigilant.)
+
+The `#execute` method does not take any arguments. Most operations require one or more input values. Input values should be passed to the `#initialize` constructor method and stored as instance variables, which can then be accessed from the `#execute` body.
+
+There are two possible outcomes for an operation:
+1. if `#execute` returns an instance of `ValueType`, then the operation result is a success
+2. if `#execute` raises a `SorbetOperation::Error`, then the operation result is a failure
+
+Exceptions that are not an instance of `SorbetOperation::Error` will not be caught by the framework and will be propagated to the operation callsite.
+
+### Using results
+
+Operation callers call `#perform` to perform the operation. `#perform` does not directly the return value of the operation; rather, it returns an instance of `SorbetOperation::Result`, a generic class that wraps the return value or the error depending on whether the operation succeeds or fails.
+
+The `SorbetOperation::Result` class is inspired by Rust's [`Result`](https://doc.rust-lang.org/std/result/enum.Result.html) type, and as a result the API is very similar.
+
+### Operations without a return value
+
+Some operations may be pure side-effects and not need to return anything. When this is the case, you can simply define `ValueType` to be `NilClass`:
+```ruby
+ValueType = { { fixed: NilClass } }
+```
+
+(Alternatively, you could use `Sorbet::Private::Static::Void` instead of `NilClass`. This is arguably better typing, but relying on a type nested under the `Sorbet::Private` namespace is not recommended.)
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `bin/rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bin/rake install`. To release a new version, update the version number in `version.rb`, and then run `bin/rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/thatch-health/sorbet_operation.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+require "rubocop/rake_task"
+require "yard"
+require "bundler/audit/task"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+task default: :test
+
+RuboCop::RakeTask.new do |t|
+  t.options = ["--parallel"]
+end
+
+YARD::Rake::YardocTask.new
+
+Bundler::Audit::Task.new

data/lib/sorbet_operation/base.rb

@@ -0,0 +1,87 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+require "logger"
+
+require_relative "failure"
+require_relative "result"
+
+module SorbetOperation
+  # Abstract base class for operations.
+  #
+  # Subclasses must:
+  #
+  # 1. define the {ValueType} type member
+  # 2. implement the {#execute} method
+  class Base
+    extend T::Sig
+    extend T::Helpers
+    extend T::Generic
+
+    abstract!
+
+    # The type of the value returned by this operation. The type can be any
+    # valid Sorbet type, as long as it's a subtype of `Object`.
+    #
+    # @example If the operation returns a String or nil
+    #   ValueType = type_member { { fixed: T.nilable(String) } }
+    #
+    # @example If the operation does not return a value
+    #   ValueType = type_member { { fixed: NilClass } }
+    #
+    # @see https://sorbet.org/docs/generics#type_member--type_template
+    # @see https://sorbet.org/docs/generics#bounds-on-type_members-and-type_templates-fixed-upper-lower
+    ValueType = type_member { { upper: Object } }
+
+    # Performs the operation and returns the result.
+    sig { returns(Result[ValueType]) }
+    def perform
+      logger.debug("Performing operation #{self.class.name}")
+
+      begin
+        value = execute
+      rescue Failure => e
+        logger.debug("Operation #{self.class.name} failed, failure = #{e.inspect}")
+
+        Result.new(false, nil, e)
+      else
+        logger.debug("Operation #{self.class.name} succeeded, return value = #{value.inspect}")
+
+        Result.new(true, value, nil)
+      end
+    end
+
+    # The logger for this operation.
+    sig { params(logger: ::Logger).void }
+    attr_writer :logger
+
+    protected
+
+    # Implement this method in subclasses to perform the operation.
+    #
+    # This method must either return a value of type {ValueType}, in which
+    # case the operation is considered successful, or raise an exception of
+    # type {SorbetOperation::Failure}, in which case the operation is
+    # considered failed.
+    #
+    # Raising an exception of any other type will result in an unhandled
+    # exception. The exception will not be caught and will be propagated to
+    # the caller.
+    #
+    # This method should be declared as `protected` in subclasses to prevent
+    # callers from calling it directly. Callers should instead call {#perform}
+    # to perform the operation and get the result.
+    sig { abstract.returns(ValueType) }
+    def execute; end
+
+    # Returns the logger for this operation. If no logger has been set, the
+    # default logger will be returned instead.
+    sig { returns(::Logger) }
+    def logger
+      @logger = T.let(@logger, T.nilable(::Logger))
+      @logger ||= SorbetOperation.default_logger
+    end
+  end
+end

data/lib/sorbet_operation/failure.rb

@@ -0,0 +1,17 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+module SorbetOperation
+  # Exception class used to indicate that an operation failed.
+  #
+  # Raise this exception (or a subclass of it) from an operation's
+  # {SorbetOperation::Operation#execute} method to indicate that the operation
+  # failed.
+  #
+  # If you need to pass additional information about the failure, you can
+  # subclass this exception and add any additional attributes you need.
+  class Failure < ::StandardError
+  end
+end

data/lib/sorbet_operation/result.rb

@@ -0,0 +1,200 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+require_relative "failure"
+
+module SorbetOperation
+  # {SorbetOperation::Result} is a generic class that represents the result of
+  # an operation, either success or failure.
+  #
+  # If the result is a success, it wraps a value of type member
+  # {SorbetOperation::Result::ValueType}.
+  #
+  # If the result is a failure, it wraps an exception of type
+  # {SorbetOperation::Failure}.
+  class Result
+    extend T::Sig
+    extend T::Generic
+
+    # The type of the value wrapped by the {Result}. The type can be any
+    # valid Sorbet type, as long as it's a subtype of `Object`.
+    ValueType = type_member { { upper: Object } }
+
+    # Constructs a new {Result}, either a success or a failure.
+    #
+    # If `success` is `true`, then `value` must be provided (although it can
+    # be nil, because {ValueType} may be nilable) and `error` must be nil.
+    #
+    # If `success` is `false`, then `value` must be nil and `error` must be
+    # non-nil.
+    #
+    # Calling this constructor directly should rarely be necessary. In normal
+    # usage, {SorbetOperation::Base#perform} will return a {Result} for you.
+    sig { params(success: T::Boolean, value: T.nilable(ValueType), error: T.nilable(Failure)).void }
+    def initialize(success, value, error)
+      @success = success
+      @value = value
+      @error = error
+
+      # NOTE: these checks are annoying. A better API would be to make this
+      # constructor private and provide two factory methods:
+      # - `Result.success(value)`
+      # - `Result.failure(error)`
+      #
+      # However, in order to do this, we would need to be able to use
+      # {ValueType} in class methods. At this time, there is no way to tell
+      # Sorbet that a generic type applies to both the class and its
+      # singleton. We would need to duplicate the value type:
+      # ```
+      # ValueTypeMember = type_member { { upper: Object } }
+      # ValueTypeTemplate = type_template { { upper: Object } }
+      # ```
+      # and every subclass would need to specify both (and ensure that
+      # they're both set to the same type). This would be quite clumsy. Since
+      # `Result` should rarely be instantiated directly (rather, it's
+      # instantiated by `SorbetOperation::Base#perform`), we'll just live with
+      # this less than ideal API for now.
+      if @success
+        # We can't test that value is not nil because the value type can be
+        # nilable. (In theory we could check if the type is nilable and only
+        # apply the check if it's not, but that's not worth the complexity.)
+        unless error.nil?
+          raise ArgumentError, "Cannot pass an error to a success result"
+        end
+      elsif error.nil?
+        raise ArgumentError, "Must pass an error to a failure result"
+      elsif !value.nil?
+        raise ArgumentError, "Cannot pass a value to a failure result"
+      end
+    end
+
+    # Returns `true` if the result is a success.
+    sig { returns(T::Boolean) }
+    def success?
+      @success
+    end
+
+    # Returns `true` if the result is a failure.
+    sig { returns(T::Boolean) }
+    def failure?
+      !success?
+    end
+
+    # Returns the contained value if the result is a success, otherwise raises
+    # the contained error.
+    sig { returns(ValueType) }
+    def unwrap!
+      raise T.must(@error) if failure?
+
+      casted_value
+    end
+
+    # Returns the contained value if the result is a success, otherwise
+    # returns `nil`.
+    sig { returns(T.nilable(ValueType)) }
+    def safe_unwrap
+      return nil if failure?
+
+      casted_value
+    end
+
+    # Returns the contained value if the result is a success, otherwise
+    # returns the provided default value.
+    #
+    # @example
+    #   result = SomeOperation.new.perform
+    #   result.failure? # => true
+    #   value = result.unwrap_or(456)
+    #   value # => 456
+    sig { params(default: ValueType).returns(ValueType) }
+    def unwrap_or(default)
+      return casted_value if success?
+
+      default
+    end
+
+    # Returns the contained value if the result is a success, otherwise calls
+    # the block with the contained error and returns the block's return value.
+    #
+    # @example
+    #   result = SomeOperation.new.perform
+    #   result.failure? # => true
+    #   value = result.unwrap_or_else { |_| 456 }
+    #   value # => 456
+    sig { params(blk: T.proc.params(error: Failure).returns(ValueType)).returns(ValueType) }
+    def unwrap_or_else(&blk)
+      return casted_value if success?
+
+      yield(T.must(@error))
+    end
+
+    # Returns the contained error if the result is a failure, otherwise raises
+    # an error.
+    sig { returns(Failure) }
+    def unwrap_error!
+      return T.must(@error) if failure?
+
+      # TODO: custom error type?
+      raise "Called `unwrap_err!` on a success"
+    end
+
+    # Returns the contained error if the result is a failure, otherwise
+    # returns `nil`.
+    sig { returns(T.nilable(Failure)) }
+    def safe_unwrap_error
+      return T.must(@error) if failure?
+
+      nil
+    end
+
+    # Yields the contained value if the result is a success, otherwise does
+    # nothing. Returns `self` so this call can be chained to `#on_failure`.
+    #
+    # @example
+    #   SomeOperation.new.perform
+    #    .on_success { |value| puts "Success! Value: #{value}" }
+    #    .on_failure { |error| puts "Failure! Error: #{error}" }
+    sig { params(blk: T.proc.params(value: ValueType).void).returns(T.self_type) }
+    def on_success(&blk)
+      yield(casted_value) if success?
+      self
+    end
+
+    # Yields the contained error if the result is a failure, otherwise does
+    # nothing. Returns `self` so this call can be chained to `#on_success`.
+    #
+    # @example
+    #   SomeOperation.new.perform
+    #    .on_success { |value| puts "Success! Value: #{value}" }
+    #    .on_failure { |error| puts "Failure! Error: #{error}" }
+    sig { params(blk: T.proc.params(error: Failure).void).returns(T.self_type) }
+    def on_failure(&blk)
+      yield(T.must(@error)) if failure?
+      self
+    end
+
+    private
+
+    # A word of explanation as to why this is necessary: the `value` argument
+    # in `Result`'s constructor is typed as `T.nilable(ValueType)`, because it
+    # will be `nil` for failure results.
+    #
+    # The signatures for `unwrap!`, `unwrap_or_else`, and `on_success` all use
+    # (non-nilable) `ValueType` because in those cases, we know that the result
+    # is a success.
+    #
+    # However, `ValueType` can be nilable, in which case `nil` is a valid
+    # value for a success result. As a result, we can't just wrap `value` in
+    # `T.must`. Instead, we cast `@value` from `T.nilable(ValueType)` to
+    # `ValueType`, which is ~the same thing as `T.must` but doesn't raise a
+    # runtime error if `ValueType` is nilable and `@value` is `nil`.
+    #
+    # There's probably a better way to handle this.
+    sig { returns(ValueType) }
+    def casted_value
+      T.cast(@value, ValueType)
+    end
+  end
+end

data/lib/sorbet_operation/version.rb

@@ -0,0 +1,6 @@
+# typed: strict
+# frozen_string_literal: true
+
+module SorbetOperation
+  VERSION = "0.1.0"
+end

data/lib/sorbet_operation.rb

@@ -0,0 +1,31 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+require "logger"
+
+# foo
+#
+# fewfwefw
+module SorbetOperation
+  class << self
+    extend T::Sig
+
+    # Returns the default logger used by operations.
+    sig { returns(::Logger) }
+    def default_logger
+      @default_logger = T.let(@default_logger, T.nilable(::Logger))
+      @default_logger ||= ::Logger.new($stdout, level: ::Logger::INFO)
+    end
+
+    # Sets the default logger used by operations.
+    sig { params(default_logger: T.nilable(::Logger)).void }
+    attr_writer :default_logger
+  end
+end
+
+require_relative "sorbet_operation/base"
+require_relative "sorbet_operation/failure"
+require_relative "sorbet_operation/result"
+require_relative "sorbet_operation/version"

data/sorbet_operation.gemspec

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "lib/sorbet_operation/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "sorbet_operation"
+  spec.version = SorbetOperation::VERSION
+  spec.authors = ["Thatch Health, Inc."]
+  spec.email = ["sorbet-operation@thatch.ai"]
+
+  spec.summary = "Sorbet-powered operation framework."
+  spec.description = "sorbet_operation is a minimal operation framework that leverages Sorbet's type system to "\
+    "ensure that operations are well-typed and that their inputs and outputs are well-defined."
+  spec.homepage = "https://github.com/thatch-health/sorbet_operation"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.0.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "https://github.com/thatch-health/sorbet_operation/blob/main/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(__dir__) do
+    %x(git ls-files -z).split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:bin|test|spec|features|sorbet)/|\.(?:git|circleci|vscode)|appveyor)})
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Uncomment to register a new dependency of your gem
+  spec.add_runtime_dependency("sorbet-runtime", "~> 0.5.10741")
+
+  # For more information and examples about making a new gem, check out our
+  # guide at: https://bundler.io/guides/creating_gem.html
+end

metadata

@@ -0,0 +1,77 @@
+--- !ruby/object:Gem::Specification
+name: sorbet_operation
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Thatch Health, Inc.
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2023-08-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: sorbet-runtime
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.5.10741
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.5.10741
+description: sorbet_operation is a minimal operation framework that leverages Sorbet's
+  type system to ensure that operations are well-typed and that their inputs and outputs
+  are well-defined.
+email:
+- sorbet-operation@thatch.ai
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".editorconfig"
+- ".rubocop.yml"
+- ".ruby-version"
+- ".yardopts"
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/sorbet_operation.rb
+- lib/sorbet_operation/base.rb
+- lib/sorbet_operation/failure.rb
+- lib/sorbet_operation/result.rb
+- lib/sorbet_operation/version.rb
+- sorbet_operation.gemspec
+homepage: https://github.com/thatch-health/sorbet_operation
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/thatch-health/sorbet_operation
+  source_code_uri: https://github.com/thatch-health/sorbet_operation
+  changelog_uri: https://github.com/thatch-health/sorbet_operation/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: Sorbet-powered operation framework.
+test_files: []