sorbet-rails 0.5.9.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d1f0f0abf650a5deb1d7a365fc7feff0d07965c6aba43cdd5f8fc856351c9a54
-  data.tar.gz: 134c9924721309eda4b8a50c80bb97380e1d6628f7d4fbb6fb9447d7ec836b63
+  metadata.gz: 58c588bf2eb9eb09d2c4322d54436840452bb5a026e6ca4132df8e651aa26968
+  data.tar.gz: 11b54b70f6c86f5d97152fc5a7c9f0b48b021b8be03472fcb83014557353dc4c
 SHA512:
-  metadata.gz: 1170b14c1c3b0d1f3751f88b3d5b85e48b61569432eb9941fd569acf4089e1f466ebcd27c4cb41815adc5b6203cd40759276b1f6210efc435f859a220f8b86af
-  data.tar.gz: 4fd1da4f8639130b3a281fd68196f7228eed591d0e0b8fb173e332e06899ab32363a7d2d5d14b69741f7c931a9320758b83bbb42875ae1ece4119e89ac33c223
+  metadata.gz: 6b88d51c0fae405a9249974746b250ad6ad2ce8ca09a5620c385105bffd0617dd2fbf5584a07a35abb35104c8242a1954156be9f98ddc456554803ad3b2a92ac
+  data.tar.gz: 98c2836dcbbb20798d0b57579eb7c3a07175bf8e5c58ed062cb652d2c7826bf62c1586cc4a9a5337702e88151862c8caf4cda81a21765f583a3c85caefc3d659

data/.gitattributes

@@ -0,0 +1,4 @@
+lib/sorbet/* linguist-generated
+spec/test_data/* linguist-generated
+spec/support/* linguist-generated
+

data/.travis.yml

@@ -8,15 +8,15 @@ env:
   global:
     secure: S3rpBSDgDQjhA11/80dZ4RUlBP3XLJWOgvcl1eySFdXqHCZGS5p8Fa97yEvZHWiPInUTNhdvyQ5LHlgzu1CCZ9+MOykpEgYo+1yIueriv9Ia5PUNFbwhRp2eBkluSUMPNPOxf15mUlgAGdScnssRL9zftYel29dw4yg+BQnnkLOqpnLO7wHTjouEmp7M8Y/1j0ScIZ0tZL1ovDq70Lst+TJKHm4jdBbwoNmILIwNBgnzZT1LdAuaXVHEmwLvy0GLvClewuSmToJ4jyjuJorCjyMhyoBLrutSuN4KaJcSlP/LVtH4ZCFkFDayDMiVcSyUE3asSnL3yxGL0K99lgwNk4D58WWic7N+0UKnGoiMQOHC9EIsQKaxfXMOpO+Cq5wYhgmFzPGF4iL6ZBNCehcc+ToBojprmJw/0Ev71OS2YGvu5SZpYco5AvJeR73IUA2K0rjUEeY3gXm60aIac09kQuuminN3hUkJ894YoA35B8IEU0uW2uL5n/vX2Y8SD6RV8csbKlhpJmphYYWQQOYjHuFoW4MVnnrFHq6YIUDQpi6/We3I4xH3kvfjIpSemrYOmfF4PPXCarWA7ryI9ytR7BloQ0NQH7hqp1hbKN86LAy8zanW08xNOrxI7VDdbtV1k6mf+wiV1W2Vo54HYEDIw0+jwmW/uKWatTyRo5AUsMc=
 rvm:
-- 2.3
 - 2.4
 - 2.5
 - 2.6
+- 2.7
 - ruby-head
 matrix:
   include:
   - rvm: 2.5
-    env: RAILS_VERSION=5.2 SORBET_VERSION=0.4.4929
+    env: RAILS_VERSION=5.2 SORBET_VERSION=0.5.5400
   exclude:
   - rvm: 2.3
     env: RAILS_VERSION=6.0
@@ -28,7 +28,7 @@ before_install:
 - gem install bundler -v 2.0.1 --no-doc
 - gem install bundler -v 1.17.3 --no-doc
 script:
-- (cd lib && bundle exec srb tc)
+- bundle exec srb tc
 - "./spec/bin/run_spec.sh"
 deploy:
   provider: rubygems

data/README.md

@@ -7,9 +7,9 @@ A set of tools to make the [Sorbet](https://sorbet.org) typechecker work with Ru
 
 This gem adds a few Rake tasks to generate Ruby Interface (RBI) files for dynamic methods generated by Rails. It also includes signatures for related Rails classes. The RBI files are added to a `sorbet/rails-rbi/` folder.
 
-`sorbet-rails` supports Rails 4.2 or later.
+`sorbet-rails` supports Rails 5+ or later.
 
-**Notice**: From v0.6, we'll stop supporting Rails 4.2. Fixes targeting Rails 4.2 specifically can be merged to v0.5.x branch.
+**Notice**: we no longer supports Rails 4.2. [Version 0.5.6](https://github.com/chanzuckerberg/sorbet-rails/releases/tag/v0.5.6) is the last version supporting Rails 4.2.
 
 ## Initial Setup
 
@@ -72,44 +72,120 @@ It is possible to add custom RBI generation logic for your custom module or gems
 We also add following methods to make type-checking more easily:
 - [`find_n`, `first_n`, `last_n`](https://github.com/chanzuckerberg/sorbet-rails#find-first-and-last)
 - [`pluck_to_tstruct`](#pluck_to_tstruct-instead-of-pluck)
+- [`typed_enum`](#enums)
 
-### Controllers
-```sh
-❯ rake rails_rbi:custom
+#### `pluck_to_tstruct` instead of `pluck`
+
+The [`pluck` method](https://apidock.com/rails/ActiveRecord/Calculations/pluck) in Rails is a performant way to query value without instantiating ActiveRecord objects. However, it doesn't have any type information: it doesn't have type information (or name) of the attribute plucked. Sorbet-rails provides `pluck_to_tstruct` method as a replacement that returns an array of `T::Struct` instead. The attributes plucked is based on props defined in the `T::Struct`
+
+```ruby
+# -- API
+Arel.pluck_to_tstruct(TA[ <TStructSubClass> ].new)
+
+# -- example
+class WizardStruct < T::Struct
+  const :name, String
+  const :house, T.nilable(String)
+end
+
+Wizard.pluck_to_tstruct(TA[WizardStruct].new)  # T::Array[WizardStruct]
+Wizard.all.pluck_to_tstruct(TA[WizardStruct].new)  # T::Array[WizardStruct]
+```
+
+This method is based on [pluck_to_hash](https://github.com/girishso/pluck_to_hash) gem.
+
+#### Enums
+
+If you use [Rails `enum`](https://guides.rubyonrails.org/active_record_querying.html#enums), `sorbet-rails` will generate a corresponding `T::Enum`. It will also include getters, setters, and scope methods in the rbi file it generates.
+
+ie.
+
+```ruby
+  enum house: {
+    Gryffindor: 0,
+    Hufflepuff: 1,
+    Ravenclaw: 2,
+    Slytherin: 3,
+  }
+```
+
+Will generate this enum:
+
+```ruby
+class Wizard::House < T::Enum
+  enums do
+    Gryffindor = new('Gryffindor')
+    Hufflepuff = new('Hufflepuff')
+    Ravenclaw = new('Ravenclaw')
+    Slytherin = new('Slytherin')
+  end
+end
+```
+
+And these methods:
+
+```ruby
+  sig { returns(T.nilable(String)) }
+  def house; end
+
+  sig { params(value: T.nilable(T.any(Integer, String, Symbol))).void }
+  def house=(value); end
+
+  sig { returns(T.nilable(Wizard::House)) }
+  def typed_house; end
+
+  sig { params(value: T.nilable(Wizard::House)).void }
+  def typed_house=(value); end
 ```
 
-`sorbet-rails` adds methods to extract typed parameters from `params`, namely `require_typed` and `fetch_typed`. They are direct replacement of `require` and `fetch` that return typed object. They have the same API their counterpart, with an addition of the parameter's type, which can be any type understood by `sorbet`
+Alternatively, you can replace your call to `enum` with `typed_enum`. This will hide the Rails methods (`house`) from Sorbet static-check (they are still usable in un-checked files).
 
-This is the conversion in essence:
 ```ruby
-params.require(:key)              -> params.require_typed(:key, TA[Type].new)
-params.fetch(:key)                -> params.fetch_typed(:key, TA[Type].new)
-params.fetch(:key, default_value) -> params.fetch_typed(:key, TA[Type].new, default_value)
-params[:key]                      -> params.fetch_typed(:key, TA[T.nilable(Type)].new, nil)
+  typed_enum house: {
+    Gryffindor: 0,
+    Hufflepuff: 1,
+    Ravenclaw: 2,
+    Slytherin: 3,
+  }
 ```
 
-For example:
+Generates only typed enum setter & getter:
+
 ```ruby
-# require_typed
-key = params.require_typed(:key, TA[String].new)
-T.reveal_type(key) # String
-
-# nested params
-nested_params = params.require_typed(:nested, TA[ActionController::Parameters].new)
-T.reveal_type(nested_params) # ActionController::Parameters
-key = nested_params.require_typed(:key, TA[String.new])
-T.reveal_type(key) # String
-
-# fetch_typed
-key = params.fetch_typed(:key, TA[T.nilable(String)].new) # raises error if params doesn't have :key
-T.reveal_type(key) # T.nilable(String)
-
-key = params.fetch_typed(:key, TA[T.nilable(String)].new, nil) # returns nil when key doesn't have :key
-T.reveal_type(key) # T.nilable(String)
+  sig { returns(T.nilable(Wizard::House)) }
+  def typed_house; end
+
+  sig { params(value: T.nilable(Wizard::House)).void }
+  def typed_house=(value); end
+```
+
+### Controllers
+```sh
+❯ rake rails_rbi:custom
 ```
-The parameters are type-checked both statically and at runtime.
 
-Note: The API `TA[...].new` may seem verbose, but necessary to support this feature. Ideally, the API can be simply `require_typed(:key, Type)`. However, `sorbet` [doesn't support](http://github.com/sorbet/sorbet/issues/62) defining a method that accept a type and return an instance of the type. The library provides a wrapper `TA` (which stands for `TypeAssert`) in order to achieve the behavior. If this feature is supported by `sorbet` in the future, it will be easy to codemod to remove the `TA[...].new` part from your code.
+`sorbet-rails` adds `TypedParams` to extact typed controller parameters.
+
+TypedParams takes a parameter definition, which is a subclass of `T::Struct` and coerces the `params` object into an instance of that subclass using [sorbet-coerce](https://github.com/chanzuckerberg/sorbet-coerce):
+```ruby
+class MyCoolController < ApplicationController
+  class MyActionParams < T::Struct
+    const :id, T.nilable(Integer)
+    const :show, T.nilable(T::Boolean)
+    const :wands, T::Array[Integer]
+  end
+  sig { void }
+  def my_action
+    typed_params = TypedParams[MyActionParams].new.extract!(params)
+    # T.reveal_type(typed_params) => MyActionParams
+    # T.reveal_type(typed_params.show) => T.nilable(T::Boolean)
+  end
+end
+```
+If it fails to coerce the params into the right type, an `ActionController::BadRequest` exception will be raised with the coercion context for debugging.
+
+Note: The API `TypedParams[...].new.extract!` may seem verbose, but necessary to support this feature. Ideally, the API can be simply `TypedParams.extract!(...)`. However, `sorbet` [doesn't support](http://github.com/sorbet/sorbet/issues/62) defining a method that accept a type and return an instance of the type. If this feature is supported by `sorbet` in the future, it will be easy to codemod to be `TypedParams.extract(...)!` part from your code.
+Note: [`require_typed` and `fetch_typed`](https://github.com/chanzuckerberg/sorbet-rails/blob/v0.5.9.1/README.md) are deprecated in favor of `TypedParams`.
 
 ### Routes
 
@@ -157,8 +233,11 @@ specific environment group (eg. `development` only).
 
 - Relation class: Making the relations available at runtime (they are normally private constants, the gem makes them public)
   - Examples: `User::ActiveRecord_Relation`, `User::ActiveRecord_AssociationRelation`
-- Model: `find_n`, `first_n`, `last_n` are the methods we added. `pluck_to_tstruct` as well.
-- Controller: adding `fetch_typed` and `require_typed`
+- Model:
+  - `find_n`, `first_n`, `last_n`
+  - `pluck_to_tstruct`
+  - `typed_enum`
+- Controller: using `TypedParams`
 
 In addition to `require`ing `sorbet-rails`, you must also run
 `rake rails_rbi:custom`, which will produce the RBI for these runtime features.
@@ -188,6 +267,22 @@ class ModelName
 end
 ```
 
+### Replace `Rails.application.routes.url_helpers`
+
+When using url helpers like _url or _path methods outside of a controller,
+we usually have to add `include Rails.application.routes.url_helpers` in the class.
+However, Sorbet does not allow code that
+[includes dynamic module](https://sorbet.org/docs/error-reference#4002).
+Sorbet Rails provides a drop-in replacement module for the dynamic url_helpers module, called `GeneratedUrlHelpers`.
+Following code change should resolve the sorbet type-check error:
+
+```ruby
+class MyClass
+-  include Rails.application.routes.url_helpers
++  include GeneratedUrlHelpers
+end
+```
+
 ### `find`, `first` and `last`
 
 These 3 methods can either return a single nilable record or an array of records. Sorbet does not allow us to define multiple signatures for a function ([except stdlib](https://github.com/chanzuckerberg/sorbet-rails/issues/18)). It doesn't support defining one function signature that has varying returning value depending on the input parameter type. We opt to define the most commonly used signature for these methods, and monkey-patch new functions for the secondary use case.
@@ -204,7 +299,9 @@ Following are the list of attribute dynamic methods and their static counterpart
 - `find_by_<attributes>` -> `find_by(<attributes>)`
 - `find_by_<attributes>!` -> `find_by!(<attributes>)`
 - `<attribute>_changed?` -> `attribute_changed?(<attribute>)`
+- `<attribute>_was` -> `attribute_was(<attribute>)`
 - `saved_change_to_<attribute>?` -> `saved_change_to_attribute?(<attribute>)`
+- `<attribute>_before_type_cast` -> `read_attribute_before_type_cast(<attribute>)`
 
 ### `after_commit` and other callbacks
 
@@ -259,26 +356,6 @@ Model.unscoped.scoping do … end
 
 The [`select` method](https://apidock.com/rails/v4.0.2/ActiveRecord/QueryMethods/select) in Rails has two modes: it can be given a list of symbols, in which case rails will only return the given columns from the database, or it can be given a block, in which case it acts like [`Enumerable.select`](https://ruby-doc.org/core-2.6.4/Enumerable.html) and returns an array. We have chosen to support the first use case. If you want to pass a block to `select`, you can simply call `to_a` before you do. Note that this would be done within the `select` call anyway, so the performance penalty will be minimal.
 
-### `pluck_to_tstruct` instead of `pluck`
-
-The [`pluck` method](https://apidock.com/rails/ActiveRecord/Calculations/pluck) in Rails is a performant way to query value without instantiating ActiveRecord objects. However, it doesn't have any type information: it doesn't have type information (or name) of the attribute plucked. Sorbet-rails provides `pluck_to_tstruct` method as a replacement that does the same thing, but creates `T::Struct` object instead, and returns an array of `T::Struct`. The attributes plucked is based on props defined in the `T::Struct`
-
-```ruby
-# -- API
-Arel.pluck_to_tstruct(TA[ <TStructSubClass> ].new)
-
-# -- example
-class WizardStruct < T::Struct
-  const :name, String
-  const :house, T.nilable(String)
-end
-
-Wizard.pluck_to_tstruct(TA[WizardStruct].new)  # T::Array[WizardStruct]
-Wizard.all.pluck_to_tstruct(TA[WizardStruct].new)  # T::Array[WizardStruct]
-```
-
-This method is based on [pluck_to_hash](https://github.com/girishso/pluck_to_hash) gem.
-
 ## Extending Model Generation Task with Custom Plugins
 
 `sorbet-rails` support a customizable plugin system that you can use to generate additional RBI for each model. This will be useful to generate RBI for methods dynamically added by gems or private concerns. If you write plugins for public gems, please feel free to contribute it to this repo.

data/lib/bundled_rbi/active_record_base.rbi

@@ -0,0 +1,83 @@
+# typed: strong
+class ActiveRecord::Base
+  sig { params(args: T.untyped).returns(T.attached_class) }
+  def self.find(*args); end
+
+  sig { params(args: T.untyped).returns(T.nilable(T.attached_class)) }
+  def self.find_by(*args); end
+
+  sig { params(args: T.untyped).returns(T.attached_class) }
+  def self.find_by!(*args); end
+
+  sig {
+    params(
+      attributes: T.untyped,
+      block: T.nilable(T.proc.params(object: T.attached_class).void),
+    ).
+    returns(T.attached_class)
+  }
+  def self.find_or_initialize_by(attributes, &block); end
+
+  sig {
+    params(
+      attributes: T.untyped,
+      block: T.nilable(T.proc.params(object: T.attached_class).void),
+    ).
+    returns(T.attached_class)
+  }
+  def self.find_or_create_by(attributes, &block); end
+
+  sig {
+    params(
+      attributes: T.untyped,
+      block: T.nilable(T.proc.params(object: T.attached_class).void),
+    ).
+    returns(T.attached_class)
+  }
+  def self.find_or_create_by!(attributes, &block); end
+
+  sig { returns(T.nilable(T.attached_class)) }
+  def self.first; end
+
+  sig { returns(T.attached_class) }
+  def self.first!; end
+
+  sig { returns(T.nilable(T.attached_class)) }
+  def self.second; end
+
+  sig { returns(T.attached_class) }
+  def self.second!; end
+
+  sig { returns(T.nilable(T.attached_class)) }
+  def self.third; end
+
+  sig { returns(T.attached_class) }
+  def self.third!; end
+
+  sig { returns(T.nilable(T.attached_class)) }
+  def self.third_to_last; end
+
+  sig { returns(T.attached_class) }
+  def self.third_to_last!; end
+
+  sig { returns(T.nilable(T.attached_class)) }
+  def self.second_to_last; end
+
+  sig { returns(T.attached_class) }
+  def self.second_to_last!; end
+
+  sig { returns(T.nilable(T.attached_class)) }
+  def self.last; end
+
+  sig { returns(T.attached_class) }
+  def self.last!; end
+
+  sig { params(attributes: T.untyped, block: T.untyped).returns(T.attached_class) }
+  def self.create(attributes = nil, &block); end
+
+  sig { params(attributes: T.untyped, block: T.untyped).returns(T.attached_class) }
+  def self.create!(attributes = nil, &block); end
+
+  sig { params(attributes: T.untyped, block: T.untyped).returns(T.attached_class) }
+  def self.new(attributes = nil, &block); end
+end

data/lib/bundled_rbi/active_record_relation.rbi

@@ -1,5 +1,7 @@
 # typed: strong
 class ActiveRecord::Relation
+  Elem = type_member(fixed: T.untyped)
+
   sig { params(args: T.untyped).returns(Elem) }
   def find(*args); end
 
@@ -9,6 +11,33 @@ class ActiveRecord::Relation
   sig { params(args: T.untyped).returns(Elem) }
   def find_by!(*args); end
 
+  sig {
+    params(
+      attributes: T.untyped,
+      block: T.nilable(T.proc.params(object: Elem).void)
+    ).
+    returns(Elem)
+  }
+  def find_or_initialize_by(attributes, &block); end
+
+  sig {
+    params(
+      attributes: T.untyped,
+      block: T.nilable(T.proc.params(object: Elem).void)
+    ).
+    returns(Elem)
+  }
+  def find_or_create_by(attributes, &block); end
+
+  sig {
+    params(
+      attributes: T.untyped,
+      block: T.nilable(T.proc.params(object: Elem).void)
+    ).
+    returns(Elem)
+  }
+  def find_or_create_by!(attributes, &block); end
+
   sig { returns(T.nilable(Elem)) }
   def first; end
 
@@ -45,6 +74,17 @@ class ActiveRecord::Relation
   sig { returns(Elem) }
   def last!; end
 
+  sig do
+    override.params(
+      start: T.nilable(Integer),
+      finish: T.nilable(Integer),
+      batch_size: T.nilable(Integer),
+      error_on_ignore: T.nilable(T::Boolean),
+      block: T.nilable(T.proc.params(e: Elem).void) # block is optional, eg. you can do Klass.find_each.map
+    ).returns(T::Array[Elem])
+  end
+  def find_each(start: nil, finish: nil, batch_size: 1000, error_on_ignore: nil, &block); end
+
   sig { override.params(block: T.proc.params(e: Elem).void).returns(T::Array[Elem]) }
   def each(&block); end
 
@@ -68,6 +108,9 @@ class ActiveRecord::Relation
   sig { returns(T::Boolean) }
   def any?; end
 
+  sig { returns(T::Boolean) }
+  def empty?; end
+
   sig { returns(T::Boolean) }
   def many?; end
 

data/lib/bundled_rbi/pluck_to_tstruct.rbi

@@ -17,6 +17,5 @@ class ActiveRecord::Base
 end
 
 class ActiveRecord::Relation
-  Elem = type_member
   include SorbetRails::PluckToTStruct
 end

data/lib/bundled_rbi/typed_params.rbi

@@ -0,0 +1,9 @@
+# typed: true
+module TypedParams
+  extend T::Generic
+
+  Elem = type_member
+
+  sig { params(args: ActionController::Parameters, raise_coercion_error: T.nilable(T::Boolean)).returns(Elem) }
+  def extract!(args, raise_coercion_error: nil); end
+end