sorbet-rails 0.5.4 → 0.5.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6b43d7a27b379e20892375b314afd08e4897ad6e0b20167b1a366de3121d0470
-  data.tar.gz: f6817dea5503132acc030da42ce68149675192c98536b8c795d8705a0e42649d
+  metadata.gz: 4532cfd7b6aa106f5b870cd2b6013acd7d72644985a29cb398f0b25959b2d4b0
+  data.tar.gz: 39329d64e2eaee0afd14a180404897c1ec0b1601a8b33bdedb6e3d3e9f12695e
 SHA512:
-  metadata.gz: 15251522124262b9c7aab57915d2cc5bc18e0807ccf27e2ea47e0d17173473a5d8a5a09ac4ea41e899de47a7972456ae060ef981e811e5f22095309c79d89b27
-  data.tar.gz: 7178e09505141a408617d2513f9da84ee8868edf5c808c3bca0ba293dbec4bb3cbbbe1362ad8b0af2f75f20862de4f95b67ddf6b1365a6d10111598bd9779b75
+  metadata.gz: 693c741863b4edf77cbb843b9cf030e91f098ad6291be63d2a365e845c99701b32f14a1c35658a0375aeeec25f9fcff702d0045fc36904704c3f49dd9640fca9
+  data.tar.gz: 9985e82caf4debbbac6512698190c2f787d0e8bb51ae2853bf17a3828ee4f1921330ad86829615f3f4e503d992617f43c5b6bd1c11d32f62cb75f1d03fd267e9

data/.travis.yml

@@ -17,7 +17,7 @@ rvm:
 matrix:
   include:
   - rvm: 2.5
-    env: RAILS_VERSION=5.2 SORBET_VERSION=0.4.4602
+    env: RAILS_VERSION=5.2 SORBET_VERSION=0.4.4755
   exclude:
   - rvm: 2.3
     env: RAILS_VERSION=6.0

data/README.md

@@ -25,12 +25,13 @@ gem 'sorbet-rails'
 ❯ bundle install
 ```
 
-3. Generate RBI files for your routes, models, and helpers:
+3. Generate RBI files for your routes, models, etc
 ```sh
 ❯ rake rails_rbi:routes
 ❯ rake rails_rbi:models
 ❯ rake rails_rbi:helpers
 ❯ rake rails_rbi:mailers
+❯ rake rails_rbi:params
 
 # or run them all at once
 ❯ rake rails_rbi:all
@@ -43,18 +44,8 @@ gem 'sorbet-rails'
 ```
 Because we've generated RBI files for routes, models, and helpers, a lot more files should be typecheckable now. Many methods in `hidden.rbi` may be removed because they are now typed.
 
-## RBI Files
+## Type-checking Rails code
 
-### ActiveRecord
-
-There is an ActiveRecord RBI file that we vendor with this gem. Sorbet picks up these vendored RBI files automatically. (Please make sure you are running the latest version.)
-
-### Routes
-
-This Rake task generates an RBI file defining `_path` and `_url` methods for all named routes in `routes.rb`:
-```sh
-❯ rake rails_rbi:routes
-```
 ### Models
 
 This Rake task generates RBI files for all models in the Rails application (all descendants of `ActiveRecord::Base`):
@@ -75,6 +66,45 @@ The generation task currently creates the following signatures:
 
 It is possible to add custom RBI generation logic for your custom module or gems via the plugin system. Check out the [plugins section](#extending-model-generation-task-with-custom-plugins) below if you are interested.
 
+### Controllers
+```sh
+❯ rake rails_rbi:params
+```
+
+`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`
+
+This is the conversion in essence:
+```
+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)
+```
+
+For example:
+```
+# require_typed
+key = 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)
+```
+The parameters are type-checked both statically and at runtime.
+
+Note: The API `TA[...].new` may seems 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` (stands for TypeAssert) in order to achieve the behavior. If it is by `sorbet` in the future, it will be easy to codemod to remove the `TA[...].new` part from your code.
+
+### Routes
+
+This Rake task generates an RBI file defining `_path` and `_url` methods for all named routes in `routes.rb`:
+```sh
+❯ rake rails_rbi:routes
+```
+
 ### Helpers
 
 This Rake task generates a `helpers.rbi` file that includes a basic module definition which includes the `Kernel` module and `ActionView::Helpers`, to allow for some basic Ruby methods to be used in helpers without Sorbet complaining.
@@ -90,6 +120,7 @@ If you have additional modules that are included in all your helpers and you wan
 SorbetRails.configure do |config|
   config.extra_helper_includes = ['ApplicationHelper', 'Devise::Controllers::Helpers']
 end
+```
 
 ### Mailers
 
@@ -195,7 +226,7 @@ Model.unscoped.scoping do … end
 
 `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.
 
-### Defining a Custom `ModelPlugin` 
+### Defining a Custom `ModelPlugin`
 
 A custom plugin should be a subclass of `SorbetRails::ModelPlugins::Base`. Each plugin would implement a `generate(root)` method that generate additional rbi for the model.
 
@@ -203,7 +234,7 @@ At a high level, here is the structure of a plugin:
 ```ruby
 # -- lib/my_custom_plugin.rb
 class MyCustomPlugin < SorbetRails::ModelPlugins::Base
-  sig { implementation.params(root: Parlour::RbiGenerator::Namespace).void }
+  sig { override.params(root: Parlour::RbiGenerator::Namespace).void }
   def generate(root)
     # TODO: implement the generation logic
     # You can use @model_class and @available_classes here
@@ -226,17 +257,17 @@ At a high level, you'd usually want to create a model-scoped module for your met
     # here we re-create the model class!
     model_class_rbi = root.create_class(self.model_class_name)
     model_class_rbi.create_extend(custom_module_name)
-    
+
     # then create custom methods, constants, etc. for this module.
     custom_module_rbi.create_method(...)
-    
+
     # this is allowed but not recommended, because it limit the ability to override the method.
     model_class_rbi.create_method(...)
   end
 ```
 Notice that we re-create `model_class_rbi` here. Parlour's [ConflictResolver](https://github.com/AaronC81/parlour/wiki/Internals#overall-flow) will merge the classes or modules with the same name together to generate 1 beautiful RBI file. It'll also flag and skip if any method is created multiple times with conflict signatures. Check-out useful predefined module names & helper methods in [model_utils](https://github.com/chanzuckerberg/sorbet-rails/blob/master/lib/sorbet-rails/model_utils.rb).
 
-It is also allowed to put methods into a model class directly. However, it is not recommended because it'll be harder to override the method. `sorbet` will enforce that the overriding method match the signature generated. It also makes the generated RBI file less modularized.  
+It is also allowed to put methods into a model class directly. However, it is not recommended because it'll be harder to override the method. `sorbet` will enforce that the overriding method match the signature generated. It also makes the generated RBI file less modularized.
 
 However, sometimes this is required to make `sorbet` recognize the signature. This is the case for class methods added by `ActiveRecord::Concerns`. Because `ActiveSupport::Concern` class methods will be inserted to the class directly, you need to also put the sig in the model class rbi directly.
 

data/lib/bundled_rbi/parameters.rbi

@@ -0,0 +1,50 @@
+# typed: strong
+
+module ITypeAssert
+  extend T::Sig
+  extend T::Generic
+
+  Elem = type_member(:out)
+
+  abstract!
+
+  sig { abstract.params(val: T.untyped).returns(Elem) }
+  def assert(val); end
+end
+
+module TypeAssertImpl; end
+
+class TA
+  extend T::Sig
+  extend T::Generic
+  include ITypeAssert
+  extend TypeAssertImpl
+
+  Elem = type_member
+
+  sig { override.params(val: T.untyped).returns(Elem) }
+  def assert(val); end
+end
+
+module SorbetRails::CustomParamsMethods
+  extend T::Sig
+
+  sig {
+    type_parameters(:U).
+    params(key: Symbol, ta: ITypeAssert[T.type_parameter(:U)]).
+    returns(T.type_parameter(:U))
+  }
+  def require_typed(key, ta); end
+
+  # Note: when default value is a hash, it'll be converted into an ActionController::Parameters
+  sig {
+    type_parameters(:U).
+    params(
+      key: Symbol,
+      ta: ITypeAssert[T.type_parameter(:U)],
+      args: T.untyped,
+    ).
+    returns(T.type_parameter(:U))
+  }
+  def fetch_typed(key, ta, *args); end
+end

data/lib/sorbet-rails.rb

@@ -3,5 +3,6 @@ module SorbetRails
   if defined?(Rails)
     require 'sorbet-rails/railtie'
     require 'sorbet-rails/model_rbi_formatter'
+    require 'sorbet-rails/type_assert/type_assert'
   end
 end

data/lib/sorbet-rails/gem_plugins/friendly_id_plugin.rb

@@ -1,6 +1,6 @@
 # typed: strict
 class FriendlyIdPlugin < SorbetRails::ModelPlugins::Base
-  sig { implementation.params(root: Parlour::RbiGenerator::Namespace).void }
+  sig { override.params(root: Parlour::RbiGenerator::Namespace).void }
   def generate(root)
     return unless @model_class.singleton_class.included_modules.include?(::FriendlyId)
 

data/lib/sorbet-rails/gem_plugins/kaminari_plugin.rb

@@ -2,7 +2,7 @@
 class KaminariPlugin < SorbetRails::ModelPlugins::Base
   # Kaminari generates a dynamic `page` method on ActiveRecord relations.
   # https://github.com/kaminari/kaminari/blob/c5186f5d9b7f23299d115408e62047447fd3189d/kaminari-activerecord/lib/kaminari/activerecord/active_record_model_extension.rb#L15
-  sig { implementation.params(root: Parlour::RbiGenerator::Namespace).void }
+  sig { override.params(root: Parlour::RbiGenerator::Namespace).void }
   def generate(root)
     return unless @model_class.include?(::Kaminari::ActiveRecordModelExtension)
 

data/lib/sorbet-rails/gem_plugins/pg_search_plugin.rb

@@ -2,7 +2,7 @@
 class PgSearchPlugin < SorbetRails::ModelPlugins::Base
   # If you include PgSearch::Model, the class implicitly gets methods from
   # PgSearch::Model::ClassMethods.
-  sig { implementation.params(root: Parlour::RbiGenerator::Namespace).void }
+  sig { override.params(root: Parlour::RbiGenerator::Namespace).void }
   def generate(root)
     return unless @model_class.include?(::PgSearch::Model)
 

data/lib/sorbet-rails/mailer_rbi_formatter.rb

@@ -33,6 +33,6 @@ class SorbetRails::MailerRbiFormatter
       end
     end
 
-    @parlour.rbi + "\n"
+    @parlour.rbi
   end
-end
+end

data/lib/sorbet-rails/model_plugins/active_record_assoc.rb

@@ -7,7 +7,7 @@ class SorbetRails::ModelPlugins::ActiveRecordAssoc < SorbetRails::ModelPlugins::
     @columns_hash = @model_class.table_exists? ? @model_class.columns_hash : {}
   end
 
-  sig { implementation.params(root: Parlour::RbiGenerator::Namespace).void }
+  sig { override.params(root: Parlour::RbiGenerator::Namespace).void }
   def generate(root)
     return unless @model_class.reflections.length > 0
 

data/lib/sorbet-rails/model_plugins/active_record_attribute.rb

@@ -2,7 +2,7 @@
 require ('sorbet-rails/model_plugins/base')
 class SorbetRails::ModelPlugins::ActiveRecordAttribute < SorbetRails::ModelPlugins::Base
 
-  sig { implementation.params(root: Parlour::RbiGenerator::Namespace).void }
+  sig { override.params(root: Parlour::RbiGenerator::Namespace).void }
   def generate(root)
     columns_hash = @model_class.table_exists? ? @model_class.columns_hash : {}
     return unless columns_hash.size > 0

data/lib/sorbet-rails/model_plugins/active_record_enum.rb

@@ -3,7 +3,7 @@ require ('sorbet-rails/model_plugins/base')
 require("sorbet-rails/utils")
 class SorbetRails::ModelPlugins::ActiveRecordEnum < SorbetRails::ModelPlugins::Base
 
-  sig { implementation.params(root: Parlour::RbiGenerator::Namespace).void }
+  sig { override.params(root: Parlour::RbiGenerator::Namespace).void }
   def generate(root)
     return unless model_class.defined_enums.size > 0
 

data/lib/sorbet-rails/model_plugins/active_record_finder_methods.rb

@@ -2,7 +2,7 @@
 require ('sorbet-rails/model_plugins/base')
 class SorbetRails::ModelPlugins::ActiveRecordFinderMethods < SorbetRails::ModelPlugins::Base
 
-  sig { implementation.params(root: Parlour::RbiGenerator::Namespace).void }
+  sig { override.params(root: Parlour::RbiGenerator::Namespace).void }
   def generate(root)
     model_class_rbi = root.create_class(self.model_class_name)
     create_finder_methods_for(model_class_rbi, class_method: true)

data/lib/sorbet-rails/model_plugins/active_record_named_scope.rb

@@ -3,7 +3,7 @@ require ('sorbet-rails/model_plugins/base')
 require("sorbet-rails/utils")
 class SorbetRails::ModelPlugins::ActiveRecordNamedScope < SorbetRails::ModelPlugins::Base
 
-  sig { implementation.params(root: Parlour::RbiGenerator::Namespace).void }
+  sig { override.params(root: Parlour::RbiGenerator::Namespace).void }
   def generate(root)
     model_class_rbi = root.create_class(self.model_class_name)
 

data/lib/sorbet-rails/model_plugins/active_record_querying.rb

@@ -2,7 +2,7 @@
 require ('sorbet-rails/model_plugins/base')
 class SorbetRails::ModelPlugins::ActiveRecordQuerying < SorbetRails::ModelPlugins::Base
 
-  sig { implementation.params(root: Parlour::RbiGenerator::Namespace).void }
+  sig { override.params(root: Parlour::RbiGenerator::Namespace).void }
   def generate(root)
     # All is a named scope that most method from ActiveRecord::Querying delegate to
     # rails/activerecord/lib/active_record/querying.rb:21

data/lib/sorbet-rails/model_plugins/active_relation_where_not.rb

@@ -2,7 +2,7 @@
 require ('sorbet-rails/model_plugins/base')
 class SorbetRails::ModelPlugins::ActiveRelationWhereNot < SorbetRails::ModelPlugins::Base
 
-  sig { implementation.params(root: Parlour::RbiGenerator::Namespace).void }
+  sig { override.params(root: Parlour::RbiGenerator::Namespace).void }
   def generate(root)
     where_not_module_name = self.model_module_name("ActiveRelation_WhereNot")
     where_not_module_rbi = root.create_module(where_not_module_name)

data/lib/sorbet-rails/model_plugins/active_storage_methods.rb

@@ -6,7 +6,7 @@ class SorbetRails::ModelPlugins::ActiveStorageMethods < SorbetRails::ModelPlugin
     super
   end
 
-  sig { implementation.params(root: Parlour::RbiGenerator::Namespace).void }
+  sig { override.params(root: Parlour::RbiGenerator::Namespace).void }
   def generate(root)
     # Check that ActiveStorage the attachment_reflections method exists
     # It was added in 6.0, so it isn't available for 5.2.

data/lib/sorbet-rails/model_plugins/base.rb

@@ -12,7 +12,7 @@ module SorbetRails::ModelPlugins
     # convenient rename
     Parameter = ::Parlour::RbiGenerator::Parameter
 
-    sig { implementation.returns(T.class_of(ActiveRecord::Base)) }
+    sig { override.returns(T.class_of(ActiveRecord::Base)) }
     attr_reader :model_class
 
     sig { returns(T::Set[String]) }

data/lib/sorbet-rails/model_plugins/custom_finder_methods.rb

@@ -2,7 +2,7 @@
 require ('sorbet-rails/model_plugins/base')
 class SorbetRails::ModelPlugins::CustomFinderMethods < SorbetRails::ModelPlugins::Base
 
-  sig { implementation.params(root: Parlour::RbiGenerator::Namespace).void }
+  sig { override.params(root: Parlour::RbiGenerator::Namespace).void }
   def generate(root)
     model_class_rbi = root.create_class(self.model_class_name)
     model_relation_class_rbi = root.create_class(self.model_relation_class_name)

data/lib/sorbet-rails/model_plugins/enumerable_collections.rb

@@ -2,7 +2,7 @@
 require ('sorbet-rails/model_plugins/base')
 class SorbetRails::ModelPlugins::EnumerableCollections < SorbetRails::ModelPlugins::Base
 
-  sig { implementation.params(root: Parlour::RbiGenerator::Namespace).void }
+  sig { override.params(root: Parlour::RbiGenerator::Namespace).void }
   def generate(root)
     # model relation & association proxy are enumerable
     # we need to implement "each" in these methods so that they work

data/lib/sorbet-rails/model_plugins/plugins.rb

@@ -9,7 +9,6 @@ require('sorbet-rails/model_plugins/active_record_assoc')
 require('sorbet-rails/model_plugins/active_record_finder_methods')
 require('sorbet-rails/model_plugins/custom_finder_methods')
 require('sorbet-rails/model_plugins/enumerable_collections')
-require('sorbet-rails/model_plugins/active_record_overrides')
 require('sorbet-rails/model_plugins/active_storage_methods')
 
 module SorbetRails::ModelPlugins

data/lib/sorbet-rails/model_rbi_formatter.rb

@@ -8,7 +8,7 @@ class SorbetRails::ModelRbiFormatter
   extend SorbetRails::ModelPlugins
   include SorbetRails::ModelUtils
 
-  sig { implementation.returns(T.class_of(ActiveRecord::Base)) }
+  sig { override.returns(T.class_of(ActiveRecord::Base)) }
   attr_reader :model_class
 
   sig { returns(T::Set[String]) }
@@ -56,12 +56,14 @@ class SorbetRails::ModelRbiFormatter
       nil
     end
 
-    <<~MESSAGE
+    rbi = <<~MESSAGE
       # This is an autogenerated file for dynamic methods in #{self.model_class_name}
       # Please rerun rake rails_rbi:models[#{self.model_class_name}] to regenerate.
 
-      #{generator.rbi}
     MESSAGE
+
+    rbi += generator.rbi
+    return rbi
   end
 
   sig { params(root: Parlour::RbiGenerator::Namespace).void }

data/lib/sorbet-rails/{custom_finder_methods.rb → rails_mixins/custom_finder_methods.rb}

@@ -2,7 +2,7 @@
 module SorbetRails
   module CustomFinderMethods
     def find_n(*ids)
-      find(ids)
+      find(*ids)
     end
 
     def first_n(n)

data/lib/sorbet-rails/rails_mixins/custom_params_methods.rb

@@ -0,0 +1,46 @@
+# typed: false
+require 'sorbet-runtime'
+
+module SorbetRails::CustomParamsMethods
+  include Kernel
+  extend T::Sig
+  extend T::Helpers
+
+  # methods exists on ActionController::Parameter
+  # def require(key); super; end
+  # def fetch(key, *args); super; end
+
+  sig {
+    type_parameters(:U).
+    params(key: Symbol, ta: ITypeAssert[T.type_parameter(:U)]).
+    returns(T.type_parameter(:U))
+  }
+  def require_typed(key, ta)
+    val = require(key)
+    ta.assert(val)
+  rescue TypeError
+    raise ActionController::BadRequest.new(
+      "Expected parameter #{key} to be an instance of type #{ta.get_type}, got `#{val}`"
+    )
+  end
+
+  # Note: when default value is a hash, it'll be converted into an ActionController::Parameters
+  sig {
+    type_parameters(:U).
+    params(
+      key: Symbol,
+      ta: ITypeAssert[T.type_parameter(:U)],
+      args: T.untyped,
+    ).
+    returns(T.type_parameter(:U))
+  }
+  def fetch_typed(key, ta, *args)
+    val = fetch(key, *args)
+    ta.assert(val)
+  rescue TypeError
+    raise ActionController::BadRequest.new(
+      "Expected parameter #{key} to be an instance of type T.nilable(#{ta.get_type}),
+      got `#{val}`".squish!
+    )
+  end
+end