sorbet_typed-props 1.5.0 → 1.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9f174dad33ad91ad3f978dca0a7048436f5174ddc4697d986352eea398efe3ce
-  data.tar.gz: 0425e0dbfc6549cccdac000060c1f968d7877fb815c2f7e0374e494101887d40
+  metadata.gz: 38708cf1f39a8cef314d4843c4fed453f4faf8f2fc35db4e47e1c659dcd581d7
+  data.tar.gz: 94b1bf4f088610d3e3e3bb1eb1ea7f09da8428f9849176d214f4f0a9d2760ff7
 SHA512:
-  metadata.gz: 1e63e26d0ad9e645e56efeda20b3df2aab26f0fac3da887a175c8d1b75dc8062a1360b6e615f370b8b6f065f93c93961e7947006a1840d76e89c2014c233c5c0
-  data.tar.gz: 9e7310699fe6272d445e59a46b1c08c17fc3ccf0e27c0aecf3b41b8a595415ab5bcf52919db8a40d43e2efe4b971dc2516df2bf76c017ad87d07c7ed35fb7e27
+  metadata.gz: d37eeeaea430f1950b0a9bc80e50e5c98945458082ee037989c213151a593e67ecf9e52816b05c371636b8110b01d161ba53418f601ec514d654c5ea4abfa374
+  data.tar.gz: e54af5f419e3cea6b5aaacc4379db254d17c3cc6da84be35c8ab715149194466a1c5cec687896dc2cf93027541f1a5af88246ac4fd83d99fa92d3d54801e973e

data/.cz.yaml

@@ -15,7 +15,7 @@ commitizen:
     - mise run format
   tag_format: v$version
   update_changelog_on_bump: true
-  version: 1.5.0
+  version: 1.5.2
   version_files:
     - lib/sorbet_typed/props/version.rb
   version_scheme: semver2

data/.prettierignore

@@ -0,0 +1 @@
+.superpowers/

data/CHANGELOG.md

@@ -1,3 +1,15 @@
+## v1.5.2 (2026-07-03)
+
+### Fix
+
+- **renovate**: stop creating MRs before minimumReleaseAge elapses
+
+## v1.5.1 (2026-06-23)
+
+### Fix
+
+- **props**: adapt to sorbet-runtime bound_setter signature change
+
 ## v1.5.0 (2026-06-22)
 
 ### Feat

data/README.md

@@ -14,10 +14,13 @@ the
 which doesn't really work with sorbet, if you want to have everything fully typed (and not use two runtime type-systems
 in parallel).
 
+- [Tested with](#tested-with)
 - [Installation](#installation)
 - [Usage](#usage)
-  - [Phlex Example](#phlex-example)
-  - [Instance Variables](#instance-variables)
+  - [Defaults and optional props](#defaults-and-optional-props)
+  - [Internal props](#internal-props)
+  - [Inheritance](#inheritance)
+  - [Phlex integration](#phlex-integration)
   - [Extending initializer logic](#extending-initializer-logic)
   - [Method Visibility](#method-visibility)
 - [Development](#development)
@@ -27,12 +30,27 @@ in parallel).
 
 <!-- begin:tested-versions -->
 
-|                | Tested versions  |
-| -------------- | ---------------- |
-| Ruby           | 3.3, 3.4, 4.0    |
-| sorbet-runtime | 0.6              |
-| tapioca        | 0.17, 0.18, 0.19 |
-| sorbet         | 0.6              |
+This gem is tested against all combinations of the following dependency versions.
+
+|                | Tested versions      |
+| -------------- | -------------------- |
+| Ruby           | 3.3, 3.4, 4.0        |
+| sorbet-runtime | 0.6.12997, 0.6.13321 |
+| tapioca        | 0.17, 0.18, 0.19     |
+| sorbet         | 0.6.12997, 0.6.13321 |
+
+### Excluded combinations
+
+Some version combinations are incompatible with each other independently of this gem — users depending on those
+combinations would face the same conflict in their own projects. These are excluded from the test matrix:
+
+- `tapioca < 0.19.0` + `sorbet-runtime >= 0.6.13149` — tapioca < 0.19 calls has_rest on T::Private::Methods::Signature
+  which was removed in sorbet-runtime 0.6.13149
+- `tapioca < 0.19.1` + `sorbet-runtime < 0.6.12698` — tapioca < 0.19.1 references T::Module which was added to
+  sorbet-runtime in 0.6.12698
+- `tapioca >= 0.19.1` + `sorbet-runtime < 0.6.12698` — tapioca >= 0.19.1 enforces sorbet-runtime >= 0.6.12698 in its
+  gemspec; listed explicitly so the test generator skips sorbet-runtime < 0.6.12698 rather than treating the bundler
+  rejection as an unexpected error
 
 <!-- end:tested-versions -->
 
@@ -67,43 +85,99 @@ my_object.my_prop # => "foo"
 my_object.my_prop = 'bar'
 ```
 
-### Phlex Example
+→ [Full documentation](docs/props-and-const.md)
+
+### Defaults and optional props
+
+Use `default:` for a static fallback value or `factory:` for a freshly constructed default per instance:
 
 ```ruby
-class Components::HelloWorld < Phlex::HTML
-  extend T::Sig
+class Config
   include SorbetTyped::Props
 
-  prop :name, String
+  const :timeout_seconds, Integer, default: 30
+  const :logger, Logger, factory: -> { Logger.new($stdout) }
+end
 
-  sig { void }
-  def view_template
-    h1 { "Hello, #{name}!" }
+Config.new                      # uses defaults
+Config.new(timeout_seconds: 60) # override specific prop
+```
+
+→ [Full documentation](docs/defaults.md)
+
+### Internal props
+
+Use `extra: { initializer: false }` for attributes that are set after construction, not at it — avoiding `T.must` noise
+at read sites for order-dependent implementations:
+
+```ruby
+class Pipeline
+  include SorbetTyped::Props
+
+  const  :input,  String
+  prop   :result, String, extra: { initializer: false }
+
+  def run
+    self.result = process(input)
   end
+
+  private
+
+  def process(value) = value.upcase
 end
+
+pipeline = Pipeline.new(input: 'hello')
+pipeline.result  # => TypeError("Property `result` of `Pipeline` was read before being set")
+pipeline.run
+T.reveal_type(pipeline.result)  # => String
+pipeline.result  # => 'HELLO'
 ```
 
-### Instance Variables
+→ [Full documentation](docs/internal-props.md)
 
-If you need more instance variables beside defined props, define them within the class body, not the initializer.
+### Inheritance
+
+Props are inherited by subclasses. The Tapioca compiler generates a combined `initialize` signature for each concrete
+class:
 
 ```ruby
-class MyClass
-  extend T::Sig
+class Animal
   include SorbetTyped::Props
 
-  prop :my_prop, Integer
+  prop :name, String
+end
 
-  @my_var = T.let(nil, T.nilable(String))
+class Dog < Animal
+  prop :breed, String
+end
+
+Dog.new(name: 'Rex', breed: 'Labrador')
+```
+
+→ [Full documentation](docs/inheritance.md)
+
+### Phlex integration
+
+```ruby
+class Components::HelloWorld < Phlex::HTML
+  extend T::Sig
+  include SorbetTyped::Props
+
+  prop :name, String
 
   sig { void }
-  def foo
-    T.reveal_type(my_prop) # => Integer
-    T.reveal_type(@my_var) # => T.nilable(String)
+  def view_template
+    h1 { "Hello, #{name}!" }
   end
 end
 ```
 
+> **Known limitation:** Phlex overrides `::new` rather than `#initialize` in `Phlex::SGML`, so Sorbet cannot statically
+> validate props on Phlex components. Calling `HelloWorld.new` without required props will not raise a Sorbet error. See
+> issue [#23](https://gitlab.com/sorbet_typed/props/-/work_items/23).
+
+→ [Full documentation](docs/phlex.md)
+
 ### Extending initializer logic
 
 If you want to implement some logic on instance initialization, implementing a custom `initializer` method would require
@@ -128,8 +202,9 @@ class MyClass
 end
 ```
 
-**Note:** you cannot do instance variable initialization here. Define them [within the class body](#instance-variables)
-instead.
+→ [Full documentation](docs/post-init-hook.md)
+
+**Note:** you cannot do instance variable initialization here.
 
 ### Method Visibility
 
@@ -186,6 +261,8 @@ my_object.baz
 my_object.bar # => "baz"
 ```
 
+→ [Full documentation](docs/method-visibility.md)
+
 Putting prop-definition after an access modifier without arguments does not work:
 
 ```ruby

data/docs/defaults.md

@@ -0,0 +1,198 @@
+# Defaults and optional props
+
+## Table of Contents
+
+- [Table of Contents](#table-of-contents)
+- [What they do](#what-they-do)
+- [When to use](#when-to-use)
+- [Options](#options)
+- [Examples](#examples)
+  - [Prop with a static default](#prop-with-a-static-default)
+  - [Const with a static default](#const-with-a-static-default)
+  - [Nilable prop without default — still required (statically)](#nilable-prop-without-default--still-required-statically)
+  - [Nilable prop with default nil — optional](#nilable-prop-with-default-nil--optional)
+  - [Const with factory — dependency injection](#const-with-factory--dependency-injection)
+- [Behavior notes](#behavior-notes)
+
+## What they do
+
+`default:` and `factory:` are native [Sorbet `T::Props`](https://sorbet.org/docs/tstruct) options. They make a prop or
+const optional in `initialize`. When the caller does not supply the argument, the declared default or factory result is
+used instead.
+
+## When to use
+
+- A prop has a sensible fallback value that most callers will not need to override.
+- You want to inject a collaborator (e.g. a repository or service object) with a real-world default, while keeping the
+  ability to swap it out in tests.
+
+## Options
+
+| Option              | Value type                     | Description                                                                                                       |
+| ------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
+| `default: value`    | Any value matching prop type   | Static default. The same object is used across all instances. Use only for immutable values (numbers, Symbols).   |
+| `factory: -> { … }` | `Proc` returning the prop type | Called once per instantiation. Use for mutable defaults or objects that must be freshly constructed per instance. |
+
+## Examples
+
+### Prop with a static default
+
+```ruby
+class Counter
+  include SorbetTyped::Props
+
+  prop :count, Integer
+  prop :step,  Integer, default: 1
+end
+
+Counter.new(count: 0)           # step defaults to 1
+Counter.new(count: 0, step: 5)  # step overridden
+```
+
+Generated `initialize` signature — `count` required, `step` optional:
+
+```ruby
+# sorbet/rbi/dsl/counter.rbi
+# typed: true
+
+class Counter
+  # Generated from sorbet SorbetTyped::Props
+  sig { params(count: ::Integer, step: ::Integer).void }
+  def initialize(count:, step: T.unsafe(nil)); end
+end
+```
+
+### Const with a static default
+
+`const` with `default:` is optional in `initialize` but has no writer — the value is fixed after construction.
+
+```ruby
+class Config
+  include SorbetTyped::Props
+
+  const :timeout_seconds, Integer, default: 30
+end
+
+Config.new                         # timeout_seconds == 30
+Config.new(timeout_seconds: 60)    # timeout_seconds == 60
+# Config.new.timeout_seconds = 10  # NoMethodError — const has no writer
+```
+
+Generated `initialize` signature:
+
+```ruby
+# sorbet/rbi/dsl/config.rbi
+# typed: true
+
+class Config
+  # Generated from sorbet SorbetTyped::Props
+  sig { params(timeout_seconds: ::Integer).void }
+  def initialize(timeout_seconds: T.unsafe(nil)); end
+end
+```
+
+### Nilable prop without default — still required (statically)
+
+Sorbet's native `T::Props` runtime behavior is that `T.nilable` **always implies `default: nil`**, with
+[no way to opt out](https://sorbet.org/docs/tstruct#tnilable-without-implying-default-nil). At actual Ruby runtime, a
+`T.nilable` prop without an explicit `default:`/`factory:` is optional — omitting it simply sets it to `nil`.
+
+This gem's Tapioca compiler deliberately diverges from that for the **generated static signature**: it never treats a
+nilable prop as optional unless `default:`/`factory:` is set explicitly. This means `srb tc` will flag a missing nilable
+prop as a static type error, even though it would succeed at runtime. This is intentional — it surfaces "forgot to pass
+this prop" mistakes at type-check time instead of letting them silently become `nil`.
+
+```ruby
+class Notification
+  include SorbetTyped::Props
+
+  prop :message, T.nilable(String)
+end
+
+Notification.new(message: nil)   # ok
+Notification.new                 # ok at runtime — message is nil
+# But `srb tc` reports: Missing required keyword argument `message`
+```
+
+### Nilable prop with default nil — optional
+
+Adding `default: nil` makes the prop optional. `nil` is both the type-safe value and the default.
+
+```ruby
+class Notification
+  include SorbetTyped::Props
+
+  prop :message, T.nilable(String), default: nil
+end
+
+Notification.new                     # ok — message is nil
+Notification.new(message: 'hello')   # ok
+```
+
+Generated `initialize` signature:
+
+```ruby
+# sorbet/rbi/dsl/notification.rbi
+# typed: true
+
+class Notification
+  # Generated from sorbet SorbetTyped::Props
+  sig { params(message: T.nilable(::String)).void }
+  def initialize(message: T.unsafe(nil)); end
+end
+```
+
+### Const with factory — dependency injection
+
+`factory:` provides a proc that constructs a fresh default value for each instance. Combined with `private`, this
+creates a clean dependency injection point: the real implementation is used by default; tests can supply a test double
+by passing it to the constructor.
+
+```ruby
+class OrderRepository
+  include SorbetTyped::Props
+
+  const :database, Database, factory: -> { Database.connect }
+  const :cache,    Cache,    factory: -> { Cache.new }
+  private :database, :cache
+
+  def find(id)
+    cache.fetch(id) { database.query(id) }
+  end
+end
+
+# Production — real database and cache are created by the factory:
+repo = OrderRepository.new
+
+# Tests — inject test doubles:
+repo = OrderRepository.new(database: test_db, cache: test_cache)
+```
+
+Generated `initialize` signature — both deps are optional (factory provides defaults):
+
+```ruby
+# sorbet/rbi/dsl/order_repository.rbi
+# typed: true
+
+class OrderRepository
+  # Generated from sorbet SorbetTyped::Props
+  sig { params(database: Database, cache: Cache).void }
+  def initialize(database: T.unsafe(nil), cache: T.unsafe(nil)); end
+end
+```
+
+## Behavior notes
+
+- Props with `default:` or `factory:` become optional keyword arguments in the generated `initialize`. They appear after
+  all required props in the signature, regardless of declaration order.
+- `factory:` is called once per object construction. It is safe for mutable objects (arrays, hashes, service instances).
+- `default:` reuses the same object across all instances. Do **not** use `default: []` or `default: {}` — use
+  `factory: -> { [] }` instead.
+- The Tapioca compiler treats `default:` and `factory:` identically — both produce optional keyword arguments in the
+  generated signature.
+- For the difference between a `T.nilable` prop and an internal prop that is never in `initialize`, see
+  [Internal props](internal-props.md).
+- Native sorbet `T::Props` runtime behavior: `T.nilable` always implies `default: nil`, with no opt-out
+  ([sorbet docs](https://sorbet.org/docs/tstruct#tnilable-without-implying-default-nil)). This gem's static signature
+  generation intentionally does not mirror that — see
+  [Nilable prop without default — still required (statically)](#nilable-prop-without-default--still-required-statically).

data/docs/inheritance.md

@@ -0,0 +1,139 @@
+# Inheritance
+
+## Table of Contents
+
+- [Table of Contents](#table-of-contents)
+- [What it does](#what-it-does)
+- [When to use](#when-to-use)
+- [Examples](#examples)
+  - [Subclass inherits parent props](#subclass-inherits-parent-props)
+  - [Child adds a required prop](#child-adds-a-required-prop)
+  - [Child adds a prop with a default](#child-adds-a-prop-with-a-default)
+- [Behavior notes](#behavior-notes)
+
+## What it does
+
+Props declared in a parent class are inherited by subclasses. The Tapioca compiler generates a separate `initialize` RBI
+for each concrete class that has props, including all inherited ones.
+
+## When to use
+
+- You have a base class that defines common constructor parameters shared by all subclasses.
+- You want subclasses to extend the constructor with additional props without repeating the parent's declarations.
+
+## Examples
+
+### Subclass inherits parent props
+
+```ruby
+class Animal
+  include SorbetTyped::Props
+
+  prop :name,   String
+  prop :weight, Float
+end
+
+class Dog < Animal
+  prop :breed, String
+end
+
+Dog.new(name: 'Rex', weight: 30.5, breed: 'Labrador')
+```
+
+Parent RBI — generated for `Animal`:
+
+```ruby
+# sorbet/rbi/dsl/animal.rbi
+# typed: true
+
+class Animal
+  # Generated from sorbet SorbetTyped::Props
+  sig { params(name: ::String, weight: ::Float).void }
+  def initialize(name:, weight:); end
+end
+```
+
+Child RBI — includes both parent and child props:
+
+```ruby
+# sorbet/rbi/dsl/dog.rbi
+# typed: true
+
+class Dog < Animal
+  # Generated from sorbet SorbetTyped::Props
+  sig { params(name: ::String, weight: ::Float, breed: ::String).void }
+  def initialize(name:, weight:, breed:); end
+end
+```
+
+### Child adds a required prop
+
+```ruby
+class Vehicle
+  include SorbetTyped::Props
+
+  const :make,  String
+  const :model, String
+end
+
+class ElectricVehicle < Vehicle
+  const :range_km, Integer
+end
+
+ElectricVehicle.new(make: 'Tesla', model: 'Model 3', range_km: 450)
+```
+
+Generated child RBI:
+
+```ruby
+# sorbet/rbi/dsl/electric_vehicle.rbi
+# typed: true
+
+class ElectricVehicle < Vehicle
+  # Generated from sorbet SorbetTyped::Props
+  sig { params(make: ::String, model: ::String, range_km: ::Integer).void }
+  def initialize(make:, model:, range_km:); end
+end
+```
+
+### Child adds a prop with a default
+
+```ruby
+class Notification
+  include SorbetTyped::Props
+
+  const :recipient, String
+  const :subject,   String
+end
+
+class EmailNotification < Notification
+  const :priority, String, default: 'normal'
+end
+
+EmailNotification.new(recipient: 'user@example.com', subject: 'Hello')
+# priority defaults to 'normal'
+```
+
+Generated child RBI — `priority` is optional:
+
+```ruby
+# sorbet/rbi/dsl/email_notification.rbi
+# typed: true
+
+class EmailNotification < Notification
+  # Generated from sorbet SorbetTyped::Props
+  sig { params(recipient: ::String, subject: ::String, priority: ::String).void }
+  def initialize(recipient:, subject:, priority: T.unsafe(nil)); end
+end
+```
+
+## Behavior notes
+
+- Props are inherited in definition order: parent props come first in the generated `initialize` signature, followed by
+  child props.
+- Required props appear before optional props (those with `default:` or `factory:`), regardless of declaration order
+  across parent and child.
+- The Tapioca compiler generates a separate RBI for each concrete class. Each RBI includes all inherited props.
+- Abstract classes (those with `abstract!`) are skipped by the Tapioca compiler — no `initialize` RBI is generated for
+  them.
+- Props cannot be removed or re-typed in a subclass.