light-services 2.2 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a5ccceda02f284ebdd089f5b2ecc556e5a8cdea068a94d84e0b59d4cebb71d72
-  data.tar.gz: dd35a45b128b94f31cbf4b7bd84afce58fe50f416ef235dae181542c478f93de
+  metadata.gz: a45a0a0ba2e870c7188f55865004d697646da536e3cecb05b9b0eb30fda9651d
+  data.tar.gz: 4ad5df86f1a1ff129ac85f3f2ed1ecda11466d52c8639fbbfda410951e8dc8c5
 SHA512:
-  metadata.gz: 45e62c84a24199d47085e3f6aaddec90612df913ace4a601be57c6cb8d1df473fdd231980de92b3b5f54b1043c5a6583a8fede03d56dfef14f5cca1261dadef2
-  data.tar.gz: ed4da976538c4ea372bfc1c8f8c5e137f4c9653a71e47cda425f8e06fe4c7d9d66ff3550cf2e9681aad2623286879bb4ee9d0bb1c0d37a6612c1bc236a0614f5
+  metadata.gz: 75bbc704971352293401dfcfaf0191aceb3d19ebfd150ce4db1aac0140b4044ee65942ff205484379a7169342298a7164fb76f1fbbf1907d3bb33d99485d1b03
+  data.tar.gz: 231a847015fcabfa0373693c0f13ac31d2ea2d636aae355b5ec023838efd3a15ae0b4baba0d7604f3c8980272419078268d155cd9d5b4ca7ca9e22f976667c62

data/.github/config/rubocop_linter_action.yml

@@ -1,5 +1,5 @@
 versions:
-  - rubocop: "1.64"
-  - rubocop-performance: "1.21"
-  - rubocop-rake: "0.6"
-  - rubocop-rspec: "2.31"
+  - rubocop: "1.81.7"
+  - rubocop-performance: "1.26.1"
+  - rubocop-rake: "0.7.1"
+  - rubocop-rspec: "3.8.0"

data/.github/workflows/ci.yml

@@ -2,24 +2,24 @@ name: CI
 on: push
 
 jobs:
-#  rubocop:
-#    name: Rubocop
-#    runs-on: ubuntu-latest
-#    steps:
-#      - name: Git Checkout
-#        uses: actions/checkout@v2
-#
-#      - name: Rubocop
-#        uses: andrewmcodes/rubocop-linter-action@v3.2.0
-#        env:
-#          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+  rubocop:
+    name: Rubocop
+    runs-on: ubuntu-latest
+    steps:
+      - name: Git Checkout
+        uses: actions/checkout@v2
+
+      - name: Rubocop
+        uses: andrewmcodes/rubocop-linter-action@v3.2.0
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
   rspec:
     name: RSpec
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        ruby: [3.0, 3.1, 3.2, 3.3, head, debug]
+        ruby: [3.2, 3.3, 3.4, head, debug]
     steps:
       - name: Git Checkout
         uses: actions/checkout@v2

data/.gitignore

@@ -15,6 +15,11 @@
 # Ignore IDE files
 /.idea
 *.iml
+.vscode/settings.json
 
 # Ignore gem files
 *.gem
+
+# Ignore mac files
+*.DS_Store
+

data/.rubocop.yml

@@ -1,34 +1,104 @@
-require:
+plugins:
   - rubocop-rake
   - rubocop-rspec
   - rubocop-performance
 
 AllCops:
+  DisplayCopNames: true
+  DisplayStyleGuide: true
   NewCops: enable
+  TargetRubyVersion: 3
+
+Layout/FirstArrayElementIndentation:
+  EnforcedStyle: consistent
+
+Layout/FirstHashElementIndentation:
+  EnforcedStyle: consistent
 
 Layout/MultilineMethodCallIndentation:
   EnforcedStyle: indented
 
+Layout/SpaceInsideArrayLiteralBrackets:
+  EnforcedStyle: no_space
+
+Lint/EmptyFile:
+  Enabled: true
+
+Metrics/AbcSize:
+  Exclude:
+    - lib/light/services/dsl/steps_dsl.rb
+    - lib/light/services/messages.rb
+  Max: 20
+
 Metrics/BlockLength:
   Exclude:
     - spec/**/*_spec.rb
 
+Metrics/ClassLength:
+  Max: 150
+
+Metrics/CyclomaticComplexity:
+  Max: 10
+
+Metrics/MethodLength:
+  Max: 20
+
+Metrics/PerceivedComplexity:
+  Max: 10
+
+Naming/PredicatePrefix:
+  Enabled: false
+
+RSpec/ExampleLength:
+  Max: 20
+
+RSpec/MultipleDescribes:
+  Enabled: false
+
+RSpec/MultipleExpectations:
+  Max: 10
+
+RSpec/NestedGroups:
+  Max: 5
+
 Security/Eval:
   Exclude:
     - spec/light/services/error_spec.rb
 
-Style/Documentation:
-  Enabled: false
+Style/ClassAndModuleChildren:
+  Exclude:
+    - spec/data/services/**/*.rb
 
 Style/ClassVars:
   Enabled: false
 
-Style/StringLiterals:
-  EnforcedStyle: double_quotes
+Style/ConditionalAssignment:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
 
 Style/GuardClause:
   Enabled: false
 
-Style/ClassAndModuleChildren:
+Style/OptionalBooleanParameter:
   Exclude:
-    - spec/data/services/**/*.rb
+    - lib/light/services/rspec/matchers/**/*.rb
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/SymbolArray:
+  EnforcedStyle: brackets
+
+Style/TrailingCommaInArguments:
+  EnforcedStyleForMultiline: diff_comma
+
+Style/TrailingCommaInArrayLiteral:
+  EnforcedStyleForMultiline: consistent_comma
+
+Style/TrailingCommaInHashLiteral:
+  EnforcedStyleForMultiline: consistent_comma
+
+Style/WordArray:
+  EnforcedStyle: brackets

data/CHANGELOG.md

@@ -1 +1,24 @@
 # Changelog
+
+## 3.0.0 (2025-12-12)
+
+### Breaking changes
+
+- Removed support for symbol types (e.g., `:array`, `:hash`, `:boolean`). Use Ruby classes (e.g., `Array`, `Hash`, `[TrueClass, FalseClass]`) or dry-types
+- Removed `benchmark: true` option
+- Removed `verbose: true` option
+- Bumped minimum supported Ruby version to **3.0**.
+- Removed `errors.copy_to`
+
+### Added
+
+- Output type validation
+- dry-types support for arguments and outputs (with coercion and constraints)
+- Callback system (service + step callbacks)
+- Built-in RSpec matchers for services
+- Name validation for arguments, steps, and outputs
+- `run` method fallback when no steps are defined
+
+### Documentation
+
+- Documentation moved into this repository and refreshed to match v3 behavior

data/CLAUDE.md

@@ -0,0 +1,139 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## About Light Services
+
+Light Services is a Ruby gem providing a service architecture pattern for organizing business logic. Services are defined as classes with `arguments`, `steps`, and `outputs`, featuring transactions, inheritance, error handling, and context sharing.
+
+## Development Commands
+
+### Testing
+```bash
+# Run all tests
+bundle exec rspec
+
+# Run specific test file
+bundle exec rspec spec/path/to/file_spec.rb
+
+# Run with coverage (uses SimpleCov)
+bundle exec rspec
+```
+
+### Linting
+```bash
+# Run RuboCop linter
+bundle exec rubocop
+
+# Auto-fix RuboCop issues
+bundle exec rubocop -a
+```
+
+### Build and Release
+```bash
+# Build gem
+bundle exec rake build
+
+# Default task (runs tests)
+bundle exec rake
+```
+
+## Architecture
+
+### Core Components
+
+1. **Base Service (`lib/light/services/base.rb:15`)**
+   - Main service class that all services inherit from
+   - Handles service lifecycle: initialization, execution, callbacks, error management
+   - Provides DSL for defining arguments, steps, and outputs
+   - Manages transactions and error propagation to parent services
+
+2. **Callbacks System (`lib/light/services/callbacks.rb:5`)**
+   - Supports service and step-level callbacks
+   - Events: `before_service_run`, `after_service_run`, `around_service_run`, `on_service_success`, `on_service_failure`
+   - Step events: `before_step_run`, `after_step_run`, `around_step_run`, `on_step_success`, `on_step_failure`
+
+3. **Settings**
+   - **Step (`lib/light/services/settings/step.rb:7`)**: Handles step execution with conditional logic (`if`, `unless`, `always`)
+   - **Field (`lib/light/services/settings/field.rb`)**: Manages argument and output validation and type checking
+
+4. **Messages System (`lib/light/services/messages.rb`)**
+   - Collects errors and warnings with options for breaking, raising, or rolling back
+   - Supports copying messages between parent and child services
+
+5. **Collection (`lib/light/services/collection.rb`)**
+   - Manages arguments and outputs as collections with validation and defaults
+   - Supports dry-types for advanced type validation and coercion
+
+### Service DSL
+
+Services use a declarative DSL:
+```ruby
+class ExampleService < Light::Services::Base
+  # Define input arguments
+  arg :name, type: String
+  arg :age, type: Integer, optional: true, default: 25
+
+  # Define execution steps
+  step :validate_input
+  step :process_data, if: :should_process?
+  step :cleanup, always: true
+
+  # Define outputs
+  output :result, type: Hash
+
+  private
+
+  def validate_input
+    errors.add(:name, "required") if name.nil? || name.strip.empty?
+  end
+
+  def process_data
+    self.result = { name: name, age: age }
+  end
+
+  def cleanup
+    # Runs regardless of errors/warnings, unless done! was called
+  end
+
+  def should_process?
+    !(name.nil? || name.strip.empty?)
+  end
+end
+```
+
+### Service Execution
+
+- Services can be run with `.run(args)` or `.run!(args)` (raises on error)
+- Use `.with(service_or_context)` to chain services with shared context
+- Transactions automatically rollback on errors when `use_transactions: true`
+- Steps run sequentially, stopping on errors unless `always: true`
+
+### Error Handling
+
+- Errors collected in `@errors` message collection
+- Supports `break_on_error`, `raise_on_error`, `rollback_on_error` configuration
+- Warnings work similarly with `@warnings` collection
+- Parent services can inherit child errors/warnings based on configuration
+
+### Testing Patterns
+
+- Services are tested using RSpec with database transactions
+- Use `DatabaseCleaner` for test isolation
+- Mock database models and external dependencies
+- Test both success and failure scenarios
+- Validate arguments, outputs, and error conditions
+
+## Configuration
+
+### RuboCop Rules
+- Target Ruby version: 2.7+
+- Method length max: 20 lines
+- Uses double quotes for strings
+- Enables trailing commas for multiline structures
+- Disables documentation requirements and guard clauses
+
+### Database Support
+- Optional ActiveRecord integration for transactions
+- Uses SQLite3 for testing
+- Database cleaner ensures test isolation

data/Gemfile

@@ -5,17 +5,22 @@ source "https://rubygems.org"
 gemspec
 
 group :test do
-  gem "activerecord", "~> 8.1"
-  gem "database_cleaner-active_record", "~> 2.2"
-  gem "sqlite3", "~> 2.8"
+  # Optional type system support
+  gem "dry-types", "~> 1.0"
 
-  gem "codecov", "~> 0.6.0"
-  gem "rake", "~> 13.3"
-  gem "rspec", "~> 3.13"
-  gem "simplecov", "~> 0.21"
+  gem "activerecord", "< 8"
+  gem "connection_pool", "< 3"
+  gem "database_cleaner-active_record"
+  gem "sqlite3"
 
-  gem "rubocop", "~> 1.81",             require: false
-  gem "rubocop-performance", "~> 1.26", require: false
-  gem "rubocop-rake", "~> 0.7.0",       require: false
-  gem "rubocop-rspec", "~> 3.8",        require: false
+  gem "codecov"
+  gem "rake"
+  gem "rspec"
+  gem "rspec-benchmark"
+  gem "simplecov"
+
+  gem "rubocop"
+  gem "rubocop-performance"
+  gem "rubocop-rake"
+  gem "rubocop-rspec"
 end

data/Gemfile.lock

@@ -1,39 +1,40 @@
 PATH
   remote: .
   specs:
-    light-services (2.2)
-      benchmark (>= 0.5)
+    light-services (3.0.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    activemodel (8.1.1)
-      activesupport (= 8.1.1)
-    activerecord (8.1.1)
-      activemodel (= 8.1.1)
-      activesupport (= 8.1.1)
+    activemodel (7.2.3)
+      activesupport (= 7.2.3)
+    activerecord (7.2.3)
+      activemodel (= 7.2.3)
+      activesupport (= 7.2.3)
       timeout (>= 0.4.0)
-    activesupport (8.1.1)
+    activesupport (7.2.3)
       base64
+      benchmark (>= 0.3)
       bigdecimal
       concurrent-ruby (~> 1.0, >= 1.3.1)
       connection_pool (>= 2.2.5)
       drb
       i18n (>= 1.6, < 2)
-      json
       logger (>= 1.4.2)
       minitest (>= 5.1)
       securerandom (>= 0.3)
       tzinfo (~> 2.0, >= 2.0.5)
-      uri (>= 0.13.1)
     ast (2.4.3)
     base64 (0.3.0)
     benchmark (0.5.0)
+    benchmark-malloc (0.2.0)
+    benchmark-perf (0.6.0)
+    benchmark-trend (0.4.0)
     bigdecimal (3.3.1)
     codecov (0.6.0)
       simplecov (>= 0.15, < 0.22)
     concurrent-ruby (1.3.5)
-    connection_pool (2.5.4)
+    connection_pool (2.5.5)
     database_cleaner-active_record (2.2.2)
       activerecord (>= 5.a)
       database_cleaner-core (~> 2.0)
@@ -41,14 +42,31 @@ GEM
     diff-lcs (1.6.2)
     docile (1.4.1)
     drb (2.2.3)
+    dry-core (1.1.0)
+      concurrent-ruby (~> 1.0)
+      logger
+      zeitwerk (~> 2.6)
+    dry-inflector (1.2.0)
+    dry-logic (1.6.0)
+      bigdecimal
+      concurrent-ruby (~> 1.0)
+      dry-core (~> 1.1)
+      zeitwerk (~> 2.6)
+    dry-types (1.8.3)
+      bigdecimal (~> 3.0)
+      concurrent-ruby (~> 1.0)
+      dry-core (~> 1.0)
+      dry-inflector (~> 1.0)
+      dry-logic (~> 1.4)
+      zeitwerk (~> 2.6)
     i18n (1.14.7)
       concurrent-ruby (~> 1.0)
-    json (2.16.0)
+    json (2.18.0)
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
     logger (1.7.0)
     mini_portile2 (2.8.9)
-    minitest (5.26.1)
+    minitest (5.27.0)
     parallel (1.27.0)
     parser (3.3.10.0)
       ast (~> 2.4.1)
@@ -62,6 +80,11 @@ GEM
       rspec-core (~> 3.13.0)
       rspec-expectations (~> 3.13.0)
       rspec-mocks (~> 3.13.0)
+    rspec-benchmark (0.6.0)
+      benchmark-malloc (~> 0.2)
+      benchmark-perf (~> 0.6)
+      benchmark-trend (~> 0.4)
+      rspec (>= 3.0)
     rspec-core (3.13.6)
       rspec-support (~> 3.13.0)
     rspec-expectations (3.13.5)
@@ -103,32 +126,35 @@ GEM
       simplecov_json_formatter (~> 0.1)
     simplecov-html (0.13.2)
     simplecov_json_formatter (0.1.4)
-    sqlite3 (2.8.0)
+    sqlite3 (2.8.1)
       mini_portile2 (~> 2.8.0)
-    timeout (0.4.4)
+    timeout (0.5.0)
     tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
     unicode-display_width (3.2.0)
       unicode-emoji (~> 4.1)
     unicode-emoji (4.1.0)
-    uri (1.1.1)
+    zeitwerk (2.7.3)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
-  activerecord (~> 8.1)
-  codecov (~> 0.6.0)
-  database_cleaner-active_record (~> 2.2)
+  activerecord (< 8)
+  codecov
+  connection_pool (< 3)
+  database_cleaner-active_record
+  dry-types (~> 1.0)
   light-services!
-  rake (~> 13.3)
-  rspec (~> 3.13)
-  rubocop (~> 1.81)
-  rubocop-performance (~> 1.26)
-  rubocop-rake (~> 0.7.0)
-  rubocop-rspec (~> 3.8)
-  simplecov (~> 0.21)
-  sqlite3 (~> 2.8)
+  rake
+  rspec
+  rspec-benchmark
+  rubocop
+  rubocop-performance
+  rubocop-rake
+  rubocop-rspec
+  simplecov
+  sqlite3
 
 BUNDLED WITH
    2.5.10

data/README.md

@@ -1,21 +1,35 @@
 # 🚀 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
 
@@ -50,8 +64,8 @@ end
 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
+  arg :email, type: String, optional: true
+  arg :send_email, type: [TrueClass, FalseClass], default: true
 
   # Steps
   step :validate
@@ -62,7 +76,7 @@ class User::ResetPassword < Light::Services::Base
 
   # Outputs
   output :user, type: User
-  output :reset_token, type: :string
+  output :reset_token, type: 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).