Ruby, RBS vs. Sorbet

[dannysheridan]

To be continued by Ethan...

[ethnt]

Background

Sorbet

• Sorbet is a type checker for Ruby developed by Stripe
• Supports both static and runtime type checking

RBS

• RBS is a type annotation system for Ruby developed by members of the Ruby core team
• RBS itself does not provide type checking — it is merely a type annotation system — you use a tool like Steep to run type checking

Syntax

Sorbet

• Sorbet type signatures are valid Ruby code that is inline with the code it is annotating

• Type signatures can also be annotated in separate .rbi files

• Code sample

  # typed: strict
  
  class Direction < T::Enum
    enums do
      North = new
      South = new
      East = new
      West = new
    end
  end
  
  module Vehicle
    extend T::Sig
    extend T::Helpers
    interface!
  
    sig { abstract.params(direction: Direction).returns(T::Boolean) }
    def go(direction)
    end
  end
  
  class Car
    extend T::Sig
    include Vehicle
  
    sig(:final) { override.params(direction: Direction).returns(T::Boolean) }
    def go(direction)
      case direction
      when Direction::East
        true
      else
        false
      end
    end
  end
  
  class Truck < Car
    extend T::Sig
  
    include Vehicle
  end
  
  class Boat
    extend T::Sig
    include Vehicle
  
    sig(:final) { override.params(direction: Direction).returns(T::Boolean) }
    def go(direction)
      case direction
      when Direction::West
        true
      else
        false
      end
    end
  end
  
  car = Car.new
  car.go(Direction::East) # => true
  
  boat = Boat.new
  boat.go(Direction::East) # => false

RBS

• RBS type signatures are in separate, generally co-located .rbs files

• Code sample

  interface _Vehicle
    def go: (Symbol) -> bool
  end
  
  class Car
    include _Vehicle
    
    def go: (Symbol) -> bool
  end

Advantages

Sorbet

• Mature (open-source since mid-2019, under development internally at Stripe for a year or so previously)
• Under active development (and will continue to be, as long as Stripe has a Sorbet team)
• Has support of big players in the industry (Stripe, Shopify, and Gusto)
• There are useful built-in data types:
  • T::Enum for enumerations
  • T::Struct for a typed version of the Ruby Struct class
• Inline type assertions
  • T.let(value, type) for runtime type checking
  • T.must(value) to assert non-nil values

RBS

• Has the support of the Ruby core team
• Under active development
• Can type unions between non-class values
• More expressive overloading with multiple method signatures

Disadvantages

Sorbet

• Much heavier toolchain (especially sorbet-runtime)
• For DSLs or more dynamic scenarios, almost necessitates code generation

RBS

• No inline type assertions
• Lack of adoption across the Ruby ecosystem

What about YARD/RDoc?

What’s the difference between YARD and RDoc?

YARD is a superset of RDoc, which itself is part of the Ruby langauge. YARD has very wide adoption across the Ruby ecosystem — while you can still use RDoc, YARD is much more descriptive and has mostly overtaken RDoc usage elsewhere.

Nothing about RBS or Sorbet precludes you from using YARD (or RDoc, for that matter). In fact, it’s probably beneficial to use YARD in addition to Sorbet or RBS because of its documentation generation capabilities.

Is it possible to use both?

You can, generally, use both Sorbet and RBS — with a bit of a catch. Because of the aforementioned flexibility limitations within Sorbet, there is certain code (especially around duck typing) that cannot be typed with Sorbet. There is an escape hatch in this scenario (using a return type of T.untyped) but the developer experience here isn’t great.

The way that this interoperability would work is that you would supply both .rbs and .rbi files

Recommendation

• Package both RBS (.rbs) and Sorbet (.rbi) definition files with the SDK gem
• Continue to use YARD documentation comments within the code

Open questions

• How should custom code be handled? Adding both RBS and RBI files is some overhead for implementing developers.
• Are we optimizing for developer experience with autocomplete? Or type correctness?
• How opposed are we to a larger amount of generated code? This approach would necessitate quite a bit of code that is generated in terms of type definition files.

Next steps

• Proof of concept RubyGem that implements both RBS and RBI type definitions.

Resources

• https://github.com/ruby/rbs/blob/master/docs/gem.md
• https://sorbet.org/docs/rbi

[developer88]

Note, that RBS has rbs-inline which brings inline capabilities.

[ethnt]

What about Sorbet runtime checking?

Sorbet supports runtime checks where the type signatures will be validated when the code is run in production. There are a few advantages to this:

• Tests now become defacto type checks by exercising the typed code
• Potentially problematic input types get caught earlier up in the call stack, as there are still scenarios where static checking will not catch type errors
• With a large untyped codebase that is being gradually migrated to a typed one, runtime checks adds confidence

There are also a few disadvantages:

• The sorbet-runtime gem is required, and often can be difficult to install (it ships with C extensions)
• Versioning of the sorbet-runtime gem can be... complicated. New versions are released frequently, and there can be subtle differences between the version that an application using the SDK is using vs. the one the SDK is using

Given that we have (nearly) complete control over the codebase and it can be typed from the get-go, there is not much advantage to using runtime checks here. This is a similar approach to the one that Stripe took with the stripe-ruby gem.