light-services 3.0.0 → 3.1.0

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/summary.md

@@ -12,6 +12,8 @@
 * [Configuration](configuration.md)
 * [Testing](testing.md)
 * [Rails Generators](generators.md)
+* [RuboCop Integration](rubocop.md)
+* [Ruby LSP Integration](ruby-lsp.md)
 * [Best Practices](best-practices.md)
 * [Recipes](recipes.md)
   * [CRUD](crud.md)

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,6 +21,27 @@ 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
       include Callbacks
       include Dsl::ArgumentsDsl
@@ -30,9 +51,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 +75,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 +155,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

data/lib/light/services/base_with_context.rb

@@ -1,9 +1,22 @@
 # frozen_string_literal: true
 
-# This class allows running a service object with context (parent class and custom config)
 module Light
   module Services
+    # Wrapper for running a service with a parent context or custom configuration.
+    # Created via {Base.with} method.
+    #
+    # @example Running with parent service context
+    #   ChildService.with(self).run(data: value)
+    #
+    # @example Running with custom configuration
+    #   MyService.with(use_transactions: false).run(name: "test")
     class BaseWithContext
+      # Initialize a new context wrapper.
+      #
+      # @param service_class [Class] the service class to run
+      # @param parent_service [Base, nil] parent service for error/warning propagation
+      # @param config [Hash] configuration overrides
+      # @raise [ArgTypeError] if parent_service is not a Base subclass
       def initialize(service_class, parent_service, config)
         @service_class = service_class
         @config = config
@@ -14,10 +27,19 @@ module Light
         raise Light::Services::ArgTypeError, "#{parent_service.class} - must be a subclass of Light::Services::Base"
       end
 
+      # Run the service with the configured context.
+      #
+      # @param args [Hash] arguments to pass to the service
+      # @return [Base] the executed service instance
       def run(args = {})
         @service_class.new(extend_arguments(args), @config, @parent_service).tap(&:call)
       end
 
+      # Run the service and raise an error if it fails.
+      #
+      # @param args [Hash] arguments to pass to the service
+      # @return [Base] the executed service instance
+      # @raise [Error] if the service fails
       def run!(args = {})
         @config[:raise_on_error] = true
         run(args)

data/lib/light/services/callbacks.rb

@@ -2,7 +2,38 @@
 
 module Light
   module Services
+    # Provides callback hooks for service and step lifecycle events.
+    #
+    # @example Service-level callbacks
+    #   class MyService < Light::Services::Base
+    #     before_service_run :log_start
+    #     after_service_run { |service| Rails.logger.info("Done!") }
+    #     on_service_success :send_notification
+    #     on_service_failure :log_error
+    #   end
+    #
+    # @example Step-level callbacks
+    #   class MyService < Light::Services::Base
+    #     before_step_run :log_step_start
+    #     after_step_run { |service, step_name| puts "Finished #{step_name}" }
+    #     on_step_failure :handle_step_error
+    #   end
+    #
+    # @example Around callbacks
+    #   class MyService < Light::Services::Base
+    #     around_service_run :with_timing
+    #
+    #     private
+    #
+    #     def with_timing(service)
+    #       start = Time.now
+    #       yield
+    #       puts "Took #{Time.now - start}s"
+    #     end
+    #   end
     module Callbacks
+      # Available callback events.
+      # @return [Array<Symbol>] list of callback event names
       EVENTS = [
         :before_step_run,
         :after_step_run,
@@ -21,6 +52,20 @@ module Light
         base.extend(ClassMethods)
       end
 
+      # Class methods for registering callbacks.
+      #
+      # Each callback event has a corresponding class method:
+      # - {before_step_run} - before each step executes
+      # - {after_step_run} - after each step executes
+      # - {around_step_run} - wraps step execution (must yield)
+      # - {on_step_success} - when a step completes without adding errors
+      # - {on_step_failure} - when a step adds errors
+      # - {on_step_crash} - when a step raises an exception
+      # - {before_service_run} - before the service starts
+      # - {after_service_run} - after the service completes
+      # - {around_service_run} - wraps service execution (must yield)
+      # - {on_service_success} - when service completes without errors
+      # - {on_service_failure} - when service completes with errors
       module ClassMethods
         # Define DSL methods for each callback event
         EVENTS.each do |event|
@@ -37,13 +82,19 @@ module Light
           end
         end
 
-        # Get all callbacks for a specific event (including inherited ones)
+        # Get callbacks defined in this class for a specific event.
+        #
+        # @param event [Symbol] the callback event name
+        # @return [Array<Symbol, Proc>] callbacks for this event
         def callbacks_for(event)
           @callbacks ||= {}
           @callbacks[event] ||= []
         end
 
-        # Get all callbacks including inherited ones
+        # Get all callbacks for an event including inherited ones.
+        #
+        # @param event [Symbol] the callback event name
+        # @return [Array<Symbol, Proc>] all callbacks for this event
         def all_callbacks_for(event)
           if superclass.respond_to?(:all_callbacks_for)
             inherited = superclass.all_callbacks_for(event)
@@ -55,9 +106,12 @@ module Light
         end
       end
 
-      # Run callbacks for a given event
-      # For around callbacks, yields to the block
-      # For other callbacks, just executes them in order
+      # Run all callbacks for a given event.
+      #
+      # @param event [Symbol] the callback event name
+      # @param args [Array] arguments to pass to callbacks
+      # @yield for around callbacks, the block to wrap
+      # @return [void]
       def run_callbacks(event, *args, &block)
         callbacks = self.class.all_callbacks_for(event)
 

data/lib/light/services/collection.rb

@@ -2,15 +2,34 @@
 
 require_relative "constants"
 
-# Collection to store arguments and outputs values
 module Light
   module Services
+    # Collection module for storing argument and output values.
     module Collection
+      # Storage for service arguments or outputs with type validation.
+      #
+      # @example Accessing values
+      #   service.arguments[:name]  # => "John"
+      #   service.outputs[:user]    # => #<User id: 1>
       class Base
         extend Forwardable
 
+        # @!method key?(key)
+        #   Check if a key exists in the collection.
+        #   @param key [Symbol] the key to check
+        #   @return [Boolean] true if key exists
+
+        # @!method to_h
+        #   Convert collection to a hash.
+        #   @return [Hash] the stored values
         def_delegators :@storage, :key?, :to_h
 
+        # Initialize a new collection.
+        #
+        # @param instance [Base] the service instance
+        # @param collection_type [String] "arguments" or "outputs"
+        # @param storage [Hash] initial values
+        # @raise [ArgTypeError] if storage is not a Hash
         def initialize(instance, collection_type, storage = {})
           validate_collection_type!(collection_type)
 
@@ -23,22 +42,43 @@ module Light
           raise Light::Services::ArgTypeError, "#{instance.class} - #{collection_type} must be a Hash"
         end
 
+        # Set a value in the collection.
+        #
+        # @param key [Symbol] the key to set
+        # @param value [Object] the value to store
+        # @return [Object] the stored value
         def set(key, value)
           @storage[key] = value
         end
 
+        # Get a value from the collection.
+        #
+        # @param key [Symbol] the key to retrieve
+        # @return [Object, nil] the stored value or nil
         def get(key)
           @storage[key]
         end
 
+        # Get a value using bracket notation.
+        #
+        # @param key [Symbol] the key to retrieve
+        # @return [Object, nil] the stored value or nil
         def [](key)
           get(key)
         end
 
+        # Set a value using bracket notation.
+        #
+        # @param key [Symbol] the key to set
+        # @param value [Object] the value to store
+        # @return [Object] the stored value
         def []=(key, value)
           set(key, value)
         end
 
+        # Load default values for fields that haven't been set.
+        #
+        # @return [void]
         def load_defaults
           settings_collection.each do |name, settings|
             next if !settings.default_exists || key?(name)
@@ -51,6 +91,10 @@ module Light
           end
         end
 
+        # Validate all values against their type definitions.
+        #
+        # @return [void]
+        # @raise [ArgTypeError] if a value fails type validation
         def validate!
           settings_collection.each do |name, field|
             next if field.optional && (!key?(name) || get(name).nil?)
@@ -62,7 +106,11 @@ module Light
           end
         end
 
-        # Extend args with context values (only for arguments)
+        # Extend arguments hash with context values from this collection.
+        # Only applies to arguments collections.
+        #
+        # @param args [Hash] arguments hash to extend
+        # @return [Hash] the extended arguments hash
         def extend_with_context(args)
           return args unless @collection_type == CollectionTypes::ARGUMENTS
 

data/lib/light/services/concerns/execution.rb

@@ -40,6 +40,9 @@ module Light
 
               break if @errors.break? || @warnings.break?
             end
+          rescue Light::Services::StopExecution
+            # Gracefully handle stop_immediately! inside transaction to prevent rollback
+            @stopped = true
           end
         end