light-services 3.0.0 → 3.1.1

data/docs/rubocop.md

@@ -0,0 +1,285 @@
+# RuboCop Integration
+
+Light Services provides custom RuboCop cops to help enforce best practices in your service definitions.
+
+## Setup
+
+Add this to your `.rubocop.yml`:
+
+```yaml
+require:
+  - light/services/rubocop
+```
+
+## Available Cops
+
+### LightServices/ArgumentTypeRequired
+
+Ensures all `arg` declarations include a `type:` option.
+
+```ruby
+# bad
+arg :user_id
+arg :params, default: {}
+
+# good
+arg :user_id, type: Integer
+arg :params, type: Hash, default: {}
+```
+
+### LightServices/OutputTypeRequired
+
+Ensures all `output` declarations include a `type:` option.
+
+```ruby
+# bad
+output :result
+output :data, optional: true
+
+# good
+output :result, type: Hash
+output :data, type: Hash, optional: true
+```
+
+### LightServices/StepMethodExists
+
+Ensures all `step` declarations have a corresponding method defined.
+
+```ruby
+# bad
+class MyService < ApplicationService
+  step :validate
+  step :process  # missing method
+
+  private
+
+  def validate; end
+end
+
+# good
+class MyService < ApplicationService
+  step :validate
+  step :process
+
+  private
+
+  def validate; end
+  def process; end
+end
+```
+
+**Configuration:** Use `ExcludedSteps` for inherited steps:
+
+```yaml
+LightServices/StepMethodExists:
+  ExcludedSteps:
+    - initialize_entity
+    - assign_attributes
+```
+
+### LightServices/ConditionMethodExists
+
+Ensures symbol conditions (`:if`, `:unless`) have corresponding methods defined.
+
+This cop automatically recognizes predicate methods generated by `arg` and `output` declarations (e.g., `arg :user` creates `user?`).
+
+```ruby
+# bad
+class MyService < ApplicationService
+  step :notify, if: :should_notify?  # missing method
+
+  private
+
+  def notify; end
+end
+
+# good - explicit method
+class MyService < ApplicationService
+  step :notify, if: :should_notify?
+
+  private
+
+  def notify; end
+  def should_notify?; true; end
+end
+
+# good - predicate from arg/output
+class MyService < ApplicationService
+  arg :user, type: User, optional: true
+
+  step :greet, if: :user?  # user? is auto-generated
+
+  private
+
+  def greet; end
+end
+```
+
+**Configuration:** Use `ExcludedMethods` for inherited condition methods:
+
+```yaml
+LightServices/ConditionMethodExists:
+  ExcludedMethods:
+    - admin?
+    - guest?
+```
+
+### LightServices/DslOrder
+
+Enforces consistent ordering of DSL declarations: `config` → `arg` → `step` → `output`
+
+```ruby
+# bad
+class MyService < ApplicationService
+  step :process
+  arg :name, type: String
+  config raise_on_error: true
+end
+
+# good
+class MyService < ApplicationService
+  config raise_on_error: true
+
+  arg :name, type: String
+
+  step :process
+
+  output :result, type: Hash
+end
+```
+
+### LightServices/MissingPrivateKeyword
+
+Ensures step methods are defined as private.
+
+```ruby
+# bad
+class MyService < ApplicationService
+  step :process
+
+  def process  # should be private
+    # implementation
+  end
+end
+
+# good
+class MyService < ApplicationService
+  step :process
+
+  private
+
+  def process
+    # implementation
+  end
+end
+```
+
+### LightServices/NoDirectInstantiation
+
+Prevents direct instantiation of service classes with `.new`.
+
+```ruby
+# bad
+UserService.new(name: "John")
+
+# good
+UserService.run(name: "John")
+UserService.run!(name: "John")
+UserService.call(name: "John")
+```
+
+**Configuration:** Customize the pattern for service class detection:
+
+```yaml
+LightServices/NoDirectInstantiation:
+  ServicePattern: 'Service$'  # default: matches classes ending with "Service"
+```
+
+### LightServices/DeprecatedMethods
+
+Detects deprecated `done!` and `done?` method calls and suggests using `stop!` and `stopped?` instead. Includes autocorrection.
+
+```ruby
+# bad
+class MyService < ApplicationService
+  step :process
+
+  private
+
+  def process
+    done! if condition_met?
+    return if done?
+  end
+end
+
+# good
+class MyService < ApplicationService
+  step :process
+
+  private
+
+  def process
+    stop! if condition_met?
+    return if stopped?
+  end
+end
+```
+
+**Configuration:** Customize the pattern for service class detection:
+
+```yaml
+LightServices/DeprecatedMethods:
+  ServicePattern: 'Service$'  # default: matches classes ending with "Service"
+```
+
+## Configuration
+
+Full configuration example:
+
+```yaml
+require:
+  - light/services/rubocop
+
+LightServices/ArgumentTypeRequired:
+  Enabled: true
+
+LightServices/OutputTypeRequired:
+  Enabled: true
+
+LightServices/StepMethodExists:
+  Enabled: true
+  ExcludedSteps: []
+
+LightServices/ConditionMethodExists:
+  Enabled: true
+  ExcludedMethods: []
+
+LightServices/DslOrder:
+  Enabled: true
+
+LightServices/MissingPrivateKeyword:
+  Enabled: true
+
+LightServices/NoDirectInstantiation:
+  Enabled: true
+  ServicePattern: 'Service$'
+
+LightServices/DeprecatedMethods:
+  Enabled: true
+  ServicePattern: 'Service$'
+```
+
+To disable a cop for specific files:
+
+```yaml
+LightServices/ArgumentTypeRequired:
+  Exclude:
+    - 'spec/**/*'
+    - 'test/**/*'
+```
+
+## What's Next?
+
+Learn more about testing your services:
+
+[Next: Testing](testing.md)

data/docs/ruby-lsp.md

@@ -0,0 +1,133 @@
+# Ruby LSP Integration
+
+Light Services provides a Ruby LSP add-on that enhances your editor experience by informing the language server about methods generated by the `arg` and `output` DSL keywords.
+
+## Features
+
+When you use the `arg` or `output` keywords, Light Services dynamically generates methods at runtime:
+
+```ruby
+class MyService < ApplicationService
+  arg :user, type: User
+  output :result, type: Hash
+end
+```
+
+This generates the following methods:
+- `user` - getter method (returns `User`)
+- `user?` - predicate method (returns boolean)
+- `user=` - setter method (private, accepts `User`)
+- `result` - getter method (returns `Hash`)
+- `result?` - predicate method (returns boolean)
+- `result=` - setter method (private, accepts `Hash`)
+
+The Ruby LSP add-on teaches the language server about these generated methods, enabling:
+
+- **Go to Definition** - Navigate to the `arg`/`output` declaration
+- **Completion** - Autocomplete generated method names
+- **Hover** - See information about generated methods, including return types
+- **Signature Help** - Get parameter hints for setter methods
+- **Workspace Symbol** - Find generated methods in symbol search
+
+## Setup
+
+The add-on is automatically discovered by Ruby LSP when Light Services is in your project's dependencies. No additional configuration is required.
+
+### Requirements
+
+- Ruby LSP `~> 0.26` or later
+- Light Services gem installed in your project
+
+### Verification
+
+To verify the add-on is loaded, check the Ruby LSP output in your editor. You should see "Ruby LSP Light Services" listed among the active add-ons.
+
+## How It Works
+
+The add-on uses Ruby LSP's **indexing enhancement** system to register generated methods during code indexing. When the indexer encounters an `arg` or `output` call with a symbol argument, it automatically registers the three generated methods (getter, predicate, setter) in the index.
+
+This is a static analysis approach - the add-on analyzes your source code without executing it. This means:
+
+- Methods are recognized immediately as you type
+- No running application is required
+- Works with any editor that supports Ruby LSP
+
+## Type Inference
+
+The add-on extracts type information from the `type:` option and includes it as YARD-style documentation comments. This enables hover information to display return types for generated methods.
+
+### Simple Ruby Types
+
+```ruby
+arg :user, type: User      # → User
+arg :items, type: Array    # → Array
+arg :name, type: String    # → String
+```
+
+### Namespaced Types
+
+```ruby
+arg :payment, type: Stripe::Charge      # → Stripe::Charge
+arg :config, type: MyApp::Configuration # → MyApp::Configuration
+```
+
+### Dry-Types
+
+Common dry-types are mapped to their underlying Ruby types:
+
+| Dry-Type | Ruby Type |
+|----------|-----------|
+| `Types::String`, `Types::Strict::String`, `Types::Coercible::String` | `String` |
+| `Types::Integer`, `Types::Strict::Integer`, `Types::Coercible::Integer` | `Integer` |
+| `Types::Float`, `Types::Strict::Float`, `Types::Coercible::Float` | `Float` |
+| `Types::Bool`, `Types::Strict::Bool` | `TrueClass \| FalseClass` |
+| `Types::Array`, `Types::Strict::Array` | `Array` |
+| `Types::Hash`, `Types::Strict::Hash` | `Hash` |
+| `Types::Symbol`, `Types::Strict::Symbol` | `Symbol` |
+| `Types::Date`, `Types::DateTime`, `Types::Time` | `Date`, `DateTime`, `Time` |
+
+Constrained and parameterized types extract their base type:
+
+```ruby
+arg :email, type: Types::String.constrained(format: /@/)  # → String
+arg :tags, type: Types::Array.of(Types::String)           # → Array
+arg :status, type: Types::String.enum("active", "pending") # → String
+```
+
+### Custom Type Mappings
+
+You can add custom type mappings through the Light Services configuration:
+
+```ruby
+# config/initializers/light_services.rb
+Light::Services.configure do |config|
+  config.ruby_lsp_type_mappings = {
+    "Types::UUID" => "String",
+    "Types::Money" => "BigDecimal",
+    "Types::JSON" => "Hash",
+    "CustomTypes::Email" => "String",
+    "MyApp::Types::PhoneNumber" => "String",
+  }
+end
+```
+
+Custom mappings take precedence over the default dry-types mappings, allowing you to:
+
+- Add mappings for your own custom types
+- Override default mappings if needed
+- Support domain-specific type modules
+
+## Limitations
+
+- Only `arg` and `output` declarations with a symbol as the first argument are recognized
+- The add-on cannot detect dynamically computed argument names (e.g., `arg some_variable`)
+- Inherited arguments/outputs from parent classes are not automatically discovered
+- Parameterized dry-types like `Types::Array.of(Types::String)` resolve to the container type (`Array`), not the full generic type
+- Custom dry-type definitions outside the standard `Types::` namespace are not mapped
+
+## What's Next?
+
+Learn more about other integrations:
+
+- [RuboCop Integration](rubocop.md) - Static analysis cops for services
+- [Testing](testing.md) - Testing your services with RSpec matchers

data/docs/steps.md

@@ -187,9 +187,9 @@ class ParsePage < ApplicationService
 end
 ```
 
-## Early Exit with `done!`
+## Early Exit with `stop!`
 
-Use `done!` to stop executing remaining steps without adding an error. This is useful when you've completed the service's goal early and don't need to run subsequent steps.
+Use `stop!` to stop executing remaining steps without adding an error. This is useful when you've completed the service's goal early and don't need to run subsequent steps.
 
 ```ruby
 class User::FindOrCreate < ApplicationService
@@ -205,7 +205,7 @@ class User::FindOrCreate < ApplicationService
 
   def find_existing_user
     self.user = User.find_by(email:)
-    done! if user # Skip remaining steps if user already exists
+    stop! if user # Skip remaining steps if user already exists
   end
 
   def create_user
@@ -219,23 +219,77 @@ class User::FindOrCreate < ApplicationService
 end
 ```
 
-You can check if `done!` was called using `done?`:
+You can check if `stop!` was called using `stopped?`:
 
 ```ruby
 def some_step
-  done!
+  stop!
   
   # This code still runs within the same step
-  puts "Done? #{done?}" # => "Done? true"
+  puts "Stopped? #{stopped?}" # => "Stopped? true"
 end
 
 def next_step
-  # This step will NOT run because done! was called
+  # This step will NOT run because stop! was called
 end
 ```
 
 {% hint style="info" %}
-`done!` stops subsequent steps from running, including steps marked with `always: true`. Code after `done!` within the same step method will still execute.
+`stop!` stops subsequent steps from running, including steps marked with `always: true`. Code after `stop!` within the same step method will still execute.
+{% endhint %}
+
+{% hint style="success" %}
+**Database Transactions:** Calling `stop!` does NOT rollback database transactions. All database changes made before `stop!` was called will be committed.
+{% endhint %}
+
+{% hint style="info" %}
+**Backward Compatibility:** `done!` and `done?` are still available as aliases for `stop!` and `stopped?`.
+{% endhint %}
+
+## Immediate Exit with `stop_immediately!`
+
+Use `stop_immediately!` when you need to halt execution immediately, even within the current step. Unlike `stop!`, code after `stop_immediately!` in the same step method will NOT execute.
+
+```ruby
+class Payment::Process < ApplicationService
+  arg :amount, type: Integer
+  arg :card_token, type: String
+
+  step :validate_card
+  step :charge_card
+  step :send_receipt
+
+  output :transaction_id, type: String
+
+  private
+
+  def validate_card
+    unless valid_card?(card_token)
+      errors.add(:card, "is invalid")
+      stop_immediately! # Exit immediately - don't run any more code
+    end
+    
+    # This code won't run if card is invalid
+    log_validation_success
+  end
+
+  def charge_card
+    # This step won't run if stop_immediately! was called
+    self.transaction_id = PaymentGateway.charge(amount, card_token)
+  end
+
+  def send_receipt
+    Mailer.receipt(transaction_id).deliver_later
+  end
+end
+```
+
+{% hint style="warning" %}
+`stop_immediately!` raises an internal exception to halt execution. Steps marked with `always: true` will NOT run when `stop_immediately!` is called.
+{% endhint %}
+
+{% hint style="success" %}
+**Database Transactions:** Calling `stop_immediately!` does NOT rollback database transactions. All database changes made before `stop_immediately!` was called will be committed.
 {% endhint %}
 
 ## Removing Inherited Steps

data/docs/testing.md

@@ -175,7 +175,7 @@ RSpec.describe User::Register do
 end
 ```
 
-## Testing Early Exit with done!
+## Testing Early Exit with stop!
 
 ```ruby
 RSpec.describe User::FindOrCreate do

data/lib/light/services/base.rb

@@ -21,7 +21,29 @@ require "light/services/concerns/parent_service"
 # Base class for all service objects
 module Light
   module Services
+    # Base class for building service objects with arguments, outputs, and steps.
+    #
+    # @example Basic service
+    #   class CreateUser < Light::Services::Base
+    #     arg :name, type: String
+    #     arg :email, type: String
+    #
+    #     output :user, type: User
+    #
+    #     step :create_user
+    #
+    #     private
+    #
+    #     def create_user
+    #       self.user = User.create!(name: name, email: email)
+    #     end
+    #   end
+    #
+    #   result = CreateUser.run(name: "John", email: "john@example.com")
+    #   result.success? # => true
+    #   result.user     # => #<User id: 1, name: "John">
     class Base
+      extend CallbackDsl
       include Callbacks
       include Dsl::ArgumentsDsl
       include Dsl::OutputsDsl
@@ -30,9 +52,23 @@ module Light
       include Concerns::StateManagement
       include Concerns::ParentService
 
-      # Getters
-      attr_reader :outputs, :arguments, :errors, :warnings
+      # @return [Collection::Base] collection of output values
+      attr_reader :outputs
 
+      # @return [Collection::Base] collection of argument values
+      attr_reader :arguments
+
+      # @return [Messages] collection of error messages
+      attr_reader :errors
+
+      # @return [Messages] collection of warning messages
+      attr_reader :warnings
+
+      # Initialize a new service instance.
+      #
+      # @param args [Hash] arguments to pass to the service
+      # @param config [Hash] runtime configuration overrides
+      # @param parent_service [Base, nil] parent service for nested calls
       def initialize(args = {}, config = {}, parent_service = nil)
         @config = Light::Services.config.merge(self.class.class_config || {}).merge(config)
         @parent_service = parent_service
@@ -40,37 +76,70 @@ module Light
         @outputs = Collection::Base.new(self, CollectionTypes::OUTPUTS)
         @arguments = Collection::Base.new(self, CollectionTypes::ARGUMENTS, args.dup)
 
-        @done = false
+        @stopped = false
         @launched_steps = []
 
         initialize_errors
         initialize_warnings
       end
 
+      # Check if the service completed without errors.
+      #
+      # @return [Boolean] true if no errors were added
       def success?
         !errors?
       end
 
+      # Check if the service completed with errors.
+      #
+      # @return [Boolean] true if any errors were added
       def failed?
         errors?
       end
 
+      # Check if the service has any errors.
+      #
+      # @return [Boolean] true if errors collection is not empty
       def errors?
         @errors.any?
       end
 
+      # Check if the service has any warnings.
+      #
+      # @return [Boolean] true if warnings collection is not empty
       def warnings?
         @warnings.any?
       end
 
-      def done!
-        @done = true
+      # Stop executing remaining steps after the current step completes.
+      #
+      # @return [Boolean] true
+      def stop!
+        @stopped = true
       end
+      alias done! stop!
 
-      def done?
-        @done
+      # Check if the service has been stopped.
+      #
+      # @return [Boolean] true if stop! was called
+      def stopped?
+        @stopped
+      end
+      alias done? stopped?
+
+      # Stop execution immediately, skipping any remaining code in the current step.
+      #
+      # @raise [StopExecution] always raises to halt execution
+      # @return [void]
+      def stop_immediately!
+        @stopped = true
+        raise Light::Services::StopExecution
       end
 
+      # Execute the service steps.
+      #
+      # @return [void]
+      # @raise [StandardError] re-raises any exception after running always steps
       def call
         load_defaults_and_validate
 
@@ -87,20 +156,54 @@ module Light
       end
 
       class << self
+        # @return [Hash, nil] class-level configuration options
         attr_accessor :class_config
 
+        # Set class-level configuration for this service.
+        #
+        # @param config [Hash] configuration options
+        # @return [Hash] the configuration hash
         def config(config = {})
           self.class_config = config
         end
 
+        # Run the service and return the result.
+        #
+        # @param args [Hash] arguments to pass to the service
+        # @param config [Hash] runtime configuration overrides
+        # @return [Base] the executed service instance
+        #
+        # @example
+        #   result = MyService.run(name: "test")
+        #   result.success? # => true
         def run(args = {}, config = {})
           new(args, config).tap(&:call)
         end
 
+        # Run the service and raise an error if it fails.
+        #
+        # @param args [Hash] arguments to pass to the service
+        # @param config [Hash] runtime configuration overrides
+        # @return [Base] the executed service instance
+        # @raise [Error] if the service fails
+        #
+        # @example
+        #   MyService.run!(name: "test") # raises if service fails
         def run!(args = {}, config = {})
           run(args, config.merge(raise_on_error: true))
         end
 
+        # Create a context for running the service with a parent service or config.
+        #
+        # @param service_or_config [Base, Hash] parent service or configuration hash
+        # @param config [Hash] configuration hash (when first param is a service)
+        # @return [BaseWithContext] context wrapper for running the service
+        #
+        # @example With parent service
+        #   ChildService.with(self).run(data: value)
+        #
+        # @example With configuration
+        #   MyService.with(use_transactions: false).run(name: "test")
         def with(service_or_config = {}, config = {})
           service = service_or_config.is_a?(Hash) ? nil : service_or_config
           config = service_or_config unless service