light-services 2.2.1 → 3.1.0

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/service-rendering.md

@@ -0,0 +1,222 @@
+# Service Rendering
+
+This recipe provides a clean way to render service results and errors in your Rails controllers, reducing boilerplate and ensuring consistent API responses.
+
+## The Problem
+
+Without a helper, controller actions become repetitive:
+
+```ruby
+class PostsController < ApplicationController
+  def create
+    service = Post::Create.run(service_args(attributes: params[:post]))
+
+    if service.success?
+      render json: service.post, status: :created
+    else
+      render json: { errors: service.errors.to_h }, status: :unprocessable_entity
+    end
+  end
+
+  def update
+    service = Post::Update.run(service_args(record: @post, attributes: params[:post]))
+
+    if service.success?
+      render json: service.post
+    else
+      render json: { errors: service.errors.to_h }, status: :unprocessable_entity
+    end
+  end
+
+  # ... same pattern repeated for every action
+end
+```
+
+## The Solution
+
+Create a `render_service` helper that handles success and failure automatically.
+
+## Implementation
+
+### Basic Helper
+
+Add this to your `ApplicationController`:
+
+```ruby
+class ApplicationController < ActionController::API
+  private
+
+  def render_service(service, success_status: :ok, error_status: :unprocessable_entity)
+    if service.success?
+      yield(service) if block_given?
+      render json: service_response(service), status: success_status
+    else
+      render json: { errors: service.errors.to_h }, status: error_status
+    end
+  end
+
+  def service_response(service)
+    # Returns the first output that is set
+    service.class.outputs.each do |name, _|
+      value = service.public_send(name)
+      return value unless value.nil? || (value.respond_to?(:empty?) && value.empty?)
+    end
+    
+    {}
+  end
+end
+```
+
+### Usage
+
+```ruby
+class PostsController < ApplicationController
+  def create
+    render_service Post::Create.run(service_args(attributes: params[:post])), 
+                   success_status: :created
+  end
+
+  def update
+    render_service Post::Update.run(service_args(record: @post))
+  end
+
+  def destroy
+    render_service Post::Destroy.run(service_args(record: @post))
+  end
+end
+```
+
+## Advanced Implementation
+
+### With Custom Response Building
+
+```ruby
+class ApplicationController < ActionController::API
+  private
+
+  def render_service(service, **options)
+    if service.success?
+      render_service_success(service, options)
+    else
+      render_service_failure(service, options)
+    end
+  end
+
+  def render_service_success(service, options)
+    status = options[:success_status] || :ok
+    
+    response = if options[:response]
+      options[:response]
+    elsif options[:output]
+      service.public_send(options[:output])
+    else
+      auto_detect_response(service)
+    end
+
+    render json: response, status: status
+  end
+
+  def render_service_failure(service, options)
+    status = options[:error_status] || :unprocessable_entity
+    
+    render json: {
+      errors: service.errors.to_h,
+      warnings: service.warnings.to_h
+    }.compact, status: status
+  end
+
+  def auto_detect_response(service)
+    service.class.outputs.each do |name, _|
+      value = service.public_send(name)
+      return value unless value.nil? || (value.respond_to?(:empty?) && value.empty?)
+    end
+    
+    { success: true }
+  end
+end
+```
+
+### Usage with Options
+
+```ruby
+class PostsController < ApplicationController
+  def create
+    service = Post::Create.run(service_args(attributes: params[:post]))
+    
+    render_service service,
+                   success_status: :created,
+                   output: :post
+  end
+
+  def bulk_create
+    service = Post::BulkCreate.run(service_args(items: params[:posts]))
+    
+    render_service service,
+                   success_status: :created,
+                   response: { posts: service.posts, count: service.posts.count }
+  end
+end
+```
+
+## With Serializers
+
+If you're using a serializer library (like Alba, Blueprinter, or ActiveModel::Serializers):
+
+```ruby
+class ApplicationController < ActionController::API
+  private
+
+  def render_service(service, serializer: nil, **options)
+    if service.success?
+      response = auto_detect_response(service)
+      response = serializer.new(response).to_h if serializer && response
+      
+      render json: response, status: options[:success_status] || :ok
+    else
+      render json: { errors: service.errors.to_h }, 
+             status: options[:error_status] || :unprocessable_entity
+    end
+  end
+end
+```
+
+```ruby
+class PostsController < ApplicationController
+  def show
+    service = Post::Find.run(service_args(id: params[:id]))
+    render_service service, serializer: PostSerializer
+  end
+end
+```
+
+## Handling Different Error Types
+
+```ruby
+def render_service(service, **options)
+  if service.success?
+    render_service_success(service, options)
+  else
+    status = determine_error_status(service, options)
+    render json: { errors: service.errors.to_h }, status: status
+  end
+end
+
+private
+
+def determine_error_status(service, options)
+  return options[:error_status] if options[:error_status]
+  
+  # Map specific error keys to HTTP statuses
+  return :not_found if service.errors[:record]&.any?
+  return :forbidden if service.errors[:authorization]&.any?
+  return :unauthorized if service.errors[:authentication]&.any?
+  
+  :unprocessable_entity
+end
+```
+
+## What's Next?
+
+Learn how to integrate Pundit authorization with Light Services:
+
+[Next: Pundit Authorization](pundit-authorization.md)