service_base 1.0.3 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 17af4f8d7a5f86ee24adbbbba2118e7b47134f2730e4e04fb0c0107c86cfa168
-  data.tar.gz: 1ad5a04d75c99bbc061d1ab53ce67d0d8864c132b8be85ebeb4da3b1f759d996
+  metadata.gz: 0f709f1e0e410fab6ddd7be7497a63b157433a8137d29a315039bde500c181d4
+  data.tar.gz: 436d06c1d55ac4c3e4d5b803a370e26976201bc88c2c934de5ac43f89275b52d
 SHA512:
-  metadata.gz: 559196375ec8a48520b076feb989287c43e84cf7a759b91d0db753448f9199fe02f3febff0a06e9d797523f5774e58d26e4745f921820f94298519873d4a5732
-  data.tar.gz: ec37a4775094ebf67fa9e09b3db800206f31f8cfa5775866675f0213f9f188f5b228bc503e6e2ff7b3827bcfae039cc1dc0285796e96831ef990f182174a5709
+  metadata.gz: f2dc449665465e7952604be4700330eedd024681334df857caca45e471a7649bea92a1eaec4a526257d6c1d6d84a6ae30a08009d624f93b98b95085e88b4e266
+  data.tar.gz: fae721976b7ef7e82e2d66c18ca4718e5d25673148e98effcf41498d7bea351c52b7d7cbcb4029a13dac73e804f0f00a6c49786b2c067c080813e0e2d81b9ebd

data/CHANGELOG.md

@@ -0,0 +1,87 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.1.0] - 2025-09-09
+
+### Added
+- Support for parameter-less failure and success handlers in ServiceSupport test helpers
+- Flexible block parameter handling that works with both `on.failure { |error| ... }` and `on.failure do ... end` patterns
+- Comprehensive test coverage for parameter-less handler scenarios
+- New helper methods in ServiceSupport for improved code organization
+
+### Changed  
+- Refactored ServiceSupport methods to use helper methods for better maintainability
+- Enhanced ServiceSupport stubbing to automatically detect block parameter requirements
+- Improved error handling in test stubs with fallback to parameter-less calls
+
+### Technical Details
+- ServiceSupport methods now use Ruby's `ArgumentError` rescue mechanism to detect block parameter compatibility
+- `stub_service_success` and `stub_service_failure` automatically handle both parameterized and parameter-less blocks
+- Test stubs try calling with parameters first, then fall back to parameter-less calls when blocks don't accept them
+- This enables cleaner test code without requiring unused `|_|` parameters in failure handlers
+
+## [1.0.4] - 2025-08-27
+
+### Added
+- Comprehensive test coverage achieving 100%
+- GitHub Actions workflow for running tests
+- GitHub Actions status badge to README
+
+### Changed
+- Improved README formatting and clarity
+
+### Fixed
+- GitHub Actions workflow compatibility with Rails 8.0+
+
+## [1.0.3] - 2025-04-30
+
+### Fixed
+- ServiceSupport now properly yields success block values in stubbed services
+
+## [1.0.2] - 2025-04-24
+
+### Changed
+- Improved constant namespacing to avoid need for global search with `::`
+- Fixed generator issues for proper file creation
+
+### Fixed
+- Type generator now works correctly
+- Generator template improvements
+
+## [1.0.1] - 2025-04-02
+
+### Changed
+- Removed types and locale support to simplify the gem
+- Improved namespacing - everything now properly namespaced to `ServiceBase::`
+- Enhanced test coverage
+
+### Removed
+- Active Support dependency for lighter footprint
+- Locale support functionality
+- Custom types functionality
+
+## [1.0.0] - 2025-04-01
+
+### Added
+- Initial release of ServiceBase gem
+- Service Object pattern implementation with dry-rb integration
+- Railway-oriented programming using dry-monads
+- Type validation using dry-struct and dry-types
+- ArgumentTypeAnnotations DSL for service arguments
+- Service generators for Rails integration
+- RSpec test helpers with ServiceSupport
+- Comprehensive documentation and examples
+
+### Features
+- Base Service class with automatic type validation
+- Result monad integration (Success/Failure)
+- Service description and pretty-printing support
+- Rails generators for ApplicationService and Type modules
+- Test stubbing utilities for service success/failure scenarios
+- Argument validation with descriptive error messages

data/README.md

@@ -1,10 +1,57 @@
 # Service Base
 
-A base service class for Ruby applications that provides common functionality and argument type annotations DSL.
+[![Test](https://github.com/kleinjm/service_base/actions/workflows/test.yml/badge.svg)](https://github.com/kleinjm/service_base/actions/workflows/test.yml)
+[![Gem Version](https://badge.fury.io/rb/service_base.svg)](https://badge.fury.io/rb/service_base)
 
-## Dependencies
+A powerful base service class for Ruby applications that implements the Service Object pattern with type-safe arguments and railway-oriented programming using dry-rb gems.
 
-Simply Ruby. This gem can be used in a standalone fashion and Rails is not a dependency. This gem does, however, work very nicely with Rails conventions and includes generators for getting set up quickly.
+## ✨ Features
+
+- 🚂 **Railway-oriented programming** with automatic error handling
+- 🔒 **Type-safe arguments** with validation and coercion
+- 📝 **Self-documenting** services with descriptions
+- 🧪 **Test helpers** for easy mocking and stubbing  
+- ⚡ **Zero dependencies** - works standalone or with Rails
+- 🛠️ **Rails generators** for quick setup
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Installation](#installation)
+- [Service Pattern Overview](#service-pattern-overview)
+- [Usage](#usage)
+- [Arguments](#arguments)
+- [Types](#types)
+- [Transactions](#working-with-transactions)
+- [Testing](#test-support)
+- [Development](#development)
+
+## Quick Start
+
+```ruby
+# Define a service
+class User::CreateService < ApplicationService
+  description "Creates a new user with validation"
+  
+  argument :name, Type::String, description: "User's full name"
+  argument :email, Type::String, description: "User's email address"
+  argument :age, Type::Integer, optional: true, description: "User's age"
+
+  def call
+    user = User.new(arguments)
+    return Failure("Invalid user data") unless user.valid?
+    
+    user.save!
+    Success(user)
+  end
+end
+
+# Use the service
+User::CreateService.call(name: "John Doe", email: "john@example.com") do |on|
+  on.success { |user| redirect_to user_path(user) }
+  on.failure { |error| render json: { error: error }, status: 422 }
+end
+```
 
 ## Installation
 
@@ -36,14 +83,11 @@ class ApplicationService < ServiceBase::Service
 end
 ```
 
-# Base Service Pattern
+## Service Pattern Overview
 
-The general concept of a Service Pattern is useful when a you need to execute a set of
-sequential steps. The service encapsulates those steps into a single class with a single action to trigger the steps.
+The Service Object pattern is useful when you need to execute a set of sequential steps. The service encapsulates those steps into a single class with a single action to trigger the steps.
 
-The Base Service Pattern uses a modified [Railway
-Pattern](https://fsharpforfunandprofit.com/posts/recipe-part2/) set up and enforced by the `Service` class,
-which every service inherits from.
+This gem implements a modified [Railway Pattern](https://fsharpforfunandprofit.com/posts/recipe-part2/) that's set up and enforced by the `ServiceBase::Service` class, which every service inherits from.
 
 ## Recommended resources
 
@@ -79,14 +123,48 @@ responsible for handling that logic.
 
 One of the best ways to use the service pattern is for CRUD services - Ie. `ActiveRecordModel` + `::CreateService`, `::UpdateService`, `::DeleteService`. This avoids the use of callbacks, mystery guests, and unexpected side effects because all the steps to do a CRUD action are in one place and in order of execution.
 
-## Returning a Result
+## Usage
+
+### Defining a Service
+
+Every service must:
+1. Inherit from `ApplicationService` (or `ServiceBase::Service` directly)
+2. Define a `#call` method that returns `Success(value)` or `Failure(error)`
+3. Use the `argument` DSL to define typed arguments
+4. Optionally include a `description` for documentation
+
+```ruby
+class User::UpdateService < ApplicationService
+  description "Updates user attributes with validation"
+  
+  argument :user, Type::User, description: "User to update"
+  argument :attributes, Type::Hash, description: "Attributes to update"
+  argument :notify, Type::Boolean, default: true, description: "Send notification email"
+
+  def call
+    return Failure("User is archived") if user.archived?
+    
+    user.assign_attributes(attributes)
+    return Failure(user.errors.full_messages) unless user.valid?
+    
+    user.save!
+    send_notification if notify
+    Success(user)
+  end
+  
+  private
+  
+  def send_notification
+    UserMailer.updated(user).deliver_now
+  end
+end
+```
 
-Each service inheriting from BaseService must define `#call` and return a `Success` or `Failure`. These types are `Result` Monads from
-the [dry-monads gem](https://dry-rb.org/gems/dry-monads/1.3/). Both `Result` types may take any value as input, ie. `Success(user)`, `Failure(:not_found)`
+### Calling a Service
 
-`Failure` can return any value you’d like the caller to have in order to understand the failure.
+Services return `Result` monads from the [dry-monads gem](https://dry-rb.org/gems/dry-monads/1.3/). Both `Success` and `Failure` can contain any value, like `Success(user)` or `Failure(:not_found)`.
 
-The caller of service can unwrap the `Success` or `Failure`.
+The caller can unwrap the `Success` or `Failure`:
 
 ```ruby
 MyService.call(name: user.name) do |on|
@@ -146,36 +224,36 @@ end
 
 ## Arguments
 
-Arguments to a service are defined via the `argument` DSL.
-The positional name and type arguments are required, the other options are as follows.
-`argument(:name, Type::String, optional: true, description: "The User's name")`
+Arguments to a service are defined via the `argument` DSL. The positional name and type arguments are required, with additional options available:
+
+```ruby
+argument(:name, Type::String, optional: true, description: "The User's name")
+```
 
 If an argument is optional and has a default value, simply set `default: your_value` but do not also specify `optional: true`.
 Doing so will raise an `ArgumentError`.
 
-Additionally, be sure to `.freeze` any mutable default values, ie.  `default: {}.freeze`.
-Failure to do so will raise an `ArgumentError`.
+Additionally, be sure to `.freeze` any mutable default values, e.g., `default: {}.freeze`. Failure to do so will raise an `ArgumentError`.
 
-To allow multiple types as arguments, use `|`. For example,
+To allow multiple types as arguments, use `|`:
 
-```rb
+```ruby
 argument(:value, Type::String | Type::Integer)
 ```
 
-A service should also define a `description`. This is recommended for self-documentation, ie.
+A service should also define a `description`. This is recommended for self-documentation:
 
 ```ruby
 class MyService < ApplicationService
-  description("Does a lot of cool things")
+  description "Does a lot of cool things"
 end
 ```
 
-To get the full hash of `argument`'s keys and values passed into a service,
-call `arguments`. This is a very useful technique for services that update an object. For example
+To get the full hash of arguments passed into a service, call `arguments`. This is a very useful technique for services that update an object:
 
 ```ruby
 class User::UpdateService < ApplicationService
-  argument(:name, String)
+  argument :name, Type::String
 
   def call
     user.update(arguments)
@@ -183,12 +261,15 @@ class User::UpdateService < ApplicationService
 end
 ```
 
-### Nil
+### Nil Values
 
-Empty strings attempted to coerce into integers will throw an error.
-See [this GH issue for an explaination](https://github.com/dry-rb/dry-types/issues/344#issuecomment-518743661)
-To instead accept `nil`, do the following:
-`argument(:some_integer, Type::Params::Nil | Type::Params::Integer)`
+Empty strings attempted to coerce into integers will throw an error. See [this GitHub issue for an explanation](https://github.com/dry-rb/dry-types/issues/344#issuecomment-518743661).
+
+To instead accept `nil`, use the following:
+
+```ruby
+argument :some_integer, Type::Params::Nil | Type::Params::Integer
+```
 
 
 ## Types
@@ -198,7 +279,7 @@ You may also add custom types as outlined in [Dry.rb Custom Types](https://dry-r
 
 The Rails generators will create a Type module, which includes `ServiceBase::Types`, which includes `Dry.Types`. Therefore, all types defined in Dry.rb's Types are available to you.
 
-```rb
+```ruby
 # app/models/type.rb
 module Type
   include ServiceBase::Types
@@ -211,7 +292,7 @@ module Type
   # Controller params are an ActionController::Parameters instance or a hash (easier for testing)
   ControllerParams = Dry.Types.Instance(ActionController::Parameters) | Dry.Types.Instance(Hash)
 
-  # Customer param hashes
+  # Custom param hashes
   AddressParams = Dry::Types['hash'].schema(
     address: Dry::Types['string'],
     address2: Dry::Types['string'],
@@ -223,40 +304,38 @@ end
 
 # app/services/example_service.rb
 class ExampleService < ApplicationService
-  argument(:any_model, Type::ApplicationRecord, description: "The model to update")
-  argument(:params, Type::ControllerParams, description: "The attributes to update")
-  argument(:user, Type::User, description: "A cool user that relates to the model")
-  argument(:project, Type::Project, description: "A project that the user is working on")
-  argument(:address, Type::AddressParams, description: "The user's address")
+  argument :any_model, Type::ApplicationRecord, description: "The model to update"
+  argument :params, Type::ControllerParams, description: "The attributes to update"
+  argument :user, Type::User, description: "A cool user that relates to the model"
+  argument :project, Type::Project, description: "A project that the user is working on"
+  argument :address, Type::AddressParams, description: "The user's address"
 end
 ```
 
-Dry.rb's `Coercible` and `Params` Types are very powerful and recommended for automatic parsing of inputs, ie. controller parameters.
+Dry.rb's `Coercible` and `Params` Types are very powerful and recommended for automatic parsing of inputs, e.g., controller parameters.
 
-For example `argument(:number, Type::Params::Integer)` will convert `"12"` ⇒ `12`.
+For example, `argument :number, Type::Params::Integer` will convert `"12"` ⇒ `12`.
 
 Entire hash structures may also be validated and automatically parsed, for example:
 
 ```ruby
-argument(
-  :line_items,
+argument :line_items,
   Type::Array(
     Type::Hash.schema(
       vintage_year: Type::Params::Integer,
       number_of_credits: Type::Params::Integer,
       price_dollars_usd: Type::Params::Float,
-    ),
-  ),
+    )
+  )
 ```
 
-## Working with transactions
+## Working with Transactions
 
 ⚠️  If your service makes more than one write call to the DB, you
 should wrap all operations in a single transaction with
-`::ApplicationRecord.transaction`.
+`ApplicationRecord.transaction`.
 
-According to the [Dry
-RB docs](https://dry-rb.org/gems/dry-monads/1.3/do-notation/#transaction-safety):
+According to the [Dry-RB documentation](https://dry-rb.org/gems/dry-monads/1.3/do-notation/#transaction-safety):
 
 > Under the hood, Do uses exceptions to halt unsuccessful
 operations…Since yield internally uses exceptions to
@@ -303,7 +382,7 @@ blocks or other sub-modules. See [https://github.com/dry-rb/dry-monads/issues/68
 
 ## Misc
 
-- To get a pretty printed description of a service and it’s args, run `ServiceClass.pp`
+- To get a pretty printed description of a service and its args, run `ServiceClass.pp`
 
 ## Test Support
 
@@ -314,18 +393,23 @@ require "service_base/rspec"
 ```
 
 ```ruby
-stub_service_success(User::CreateService)
-stub_service_success(User::CreateService, success: true)
-stub_service_success(User::CreateService, success: create(:user))
+stub_service_success(User::CreateService) # yields the success block of the service call, disregarding the Success's value
+stub_service_success(User::CreateService, success: true) # yields the success block of the service call, returning `true` as the Success's value
+stub_service_success(User::CreateService, success: create(:user)) # yields the success block of the service call, returning a `User` instance as the Success's value
+stub_service_success(User::CreateService, success_nil: true) # yields the success block of the service call, returning `nil` as the Success's value
 
 stub_service_failure(User::CreateService, failure: "error")
-stub_service_failure(User::CreateService failure: :invalid_email, matched: true)
+stub_service_failure(User::CreateService, failure: :invalid_email, matched: true)
 ```
 
 ## Development
 
 After checking out the repo, run `bundle install` to install dependencies. Then, run `rspec` to run the tests.
 
+### Test Coverage
+
+The gem maintains **100%** test coverage across all core components.
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub.

data/lib/service_base/rspec/service_support.rb

@@ -3,14 +3,12 @@
 module ServiceSupport
   # Note that you must have at least one `on.success` and one `on.failure`
   # matcher for each block-style service call
-  def stub_service_success(service_class, success: nil)
+  def stub_service_success(service_class, success: nil, success_nil: false)
     block = double(:on)
     allow(block).to receive(:failure)
-    if success.present?
-      allow(block).to receive(:success).and_yield(success)
-    else
-      allow(block).to receive(:success)
-    end
+
+    yield_value = determine_success_yield_value(success, success_nil)
+    allow(block).to receive(:success) { |&block_proc| call_with_flexible_params(block_proc, yield_value) }
     allow(service_class).to receive(:call).and_yield(block)
   end
 
@@ -21,16 +19,57 @@ module ServiceSupport
   def stub_service_failure(service_class, failure:, matched: false)
     block = double(:on)
     allow(block).to receive(:success)
-    if matched # on.failure(:some_error)
-      allow(block).to receive(:failure) # ignore unmatched on.failure
-      allow(block).to receive(:failure).with(failure).and_yield(failure)
-    else # on.failure
-      # ignore matched on.failure(:some_error)
-      allow(block).to receive(:failure).with(anything)
-      allow(block).to receive(:failure).with(no_args).and_yield(failure)
-    end
+
+    setup_failure_stub(block, failure, matched)
     allow(service_class).to receive(:call).and_yield(block)
   end
+
+  private
+
+  def determine_success_yield_value(success, success_nil)
+    return success unless success.nil?
+    return nil if success_nil
+
+    :no_yield
+  end
+
+  def call_with_flexible_params(block_proc, yield_value)
+    if yield_value == :no_yield
+      block_proc.call
+    else
+      call_block_with_fallback(block_proc, yield_value)
+    end
+  end
+
+  def call_block_with_fallback(block_proc, value)
+    block_proc.call(value)
+  rescue ArgumentError
+    # Block doesn't accept parameters, call without arguments
+    block_proc.call
+  end
+
+  def setup_failure_stub(block, failure, matched)
+    if matched
+      setup_matched_failure_stub(block, failure)
+    else
+      setup_unmatched_failure_stub(block, failure)
+    end
+  end
+
+  def setup_matched_failure_stub(block, failure)
+    allow(block).to receive(:failure) # ignore unmatched on.failure
+    allow(block).to receive(:failure).with(failure) do |&failure_block|
+      call_block_with_fallback(failure_block, failure)
+    end
+  end
+
+  def setup_unmatched_failure_stub(block, failure)
+    # ignore matched on.failure(:some_error)
+    allow(block).to receive(:failure).with(anything)
+    allow(block).to receive(:failure).with(no_args) do |&failure_block|
+      call_block_with_fallback(failure_block, failure)
+    end
+  end
 end
 
 RSpec.configure do |config|

data/lib/service_base/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ServiceBase
-  VERSION = '1.0.3'
+  VERSION = '1.1.0'
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: service_base
 version: !ruby/object:Gem::Version
-  version: 1.0.3
+  version: 1.1.0
 platform: ruby
 authors:
 - James Klein
 bindir: bin
 cert_chain: []
-date: 2025-04-24 00:00:00.000000000 Z
+date: 2025-09-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dry-matcher
@@ -87,6 +87,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - LICENSE.txt
 - README.md
 - lib/generators/application_service_generator.rb
@@ -105,7 +106,7 @@ licenses:
 metadata:
   homepage_uri: https://github.com/kleinjm/service_base
   source_code_uri: https://github.com/kleinjm/service_base
-  changelog_uri: https://github.com/kleinjm/service_base/blob/main/README.md
+  changelog_uri: https://github.com/kleinjm/service_base/blob/main/CHANGELOG.md
 rdoc_options: []
 require_paths:
 - lib