light-services 2.2.1 → 3.1.0

data/README.md

@@ -1,36 +1,50 @@
 # 🚀 Light Services
 
-Light Services is a simple yet powerful way to organize your business logic. This Ruby gem helps you build services that are easy to test, maintain, and understand.
+Light Services is a simple yet powerful way to organize business logic in Ruby applications. Build services that are easy to test, maintain, and understand.
 
 ![GitHub CI](https://github.com/light-ruby/light-services/actions/workflows/ci.yml/badge.svg)
 [![Codecov](https://codecov.io/gh/light-ruby/light-services/graph/badge.svg?token=IGJNZ2BQ26)](https://codecov.io/gh/light-ruby/light-services)
 
+[Get started with Quickstart](https://light-services.kodkod.me/quickstart)
+
 ## Features
 
-- 🧩 **Simple**: Define your service as a class with `arguments`, `steps`, and `outputs`
-- 🎢 **Transactions**: Automatically rollback database changes if any step fails
-- 👵 **Inheritance**: Inherit from other services to reuse logic seamlessly
-- 🚨 **Error Handling**: Collect errors from steps and handle them your way
-- ⛓️ **Context**: Run multiple services sequentially within the same context
-- 🤔 **Framework Agnostic**: Compatible with Rails, Hanami, or any Ruby framework
-- 🏗️ **Modularity**: Isolate and test your services with ease
-- 🐛 **100% Test Coverage**: Bugs are not welcome here!
-- 🛡️ **Battle-Tested**: In production use since 2017
+- ✨ **Simple**: Define your service as a class with `arguments`, `steps`, and `outputs`
+- 📦 **No runtime dependencies**: Works stand-alone without requiring external gems at runtime
+- 🔄 **Transactions**: Automatically rollback database changes if any step fails
+- 🧬 **Inheritance**: Inherit from other services to reuse logic seamlessly
+- ⚠️ **Error Handling**: Collect errors from steps and handle them your way
+- 🔗 **Context**: Run multiple services sequentially within the same context
+- 🧪 **RSpec Matchers**: Built-in RSpec matchers for expressive service tests
+- 🌐 **Framework Agnostic**: Compatible with Rails, Hanami, or any Ruby framework
+- 🧩 **Modularity**: Isolate and test your services with ease
+- ✅ **100% Test Coverage**: Thoroughly tested and reliable
+- ⚔️ **Battle-Tested**: In production use since 2017
+
+## Installation
+
+```ruby
+gem "light-services", "~> 3.0"
+```
+
+```bash
+rails generate light_services:install
+```
 
 ## Simple Example
 
 ```ruby
 class GreetService < Light::Services::Base
   # Arguments
-  arg :name
-  arg :age
+  arg :name, type: String
+  arg :age, type: Integer
 
   # Steps
   step :build_message
   step :send_message
 
   # Outputs
-  output :message
+  output :message, type: String
 
   private
 
@@ -44,14 +58,14 @@ class GreetService < Light::Services::Base
 end
 ```
 
-## Advanced Example
+## Advanced Example (with dry-types and conditions)
 
 ```ruby
 class User::ResetPassword < Light::Services::Base
-  # Arguments
-  arg :user, type: User, optional: true
-  arg :email, type: :string, optional: true
-  arg :send_email, type: :boolean, default: true
+  # Arguments with dry-types for advanced validation and coercion
+  arg :user, type: Types.Instance(User), optional: true
+  arg :email, type: Types::Coercible::String, optional: true
+  arg :send_email, type: Types::Params::Bool, default: true
 
   # Steps
   step :validate
@@ -60,9 +74,9 @@ class User::ResetPassword < Light::Services::Base
   step :save_reset_token
   step :send_reset_email, if: :send_email?
 
-  # Outputs
-  output :user, type: User
-  output :reset_token, type: :string
+  # Outputs with dry-types
+  output :user, type: Types.Instance(User)
+  output :reset_token, type: Types::Strict::String
 
   private
 
@@ -96,6 +110,55 @@ class User::ResetPassword < Light::Services::Base
 end
 ```
 
+[Get started with Light Services](https://light-services.kodkod.me/quickstart)
+
+## Rails Generators
+
+Light Services includes Rails generators to help you quickly set up and create services in your Rails application.
+
+### Install Generator
+
+Set up Light Services in your Rails application:
+
+```bash
+bin/rails generate light_services:install
+```
+
+This creates:
+- `app/services/application_service.rb` - Base service class for your application
+- `config/initializers/light_services.rb` - Configuration file
+- `spec/services/application_service_spec.rb` - RSpec test file (if RSpec is detected)
+
+**Options:**
+- `--skip-initializer` - Skip creating the initializer file
+- `--skip-spec` - Skip creating the spec file
+
+### Service Generator
+
+Create a new service class:
+
+```bash
+# Basic service
+bin/rails generate light_services:service user/create
+
+# Service with predefined structure
+bin/rails generate light_services:service CreateOrder \
+  --args=user product \
+  --steps=validate process \
+  --outputs=order
+```
+
+This creates:
+- `app/services/user/create.rb` - Service class file
+- `spec/services/user/create_spec.rb` - RSpec test file (if RSpec is detected)
+
+**Options:**
+- `--args` - List of arguments for the service (e.g., `--args=user product`)
+- `--steps` - List of steps for the service (e.g., `--steps=validate process`)
+- `--outputs` - List of outputs for the service (e.g., `--outputs=result`)
+- `--skip-spec` - Skip creating the spec file
+- `--parent` - Parent class (default: ApplicationService)
+
 ## Documentation
 
 You can find the full documentation at [light-services.kodkod.me](https://light-services.kodkod.me).

data/docs/arguments.md

@@ -0,0 +1,290 @@
+# 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 a specific service:
+
+```ruby
+class LegacyService < ApplicationService
+  config require_type: false
+  
+  arg :name              # Allowed when require_type is disabled
+end
+```
+
+See the [Configuration documentation](configuration.md) for more details.
+
+### dry-types Support
+
+Light Services supports [dry-types](https://dry-rb.org/gems/dry-types) for advanced type validation and coercion. When using dry-types, values are automatically coerced to the expected type.
+
+First, set up your types module:
+
+```ruby
+require "dry-types"
+
+module Types
+  include Dry.Types()
+end
+```
+
+Then use dry-types in your service arguments:
+
+```ruby
+class User::Create < ApplicationService
+  # Strict types - must match exactly
+  arg :name, type: Types::Strict::String
+  
+  # Coercible types - automatically convert values
+  arg :age, type: Types::Coercible::Integer
+  
+  # Constrained types - add validation rules
+  arg :email, type: Types::String.constrained(format: /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z]+)*\.[a-z]+\z/i)
+  
+  # Enum types - restrict to specific values
+  arg :status, type: Types::String.enum("active", "inactive", "pending")
+  
+  # Array types with element validation
+  arg :tags, type: Types::Array.of(Types::String)
+  
+  # Hash schemas
+  arg :metadata, type: Types::Hash.schema(key: Types::String)
+end
+```
+
+**Coercion Example:**
+
+```ruby
+# With coercible types, string "25" is automatically converted to integer 25
+service = User::Create.run(name: "John", age: "25")
+service.age # => 25 (Integer, not String)
+```
+
+## 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 < Light::Services::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 `arguments`
+
+For dynamic access or to avoid conflicts, use the `arguments` method.
+
+```ruby
+class HappyBirthdayService < ApplicationService
+  # Arguments
+  arg :name, type: String
+  arg :age, type: Integer
+
+  # Steps
+  step :greet
+
+  private
+
+  def greet
+    name = arguments[:name] # or arguments.get(:name)
+    age = arguments[:age] # or arguments.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 Light Services, 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 < Light::Services::Base
+  include AuthorizeUser
+end
+```
+
+## What's Next?
+
+Explore practical recipes for common patterns:
+
+[Next: Recipes](recipes.md)