type_toolkit 0.0.5 → 0.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5a743f2b4d2786fb8c08c666974f6f913a4baea59dc9d99dba7a5982ec13441a
-  data.tar.gz: '097ea19c5691a4416de13f1d49ad05544793a9246cd358fcc5619ccca39f6419'
+  metadata.gz: f4227c717f707bc4d21aea4b6026e4ec48c62bf48044518b7545b4a12d499662
+  data.tar.gz: afbee5d26bf77e402c0425dc60cfb53b6d8c80ba8af6f69af39bad034459a3bc
 SHA512:
-  metadata.gz: 66a3f796e922912c0909a4a7548fd72f75a2cee65800a64c37189176cb6bbb323e4693c458b6bef99f828550e83693b036ef3f1e46542a4cf8da547255ed7c76
-  data.tar.gz: 846e557b1e223a17adfc8ad6df338a9032cc3ea983e8f0079881f85f9012b0f20968ffd08f176386504393133cc63124e19a0cdb88b6124bac5452f0f20798b3
+  metadata.gz: a251f77a0cc924ae2b621f1eda192d24d862406f076c875227ada2f7d16883a8c98e8c8b7310843a00a7d08b2fcab902e0f7bf6bcc5c4262da519a2e7a2721d8
+  data.tar.gz: a93074b2e21d1ea1b7dac91b9cf8e52690f68d1a2ae12e2c898cbd87b3ea71367a4d956d13933faef666e6683d868e7360a5b66a2039c8ccd735bdeefa82ae09

data/README.md

@@ -70,6 +70,49 @@ last_delivery = user.not_nil!
   .deliveries.last.not_nil!
 ```
 
+### Interfaces
+
+Interfaces are modules with abstract methods which a conforming class must implement. They help make duck-typing easier to use in Ruby, by validating that your conforming classes do actually provide the correct methods needed of them.
+
+The Type Toolkit provides runtime support for interfaces (marked with `interface!`) and abstract methods (marked with `abstract` before the `def` keyword).
+
+Example:
+
+```ruby
+module Notifier
+  interface!
+
+  #: (String) -> void
+  abstract def send_notification(message); end
+end
+
+class SlackNotifier
+  include Notifier
+
+  # @override
+  #: (String) -> void
+  def send_notification(message)
+    puts "Posting to Slack API: #{message.inspect}"
+  end
+end
+
+SlackNotifier.new.send_notification("Hello, world!") # ✅
+# => Posting to Slack API: "Hello, world!"
+```
+
+Unimplemented abstract methods cannot be called, and the Type Toolkit runtime will raise an error if you try to do so:
+
+```ruby
+class EmailNotifier
+  include Notifier
+  
+  # Oops, forgot to implement `#send_notification`!
+end
+
+EmailNotifier.new.send_notification("Hello, world!") # ❌ TypeToolkit::AbstractMethodNotImplementedError
+# => Abstract method #send_notification was never implemented.
+```
+
 ## Guiding Principles
 
 ### Blazingly fast™

data/benchmark/.rubocop.yml

@@ -0,0 +1,7 @@
+inherit_from: ../.rubocop.yml
+
+Naming/ClassAndModuleCamelCase:
+  Enabled: false # Sometimes underscores are useful, m'kay?
+
+Style/ClassMethodsDefinitions:
+  Enabled: false # We need to be able to compare `class << self` and `def self.`

data/benchmark/abstract_methods_benchmark.rb

@@ -0,0 +1,221 @@
+# typed: ignore
+# frozen_string_literal: true
+
+# Benchmark the performance overhead of calling:
+# - A concrete implementation of an abstract method
+# - An inherited concrete implementation of an abstract method
+# - The error case of calling an unimplemented abstract method
+
+############################################# Results #############################################
+#
+# ruby 3.4.3 (2025-04-14 revision d0b7e5b6a0) +PRISM [arm64-darwin23]
+#
+# ## Interpreter
+#
+# | Call to...        |        Regular impl |          Inherited impl |              Missing impl |
+# |-------------------|--------------------:|------------------------:|--------------------------:|
+# | sorbet-runtime    | (same-ish) 23.02 ns | (2.70x slower) 57.30 ns | (1.13x  slower) 472.86 ns |
+# | manual delegation | (same-ish) 22.18 ns | (2.07x slower) 44.90 ns |               *415.36 ns* |
+# | type_toolkit      | (same-ish) 22.56 ns |              *22.03 ns* | (2.11x  slower) 890.38 ns |
+#
+# ## YJIT#
+# | Call to...        |        Regular impl |           Inherited impl |              Missing impl |
+# |-------------------|--------------------:|-------------------------:|--------------------------:|
+# | sorbet-runtime    |  (same-ish) 1.63 ns | (21.41x slower) 34.91 ns | (1.10x  slower) 447.59 ns |
+# | manual delegation |  (same-ish) 1.63 ns |  (7.15x slower) 11.66 ns |               *405.84 ns* |
+# | type_toolkit      |  (same-ish) 1.67 ns |                *1.63 ns* | (1.91x  slower) 774.91 ns |
+#
+####################################################################################################
+
+require "bundler"
+Bundler.require(:default, :benchmark)
+
+require "type_toolkit"
+
+module TypeKitDemo
+  # Provides the concrete implementation of `m`
+  class Parent
+    def m1 = "Parent#m1"
+  end
+
+  module I
+    interface!
+
+    abstract def m1; end
+    abstract def m2; end
+    abstract def not_implemented; end
+  end
+
+  # Inherits the concrete implementation of `m` from DemoParentClass.
+  class Child < Parent
+    include I
+
+    def m2 = "Child#m2"
+  end
+end
+
+module SorbetRuntimeDemo
+  # Provides the concrete implementation of `m`
+  class Parent
+    def m1 = "Parent#m1"
+  end
+
+  module I
+    extend T::Sig
+    extend T::Helpers
+
+    interface!
+
+    sig { abstract.returns(String) }
+    def m1; end
+
+    sig { abstract.returns(String) }
+    def m2; end
+
+    sig { abstract.returns(String) }
+    def not_implemented; end
+  end
+
+  # Inherits the concrete implementation of `m` from DemoParentClass.
+  class Child < Parent
+    include I
+
+    def m2 = "Child#m2"
+  end
+end
+
+module ManualDelegationDemo
+  class Parent
+    def m1 = "Parent#m1"
+  end
+
+  module I
+    def m1 = defined?(super) ? super : raise
+    def m2 = defined?(super) ? super : raise
+    def not_implemented = defined?(super) ? super : raise
+  end
+
+  # Inherits the concrete implementation of `m` from DemoParentClass.
+  class Child < Parent
+    include I
+
+    def m2 = "Child#m2"
+  end
+end
+
+type_toolkit_object = TypeKitDemo::Child.new
+manual_delegation_object = ManualDelegationDemo::Child.new
+sorbet_runtime_object = SorbetRuntimeDemo::Child.new
+
+[:interpreter, :yjit].each do |mode|
+  if mode == :yjit
+    puts <<~MSG
+
+
+      ================================================================================
+      Enabling YJIT...
+      ================================================================================
+
+
+    MSG
+    RubyVM::YJIT.enable
+  end
+
+  warmup = 5
+  time = 10
+
+  width = ["type_toolkit", "sorbet-runtime", "manual delegation"].max_by(&:length).length
+
+  puts "Benchmark the performance of calling the concrete implementation directly..."
+  Benchmark.ips do |x|
+    x.config(warmup:, time:)
+
+    x.report("type_toolkit".rjust(width)) do |times|
+      i = 0
+      while (i += 1) < times
+        type_toolkit_object.m2
+      end
+    end
+
+    x.report("sorbet-runtime".rjust(width)) do |times|
+      i = 0
+      while (i += 1) < times
+        sorbet_runtime_object.m2
+      end
+    end
+
+    x.report("manual delegation".rjust(width)) do |times|
+      i = 0
+      while (i += 1) < times
+        manual_delegation_object.m2
+      end
+    end
+
+    x.compare!
+  end
+
+  puts "\n\nBenchmark the performance of calling the inherited concrete implementation..."
+  Benchmark.ips do |x|
+    x.config(warmup:, time:)
+
+    x.report("type_toolkit".rjust(width)) do |times|
+      i = 0
+      while (i += 1) < times
+        type_toolkit_object.m1
+      end
+    end
+
+    x.report("sorbet-runtime".rjust(width)) do |times|
+      i = 0
+      while (i += 1) < times
+        sorbet_runtime_object.m1
+      end
+    end
+
+    x.report("manual delegation".rjust(width)) do |times|
+      i = 0
+      while (i += 1) < times
+        manual_delegation_object.m1
+      end
+    end
+
+    x.compare!
+  end
+
+  puts "\n\nTest the performance of calling an unimplemented abstract method..."
+  Benchmark.ips do |x|
+    x.config(warmup:, time:)
+
+    x.report("type_toolkit".rjust(width)) do |times|
+      i = 0
+      while (i += 1) < times
+        begin
+          type_toolkit_object.not_implemented
+        rescue AbstractMethodNotImplementedError # rubocop:disable Lint/SuppressedException
+        end
+      end
+    end
+
+    x.report("sorbet-runtime".rjust(width)) do |times|
+      i = 0
+      while (i += 1) < times
+        begin
+          sorbet_runtime_object.not_implemented
+        rescue NotImplementedError # rubocop:disable Lint/SuppressedException
+        end
+      end
+    end
+
+    x.report("manual delegation".rjust(width)) do |times|
+      i = 0
+      while (i += 1) < times
+        begin
+          manual_delegation_object.not_implemented
+        rescue StandardError # rubocop:disable Lint/SuppressedException
+        end
+      end
+    end
+
+    x.compare!
+  end
+end

data/benchmark/interface_startup_performance.rb

@@ -0,0 +1,128 @@
+# typed: ignore
+# frozen_string_literal: true
+
+# Benchmark the startup performance of declaring modules/interfaces in 3 different styles:
+# - TypeToolkit (abstract gem)
+# - Sorbet runtime
+# - Manual delegation (defined?(super) pattern)
+
+############################################# Results #############################################
+#
+# ruby 3.4.3 (2025-04-14 revision d0b7e5b6a0) +PRISM [arm64-darwin23]
+#
+# |                   |              Interpreter |                       YJIT |
+# |-------------------|-------------------------:|---------------------------:|
+# | sorbet-runtime    | (21.34x slower) 50.79 μs | (152.34x slower) 377.27 μs |
+# | type_toolkit      |  (4.18x slower)  9.95 μs |   (4.18x slower)  10.35 μs |
+# | manual delegation |                  2.38 μs |                    2.48 μs |
+#
+####################################################################################################
+
+require "bundler"
+Bundler.require(:default, :benchmark)
+
+require "type_toolkit"
+
+warmup = 5
+time = 10
+
+width = ["type_toolkit", "sorbet-runtime", "manual delegation"].max_by(&:length).length
+
+puts "Benchmark the time to declare an interface module with abstract methods..."
+
+[:interpreter, :yjit].each do |mode|
+  if mode == :yjit
+    puts <<~MSG
+
+
+      ================================================================================
+      Enabling YJIT...
+      ================================================================================
+
+
+    MSG
+    RubyVM::YJIT.enable
+  end
+
+  Benchmark.ips do |x|
+    x.config(warmup:, time:)
+
+    x.report("type_toolkit".rjust(width)) do |times|
+      i = 0
+      while (i += 1) < times
+        interface = Module.new do
+          interface!
+
+          abstract def m1; end
+          abstract def m2; end
+          abstract def m3; end
+        end
+
+        Class.new do
+          include interface
+
+          def m1 = "m1"
+          def m2 = "m2"
+          def m3 = "m3"
+        end
+      end
+    end
+
+    x.report("sorbet-runtime".rjust(width)) do |times|
+      i = 0
+      while (i += 1) < times
+        interface = Module.new do
+          extend T::Sig
+          extend T::Helpers
+
+          interface!
+
+          sig { abstract.returns(String) }
+          def m1; end
+
+          sig { abstract.returns(String) }
+          def m2; end
+
+          sig { abstract.returns(String) }
+          def m3; end
+        end
+
+        Class.new do
+          extend T::Sig
+
+          include interface
+
+          sig { override.returns(String) }
+          def m1 = "m1"
+
+          sig { override.returns(String) }
+          def m2 = "m2"
+
+          sig { override.returns(String) }
+          def m3 = "m3"
+        end
+      end
+    end
+
+    x.report("manual delegation".rjust(width)) do |times|
+      i = 0
+      while (i += 1) < times
+        interface = Module.new do
+          def m1 = defined?(super) ? super : raise
+          def m2 = defined?(super) ? super : raise
+          def m3 = defined?(super) ? super : raise
+        end
+
+        Class.new do
+          include interface
+
+          def m1 = "m1"
+          def m2 = "m2"
+          def m3 = "m3"
+        end
+      end
+    end
+
+    x.compare!
+  end
+end

data/benchmark/module_benchmark.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+# Benchmark if it's worth checking `Module.include?` before calling`Module.include`
+# ... spoiler: meh, not really.
+
+############################################# Results #############################################
+#
+# ruby 3.4.3 (2025-04-14 revision d0b7e5b6a0) +PRISM [arm64-darwin23]
+#
+# |                    |             Interpreter |                    YJIT |
+# |-------------------:|------------------------:|------------------------:|
+# |       just include | (2.39x slower) 54.35 ns | (8.53x slower) 35.29 ns |
+# | check then include |                22.72 ns |                 4.14 ns |
+#
+####################################################################################################
+
+require "bundler"
+Bundler.require(:default, :benchmark)
+
+module M1; end
+module M2; end
+class C1; end
+class C2; end
+
+[:interpreter, :yjit].each do |mode|
+  if mode == :yjit
+    puts <<~MSG
+
+
+      ================================================================================
+      Enabling YJIT...
+      ================================================================================
+
+
+    MSG
+    RubyVM::YJIT.enable
+  end
+
+  warmup = 5
+  time = 10
+
+  puts "Benchmark the performance of calling the concrete implementation directly..."
+  Benchmark.ips do |x|
+    x.config(warmup:, time:)
+
+    x.report("check then include") do |times|
+      i = 0
+      while (i += 1) < times
+        C1.include(M1) unless C1.include?(M1)
+      end
+    end
+
+    x.report("just include") do |times|
+      i = 0
+      while (i += 1) < times
+        C2.include(M2)
+      end
+    end
+
+    x.compare!
+  end
+end

data/config/default.yml

@@ -2,3 +2,8 @@ TypeToolkit/DontExpectUnexpectedNil:
   Description: "Detects misuse of UnexpectedNilError (rescuing, raising, or asserting it)."
   Enabled: true
   VersionAdded: "0.1.0"
+
+TypeToolkit/PreferNotNil:
+  Description: "Replaces T.must assertions with Type Toolkit's not_nil! assertion."
+  Enabled: true
+  VersionAdded: "0.1.0"

data/docs/design/inherited_implementation_problem.md

@@ -0,0 +1,119 @@
+# The inherited implementation problem
+
+Take this example:
+
+```ruby
+class Parent
+  def m = "Parent#m"
+end
+  
+module I
+  interface!
+
+  abstract def m = raise "Abstract method `#m` not implemented"
+end
+
+class Child < Parent
+  include I
+end
+
+Child.new.m 
+# => Vanilla Ruby:   raises (from `I#m`)
+# => With this gem: `Parent#m`
+```
+
+There are two challenges here:
+
+  1. We need to not let the `I#m` stub implementation "get in the way", so that we can find real implementation that get inherited from further ancestors (like `Parent#m`).
+  2. *but* we still want something to raise an error if you attempt to call an unimplemented abstract method.
+
+If you lookup `m` on an instance of `Child`, you would usually hit the empty stub `I#m` instead of the inherited implementation `Parent#m`:
+
+```ruby
+Child.ancestors
+
+# => [Child, Interface, Parent, Object, Kernel, BasicObject]
+#     ^      ^          ^
+#     |      |          Provides the implementation for Child to inherit
+#     |      Its stub abstract method "gets in the way" and needs to be side-stepped
+#     We want Child to inherit the implementation from Parent
+
+
+Child.instance_method(:m).owner
+# => Vanilla Ruby:  `I`
+# => With this gem: `Parent`
+```
+
+# Solution
+
+Solve the inheritance problem by just yoinking the abstract method stub out of the ancestor chain, by just using `remove_method()`.
+
+Now if you send `#m` to a child, there's no `I#m` implementation to hit, so it just jumps over to `Parent#m`. This is a direct method call with absolutely no runtime overhead.
+
+This introduces a new problem, that now calling unimplemented abstract methods just raises `NoMethodError`, as if the name never existed. For a better developer experience, we'd like to give a more helpful message.
+
+To do this, we implement `#method_missing` and check if the missing method name is one of the abstract methods (based on a list we append to every time you call `abstract`). If it is, we can raise our nicer error, otherwise we just delegate up the rest of the `#method_missing` chain (ultimately triggering a `NoMethodError`, like normal). This part isn't strictly necessary, but it's a nice-to-have. We can make it configurable.
+
+Syntax:
+
+```ruby
+module I
+  interface!
+
+  abstract def m; end
+end
+```
+
+That's it. That simple!
+
+Pros:
+  - Good DX when calling an abstract method that you forgot to implement
+  - Really nice syntax
+
+Cons:
+  - Some implementation complexity (but all tucked into this gem, with less than 130 lines of implementation code)
+  - Calls to implemented abstract methods are faster, at the expense of unimplemented ones
+    - 1.9x slower than the hand-written alternative
+    - 1.1x slower than sorbet-runtime alternative
+    - but that's totally acceptable, because this should never happen in a completed program. The performance of calls to actually implemented methods is what matters, since that's what the real code will be doing at a huge volume.
+
+# Alternative 1: Hand-written delegation
+
+You duplicate this delegation logic in every abstract method:
+
+```ruby
+module I
+  interface!
+
+  # @abstract
+  def m = defined?(super) ? super : raise("Abstract method `#m` not implemented")
+end
+```
+
+Pros:
+  - There's no magic, no runtime needed.
+
+Cons:
+  - Repetitive
+  - Can be forgotten
+  - There's more overhead on every method call (but only to abstract methods with an inherited implementation):
+    - Checking `defined?(super)`
+    - Making the `super` call
+  - It adds an extra frame to your backtrace which will be seen in debuggers and exception backtraces (unless you configure them to filter it out)
+
+
+# Alternative 2: Sorbet runtime's solution
+
+Here's a Sorbet version of the example: [Sorbet.run](https://sorbet.run/#%23%20typed%3A%20true%0A%0Aclass%20Parent%0A%20%20extend%20T%3A%3ASig%0A%0A%20%20sig%20%7B%20returns%28String%29%20%7D%0A%20%20def%20m%20%3D%20%22Parent%23m%22%0Aend%0A%20%20%0Amodule%20I%0A%20%20extend%20T%3A%3ASig%0A%20%20extend%20T%3A%3AHelpers%0A%0A%20%20interface!%0A%0A%20%20sig%20%7B%20abstract.returns%28String%29%20%7D%0A%20%20def%20m%3B%20end%0Aend%0A%0Aclass%20Child%20%3C%20Parent%3B%20end).
+
+Sorbet runtime basically automates the hand-written solution above, by wrapping abstract methods:
+
+https://github.com/sorbet/sorbet/blob/703498a0dcddbe7ec4b87ec6cc5d7d55cfa9b270/gems/sorbet-runtime/lib/types/private/methods/call_validation.rb#L48-L68
+
+Pros:
+  - "just works"
+
+Cons:
+  - All the downsides of doing this the hand-written way.
+  - To determine if a method is abstract or not, every `sig` needs to have its block evaluated, to see if it calls `abstract`.
+  - This used to be slower because it was defined via `defined_methods` with a block body. This produces a slower kind of method (`VM_METHOD_TYPE_BMETHOD`), than the equivalent code via `def` (`VM_METHOD_TYPE_ISEQ`). This was fixed in [this PR](https://github.com/sorbet/sorbet/pull/8238), which switch to using `module_eval` to define the method via `def`.

data/docs/design/self_dot_methods.md

@@ -0,0 +1,79 @@
+# The `def self.` problem
+
+Ruby method definitions evaluate to the name of the method that was defined. This fact is used by the `public`/`protected`/`private` methods:
+
+```ruby
+class
+  puts def demo; end
+  # Equivalent to `puts(:demo)`
+end
+```
+
+However, there's no way to distinguish whether the method was an instance method, or a singleton method:
+
+```ruby
+class C
+  puts def      demo; end # prints ":demo"
+  puts def self.demo; end # *also* prints ":demo"
+end
+```
+
+# Solution
+
+Track into whether the last method call was an instance method or a singleton method, by hooking into `method_added` and `singleton_method_added`. See the `MethodDefRecorder` for details.
+
+This way, both of these "just work"
+
+```rb
+class C
+  # Correctly defines an abstract instance method
+  abstract def      demo; end
+
+  # Correctly defines an abstract "class method"
+  abstract def self.demo; end
+end
+```
+
+# Alternative 1: Do nothing
+
+This is already a problem for access level modifiers, which don't do anything to handle it:
+
+```ruby
+class C
+  private def self.demo; end
+  # => ❌ undefined method 'demo' for class 'C' (NameError)
+end
+```
+
+We can just follow suit. However, there's a risk that if an instance method called `demo` _actually_ existed, we inadvertently make it abstract without intending. Again, the access level modifier methods already have this issue, but it's a sharp edge that we don't need to have.
+
+If we choose to do nothing, we could encourage users to enable the [`Style/ClassMethodsDefinitions`](https://docs.rubocop.org/rubocop/cops_style.html#styleclassmethodsdefinitions) on the `EnforcedStyle: self_class` mode, so that their code bases don't contain `def self.foo` methods at all.
+
+Pros:
+  - Simpler implementation (none!)
+
+Cons:
+  - Sharp edge
+  - More complex mental model for users of RBS
+
+# Alternative 2: separate macro
+
+E.g.
+
+```rb
+class C
+  # Correctly defines an abstract instance method
+  abstract_instance_method def demo; end
+
+  # Correctly defines an abstract "class method"
+  abstract_class_method def self.demo; end
+end
+```
+
+Pros:
+  - Simple implementation
+
+Cons:
+  - Correct usage can't be enforced at runtime.
+    - Rubocop cop could enforce it, but that would need to be written
+  - Still a sharp edge, has the same cognitive complexity as alternative 1.

data/lib/rubocop/cop/type_toolkit/plugin.rb

@@ -13,7 +13,7 @@ module RuboCop
             name: "rubocop-type_toolkit",
             version: ::TypeToolkit::VERSION,
             homepage: "https://github.com/Shopify/type_toolkit",
-            description: "Detects misuse of UnexpectedNilError.",
+            description: "RuboCop rules for Type Toolkit.",
           )
         end