light-services 2.2.1 → 3.1.0

data/docs/configuration.md

@@ -0,0 +1,204 @@
+# Configuration
+
+Light Services provides a flexible configuration system that allows you to customize behavior at three levels: global, per-service, and per-call.
+
+## Global Configuration
+
+Configure Light Services globally using an initializer. For Rails applications, create `config/initializers/light_services.rb`:
+
+```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
+
+  # Error behavior
+  config.load_errors = true             # Copy errors to parent service in context chain
+  config.break_on_error = true          # Stop step execution when an error is added
+  config.raise_on_error = false         # Raise an exception when an error is added
+  config.rollback_on_error = true       # Rollback transaction when an error is added
+
+  # Warning behavior
+  config.load_warnings = true           # Copy warnings to parent service in context chain
+  config.break_on_warning = false       # Stop step execution when a warning is added
+  config.raise_on_warning = false       # Raise an exception when a warning is added
+  config.rollback_on_warning = false    # Rollback transaction when a warning is added
+end
+```
+
+## Default Values
+
+| 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 |
+| `raise_on_error` | `false` | Raises `Light::Services::Error` when an error is added |
+| `rollback_on_error` | `true` | Rolls back the transaction when an error is added |
+| `load_warnings` | `true` | Propagates warnings to parent service when using `.with(self)` |
+| `break_on_warning` | `false` | Stops executing remaining steps when a warning is added |
+| `raise_on_warning` | `false` | Raises `Light::Services::Error` when a warning is added |
+| `rollback_on_warning` | `false` | Rolls back the transaction when a warning is added |
+
+## Per-Service Configuration
+
+Override global configuration for a specific service class using the `config` class method:
+
+```ruby
+class CriticalPaymentService < ApplicationService
+  # This service will raise exceptions instead of collecting errors
+  config raise_on_error: true
+
+  step :process_payment
+  step :send_receipt
+
+  # ...
+end
+```
+
+```ruby
+class NonCriticalNotificationService < ApplicationService
+  # This service doesn't need transactions and shouldn't stop on errors
+  config use_transactions: false, break_on_error: false
+
+  step :send_push_notification
+  step :send_email_notification
+
+  # ...
+end
+```
+
+## Per-Call Configuration
+
+Override configuration for a single service call:
+
+```ruby
+# Pass config as second argument to run
+MyService.run({ name: "John" }, { raise_on_error: true })
+
+# Or use with() for context-based calls
+MyService.with({ raise_on_error: true }).run(name: "John")
+
+# Combine with parent service context
+ChildService
+  .with(self, { use_transactions: false })
+  .run(data: some_data)
+```
+
+## Configuration Precedence
+
+Configuration is merged in this order (later overrides earlier):
+
+1. Global configuration (from initializer)
+2. Per-service configuration (from `config` class method)
+3. Per-call configuration (from `run` or `with` arguments)
+
+```ruby
+# Global: raise_on_error = false
+Light::Services.configure do |config|
+  config.raise_on_error = false
+end
+
+# Per-service: raise_on_error = true (overrides global)
+class MyService < ApplicationService
+  config raise_on_error: true
+end
+
+# Per-call: raise_on_error = false (overrides per-service)
+MyService.run(args, { raise_on_error: false })
+```
+
+## Common Configuration Patterns
+
+### Strict Mode for Critical Services
+
+```ruby
+class Payment::Process < ApplicationService
+  config raise_on_error: true, rollback_on_error: true
+  
+  # Any error will raise an exception and rollback the transaction
+end
+```
+
+### Fire-and-Forget Services
+
+```ruby
+class Analytics::Track < ApplicationService
+  config use_transactions: false, break_on_error: false, load_errors: false
+  
+  # Errors won't stop execution or propagate to parent services
+end
+```
+
+### Background Job Services
+
+```ruby
+class BackgroundTaskService < ApplicationService
+  # Background jobs typically handle their own transactions
+  config use_transactions: false
+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:
+
+```ruby
+Light::Services.configure do |config|
+  config.use_transactions = false
+end
+```
+
+Or disable for specific services:
+
+```ruby
+class MyService < ApplicationService
+  config use_transactions: false
+end
+```
+
+{% hint style="info" %}
+When `use_transactions` is `true`, Light Services uses `ActiveRecord::Base.transaction(requires_new: true)` to create savepoints, allowing nested services to rollback independently.
+{% endhint %}
+
+## What's Next?
+
+Now that you understand configuration, learn about the core concepts:
+
+[Next: Concepts](concepts.md)
+

data/docs/context.md

@@ -0,0 +1,128 @@
+# Context
+
+Context allows services to be run within the same execution scope, enabling shared state and coordinated transactions.
+
+## Key Features
+
+- Services share arguments marked as `context: true`
+- If any service fails, the entire context fails and rolls back database changes
+
+## How to Run Services in the Same Context
+
+To run a service in the same context, call `with(self)` before the `#run` method.
+
+## Context Rollback
+
+### Example:
+
+Let's say we have two services: `User::Create` and `Profile::Create`. We want to ensure that if either service fails, all database changes are rolled back.
+
+```ruby
+class User::Create < ApplicationService
+  # Arguments
+  arg :attributes, type: Hash
+
+  # Steps
+  step :create_user
+  step :create_profile
+  step :send_welcome_email
+
+  # Outputs
+  output :user, type: User
+  output :profile, type: Profile
+
+  def create_user
+    self.user = User.create!(attributes)
+  end
+
+  def create_profile
+    service = Profile::Create
+      .with(self) # This runs the service in the same context
+      .run(user:)
+
+    self.profile = service.profile
+  end
+
+  # If the Profile::Create service fails, this step and any following steps won't execute
+  # And all database changes will be rolled back
+  def send_welcome_email
+    # We don't run this service in the same context
+    # Because we don't care too much if it fails
+    service = Mailer::SendWelcomeEmail.run(user:)
+
+    # Handle the failure manually if needed
+    if service.failed?
+      # Handle the failure
+    end
+  end
+end
+```
+
+## Context Arguments
+
+Context arguments are shared between services running in the same context. This can make them a bit less predictable and harder to test.
+
+It's recommended to use context arguments only when necessary and keep them as close to the root service as possible. For example, you can use them to share `current_user` or `current_organization` between services.
+
+```ruby
+class ApplicationService < Light::Services::Base
+  arg :current_user, type: User, context: true
+end
+```
+
+```ruby
+class Comment::Create < ApplicationService
+  # Arguments
+  # We don't need to specify current_user here
+  # as it's automatically inherited from the ApplicationService
+  arg :post_id, type: Integer
+  arg :text, type: String
+  arg :subscribe, type: [TrueClass, FalseClass]
+
+  # Steps
+  step :create_comment
+  step :subscribe_to_post, if: :subscribe?
+
+  private
+
+  def create_comment
+    # ...
+  end
+
+  def subscribe_to_post
+    Post::Subscribe
+      .with(self) # Run service in the same context
+      .run(post_id:) # We omit current_user here as context will handle it for us
+
+    # If we run Post::Subscribe without `with(self)`
+    # It'll fail because it won't have information about the `current_user`
+  end
+end
+```
+
+```ruby
+class Post::Subscribe < ApplicationService
+  # Arguments
+  arg :post_id, type: Integer
+
+  # Steps
+  step :subscribe
+
+  private
+
+  def subscribe
+    # We have access to current_user here because we run it in the same context
+    #
+    # Even if we would run this service without context this won't be a problem
+    # because we specified this argument in top-level service (ApplicationService)
+    current_user.subscriptions.create!(post_id:)
+  end
+end
+```
+
+# What's Next?
+
+The next step is to learn about error handling in Light Service.
+
+[Next: Errors](errors.md)
+