light-services 3.0.0 → 3.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a45a0a0ba2e870c7188f55865004d697646da536e3cecb05b9b0eb30fda9651d
-  data.tar.gz: 4ad5df86f1a1ff129ac85f3f2ed1ecda11466d52c8639fbbfda410951e8dc8c5
+  metadata.gz: a7b40ae2a9930c6ee5831c6d5f64f84aeab383b4f35295a41faf8ae9e0735c82
+  data.tar.gz: 8bb7c192556ec28c904bd931abbf502c2533b39137c2d7d989469c11c61cd70d
 SHA512:
-  metadata.gz: 75bbc704971352293401dfcfaf0191aceb3d19ebfd150ce4db1aac0140b4044ee65942ff205484379a7169342298a7164fb76f1fbbf1907d3bb33d99485d1b03
-  data.tar.gz: 231a847015fcabfa0373693c0f13ac31d2ea2d636aae355b5ec023838efd3a15ae0b4baba0d7604f3c8980272419078268d155cd9d5b4ca7ca9e22f976667c62
+  metadata.gz: 671d913a895af97d0c37e45d21e930794317d60fac03bd46df3e43ef3dc6190617b5b5522f445f57143d96434104df636f5d29cf9c6c35d60604f61f54781dfa
+  data.tar.gz: eacef0ee6679653963d6b09a6c660c9ee503e8edc3df04411547f36e07bea91210d2683ff02ed1ee6d96924062c6e1620f95b87959e40ac80e78a211c7048f96

data/.rubocop.yml

@@ -58,6 +58,9 @@ RSpec/MultipleDescribes:
 RSpec/MultipleExpectations:
   Max: 10
 
+RSpec/MultipleMemoizedHelpers:
+  Max: 10
+
 RSpec/NestedGroups:
   Max: 5
 
@@ -101,4 +104,7 @@ Style/TrailingCommaInHashLiteral:
   EnforcedStyleForMultiline: consistent_comma
 
 Style/WordArray:
-  EnforcedStyle: brackets
+  EnforcedStyle: brackets
+
+Style/NumericPredicate:
+  Enabled: false

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 3.1.1 (2025-12-13)
+
+### Added
+
+- Better IDE support for callbacks DSL
+
+## 3.1.0 (2025-12-13)
+
+### Breaking changes
+
+- Enforce arguments and output types by default. Add `config.require_type = false` to your config to disable this behavior.
+
+### Added
+
+- `stop!` and `stopped?` methods for early exit (renamed from `done!` and `done?`)
+- `stop_immediately!` method for immediate execution halt within the current step
+- `done!` and `done?` are deprecated, but remain available as aliases for backward compatibility
+- Ruby LSP support with step navigation and indexing
+- Rubocop cops `StepMethodExists`, `ConditionMethodExists`, `DslOrder`, `MissingPrivateKeyword`, `NoDirectInstantiation`, `ArgumentTypeRequired`, `OutputTypeRequired`, `DeprecatedMethods`
+- Comprehensive YARD documentation
+
 ## 3.0.0 (2025-12-12)
 
 ### Breaking changes

data/CLAUDE.md

@@ -93,7 +93,7 @@ class ExampleService < Light::Services::Base
   end
 
   def cleanup
-    # Runs regardless of errors/warnings, unless done! was called
+    # Runs regardless of errors/warnings, unless stop! was called
   end
 
   def should_process?

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    light-services (3.0.0)
+    light-services (3.1.0)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -36,15 +36,15 @@ rails generate light_services:install
 ```ruby
 class GreetService < Light::Services::Base
   # Arguments
-  arg :name
-  arg :age
+  arg :name, type: String
+  arg :age, type: Integer
 
   # Steps
   step :build_message
   step :send_message
 
   # Outputs
-  output :message
+  output :message, type: String
 
   private
 
@@ -58,14 +58,14 @@ class GreetService < Light::Services::Base
 end
 ```
 
-## Advanced Example
+## Advanced Example (with dry-types and conditions)
 
 ```ruby
 class User::ResetPassword < Light::Services::Base
-  # Arguments
-  arg :user, type: User, optional: true
-  arg :email, type: String, optional: true
-  arg :send_email, type: [TrueClass, FalseClass], default: true
+  # Arguments with dry-types for advanced validation and coercion
+  arg :user, type: Types.Instance(User), optional: true
+  arg :email, type: Types::Coercible::String, optional: true
+  arg :send_email, type: Types::Params::Bool, default: true
 
   # Steps
   step :validate
@@ -74,9 +74,9 @@ class User::ResetPassword < Light::Services::Base
   step :save_reset_token
   step :send_reset_email, if: :send_email?
 
-  # Outputs
-  output :user, type: User
-  output :reset_token, type: String
+  # Outputs with dry-types
+  output :user, type: Types.Instance(User)
+  output :reset_token, type: Types::Strict::String
 
   private
 

data/docs/{readme.md → README.md}

@@ -13,6 +13,7 @@ Light Services is a simple yet powerful way to organize business logic in Ruby a
 - ⚠️ **Error Handling**: Collect errors from steps and handle them your way
 - 🔗 **Context**: Run multiple services sequentially within the same context
 - 🧪 **RSpec Matchers**: Built-in RSpec matchers for expressive service tests
+- 🔍 **RuboCop Integration**: Custom cops to enforce best practices at lint time
 - 🌐 **Framework Agnostic**: Compatible with Rails, Hanami, or any Ruby framework
 - 🧩 **Modularity**: Isolate and test your services with ease
 - ✅ **100% Test Coverage**: Thoroughly tested and reliable
@@ -23,15 +24,15 @@ Light Services is a simple yet powerful way to organize business logic in Ruby a
 ```ruby
 class GreetService < Light::Services::Base
   # Arguments
-  arg :name
-  arg :age
+  arg :name, type: String
+  arg :age, type: Integer
 
   # Steps
   step :build_message
   step :send_message
 
   # Outputs
-  output :message
+  output :message, type: String
 
   private
 
@@ -45,14 +46,14 @@ class GreetService < Light::Services::Base
 end
 ```
 
-## Advanced Example
+## Advanced Example (with dry-types and conditions)
 
 ```ruby
 class User::ResetPassword < Light::Services::Base
-  # Arguments
-  arg :user, type: User, optional: true
-  arg :email, type: String, optional: true
-  arg :send_email, type: [TrueClass, FalseClass], default: true
+  # Arguments with dry-types for advanced validation and coercion
+  arg :user, type: Types.Instance(User), optional: true
+  arg :email, type: Types::Coercible::String, optional: true
+  arg :send_email, type: Types::Params::Bool, default: true
 
   # Steps
   step :validate
@@ -61,9 +62,9 @@ class User::ResetPassword < Light::Services::Base
   step :save_reset_token
   step :send_reset_email, if: :send_email?
 
-  # Outputs
-  output :user, type: User
-  output :reset_token, type: String
+  # Outputs with dry-types
+  output :user, type: Types.Instance(User)
+  output :reset_token, type: Types::Strict::String
 
   private
 

data/docs/{summary.md → SUMMARY.md}

@@ -1,8 +1,13 @@
-# Table of contents
+# Summary​
+
+## Introduction
 
 * [Light Services](README.md)
 * [Quickstart](quickstart.md)
 * [Concepts](concepts.md)
+
+## Deep Dive
+
 * [Arguments](arguments.md)
 * [Steps](steps.md)
 * [Outputs](outputs.md)
@@ -12,6 +17,11 @@
 * [Configuration](configuration.md)
 * [Testing](testing.md)
 * [Rails Generators](generators.md)
+* [RuboCop Integration](rubocop.md)
+* [Ruby LSP Integration](ruby-lsp.md)
+
+## Examples
+
 * [Best Practices](best-practices.md)
 * [Recipes](recipes.md)
   * [CRUD](crud.md)

data/docs/arguments.md

@@ -55,6 +55,29 @@ class HappyBirthdayService < ApplicationService
 end
 ```
 
+### Type Enforcement (Enabled by Default)
+
+By default, all arguments must have a `type` option. This helps catch type-related bugs early and makes your services self-documenting.
+
+```ruby
+class MyService < ApplicationService
+  arg :name, type: String  # ✓ Valid
+  arg :age                 # ✗ Raises MissingTypeError
+end
+```
+
+To disable type enforcement for a specific service:
+
+```ruby
+class LegacyService < ApplicationService
+  config require_type: false
+  
+  arg :name              # Allowed when require_type is disabled
+end
+```
+
+See the [Configuration documentation](configuration.md) for more details.
+
 ### dry-types Support
 
 Light Services supports [dry-types](https://dry-rb.org/gems/dry-types) for advanced type validation and coercion. When using dry-types, values are automatically coerced to the expected type.

data/docs/concepts.md

@@ -7,39 +7,39 @@ This section covers the core concepts of Light Services: **Arguments**, **Steps*
 When you call `MyService.run(args)`, the following happens:
 
 ```
-┌─────────────────────────────────────────────────────────────┐
+┌──────────────────────────────────────────────────────────────┐
 │                      Service.run(args)                       │
-├─────────────────────────────────────────────────────────────┤
+├──────────────────────────────────────────────────────────────┤
 │  1. Load default values for arguments and outputs            │
 │  2. Validate argument types                                  │
 │  3. Run before_service_run callbacks                         │
-├─────────────────────────────────────────────────────────────┤
+├──────────────────────────────────────────────────────────────┤
 │  4. Begin around_service_run callback                        │
 │  5. Begin database transaction (if use_transactions: true)   │
-│     ┌─────────────────────────────────────────────────────┐ │
-│     │  6. Execute steps in order                          │ │
-│     │     - Run before_step_run / around_step_run         │ │
-│     │     - Execute step method                           │ │
-│     │     - Run after_step_run / on_step_success          │ │
-│     │     - Skip if condition (if:/unless:) not met       │ │
-│     │     - Stop if errors.break? is true                 │ │
-│     │     - Stop if done! was called                      │ │
-│     ├─────────────────────────────────────────────────────┤ │
-│     │  7. On error → Rollback transaction                 │ │
-│     │     On success → Commit transaction                 │ │
-│     └─────────────────────────────────────────────────────┘ │
+│     ┌─────────────────────────────────────────────────────┐  │
+│     │  6. Execute steps in order                          │  │
+│     │     - Run before_step_run / around_step_run         │  │
+│     │     - Execute step method                           │  │
+│     │     - Run after_step_run / on_step_success          │  │
+│     │     - Skip if condition (if:/unless:) not met       │  │
+│     │     - Stop if errors.break? is true                 │  │
+│     │     - Stop if stop! was called                      │  │
+│     ├─────────────────────────────────────────────────────┤  │
+│     │  7. On error → Rollback transaction                 │  │
+│     │     On success → Commit transaction                 │  │
+│     └─────────────────────────────────────────────────────┘  │
 │  8. End around_service_run callback                          │
-├─────────────────────────────────────────────────────────────┤
-│  9. Run steps marked with always: true (unless done! called) │
+├──────────────────────────────────────────────────────────────┤
+│  9. Run steps marked with always: true (unless stop! called) │
 │ 10. Validate output types (if success)                       │
 │ 11. Copy errors/warnings to parent service (if in context)   │
 │ 12. Run after_service_run callback                           │
 │ 13. Run on_service_success or on_service_failure callback    │
-├─────────────────────────────────────────────────────────────┤
+├──────────────────────────────────────────────────────────────┤
 │ 14. Return service instance                                  │
 │     - service.success? / service.failed?                     │
 │     - service.outputs / service.errors                       │
-└─────────────────────────────────────────────────────────────┘
+└──────────────────────────────────────────────────────────────┘
 ```
 
 ## Arguments

data/docs/configuration.md

@@ -8,6 +8,9 @@ Configure Light Services globally using an initializer. For Rails applications,
 
 ```ruby
 Light::Services.configure do |config|
+# Type enforcement
+  config.require_type = true            # Require type option for all arguments and outputs
+
   # Transaction settings
   config.use_transactions = true        # Wrap each service in a database transaction
 
@@ -29,6 +32,7 @@ end
 
 | Option | Default | Description |
 |--------|---------|-------------|
+| `require_type` | `true` | Raises `Light::Services::MissingTypeError` when defining arguments or outputs without a `type` option |
 | `use_transactions` | `true` | Wraps service execution in `ActiveRecord::Base.transaction` |
 | `load_errors` | `true` | Propagates errors to parent service when using `.with(self)` |
 | `break_on_error` | `true` | Stops executing remaining steps when an error is added |
@@ -138,6 +142,38 @@ class BackgroundTaskService < ApplicationService
 end
 ```
 
+### Type Enforcement (Enabled by Default)
+
+By default, all arguments and outputs must have a `type` option. This helps catch type-related bugs early and makes your services self-documenting.
+
+```ruby
+class User::Create < ApplicationService
+  arg :name, type: String        # ✓ Valid
+  arg :email                     # ✗ Raises MissingTypeError
+  output :user, type: User       # ✓ Valid
+  output :token                  # ✗ Raises MissingTypeError
+end
+```
+
+To disable type enforcement globally (not recommended):
+
+```ruby
+Light::Services.configure do |config|
+  config.require_type = false
+end
+```
+
+Or disable for specific services:
+
+```ruby
+class LegacyService < ApplicationService
+  config require_type: false
+  
+  arg :data              # Allowed when require_type is disabled
+  output :result         # Allowed when require_type is disabled
+end
+```
+
 ## Disabling Transactions
 
 If you're not using ActiveRecord or want to manage transactions yourself:

data/docs/errors.md

@@ -201,10 +201,40 @@ Light Services defines several exception classes for different error scenarios:
 | Exception | Description |
 |-----------|-------------|
 | `Light::Services::Error` | Base exception class for all Light Services errors |
-| `Light::Services::ArgTypeError` | Raised when an argument type validation fails |
+| `Light::Services::ArgTypeError` | Raised when an argument or output type validation fails |
 | `Light::Services::ReservedNameError` | Raised when using a reserved name for arguments, outputs, or steps |
 | `Light::Services::InvalidNameError` | Raised when using an invalid name format |
 | `Light::Services::NoStepsError` | Raised when a service has no steps defined and no `run` method |
+| `Light::Services::MissingTypeError` | Raised when defining an argument or output without a `type` option when `require_type` is enabled |
+
+### MissingTypeError
+
+This exception is raised when you define an argument or output without a `type` option. Since `require_type` is enabled by default, all arguments and outputs must have a type.
+
+```ruby
+class MyService < ApplicationService
+  arg :name  # => raises Light::Services::MissingTypeError
+end
+```
+
+To fix this, add a `type` option to all arguments and outputs:
+
+```ruby
+class MyService < ApplicationService
+  arg :name, type: String
+  output :result, type: Hash
+end
+```
+
+If you need to disable type enforcement for legacy services, you can use the `config` method:
+
+```ruby
+class LegacyService < ApplicationService
+  config require_type: false
+  
+  arg :data              # Allowed when require_type is disabled
+end
+```
 
 ### NoStepsError
 

data/docs/outputs.md

@@ -78,6 +78,29 @@ class AI::Chat < ApplicationService
 end
 ```
 
+### Type Enforcement (Enabled by Default)
+
+By default, all outputs must have a `type` option. This helps catch type-related bugs early and makes your services self-documenting.
+
+```ruby
+class MyService < ApplicationService
+  output :result, type: Hash  # ✓ Valid
+  output :data                # ✗ Raises MissingTypeError
+end
+```
+
+To disable type enforcement for a specific service:
+
+```ruby
+class LegacyService < ApplicationService
+  config require_type: false
+  
+  output :data             # Allowed when require_type is disabled
+end
+```
+
+See the [Configuration documentation](configuration.md) for more details.
+
 ### dry-types Support
 
 Outputs also support [dry-types](https://dry-rb.org/gems/dry-types) for advanced type validation and coercion.

data/docs/quickstart.md

@@ -74,7 +74,7 @@ class GreetService < ApplicationService
   step :greet
 
   # Outputs
-  output :greeted, default: false
+  output :greeted, type: [TrueClass, FalseClass], default: false
 
   private