light-services 3.1.1 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a7b40ae2a9930c6ee5831c6d5f64f84aeab383b4f35295a41faf8ae9e0735c82
-  data.tar.gz: 8bb7c192556ec28c904bd931abbf502c2533b39137c2d7d989469c11c61cd70d
+  metadata.gz: eaf377a62c2b05d82860527f64df11bb2239745d2e3b6ab1bc060cddc153effc
+  data.tar.gz: 86eb6a64e0744e6fe2f80b1b4fc06e9d38a740911f88c2b076da9e9a2aab082b
 SHA512:
-  metadata.gz: 671d913a895af97d0c37e45d21e930794317d60fac03bd46df3e43ef3dc6190617b5b5522f445f57143d96434104df636f5d29cf9c6c35d60604f61f54781dfa
-  data.tar.gz: eacef0ee6679653963d6b09a6c660c9ee503e8edc3df04411547f36e07bea91210d2683ff02ed1ee6d96924062c6e1620f95b87959e40ac80e78a211c7048f96
+  metadata.gz: b11918fed0617837cd922a9c7c2181a855844d359bce30aa7f523a828e77e3605522cff64440cf200f90732cb17bbee901305a01920bde54a3cb4777b748a760
+  data.tar.gz: aa78896f8cf22b7e2cf17853700bbe347d0dd364409ee4033064d7c4c5fa57d9377620e5ab6b29473cf15c2894e29b189aa8634e7d71ffda9ad2ca6fa6fce792

data/.cursor/rules/services/RULE.md

@@ -0,0 +1,265 @@
+---
+description: "Rules for managing Light Services - Ruby service objects with arguments, steps, and outputs"
+globs: "**/services/**/*.rb"
+alwaysApply: false
+---
+
+# Light Services Creation Rules
+
+When creating or modifying services that inherit from `Light::Services::Base` or `ApplicationService`, follow these patterns.
+
+## Service Structure
+
+Always structure services in this order:
+1. Configuration (`config`) if needed
+2. Arguments (`arg`)
+3. Steps (`step`)
+4. Outputs (`output`)
+5. Private methods implementing steps
+
+```ruby
+class ModelName::ActionName < ApplicationService
+  # Arguments
+  arg :required_param, type: String
+  arg :optional_param, type: Integer, optional: true, default: 0
+
+  # Steps
+  step :validate
+  step :perform
+  step :cleanup, always: true
+
+  # Outputs
+  output :result, type: Hash
+
+  private
+
+  def validate
+    errors.add(:required_param, "can't be blank") if required_param.blank?
+  end
+
+  def perform
+    self.result = { success: true }
+  end
+
+  def cleanup
+    # Always runs
+  end
+end
+```
+
+## Naming Conventions
+
+- **Class name**: `ModelName::ActionVerb` (e.g., `User::Create`, `Order::Process`)
+- **File path**: `app/services/model_name/action_verb.rb`
+- **Step methods**: Use descriptive verbs (`validate`, `authorize`, `build_record`, `save`)
+
+## Arguments
+
+```ruby
+# Required with type
+arg :user_id, type: Integer
+
+# Optional with default
+arg :notify, type: [TrueClass, FalseClass], default: true
+
+# Context argument (auto-passed to child services)
+arg :current_user, type: User, optional: true, context: true
+
+# Multiple allowed types
+arg :id, type: [String, Integer]
+
+# Proc default (evaluated at runtime)
+arg :created_at, type: Time, default: -> { Time.current }
+```
+
+## Steps
+
+```ruby
+# Basic step
+step :process
+
+# Conditional execution
+step :send_email, if: :should_notify?
+step :skip_audit, unless: :production?
+
+# Always run (even after errors, unless stop! or stop_immediately! are called)
+step :cleanup, always: true
+
+# Insertion points (for inheritance)
+step :log_action, before: :save
+step :broadcast, after: :save
+```
+
+## Outputs
+
+```ruby
+# Required output
+output :user, type: User
+
+# Optional output
+output :metadata, type: Hash, optional: true
+
+# With default
+output :status, type: String, default: "completed"
+```
+
+## Error Handling
+
+```ruby
+# Add error (stops execution of next steps by default)
+errors.add(:email, "is invalid")
+
+# Add to base
+errors.add(:base, "Something went wrong")
+fail!("Something went wrong")  # Shorthand
+
+# Copy from ActiveRecord model
+errors.copy_from(user)
+
+# Stop next steps without error (commits transaction)
+stop!
+
+# Stop with rollback
+fail_immediately!("Critical error")
+```
+
+## Service Chaining
+
+```ruby
+# Run in same context (shared arguments, errors propagate, rollback propagate)
+ChildService.with(self).run(param: value)
+
+# Independent service (separate transaction)
+OtherService.run(param: value)
+```
+
+## Configuration
+
+```ruby
+config use_transactions: true      # Wrap in DB transaction (default)
+config raise_on_error: false       # Raise exception on error
+config break_on_error: true        # Stop on error (default)
+config rollback_on_error: true     # Rollback on error (default)
+```
+
+## Testing Pattern
+
+```ruby
+RSpec.describe ModelName::ActionName do
+  describe ".run" do
+    subject(:service) { described_class.run(params) }
+    let(:params) { { required_param: "value" } }
+
+    context "when successful" do
+      it { is_expected.to be_successful }
+      it { expect(service.result).to eq(expected) }
+    end
+
+    context "when validation fails" do
+      let(:params) { { required_param: "" } }
+
+      it { is_expected.to be_failed }
+      it { is_expected.to have_error_on(:required_param) }
+    end
+  end
+end
+```
+
+## Common Patterns
+
+### CRUD Create
+```ruby
+class User::Create < CreateRecordService
+  private
+
+  def entity_class
+    User
+  end
+
+  def filtered_params
+    params.slice(:name, :email, :role)
+  end
+end
+```
+
+### With Authorization
+```ruby
+step :authorize
+step :perform
+
+def authorize
+  fail!("Not authorized") unless current_user&.admin?
+end
+```
+
+### With Callbacks
+```ruby
+before_service_run :log_start
+after_service_run :log_finish
+on_service_failure :notify_error
+```
+
+## Using dry-types
+
+Light Services supports [dry-types](https://dry-rb.org/gems/dry-types) for advanced type validation and coercion.
+
+### Arguments with dry-types
+
+```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"), default: "pending"
+  
+  # Array types with element validation
+  arg :tags, type: Types::Array.of(Types::String), optional: true
+  
+  # Hash schemas with key transformation
+  arg :metadata, type: Types::Hash.schema(key: Types::String).with_key_transform(&:to_sym), optional: true
+end
+```
+
+### Outputs with dry-types
+
+```ruby
+class AI::Chat < ApplicationService
+  # Strict type validation
+  output :messages, type: Types::Strict::Array.of(Types::Hash)
+  
+  # Coercible types
+  output :total_tokens, type: Types::Coercible::Integer
+  
+  # Constrained types (must be >= 0)
+  output :cost, type: Types::Float.constrained(gteq: 0)
+end
+```
+
+### Coercion Behavior
+
+With coercible types, values are automatically converted:
+
+```ruby
+# String "25" is automatically converted to integer 25
+service = User::Create.run(name: "John", age: "25")
+service.age # => 25 (Integer, not String)
+```
+
+### Common dry-types Patterns
+
+| Type | Description |
+|------|-------------|
+| `Types::Strict::String` | Must be a String, no coercion |
+| `Types::Coercible::Integer` | Coerces to Integer (e.g., "25" → 25) |
+| `Types::String.optional` | String or nil |
+| `Types::String.enum("a", "b")` | Must be one of the listed values |
+| `Types::Array.of(Types::String)` | Array where all elements are Strings |
+| `Types::Hash.schema(key: Type)` | Hash with typed schema |
+| `Types::Float.constrained(gteq: 0)` | Float >= 0 |

data/.cursor/rules/services-rspec/RULE.md

@@ -0,0 +1,354 @@
+---
+description: "Rules for writing RSpec tests for Light Services - testing arguments, steps, outputs, and behavior"
+globs: "**/spec/services/*_spec.rb"
+alwaysApply: false
+---
+
+# Light Services RSpec Testing Rules
+
+When writing RSpec tests for services that inherit from `Light::Services::Base` or `ApplicationService`, follow these patterns.
+
+## Setup
+
+Add to `spec/spec_helper.rb` or `spec/rails_helper.rb`:
+
+```ruby
+require "light/services/rspec"
+```
+
+## Test Structure
+
+Always structure test files in this order:
+1. Describe block with service class
+2. DSL definition tests (arguments, outputs, steps)
+3. Behavior tests (`.run` scenarios)
+4. Edge cases and error handling
+
+```ruby
+# spec/services/model_name/action_name_spec.rb
+RSpec.describe ModelName::ActionName do
+  # DSL Definition Tests
+  describe "arguments" do
+    it { expect(described_class).to define_argument(:required_param).with_type(String) }
+    it { expect(described_class).to define_argument(:optional_param).with_type(Integer).optional.with_default(0) }
+  end
+
+  describe "outputs" do
+    it { expect(described_class).to define_output(:result).with_type(Hash) }
+  end
+
+  describe "steps" do
+    it { expect(described_class).to define_steps_in_order(:validate, :perform, :cleanup) }
+    it { expect(described_class).to define_step(:cleanup).with_always(true) }
+  end
+
+  # Behavior Tests
+  describe ".run" do
+    subject(:service) { described_class.run(params) }
+    let(:params) { { required_param: "value" } }
+
+    context "when successful" do
+      it { is_expected.to be_successful }
+      it { expect(service.result).to eq(expected_result) }
+    end
+
+    context "when validation fails" do
+      let(:params) { { required_param: "" } }
+      it { is_expected.to be_failed }
+      it { is_expected.to have_error_on(:required_param) }
+    end
+  end
+end
+```
+
+## Naming Conventions
+
+- **File path**: `spec/services/model_name/action_name_spec.rb`
+- **Describe block**: Use the service class name directly
+- **Context blocks**: Start with "when" or "with" to describe conditions
+- **It blocks**: Be specific about what is being tested
+
+## DSL Matchers
+
+### Arguments
+
+```ruby
+# Basic argument
+it { expect(described_class).to define_argument(:id) }
+
+# With type (single or multiple)
+it { expect(described_class).to define_argument(:id).with_type([String, Integer]) }
+
+# Optional with default
+it { expect(described_class).to define_argument(:status).optional.with_default("pending") }
+
+# Context argument
+it { expect(described_class).to define_argument(:current_user).with_context }
+```
+
+### Outputs
+
+```ruby
+# Basic output
+it { expect(described_class).to define_output(:user) }
+
+# With type
+it { expect(described_class).to define_output(:user).with_type(User) }
+
+# Optional with default
+it { expect(described_class).to define_output(:count).optional.with_default(0) }
+```
+
+### Steps
+
+```ruby
+# Basic step
+it { expect(described_class).to define_step(:validate) }
+
+# With always flag
+it { expect(described_class).to define_step(:cleanup).with_always(true) }
+
+# Conditional steps
+it { expect(described_class).to define_step(:notify).with_if(:should_notify?) }
+it { expect(described_class).to define_step(:skip_audit).with_unless(:production?) }
+
+# Multiple steps in order
+it { expect(described_class).to define_steps_in_order(:validate, :process, :save) }
+```
+
+## Behavior Testing
+
+### Success Cases
+
+```ruby
+describe ".run" do
+  subject(:service) { described_class.run(params) }
+  let(:params) { { name: "John", email: "john@example.com" } }
+
+  it { is_expected.to be_successful }
+  it { expect(service.user).to be_persisted }
+  it { expect(service.user.name).to eq("John") }
+end
+```
+
+### Failure Cases
+
+```ruby
+context "when validation fails" do
+  let(:params) { { name: "", email: "" } }
+
+  it { is_expected.to be_failed }
+  it { is_expected.to have_error_on(:name) }
+  it { is_expected.to have_error_on(:email).with_message("can't be blank") }
+  it { is_expected.to have_errors_on(:name, :email) }
+end
+```
+
+### Warnings
+
+```ruby
+it { expect(service.warnings?).to be true }
+it { is_expected.to have_warning_on(:format).with_message("format is deprecated") }
+```
+
+### run! vs run
+
+```ruby
+# .run returns failed service
+it { expect(described_class.run(amount: -100)).to be_failed }
+
+# .run! raises exception
+it { expect { described_class.run!(amount: -100) }.to raise_error(Light::Services::Error, /must be positive/) }
+```
+
+### Config Overrides
+
+```ruby
+# With raise_on_error
+expect { described_class.run({ invalid: true }, { raise_on_error: true }) }
+  .to raise_error(Light::Services::Error)
+
+# With use_transactions: false
+service = described_class.with(use_transactions: false).run(params)
+```
+
+## Database Testing
+
+```ruby
+# Record creation
+expect { described_class.run(params) }.to change(User, :count).by(1)
+expect(service.user).to be_persisted
+
+# Transaction rollback on failure
+allow_any_instance_of(ChildService).to receive(:perform) do |svc|
+  svc.errors.add(:base, "Simulated failure")
+end
+expect { described_class.run(params) }.not_to change(Order, :count)
+```
+
+## Service Chaining
+
+```ruby
+# Verify context sharing
+expect(ChildService).to receive(:with).and_call_original
+described_class.run(current_user: current_user, data: data)
+
+# Error propagation from child
+allow_any_instance_of(ChildService).to receive(:validate) { |svc| svc.fail!("Child error") }
+expect(described_class.run(current_user: current_user, data: data))
+  .to have_error_on(:base).with_message("Child error")
+```
+
+## Conditional Steps
+
+```ruby
+# When condition is true
+expect { described_class.run(send_notification: true, email: "x@example.com") }
+  .to have_enqueued_mail(UserMailer, :notification)
+
+# When condition is false
+expect { described_class.run(send_notification: false, email: "x@example.com") }
+  .not_to have_enqueued_mail(UserMailer, :notification)
+```
+
+## Early Exit (stop!)
+
+```ruby
+existing_user = create(:user, email: "exists@example.com")
+service = described_class.run(email: existing_user.email)
+
+expect { service }.not_to change(User, :count)
+expect(service.user).to eq(existing_user)
+expect(service).to be_successful
+expect(service.stopped?).to be true
+```
+
+## Argument Validation
+
+```ruby
+# Required argument nil
+expect { described_class.run(name: nil) }.to raise_error(Light::Services::ArgTypeError)
+
+# Wrong type
+expect { described_class.run(name: 123) }.to raise_error(Light::Services::ArgTypeError, /must be a String/)
+
+# Optional accepts nil
+expect(described_class.run(name: "John", nickname: nil)).to be_successful
+
+# Default values
+expect(described_class.run(name: "John").status).to eq("pending")
+```
+
+## External Services
+
+```ruby
+let(:stripe_client) { instance_double(Stripe::PaymentIntent, id: "pi_123") }
+
+before { allow(Stripe::PaymentIntent).to receive(:create).and_return(stripe_client) }
+
+it "processes payment" do
+  service = described_class.run(amount: 1000, card_token: "tok_visa")
+  expect(service).to be_successful
+  expect(service.payment_intent_id).to eq("pi_123")
+end
+
+context "when external fails" do
+  before { allow(Stripe::PaymentIntent).to receive(:create).and_raise(Stripe::CardError.new("Card declined", nil, nil)) }
+
+  it { expect(service).to be_failed }
+  it { expect(service).to have_error_on(:payment).with_message("Card declined") }
+end
+```
+
+## Optional Tracking
+
+### Step Execution
+
+```ruby
+# app/services/application_service.rb
+class ApplicationService < Light::Services::Base
+  output :executed_steps, type: Array, default: -> { [] }
+  after_step_run { |service, step| service.executed_steps << step }
+end
+```
+
+### Callback Tracking
+
+```ruby
+class ApplicationService < Light::Services::Base
+  output :callback_log, type: Array, default: -> { [] }
+  before_service_run { |s| s.callback_log << :before_service_run }
+  after_service_run  { |s| s.callback_log << :after_service_run }
+  on_service_success { |s| s.callback_log << :on_service_success }
+  on_service_failure { |s| s.callback_log << :on_service_failure }
+end
+```
+
+## Shared Examples
+
+### Create Service
+
+```ruby
+RSpec.shared_examples "a create service" do |model_class|
+  let(:valid_attributes) { attributes_for(model_class.name.underscore.to_sym) }
+  let(:current_user) { create(:user) }
+
+  it { expect { described_class.run(current_user: current_user, attributes: valid_attributes) }.to change(model_class, :count).by(1) }
+  it { expect(described_class.run(current_user: current_user, attributes: valid_attributes).record).to be_persisted }
+  it { expect(described_class.run(current_user: current_user, attributes: valid_attributes)).to be_successful }
+end
+```
+
+### Authorized Service
+
+```ruby
+RSpec.shared_examples "an authorized service" do
+  context "without current_user" do
+    let(:current_user) { nil }
+    it { is_expected.to be_failed }
+    it { is_expected.to have_error_on(:authorization) }
+  end
+
+  context "with unauthorized user" do
+    let(:current_user) { create(:user, role: :guest) }
+    it { is_expected.to be_failed }
+    it { is_expected.to have_error_on(:authorization) }
+  end
+end
+```
+
+## Test Helpers
+
+```ruby
+module ServiceHelpers
+  def expect_service_success(service)
+    expect(service).to be_successful, -> { "Expected success but got errors: #{service.errors.to_h}" }
+  end
+
+  def expect_service_failure(service, key = nil)
+    expect(service).to be_failed
+    expect(service.errors[key]).to be_present if key
+  end
+end
+
+RSpec.configure { |config| config.include ServiceHelpers, type: :service }
+```
+
+## Common Matchers Reference
+
+| Matcher | Description |
+|---------|-------------|
+| `be_successful` | Service completed without errors |
+| `be_failed` | Service has errors |
+| `have_error_on(:key)` | Has error on specific key |
+| `have_error_on(:key).with_message(msg)` | Error with specific message |
+| `have_errors_on(:key1, :key2)` | Has errors on multiple keys |
+| `have_warning_on(:key)` | Has warning on specific key |
+| `define_argument(:name)` | Service defines argument |
+| `define_output(:name)` | Service defines output |
+| `define_step(:name)` | Service defines step |
+| `define_steps(:a, :b, :c)` | Service defines all steps (any order) |
+| `define_steps_in_order(:a, :b, :c)` | Service defines steps in order |
+| `execute_step(:name)` | Step was executed (tracking required) |
+| `skip_step(:name)` | Step was skipped (tracking required) |
+| `trigger_callback(:name)` | Callback was triggered (tracking required) |

data/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 3.2.0 (2025-12-14)
+
+### Added
+
+- Add Cursor rules
+- Add `successful?` as an alias for `success?`
+- Add RuboCop cop `PreferFailMethod` to detect `errors.add(:base, "message")` and suggest using `fail!("message")` instead
+
+### Breaking changes
+
+- Service runs steps with `always: true` after `fail_immediately!` was called
+
+## 3.1.2 (2025-12-13)
+
+### Added
+
+- Add `fail!` and `fail_immediately!` helpers
+
+### Changed
+
+- Split `config.require_type` into `config.require_arg_type` and `config.require_output_type`
+
 ## 3.1.1 (2025-12-13)
 
 ### Added
@@ -10,7 +32,7 @@
 
 ### Breaking changes
 
-- Enforce arguments and output types by default. Add `config.require_type = false` to your config to disable this behavior.
+- Enforce arguments and output types by default. Use `config.require_arg_type = false` and `config.require_output_type = false` to disable this behavior. The convenience setter `config.require_type = false` sets both options at once for backward compatibility.
 
 ### Added
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    light-services (3.1.0)
+    light-services (3.2.0)
 
 GEM
   remote: https://rubygems.org/
@@ -33,7 +33,7 @@ GEM
     bigdecimal (3.3.1)
     codecov (0.6.0)
       simplecov (>= 0.15, < 0.22)
-    concurrent-ruby (1.3.5)
+    concurrent-ruby (1.3.6)
     connection_pool (2.5.5)
     database_cleaner-active_record (2.2.2)
       activerecord (>= 5.a)

data/docs/arguments.md

@@ -66,13 +66,13 @@ class MyService < ApplicationService
 end
 ```
 
-To disable type enforcement for a specific service:
+To disable type enforcement for arguments in a specific service:
 
 ```ruby
 class LegacyService < ApplicationService
-  config require_type: false
+  config require_arg_type: false
   
-  arg :name              # Allowed when require_type is disabled
+  arg :name              # Allowed when require_arg_type is disabled
 end
 ```