operandi 5.0.0

data/docs/arguments.md

@@ -0,0 +1,275 @@
+# Arguments
+
+Arguments are the inputs to a service. They are passed to the service when it is invoked.
+
+## TL;DR
+
+- Define arguments with the `arg` keyword in the service class
+- Validate arguments by type
+- Specify arguments as required or optional
+- Set default values for arguments
+- Access arguments like instance variables
+- Use predicate methods for arguments
+
+```ruby
+class User::Charge < ApplicationService
+  arg :user, type: User
+  arg :amount, type: Float
+  arg :send_receipt, type: [TrueClass, FalseClass], default: true
+  # In Rails you might prefer `Date.current`.
+  arg :invoice_date, type: Date, default: -> { Date.today }
+
+  step :send_email_receipt, if: :send_receipt?
+
+  # ...
+end
+```
+
+## Define Arguments
+
+Arguments are defined using the `arg` keyword in the service class.
+
+```ruby
+class HappyBirthdayService < ApplicationService
+  arg :name
+  arg :age
+end
+```
+
+## Type Validation
+
+Arguments can be validated by type.
+
+```ruby
+class HappyBirthdayService < ApplicationService
+  arg :name, type: String
+  arg :age, type: Integer
+end
+```
+
+You can specify multiple allowed types using an array.
+
+```ruby
+class HappyBirthdayService < ApplicationService
+  arg :name, type: [String, Symbol]
+end
+```
+
+### Type Enforcement (Enabled by Default)
+
+By default, all arguments must have a `type` option. This helps catch type-related bugs early and makes your services self-documenting.
+
+```ruby
+class MyService < ApplicationService
+  arg :name, type: String  # ✓ Valid
+  arg :age                 # ✗ Raises MissingTypeError
+end
+```
+
+To disable type enforcement for arguments in a specific service:
+
+```ruby
+class LegacyService < ApplicationService
+  config require_arg_type: false
+  
+  arg :name              # Allowed when require_arg_type is disabled
+end
+```
+
+See the [Configuration documentation](configuration.md) for more details.
+
+### Sorbet Runtime Types
+
+Operandi supports [Sorbet runtime types](https://sorbet.org/docs/runtime) for type validation. Sorbet types **only validate** and do not coerce values.
+
+```ruby
+require "sorbet-runtime"
+
+class User::Create < ApplicationService
+  # Basic types using T::Utils.coerce
+  arg :name, type: T::Utils.coerce(String)
+  arg :age, type: T::Utils.coerce(Integer)
+  
+  # Nilable types
+  arg :email, type: T.nilable(String), optional: true
+  
+  # Union types
+  arg :status, type: T.any(String, Symbol)
+  
+  # Typed arrays
+  arg :tags, type: T::Array[String]
+  
+  # Boolean type
+  arg :active, type: T::Boolean, default: true
+end
+```
+
+{% hint style="warning" %}
+**Sorbet types do NOT coerce values.** If you pass `"25"` where an `Integer` is expected, it will raise an error instead of converting the string to an integer.
+{% endhint %}
+
+See the [Sorbet Runtime Types documentation](sorbet-runtime.md) for more details.
+
+## Required Arguments
+
+By default, arguments are required. You can make them optional by setting `optional` to `true`.
+
+```ruby
+class HappyBirthdayService < ApplicationService
+  arg :name, type: String
+  arg :age, type: Integer, optional: true
+end
+```
+
+## Default Values
+
+Set a default value for an argument to make it optional.
+
+```ruby
+class HappyBirthdayService < ApplicationService
+  arg :name, type: String
+  arg :age, type: Integer, default: 18
+end
+```
+
+### Complex Default Values
+
+Default values are deep duplicated when the service is invoked, making it safe to use mutable objects.
+
+```ruby
+arg :options, type: Hash, default: { a: 1, b: 2 }
+```
+
+### Procs as Default Values
+
+Use procs for dynamic default values.
+
+```ruby
+arg :current_date, type: Date, default: -> { Date.current }
+```
+
+## Inheritance
+
+Arguments are inherited from parent classes.
+
+```ruby
+# UpdateRecordService
+class UpdateRecordService < ApplicationService
+  # Arguments
+  arg :record, type: ApplicationRecord
+  arg :attributes, type: Hash
+
+  # Steps
+  step :authorize
+  step :update_record
+end
+```
+
+```ruby
+# User::Update inherited from UpdateRecordService
+class User::Update < UpdateRecordService
+  # Nothing to do here
+  # Arguments and steps are inherited from UpdateRecordService
+end
+```
+
+### Removing Inherited Arguments
+
+To remove an inherited argument, use `remove_arg`:
+
+```ruby
+class BaseService < ApplicationService
+  arg :current_user, type: User
+  arg :audit_log, type: [TrueClass, FalseClass], default: true
+end
+
+class SystemTaskService < BaseService
+  # System tasks don't need a current_user
+  remove_arg :current_user
+end
+```
+
+## Context Arguments
+
+Context arguments are automatically passed to all child services in the same context. Define them using the `context` option. This is useful for passing objects like `current_user`.
+
+Learn more about context in the [Context documentation](context.md).
+
+```ruby
+class ApplicationService < Operandi::Base
+  arg :current_user, type: User, optional: true, context: true
+end
+```
+
+## Accessing Arguments
+
+Arguments are accessible like instance variables, similar to `attr_accessor`.
+
+```ruby
+class HappyBirthdayService < ApplicationService
+  # Arguments
+  arg :name, type: String
+  arg :age, type: Integer
+
+  # Steps
+  step :greet
+
+  private
+
+  def greet
+    puts "Happy birthday, #{name}! You are #{age} years old."
+  end
+end
+```
+
+## Accessing Arguments Using `arg`
+
+For dynamic access or to avoid conflicts, use the `arg` method.
+
+```ruby
+class HappyBirthdayService < ApplicationService
+  # Arguments
+  arg :name, type: String
+  arg :age, type: Integer
+
+  # Steps
+  step :greet
+
+  private
+
+  def greet
+    name = arg[:name] # or arg.get(:name)
+    age = arg[:age] # or arg.get(:age)
+
+    puts "Happy birthday, #{name}! You are #{age} years old."
+  end
+end
+```
+
+## Argument Predicate Methods
+
+Predicate methods are automatically generated for each argument, allowing you to check if an argument is `true` or `false`.
+
+```ruby
+class User::GenerateInvoice < ApplicationService
+  # Arguments
+  arg :user, type: User
+  arg :charge, type: [TrueClass, FalseClass], default: false
+
+  # Steps
+  step :generate_invoice
+  step :charge_user, if: :charge?
+
+  # ...
+end
+```
+
+{% hint style="info" %}
+The predicate methods return `true` or `false` based on Ruby's convention: `nil` and `false` are `false`, everything else is `true`.
+{% endhint %}
+
+## What's Next?
+
+Next step is `steps` (I love this pun). Steps are the building blocks of a service, the methods that do the actual work.
+
+[Next: Steps](steps.md)

data/docs/best-practices.md

@@ -0,0 +1,153 @@
+# Best Practices
+
+This guide explores best practices for building applications with Operandi, keeping things simple and effective.
+
+## Create Top-Level Services
+
+Creating top-level services for your application is highly recommended. This approach helps keep your services small and focused on a single task.
+
+### Application Service
+
+`ApplicationService` serves as the base class for all services in your application. Use it to place common methods, helpers, context arguments, etc. Remember, it should not contain any business logic.
+
+### Create, Update, and Destroy Services
+
+Since create, update, and destroy are fundamental operations in any application, having dedicated services for them is a good idea. This keeps important tasks like authorization, data sanitization, and WebSocket broadcasts close to the core of your application.
+
+- `CreateRecordService` - for creating records
+- `UpdateRecordService` - for updating records
+- `DestroyRecordService` - for destroying records
+
+Think of these services as wrappers around the `ActiveRecord::Base#create`, `#update`, and `#destroy` methods.
+
+### Read Services
+
+Similar to the above services but focused on finding records. Use these for generic authorization, filtering, sorting, pagination, etc.
+
+- `FindRecordService` - for finding a single record
+- `FindAllRecordsService` - for finding multiple records
+
+## Avoid Defining Context Arguments Outside Top-Level Services
+
+Using context arguments outside of top-level services can make your services less modular and more unpredictable. Keep them within the core services for better modularity.
+
+## Keep Services Small
+
+Aim to keep your services small and focused on a single task. Ideally, a service should have no more than 3-5 steps. If a service has more steps, consider splitting it into multiple services.
+
+## Passing Arguments from Controllers
+
+It's a good practice to create a wrapper method to extend arguments passed to the service from the controller.
+
+Consider this example controller:
+
+```ruby
+class PostsController < ApplicationController
+  def index
+    service = Post::FindAll.run(current_user:, current_organization:)
+    render json: service.posts
+  end
+
+  def create
+    service = Post::Create.run(attributes: params[:post], current_user:, current_organization:)
+
+    if service.success?
+      render json: service.post
+    else
+      render json: { errors: service.errors }, status: :unprocessable_entity
+    end
+  end
+
+  def unpublish
+    service = Post::Unpublish.run(id: params[:id], current_user:, current_organization:)
+
+    if service.success?
+      render json: service.post
+    else
+      render json: { errors: service.errors }, status: :unprocessable_entity
+    end
+  end
+
+  # ...
+end
+```
+
+Manually passing `current_user` and `current_organization` each time can be cumbersome. Let's simplify it with a helper method in our `ApplicationController`:
+
+```ruby
+class ApplicationController < ActionController::API
+  private
+
+  def service_args(hash = {})
+    hash.reverse_merge(
+      current_user:,
+      current_organization:,
+    )
+  end
+end
+```
+
+Now we can refactor our controller:
+
+```ruby
+class PostsController < ApplicationController
+  def index
+    service = Post::FindAll.run(service_args)
+    render json: service.posts
+  end
+
+  def create
+    service = Post::Create.run(service_args(attributes: params[:post]))
+
+    if service.success?
+      render json: service.post
+    else
+      render json: { errors: service.errors }, status: :unprocessable_entity
+    end
+  end
+
+  def unpublish
+    service = Post::Unpublish.run(service_args(id: params[:id]))
+
+    if service.success?
+      render json: service.post
+    else
+      render json: { errors: service.errors }, status: :unprocessable_entity
+    end
+  end
+
+  # ...
+end
+```
+
+With this setup, adding a new top-level context argument only requires a change to the `service_args` method in `ApplicationController`.
+
+## Use Concerns
+
+If you have common logic that you want to share between services, use concerns. Avoid putting too much logic into your `ApplicationService` class; it's better to split it into concerns.
+
+For example, create an `AuthorizeUser` concern for authorization logic.
+
+```ruby
+# app/services/concerns/authorize_user.rb
+module AuthorizeUser
+  extend ActiveSupport::Concern
+
+  included do
+    # ...
+  end
+end
+```
+
+```ruby
+# app/services/application_service.rb
+class ApplicationService < Operandi::Base
+  include AuthorizeUser
+end
+```
+
+## What's Next?
+
+Explore practical recipes for common patterns:
+
+[Next: Recipes](recipes.md)