light-services 2.2 → 3.0.0

data/docs/errors.md

@@ -0,0 +1,250 @@
+# Errors
+
+Errors are a natural part of every application. This guide explores how to handle errors within Light Services, drawing parallels to ActiveModel errors.
+
+## Error Structure
+
+Light Service errors follow a structure similar to ActiveModel errors. Here's a simplified example:
+
+```ruby
+{
+  email: ["must be a valid email"],
+  password: ["is too short", "must contain at least one number"]
+}
+```
+
+## Adding Errors
+
+To add an error to your service, use the `errors.add` method.
+
+{% hint style="info" %}
+By default, adding an error marks the service as failed, preventing subsequent steps from executing. This behavior can be customized in the configuration for individual services and errors.
+{% endhint %}
+
+```ruby
+class ParsePage < ApplicationService
+  # Arguments
+  arg :url, type: String
+  # ...
+
+  # Steps
+  step :validate
+  step :parse
+  # ...
+
+  private
+
+  def validate
+    # Multiple errors can be added with the same key
+    errors.add(:url, "must be a valid URL") unless url.match?(URI::DEFAULT_PARSER.make_regexp)
+    errors.add(:url, "must be a secure link") unless url.start_with?("https")
+  end
+
+  # ...
+end
+```
+
+## Reading Errors
+
+To check if a service has errors, you can use the `#failed?` method. You can also use methods like `errors.any?` to inspect errors.
+
+```ruby
+class ParsePage < ApplicationService
+  def parse
+    nodes.each do |node|
+      if node.nil? || (node.respond_to?(:empty?) && node.empty?)
+        errors.add(:base, "Node #{node} is blank")
+      else
+        parse_node(node)
+      end
+    end
+
+    if failed? # or errors.any?
+      puts "Not all nodes were parsed"
+    end
+  end
+end
+```
+
+You can access errors outside the service using the `#errors` method.
+
+```ruby
+service = ParsePage.run(url: "rubygems")
+
+if service.failed?
+  puts service.errors
+  puts service.errors[:url]
+  puts service.errors.to_h # Returns errors as a hash
+end
+```
+
+## Adding Warnings
+
+Sometimes, you may want to add a warning instead of an error. Warnings are similar to errors but they do not mark the service as failed. By default they also do not stop execution and do not roll back the transaction (both behaviors can be configured globally or per-message).
+
+```ruby
+class ParsePage < ApplicationService
+  def validate
+    errors.add(:url, "must be a valid URL") unless url.match?(URI::DEFAULT_PARSER.make_regexp)
+    warnings.add(:url, "should be a secure link") unless url.start_with?("https")
+  end
+end
+```
+
+```ruby
+service = ParsePage.run(url: "http://rubygems.org")
+
+if service.warnings.any?
+  puts service.warnings
+  puts service.warnings[:url]
+  puts service.warnings.to_h # Returns warnings as a hash
+end
+```
+
+## Copying Errors
+
+### From ActiveRecord Models
+
+Use `errors.copy_from` (or its alias `errors.from_record`) to copy errors from an ActiveRecord model:
+
+```ruby
+class User::Create < ApplicationService
+  def create_user
+    self.user = User.new(attributes)
+    
+    unless user.save
+      errors.copy_from(user) # Copies all validation errors from the user model
+    end
+  end
+end
+```
+
+### From Another Service
+
+Copy errors from a child service that wasn't run in the same context:
+
+```ruby
+class Order::Process < ApplicationService
+  def process_payment
+    payment_service = Payment::Charge.run(amount:, card:)
+    
+    if payment_service.failed?
+      errors.copy_from(payment_service)
+    end
+  end
+end
+```
+
+## Converting Errors to Hash
+
+Use `errors.to_h` to get a hash representation of all errors:
+
+```ruby
+service = User::Create.run(email: "invalid")
+
+if service.failed?
+  service.errors.to_h
+  # => { email: ["is invalid"], password: ["can't be blank"] }
+end
+```
+
+## Per-Message Options
+
+When adding errors, you can control behavior on a per-message basis:
+
+### Control Break Behavior
+
+```ruby
+def validate
+  # This error won't stop subsequent steps from running
+  errors.add(:warning_field, "has a minor issue", break: false)
+  
+  # This error WILL stop execution (default behavior)
+  errors.add(:critical_field, "is completely invalid")
+end
+```
+
+### Control Rollback Behavior
+
+```ruby
+def process
+  # This error won't trigger a transaction rollback
+  errors.add(:notification, "failed to send", rollback: false)
+  
+  # This error WILL rollback (default behavior when use_transactions is true)
+  errors.add(:payment, "failed to process")
+end
+```
+
+## Checking for Errors and Warnings
+
+Light Services provides convenient methods to check error/warning states:
+
+```ruby
+service = MyService.run(args)
+
+# Check if service has any errors
+service.failed?   # => true/false
+service.success?  # => true/false (opposite of failed?)
+service.errors?   # => true/false (same as errors.any?)
+
+# Check if service has any warnings
+service.warnings? # => true/false (same as warnings.any?)
+```
+
+By following these guidelines, you can effectively manage errors and warnings in Light Services, ensuring a smoother and more robust application experience.
+
+## Exception Classes
+
+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::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 |
+
+### NoStepsError
+
+This exception is raised when you attempt to execute a service that has no steps defined and no `run` method as a fallback:
+
+```ruby
+class EmptyService < ApplicationService
+  # No steps defined and no run method
+end
+
+EmptyService.run # => raises Light::Services::NoStepsError
+```
+
+To fix this, either define at least one step or implement a `run` method:
+
+```ruby
+# Option 1: Define steps
+class MyService < ApplicationService
+  step :do_work
+
+  private
+
+  def do_work
+    # ...
+  end
+end
+
+# Option 2: Use run method
+class MyService < ApplicationService
+  private
+
+  def run
+    # ...
+  end
+end
+```
+
+## What's next?
+
+Learn about callbacks to add logging, benchmarking, and other cross-cutting concerns to your services.
+
+[Next: Callbacks](callbacks.md)
+

data/docs/generators.md

@@ -0,0 +1,250 @@
+# Rails Generators
+
+Light Services includes Rails generators to help you quickly set up and create services in your Rails application. These generators follow Rails conventions and integrate seamlessly with your Rails workflow.
+
+## Install Generator
+
+The install generator sets up Light Services in your Rails application by creating the base `ApplicationService` class and configuration files.
+
+### Usage
+
+```bash
+bin/rails generate light_services:install
+```
+
+### What It Creates
+
+The install generator creates the following files:
+
+1. **`app/services/application_service.rb`** - Base service class for your application
+   ```ruby
+   class ApplicationService < Light::Services::Base
+     # Add common arguments, callbacks, or helpers shared across all services.
+     #
+     # Example: Add a context argument for the current user
+     # arg :current_user, type: User, optional: true, context: true
+   end
+   ```
+
+2. **`config/initializers/light_services.rb`** - Configuration file (unless `--skip-initializer` is used)
+   This file contains the global configuration for Light Services in your Rails application.
+
+3. **`spec/services/application_service_spec.rb`** - RSpec test file (if RSpec is detected and `--skip-spec` is not used)
+
+### Options
+
+- `--skip-initializer` - Skip creating the initializer file
+- `--skip-spec` - Skip creating the spec file
+
+### Examples
+
+```bash
+# Standard installation
+bin/rails generate light_services:install
+
+# Skip initializer
+bin/rails generate light_services:install --skip-initializer
+
+# Skip spec file
+bin/rails generate light_services:install --skip-spec
+```
+
+## Service Generator
+
+The service generator creates a new service class that inherits from `ApplicationService`. It supports namespaced services and can pre-populate arguments, steps, and outputs.
+
+### Usage
+
+```bash
+bin/rails generate light_services:service NAME [options]
+```
+
+### What It Creates
+
+The service generator creates:
+
+1. **Service file** - `app/services/{name}.rb`
+2. **Spec file** - `spec/services/{name}_spec.rb` (if RSpec is detected and `--skip-spec` is not used)
+
+### Options
+
+- `--args` - List of arguments for the service (space-separated)
+- `--steps` - List of steps for the service (space-separated)
+- `--outputs` - List of outputs for the service (space-separated)
+- `--skip-spec` - Skip creating the spec file
+- `--parent` - Parent class (default: `ApplicationService`)
+
+### Examples
+
+#### Basic Service
+
+Create a simple service without any predefined structure:
+
+```bash
+bin/rails generate light_services:service user/create
+```
+
+This creates:
+```ruby
+# app/services/user/create.rb
+class User::Create < ApplicationService
+  # step :step_a
+  # step :step_b
+
+  private
+
+  # def step_a
+  #   # TODO: Implement service logic
+  # end
+
+  # def step_b
+  #   # TODO: Implement service logic
+  # end
+end
+```
+
+#### Service with Arguments, Steps, and Outputs
+
+Create a fully structured service:
+
+```bash
+bin/rails generate light_services:service CreateOrder \
+  --args=user product quantity \
+  --steps=validate_stock create_order send_confirmation \
+  --outputs=order
+```
+
+This creates:
+```ruby
+# app/services/create_order.rb
+class CreateOrder < ApplicationService
+  # Arguments
+  arg :user
+  arg :product
+  arg :quantity
+
+  # Steps
+  step :validate_stock
+  step :create_order
+  step :send_confirmation
+
+  # Outputs
+  output :order
+
+  private
+
+  def validate_stock
+    # TODO: Implement validate_stock
+  end
+
+  def create_order
+    # TODO: Implement create_order
+  end
+
+  def send_confirmation
+    # TODO: Implement send_confirmation
+  end
+end
+```
+
+#### Namespaced Service
+
+Create a service within a namespace:
+
+```bash
+bin/rails generate light_services:service payment/process \
+  --args=order payment_method \
+  --steps=validate_payment charge_card update_order \
+  --outputs=transaction
+```
+
+This creates:
+```ruby
+# app/services/payment/process.rb
+class Payment::Process < ApplicationService
+  # Arguments
+  arg :order
+  arg :payment_method
+
+  # Steps
+  step :validate_payment
+  step :charge_card
+  step :update_order
+
+  # Outputs
+  output :transaction
+
+  private
+
+  def validate_payment
+    # TODO: Implement validate_payment
+  end
+
+  def charge_card
+    # TODO: Implement charge_card
+  end
+
+  def update_order
+    # TODO: Implement update_order
+  end
+end
+```
+
+#### Custom Parent Class
+
+Create a service that inherits from a custom parent class:
+
+```bash
+bin/rails generate light_services:service admin/reports/generate \
+  --parent=AdminService \
+  --args=start_date end_date \
+  --steps=fetch_data generate_report \
+  --outputs=report
+```
+
+## RSpec Integration
+
+Both generators automatically detect if RSpec is installed in your Rails application by checking for the presence of the `spec/` directory. If RSpec is detected, the generators will create corresponding spec files with basic test structure.
+
+### Example Spec File
+
+```ruby
+# spec/services/user/create_spec.rb
+require "rails_helper"
+
+RSpec.describe User::Create do
+  describe ".run" do
+    it "creates a user" do
+      service = described_class.run(...)
+      expect(service).to be_success
+    end
+  end
+end
+```
+
+You can skip spec file generation with the `--skip-spec` option:
+
+```bash
+bin/rails generate light_services:service user/create --skip-spec
+```
+
+## Best Practices
+
+1. **Run the install generator first** - Always run `light_services:install` before creating individual services to set up the base `ApplicationService` class.
+
+2. **Use namespaces** - Organize related services under namespaces (e.g., `User::Create`, `Payment::Process`) to keep your services organized.
+
+3. **Start with structure** - Use `--args`, `--steps`, and `--outputs` options to create a skeleton for your service, then fill in the implementation.
+
+4. **Keep it simple** - Don't over-specify. If you're not sure about the exact steps, create a basic service and add them as you develop.
+
+5. **Follow conventions** - Use descriptive names for services that indicate the action being performed (e.g., `CreateOrder`, `User::Authenticate`, `Payment::Refund`).
+
+## Next Steps
+
+After generating your services, learn more about:
+
+- [Arguments](arguments.md) - Define and validate service inputs
+- [Steps](steps.md) - Organize service logic into steps
+- [Outputs](outputs.md) - Define service outputs
+- [Testing](testing.md) - Write comprehensive tests for your services

data/docs/outputs.md

@@ -0,0 +1,135 @@
+# Outputs
+
+Outputs are the results of a service.
+
+## TL;DR
+
+- Define outputs using the `output` keyword in the service class
+- Outputs can have default values
+- Outputs can be validated by type (validated when the service succeeds)
+
+## Define Outputs
+
+You define outputs using the `output` keyword in the service class.
+
+```ruby
+class AI::Chat < ApplicationService
+  output :messages
+  output :cost
+end
+```
+
+## Write Outputs
+
+Outputs function similarly to instance variables created with `attr_accessor`.
+
+```ruby
+class AI::Chat < ApplicationService
+  # Steps
+  step :chat
+
+  # Outputs
+  output :messages
+  output :cost
+
+  private
+
+  def chat
+    self.messages = ["Hello!", "Hi, how are you?"]
+    self.cost = 0.0013
+  end
+end
+```
+
+To set outputs programmatically, use the `outputs.set` method or hash syntax.
+
+```ruby
+class AI::Chat < ApplicationService
+  # ...
+
+  def chat
+    outputs.set(:messages, ["Hello!", "Hi, how are you?"])
+    outputs.set(:cost, 0.0013)
+
+    # Or use hash syntax
+
+    outputs[:messages] = ["Hello!", "Hi, how are you?"]
+    outputs[:cost] = 0.0013
+  end
+end
+```
+
+## Type Validation
+
+You can specify the type of output using the `type` option. The output type will be validated when the service successfully completes.
+
+```ruby
+class AI::Chat < ApplicationService
+  output :messages, type: Array
+  output :cost, type: Float
+end
+```
+
+You can specify multiple allowed types using an array.
+
+```ruby
+class AI::Chat < ApplicationService
+  output :result, type: [String, Hash]
+end
+```
+
+### dry-types Support
+
+Outputs also support [dry-types](https://dry-rb.org/gems/dry-types) for advanced type validation and coercion.
+
+```ruby
+require "dry-types"
+
+module Types
+  include Dry.Types()
+end
+
+class AI::Chat < ApplicationService
+  # Strict type validation
+  output :messages, type: Types::Strict::Array.of(Types::Hash)
+  
+  # Coercible types - values are coerced on output validation
+  output :total_tokens, type: Types::Coercible::Integer
+  
+  # Constrained types
+  output :cost, type: Types::Float.constrained(gteq: 0)
+end
+```
+
+## Default Values
+
+Set default values for outputs using the `default` option. The default value will be automatically set before the execution of steps.
+
+```ruby
+class AI::Chat < ApplicationService
+  output :cost, default: 0.0
+end
+```
+
+## Removing Inherited Outputs
+
+When inheriting from a parent service, you can remove outputs using `remove_output`:
+
+```ruby
+class BaseReportService < ApplicationService
+  output :report
+  output :debug_info
+end
+
+class ProductionReportService < BaseReportService
+  # Don't expose debug info in production
+  remove_output :debug_info
+end
+```
+
+## What's Next?
+
+Next, learn about context.
+
+[Next: Context](context.md)
+