operandi 5.0.0

data/docs/errors.md

@@ -0,0 +1,331 @@
+# Errors
+
+Errors are a natural part of every application. This guide explores how to handle errors within Operandi, drawing parallels to ActiveModel errors.
+
+## Error Structure
+
+Operandi 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
+```
+
+## Quick Error with `fail!`
+
+The `fail!` method is a shortcut for adding an error to the `:base` key:
+
+```ruby
+class ParsePage < ApplicationService
+  def validate
+    fail!("URL is required") if url.blank?
+  end
+end
+```
+
+This is equivalent to:
+
+```ruby
+errors.add(:base, "URL is required")
+```
+
+## 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
+
+Operandi 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 Operandi, ensuring a smoother and more robust application experience.
+
+## Exception Classes
+
+Operandi defines several exception classes for different error scenarios:
+
+| Exception | Description |
+|-----------|-------------|
+| `Operandi::Error` | Base exception class for all Operandi errors |
+| `Operandi::RuntimeError` | Raised while a service is running; exposes the service instance through `service` |
+| `Operandi::ArgTypeError` | Raised when type validation fails; exposes the associated service class through `service_class` |
+| `Operandi::ReservedNameError` | Raised when using a reserved name for arguments, outputs, or steps |
+| `Operandi::InvalidNameError` | Raised when using an invalid name format |
+| `Operandi::NoStepsError` | Raised when a service has no steps defined and no `run` method |
+| `Operandi::MissingTypeError` | Raised when defining an argument or output without a `type` option when `require_arg_type` or `require_output_type` is enabled |
+| `Operandi::StopExecution` | Control flow exception raised by `stop_immediately!` to halt execution without rollback |
+| `Operandi::FailExecution` | Control flow exception raised by `fail_immediately!` to halt execution and rollback transactions |
+
+### RuntimeError
+
+Runtime failures caused by service errors, warnings, or invalid step execution raise
+`Operandi::RuntimeError`. The exception inherits from `Operandi::Error` and provides
+the concrete service instance that failed:
+
+```ruby
+begin
+  MyService.run!(name: "John")
+rescue Operandi::RuntimeError => error
+  error.service # => the MyService instance
+end
+```
+
+Errors raised while defining a service continue to use `Operandi::Error`.
+
+### ArgTypeError
+
+Argument and output type failures raise `Operandi::ArgTypeError`. It inherits from
+`Operandi::Error` and identifies the associated service class without requiring a
+service instance:
+
+```ruby
+begin
+  MyService.run(name: 123)
+rescue Operandi::ArgTypeError => error
+  error.service_class # => MyService
+end
+```
+
+### MissingTypeError
+
+This exception is raised when you define an argument or output without a `type` option. Since `require_arg_type` and `require_output_type` are enabled by default, all arguments and outputs must have a type.
+
+```ruby
+class MyService < ApplicationService
+  arg :name  # => raises Operandi::MissingTypeError
+end
+```
+
+To fix this, add a `type` option to all arguments and outputs:
+
+```ruby
+class MyService < ApplicationService
+  arg :name, type: String
+  output :result, type: Hash
+end
+```
+
+If you need to disable type enforcement for legacy services, you can use the `config` method:
+
+```ruby
+class LegacyService < ApplicationService
+  config require_arg_type: false, require_output_type: false
+  
+  arg :data              # Allowed when require_arg_type is disabled
+  output :result         # Allowed when require_output_type is disabled
+end
+```
+
+### 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 Operandi::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
+
+Operandi 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 Operandi in your Rails application by creating the base `ApplicationService` class and configuration files.
+
+### Usage
+
+```bash
+bin/rails generate operandi: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 < Operandi::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/operandi.rb`** - Configuration file (unless `--skip-initializer` is used)
+   This file contains the global configuration for Operandi 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 operandi:install
+
+# Skip initializer
+bin/rails generate operandi:install --skip-initializer
+
+# Skip spec file
+bin/rails generate operandi: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 operandi: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 operandi: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 operandi: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 operandi: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 operandi: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_successful
+    end
+  end
+end
+```
+
+You can skip spec file generation with the `--skip-spec` option:
+
+```bash
+bin/rails generate operandi:service user/create --skip-spec
+```
+
+## Best Practices
+
+1. **Run the install generator first** - Always run `operandi: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,150 @@
+# 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 `output.set` method or hash syntax.
+
+```ruby
+class AI::Chat < ApplicationService
+  # ...
+
+  def chat
+    output.set(:messages, ["Hello!", "Hi, how are you?"])
+    output.set(:cost, 0.0013)
+
+    # Or use hash syntax
+
+    output[:messages] = ["Hello!", "Hi, how are you?"]
+    output[: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
+```
+
+### Type Enforcement (Enabled by Default)
+
+By default, all outputs must have a `type` option. This helps catch type-related bugs early and makes your services self-documenting.
+
+```ruby
+class MyService < ApplicationService
+  output :result, type: Hash  # ✓ Valid
+  output :data                # ✗ Raises MissingTypeError
+end
+```
+
+To disable type enforcement for outputs in a specific service:
+
+```ruby
+class LegacyService < ApplicationService
+  config require_output_type: false
+  
+  output :data             # Allowed when require_output_type is disabled
+end
+```
+
+See the [Configuration documentation](configuration.md) for more details.
+
+### Sorbet Runtime Types
+
+Outputs support [Sorbet runtime types](https://sorbet.org/docs/runtime) for type validation:
+
+```ruby
+require "sorbet-runtime"
+
+class AI::Chat < ApplicationService
+  output :messages, type: T::Array[Hash]
+  output :total_tokens, type: T::Utils.coerce(Integer)
+  output :metadata, type: T.nilable(Hash), optional: true
+end
+```
+
+See the [Sorbet Runtime Types documentation](sorbet-runtime.md) for more details.
+
+## 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)