light-services 3.3.0 → 3.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3f1c7874fc2ac069ac686f0b12895567c76c7005523dc0c1b841781f73ab3988
-  data.tar.gz: 4b41b830919ac007ec7740b1a84ca7d8a39682d9623fd9fd9085546e384391a3
+  metadata.gz: 814307f260796e4439cd7e9602159281b4457003c9b9a70f5596ecb81a80c7bc
+  data.tar.gz: e9ac19b493f3559b0e2ba1b978c7dd3e51615614c1c1f239f1326412e6126950
 SHA512:
-  metadata.gz: eac0742e9f253e03b5e1cb58619798fc81b4f3139df62311c9350d4f3f1a13264dc4ad74af14e84033fa66137fbe31b390f95056783a83151ec76527c0590bc3
-  data.tar.gz: 45a9a709c76c57032c8ae71bc8fa31e32fee3aebe8e82a8c1265480c400ab2a724cfc9dc9d3572a830ff78a03235cfd94a95f782c4c92750db5d5f0d9f83bd6f
+  metadata.gz: 3ba524199e7078ad1dbbf0a4df34ef4bb50f59c8950695e74e8a2b9f6691ae0ca673b16127700e2a7d0bdc66a1762fd886d4a89efe4e531840a092a49b0490b3
+  data.tar.gz: ecacfe8dd84b3fb1b1ac944b46e4ec6ed08d15eb6857f9fec82f070f90a87a51c97855d7ab46cc62f007f32c77f528fb178b9829c46603121978a5752905cb49

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 3.3.1 (2025-12-16)
+
+### Added
+
+- Sorbet runtime type support for `arg` and `output` (validation only, no coercion)
+
 ## 3.3.0 (2025-12-15)
 
 ### Added

data/Gemfile

@@ -7,6 +7,7 @@ gemspec
 group :test do
   # Optional type system support
   gem "dry-types", "~> 1.0"
+  gem "sorbet-runtime"
 
   gem "activerecord", "< 8"
   gem "connection_pool", "< 3"

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    light-services (3.3.0)
+    light-services (3.3.1)
 
 GEM
   remote: https://rubygems.org/
@@ -126,6 +126,7 @@ GEM
       simplecov_json_formatter (~> 0.1)
     simplecov-html (0.13.2)
     simplecov_json_formatter (0.1.4)
+    sorbet-runtime (0.6.12848)
     sqlite3 (2.8.1)
       mini_portile2 (~> 2.8.0)
     timeout (0.5.0)
@@ -154,6 +155,7 @@ DEPENDENCIES
   rubocop-rake
   rubocop-rspec
   simplecov
+  sorbet-runtime
   sqlite3
 
 BUNDLED WITH

data/docs/SUMMARY.md

@@ -19,6 +19,7 @@
 * [Rails Generators](generators.md)
 * [RuboCop Integration](rubocop.md)
 * [Ruby LSP Integration](ruby-lsp.md)
+* [Sorbet Runtime Types](sorbet-runtime.md)
 * [Tapioca / Sorbet Integration](tapioca.md)
 
 ## Examples

data/docs/arguments.md

@@ -124,6 +124,38 @@ service = User::Create.run(name: "John", age: "25")
 service.age # => 25 (Integer, not String)
 ```
 
+### Sorbet Runtime Types
+
+Light Services also supports [Sorbet runtime types](https://sorbet.org/docs/runtime) for type validation. Unlike dry-types, Sorbet types **only validate** and do not coerce values.
+
+```ruby
+require "sorbet-runtime"
+
+class User::Create < ApplicationService
+  # Basic types using T::Utils.coerce
+  arg :name, type: T::Utils.coerce(String)
+  arg :age, type: T::Utils.coerce(Integer)
+  
+  # Nilable types
+  arg :email, type: T.nilable(String), optional: true
+  
+  # Union types
+  arg :status, type: T.any(String, Symbol)
+  
+  # Typed arrays
+  arg :tags, type: T::Array[String]
+  
+  # Boolean type
+  arg :active, type: T::Boolean, default: true
+end
+```
+
+{% hint style="warning" %}
+**Sorbet types do NOT coerce values.** If you pass `"25"` where an `Integer` is expected, it will raise an error instead of converting the string to an integer. Use dry-types if you need automatic coercion.
+{% endhint %}
+
+See the [Sorbet Runtime Types documentation](sorbet-runtime.md) for more details.
+
 ## Required Arguments
 
 By default, arguments are required. You can make them optional by setting `optional` to `true`.

data/docs/outputs.md

@@ -124,6 +124,22 @@ class AI::Chat < ApplicationService
 end
 ```
 
+### Sorbet Runtime Types
+
+Outputs also support [Sorbet runtime types](https://sorbet.org/docs/runtime) for type validation:
+
+```ruby
+require "sorbet-runtime"
+
+class AI::Chat < ApplicationService
+  output :messages, type: T::Array[Hash]
+  output :total_tokens, type: T::Utils.coerce(Integer)
+  output :metadata, type: T.nilable(Hash), optional: true
+end
+```
+
+See the [Sorbet Runtime Types documentation](sorbet-runtime.md) for more details.
+
 ## Default Values
 
 Set default values for outputs using the `default` option. The default value will be automatically set before the execution of steps.

data/docs/sorbet-runtime.md

@@ -0,0 +1,277 @@
+# Sorbet Runtime Types
+
+Light Services supports [Sorbet runtime types](https://sorbet.org/docs/runtime) for type validation of arguments and outputs. This provides runtime type checking using Sorbet's type system.
+
+{% hint style="info" %}
+This page covers **runtime type checking** with `sorbet-runtime`. For **static type analysis** with Sorbet and RBI file generation, see [Tapioca / Sorbet Integration](tapioca.md).
+{% endhint %}
+
+## Installation
+
+Add `sorbet-runtime` to your Gemfile:
+
+```ruby
+gem "sorbet-runtime"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Basic Usage
+
+When `sorbet-runtime` is loaded, plain Ruby classes are automatically validated using Sorbet's type system:
+
+```ruby
+require "sorbet-runtime"
+
+class User::Create < ApplicationService
+  # Basic types - plain Ruby classes work directly!
+  arg :name, type: String
+  arg :age, type: Integer
+  
+  # Nilable types (allows nil)
+  arg :email, type: T.nilable(String), optional: true
+  
+  # Union types (multiple allowed types)
+  arg :status, type: T.any(String, Symbol), default: "pending"
+  
+  # Typed arrays
+  arg :tags, type: T::Array[String], optional: true
+  
+  # Boolean type
+  arg :active, type: T::Boolean, default: true
+
+  # Outputs with Sorbet types - plain classes work here too
+  output :user, type: User
+  output :metadata, type: Hash
+  
+  step :create_user
+  step :build_metadata
+
+  private
+
+  def create_user
+    self.user = User.create!(
+      name: name,
+      age: age,
+      email: email,
+      status: status,
+      tags: tags || [],
+      active: active
+    )
+  end
+
+  def build_metadata
+    self.metadata = { created_at: Time.current }
+  end
+end
+```
+
+## Type Reference
+
+### Basic Types
+
+When `sorbet-runtime` is loaded, plain Ruby classes are automatically coerced to Sorbet types:
+
+```ruby
+arg :name, type: String
+arg :count, type: Integer
+arg :price, type: Float
+arg :data, type: Hash
+arg :items, type: Array
+```
+
+{% hint style="info" %}
+You can also use `T::Utils.coerce(String)` explicitly, but it's not required - Light Services handles the coercion automatically.
+{% endhint %}
+
+### Nilable Types
+
+Allow `nil` values with `T.nilable`:
+
+```ruby
+arg :nickname, type: T.nilable(String), optional: true
+```
+
+### Union Types
+
+Allow multiple types with `T.any`:
+
+```ruby
+arg :identifier, type: T.any(String, Integer)
+arg :status, type: T.any(String, Symbol)
+```
+
+### Typed Arrays
+
+Validate array element types with `T::Array`:
+
+```ruby
+arg :tags, type: T::Array[String]
+arg :numbers, type: T::Array[Integer]
+arg :users, type: T::Array[User]
+```
+
+{% hint style="warning" %}
+**Generic Type Erasure:** Sorbet's `T::Array[String]` only validates that the value is an `Array` at runtime. The type parameter (`String`) is **erased** and not checked. For strict array element validation, use dry-types: `Types::Array.of(Types::Strict::String)`.
+{% endhint %}
+
+### Boolean Type
+
+Use `T::Boolean` for true/false values:
+
+```ruby
+arg :active, type: T::Boolean
+arg :verified, type: T::Boolean, default: false
+```
+
+### Complex Types
+
+Combine types for more complex validations:
+
+```ruby
+# Nilable array
+arg :tags, type: T.nilable(T::Array[String]), optional: true
+
+# Array of union types
+arg :identifiers, type: T::Array[T.any(String, Integer)]
+```
+
+## Key Differences from dry-types
+
+{% hint style="warning" %}
+**Sorbet types do NOT coerce values.** Unlike dry-types which can automatically convert values (e.g., `"123"` → `123`), Sorbet runtime types only validate that values match the expected type.
+{% endhint %}
+
+### Coercion Behavior Comparison
+
+**With dry-types (coerces):**
+
+```ruby
+# dry-types with coercible integer
+arg :age, type: Types::Coercible::Integer
+
+service = MyService.run(age: "25")
+service.age # => 25 (Integer - coerced from String)
+```
+
+**With Sorbet runtime (validates only):**
+
+```ruby
+# Sorbet runtime type (plain class or T::Utils.coerce)
+arg :age, type: Integer
+
+service = MyService.run(age: "25")
+# => Raises ArgTypeError: expected Integer, got String
+```
+
+### When to Use Each
+
+| Use Case | Recommended |
+|----------|-------------|
+| Strict type validation | Sorbet runtime |
+| Automatic value coercion | dry-types |
+| Static type analysis | Sorbet + Tapioca |
+| Input from external sources (APIs, forms) | dry-types (for coercion) |
+| Internal service-to-service calls | Sorbet runtime |
+
+## Combining with Tapioca
+
+For full Sorbet support, you can use both:
+
+1. **Runtime types** (`sorbet-runtime`) - Validates types at runtime
+2. **Static types** (Tapioca) - Generates RBI files for static analysis
+
+See [Tapioca / Sorbet Integration](tapioca.md) for setting up static type analysis.
+
+```ruby
+# typed: strict
+
+class User::Create < ApplicationService
+  # Runtime validation with Sorbet types
+  arg :name, type: String
+  arg :age, type: Integer
+  
+  output :user, type: User
+  
+  # ...
+end
+```
+
+With Tapioca configured, you get:
+- **Runtime validation** from `sorbet-runtime`
+- **IDE autocompletion** from generated RBI files
+- **Static type checking** from `srb tc`
+
+## Error Messages
+
+When type validation fails, Light Services raises `ArgTypeError` with a descriptive message:
+
+```ruby
+service = User::Create.run(name: 123, age: 25)
+# => Light::Services::ArgTypeError: User::Create argument `name` expected String, but got Integer with value: 123
+```
+
+## Full Example
+
+```ruby
+require "sorbet-runtime"
+
+class Order::Create < ApplicationService
+  # Required arguments - plain classes work!
+  arg :customer, type: Customer
+  arg :items, type: T::Array[OrderItem]
+  arg :total, type: T.any(Integer, Float)
+  
+  # Optional arguments
+  arg :notes, type: T.nilable(String), optional: true
+  arg :priority, type: T::Boolean, default: false
+  arg :tags, type: T::Array[String], optional: true
+  
+  # Outputs
+  output :order, type: Order
+  output :confirmation_number, type: String
+  
+  step :validate_items
+  step :create_order
+  step :generate_confirmation
+
+  private
+
+  def validate_items
+    fail!("Order must have at least one item") if items.empty?
+  end
+
+  def create_order
+    self.order = Order.create!(
+      customer: customer,
+      items: items,
+      total: total,
+      notes: notes,
+      priority: priority,
+      tags: tags || []
+    )
+  end
+
+  def generate_confirmation
+    self.confirmation_number = "ORD-#{order.id}-#{SecureRandom.hex(4).upcase}"
+  end
+end
+
+# Usage
+result = Order::Create.run(
+  customer: current_user,
+  items: [item1, item2],
+  total: 99.99,
+  priority: true
+)
+
+if result.success?
+  puts "Order created: #{result.confirmation_number}"
+else
+  puts "Failed: #{result.errors.full_messages}"
+end
+```

data/lib/light/services/settings/field.rb

@@ -46,7 +46,7 @@ module Light
         end
 
         # Validate a value against the field's type definition.
-        # Supports both Ruby class types and dry-types.
+        # Supports Ruby class types, dry-types, and Sorbet runtime types.
         #
         # @param value [Object] the value to validate
         # @return [Object] the value (possibly coerced by dry-types)
@@ -56,6 +56,8 @@ module Light
 
           if dry_type?(@type)
             coerce_and_validate_dry_type!(value)
+          elsif sorbet_type?(@type) || (sorbet_available? && plain_class_type?(@type))
+            validate_sorbet_type!(value)
           else
             validate_ruby_type!(value)
             value
@@ -64,6 +66,16 @@ module Light
 
         private
 
+        # Check if sorbet-runtime is available
+        def sorbet_available?
+          defined?(T::Types::Base)
+        end
+
+        # Check if the type is a plain Ruby class (not dry-types or Sorbet type)
+        def plain_class_type?(type)
+          type.is_a?(Class) || type.is_a?(Module)
+        end
+
         # Check if the type is a dry-types type
         def dry_type?(type)
           return false unless defined?(Dry::Types::Type)
@@ -71,6 +83,13 @@ module Light
           type.is_a?(Dry::Types::Type)
         end
 
+        # Check if the type is a Sorbet runtime type
+        def sorbet_type?(type)
+          return false unless defined?(T::Types::Base)
+
+          type.is_a?(T::Types::Base)
+        end
+
         # Validate and coerce value against dry-types
         # Returns the coerced value
         def coerce_and_validate_dry_type!(value)
@@ -80,6 +99,20 @@ module Light
                 "#{@service_class} #{@field_type} `#{@name}` #{e.message}"
         end
 
+        # Validate value against Sorbet runtime types
+        # Note: Sorbet types only validate, they do not coerce values
+        # Automatically coerces plain Ruby classes to Sorbet types when needed
+        # @return [Object] the original value if valid
+        # @raise [ArgTypeError] if the value doesn't match the expected type
+        def validate_sorbet_type!(value)
+          sorbet_type = sorbet_type?(@type) ? @type : T::Utils.coerce(@type)
+          return value if sorbet_type.valid?(value)
+
+          raise Light::Services::ArgTypeError,
+                "#{@service_class} #{@field_type} `#{@name}` expected #{sorbet_type.name}, " \
+                "but got #{value.class} with value: #{value.inspect}"
+        end
+
         # Validate value against Ruby class types
         def validate_ruby_type!(value)
           return if [*@type].any? { |type| value.is_a?(type) }

data/lib/light/services/version.rb

@@ -2,6 +2,6 @@
 
 module Light
   module Services
-    VERSION = "3.3.0"
+    VERSION = "3.3.1"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: light-services
 version: !ruby/object:Gem::Version
-  version: 3.3.0
+  version: 3.3.1
 platform: ruby
 authors:
 - Andrew Kodkod
@@ -54,6 +54,7 @@ files:
 - docs/rubocop.md
 - docs/ruby-lsp.md
 - docs/service-rendering.md
+- docs/sorbet-runtime.md
 - docs/steps.md
 - docs/tapioca.md
 - docs/testing.md