sorbet

Sorbet with Inline RBS

How to write types in a project that typechecks with Sorbet using inline RBS comments. Signatures live in #: comments that Ruby ignores, so sorbet-runtime is not loaded and nothing about the types runs in production. The project's docs/type-checking.md takes priority over this guide. To introduce Sorbet to a project that does not have it yet, use the sorbet-adoption skill.

Ground rules

• Write signatures only as #: RBS comments in .rb files.
  • sig blocks, extend T::Sig, T.let, T.must, T.cast and T.untyped need sorbet-runtime. Where it is absent they raise NameError at load time. Where a gem pulls it in anyway, they turn into runtime checks nobody asked for.
  • .rbi shim files are the exception: they are never loaded, and sig blocks are the correct syntax there.
• Do not run srb tc -a. Its autocorrect inserts exactly the forbidden T. forms.
• A new file under app/, lib/ or config/ starts at # typed: strict. Spec files carry no sigil, because the RSpec DSL does not typecheck.
• The target level is strict, not true. At true, Sorbet requires no signatures, so a file can pass with almost none, and the signatures are what make the types useful to the next person writing a call.
• Run bundle exec srb tc from the project directory after every change.
• Before keeping or defending a workaround, delete it and run srb tc again. Many workarounds turn out to be unnecessary on a retry: a constant cast as untyped before .new, .class.to_s in place of .name, a cast on Time.current.

Signatures

#: (String, expires_in: Integer, ?scopes: Array[String]) -> Token
def issue(subject, expires_in:, scopes: [])

#: (String, readonly: bool, ?actor: User?,
#|  ?tags: Array[String]) -> void
def record_event(name, readonly:, actor: nil, tags: [])

#: [T] () { () -> T } -> T
def with_lock(&block)

#: Integer
attr_reader :max_age

DEFAULT_TTL = 300 #: Integer

def initialize(order_id:, amount:)
  @order_id = order_id
  @amount = BigDecimal(amount) #: BigDecimal
  @invoice = nil #: Invoice?
end