zen-service 2.2.1 → 2.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 207425486ecb408db660e845768e30e9cd19aa3ed1d6a7214d41fc0eecd46590
-  data.tar.gz: 74787fb37ce4bc2e6d7c139e7ca7b245c25fcafd6711a1aba434c0e681007b9b
+  metadata.gz: e345b9c915b5e8c479cfdfc7bf06a949415759d76ae8af425cc054d0265f600f
+  data.tar.gz: 9d4167512ce4b33cc5e4d9c4463b1d1e81b6e325f42a62fb88cd3f3bd8bcbfb8
 SHA512:
-  metadata.gz: 4bc0fe9454e82c5b49f9ab87e3812e002691002d1476b9258417fa12ddae5419ea3621de952c821b27716078e9008745acf02e00946a5538570dd89c3a020972
-  data.tar.gz: e26b152b882e1fc74ef35a99644bcc3b976c8710eb8c5833b5393edf0843f190006a019c157ba2958a082d03cedcf4c989fd2b6d5788c0bb27f36d0e9f63391f
+  metadata.gz: bb8c0682f5329c0f0928de04c4b6d14f0b5e81ed26714a13e8110cd814dd83543ca850b6b06b8d0df30e8737cb931c67854db0e2002d3e4ce4440de584348077
+  data.tar.gz: 429d71228e7353b32b36afb0c547a19a11955c3c55b3fac6b4bf1771a9acb44ba7df0410300174c5faa20bdc7054bc06fce3362b355e47106557889efd606cd9

data/.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby-version: ['3.2', '3.3']
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Ruby ${{ matrix.ruby-version }}
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby-version }}
+          bundler-cache: true
+
+      - name: Run tests
+        run: bundle exec rspec
+
+      - name: Upload coverage to Codecov
+        if: matrix.ruby-version == '3.3'
+        uses: codecov/codecov-action@v4
+        with:
+          files: ./coverage/coverage.xml
+          flags: unittests
+          name: codecov-umbrella
+          fail_ci_if_error: false
+          token: ${{ secrets.CODECOV_TOKEN }}

data/.gitignore

@@ -8,6 +8,7 @@
 /spec/reports/
 /tmp/
 
+.github/workflows/README.md
 .rspec_status
 .ruby-version
 .ruby-gemset

data/CHANGELOG.md

@@ -0,0 +1,98 @@
+# 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).
+
+## [2.2.3] - 2026-01-19
+
+### Fixed
+
+- Fix block passing when calling service using `.call` and `.[]` class methods
+
+### Changed
+
+- Add CI workflow with GitHub Actions
+- Add SimpleCov integration with 100% test coverage (line and branch coverage)
+- Update README with comprehensive documentation, shield badges, and improved examples
+
+## [2.2.2] - 2025-12-30
+
+### Fixed
+
+- Fix re-using plugin by inherited service classes
+
+## [2.2.1] - 2025-12-29
+
+### Fixed
+
+- Fix plugin reflection options and configuration check
+
+## [2.2.0] - 2025-12-28
+
+### Added
+
+- Allow registering plugins with class names (strings) instead of requiring class constants
+  - Useful when autoload isn't available yet, e.g., during Rails initialization
+
+### Changed
+
+- Update README with improved documentation
+
+## [2.1.0] - 2025-12-20
+
+### Added
+
+- Add `:call_unless_called` option to `:persisted_result` plugin
+  - When set to `true`, accessing `service.result` will automatically call `#call` if not yet called
+  - Default value is `false`
+
+### Changed
+
+- Allow plugin re-registration with updated configuration
+- Code cleanup and refactoring
+
+### Fixed
+
+- Drop obsolete statements from codebase
+
+## [2.0.0] - 2025-12-06
+
+### Breaking Changes
+
+- Complete rewrite focused on simplicity and extensibility
+- Drop majority of built-in plugins from v1.x
+- New plugin API based on `Zen::Service::Plugins::Plugin`
+
+### Added
+
+- New core plugin architecture where even fundamental features are plugins
+  - `:callable` - Provides `.call` and `.[]` class methods
+  - `:attributes` - Manages service initialization parameters with runtime validation
+- `:persisted_result` plugin - Provides `#result` method and `#called?` helper
+- `:result_yielding` plugin - Enables nested service calls to return block-provided values
+- Plugin lifecycle with `used` and `configure` callbacks
+- Plugin inheritance and reconfiguration support
+- Automatic plugin registration for modules extending `Plugin`
+- Manual plugin registration via `Zen::Service::Plugins.register`
+
+### Changed
+
+3]: https://github.com/akuzko/zen-service/compare/v2.2.2...v2.2.3
+[2.2.
+
+- Simplified service object pattern focusing on essential functionality
+- Improved plugin DSL with `register_as`, `default_options`, and `service_extension`
+- Complete README rewrite with comprehensive examples
+
+### Removed
+
+- Most built-in plugins from v1.x for simplicity
+- Removed legacy plugin APIs
+
+[2.2.2]: https://github.com/akuzko/zen-service/compare/v2.2.1...v2.2.2
+[2.2.1]: https://github.com/akuzko/zen-service/compare/v2.2.0...v2.2.1
+[2.2.0]: https://github.com/akuzko/zen-service/compare/v2.1.0...v2.2.0
+[2.1.0]: https://github.com/akuzko/zen-service/compare/v2.0.0...v2.1.0
+[2.0.0]: https://github.com/akuzko/zen-service/releases/tag/v2.0.0

data/Gemfile

@@ -4,3 +4,12 @@ source "https://rubygems.org"
 
 # Specify your gem"s dependencies in zen-service.gemspec
 gemspec
+
+gem "pry"
+gem "pry-nav"
+gem "rake", "~> 13.0"
+gem "rspec", "~> 3.0"
+gem "rspec-its", "~> 1.2"
+gem "rubocop", "~> 1.81"
+gem "simplecov"
+gem "simplecov-cobertura"

data/README.md

@@ -2,7 +2,11 @@
 
 Flexible and highly extensible Service Objects for business logic organization.
 
-[![github release](https://img.shields.io/github/release/akuzko/zen-service.svg)](https://github.com/akuzko/zen-service/releases)
+[![Gem Version](https://img.shields.io/gem/v/zen-service.svg)](https://rubygems.org/gems/zen-service)
+[![CI Status](https://github.com/akuzko/zen-service/actions/workflows/ci.yml/badge.svg)](https://github.com/akuzko/zen-service/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/akuzko/zen-service/branch/master/graph/badge.svg)](https://codecov.io/gh/akuzko/zen-service)
+[![Ruby Version](https://img.shields.io/badge/ruby-%3E%3D%203.2-ruby.svg)](https://www.ruby-lang.org)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
 ## Installation
 
@@ -22,12 +26,12 @@ Or install it yourself as:
 
 ## Usage
 
-The very basic usage of `Zen` services can be shown with following example:
+The most basic usage of `Zen::Service` can be demonstrated with the following example:
 
-```rb
+```ruby
 # app/services/todos/update.rb
 module Todos
-  class Update < ApplicationService # base class for app services, inherits from Zen::Service
+  class Update < ApplicationService # Base class for app services, inherits from Zen::Service
     attributes :todo, :params
 
     def call
@@ -40,7 +44,7 @@ module Todos
   end
 end
 
-# app/controllers/todos/controller
+# app/controllers/todos_controller.rb
 class TodosController < ApplicationController
   def update
     case Todos::Update.call(todo, params: todo_params)
@@ -51,97 +55,129 @@ class TodosController < ApplicationController
 end
 ```
 
-### Service attributes
+### Service Attributes
 
-Read full version on [wiki](https://github.com/akuzko/zen-service/wiki#instantiating-service-with-attributes).
+`Zen::Service` instances are initialized with _attributes_. To specify the list of available attributes, use the `attributes`
+class method. All attributes are optional during initialization. You can omit keys and pass attributes as positional
+parameters—they will be assigned in the order they were declared. However, you cannot:
 
-`Zen` services are initialized with _attributes_. To specify list of available attributes, use `attributes`
-class method. All attributes are optional during service initialization. It is possible to omit keys during
-initialization, and pass attributes as parameters - in this case attributes will be filled in correspondance
-to the order they were defined. However, you cannot pass more attributes than declared attributes list, as
-well as cannot pass single attribute multiple times (as parameter and as named attribute) or attributes that
-were not declared with `attributes` class method.
+- Pass more attributes than declared
+- Pass the same attribute multiple times (both as positional and keyword argument)
+- Pass undeclared attributes
 
-```rb
+```ruby
 class MyService < Zen::Service
   attributes :foo, :bar
 
   def call
-    # do something
+    # Your business logic here
   end
 
   def foo
-    super || 5
+    super || 5 # Provide default value
   end
 end
 
+# Different ways to initialize services
 s1 = MyService.new
 s1.foo # => 5
 s1.bar # => nil
 
 s2 = MyService.new(6)
 s2.foo # => 6
+s2.bar # => nil
 
-s3 = s2.with_attributes(foo: 1, bar: 2)
+s3 = MyService.new(foo: 1, bar: 2)
 s3.foo # => 1
 s3.bar # => 2
+
+# Create a new service from an existing one with some attributes changed
+s4 = s3.with_attributes(bar: 3)
+s4.foo # => 1
+s4.bar # => 3
+
+# Create a service from another service's attributes
+s5 = MyService.from(s3)
+s5.foo # => 1
+s5.bar # => 2
 ```
 
 ### Service Extensions (Plugins)
 
-Read full version on [wiki](https://github.com/akuzko/zen-service/wiki/Plugins).
+`zen-service` is built with extensibility at its core. Even fundamental functionality like callable behavior
+and attributes are implemented as plugins. The base `Zen::Service` class uses two core plugins:
 
-`zen-service` is built with extensions in mind. Even core functionality is organized in plugins that are
-used in base `Zen::Service` class. Version 2.0.0 drops majority of built-in plugins for sake of
-simplicity.
+- `:callable` - Provides class methods `.call` and `.[]` that instantiate and call the service
+- `:attributes` - Manages service initialization parameters with runtime validation
 
-However, `zen-service` still provides a couple of helpfull plugins out-of-the-box:
+In addition, `zen-service` provides optional built-in plugins:
 
-- `:persisted_result` - provides `#result` method that returns value of the latest `#call`
-  method call. Also provides `#called?` helper method. Supports `call_unless_called` option.
-  When set to `true`, calling `service.result` method will call `#call` method if it has
-  not yet been called. Default value is `false`.
+#### `:persisted_result`
 
-- `:result_yielding` - can be used in junction with nested service calls to result with
-  block-provided value instead of nested service `call` return value. For example:
+Provides `#result` method that returns the value from the most recent `#call` invocation, along with a
+`#called?` helper method.
 
-  ```rb
-    def call
-      logger.call do # logger uses `:result_yielding` plugin
-        todo.update!(params)
-        [:ok, todo]
-      rescue ActiveRecord::RecordInvalid
-        [:error, todo.errors.messages]
-      end
-    end
-  ```
+**Options:**
 
-#### Plugin Lifecycle
+- `call_unless_called: false` (default) - When `true`, accessing `service.result` will automatically
+  call `#call` if it hasn't been called yet.
 
-When using a plugin on a service class:
+```ruby
+class MyService < Zen::Service
+  use :persisted_result, call_unless_called: true
 
-- If the plugin is used for the first time, both `used` and `configure` callbacks are invoked
-- If the plugin was already used by an ancestor class, only the `configure` callback is invoked,
-  allowing reconfiguration without re-including the module
+  attributes :value
 
-This design allows child classes to customize plugin behavior inherited from parent classes:
+  def call
+    value * 2
+  end
+end
 
-```rb
-class BaseService < Zen::Service
-  use :persisted_result, call_unless_called: false
+service = MyService.new(5)
+service.called? # => false
+service.result  # => 10 (automatically calls #call)
+service.called? # => true
+```
+
+#### `:result_yielding`
+
+Enables nested service calls to return block-provided values instead of the nested service's return value.
+Useful for wrapping service calls with cross-cutting concerns like logging or error handling.
+
+```ruby
+class Logger < Zen::Service
+  use :result_yielding
+
+  # Will result with value return by `yield` expression
+  def call
+    Rails.logger.info("Starting operation")
+    result = yield
+    Rails.logger.info("Operation completed: #{result.inspect}")
+  end
 end
 
-class ChildService < BaseService
-  use :persisted_result, call_unless_called: true  # Only reconfigures, doesn't re-include
+class UpdateTodo < Zen::Service
+  attributes :todo, :params
+
+  def call
+    Logger.call do
+      todo.update!(params)
+      [:ok, todo]
+    rescue ActiveRecord::RecordInvalid
+      [:error, todo.errors.messages]
+    end
+  end
 end
 ```
 
-Bellow you can see sample implementation of a plugin that transforms resulting objects
-to camel-case notation (relying on ActiveSupport's core extensions)
+### Creating Custom Plugins
 
-```rb
+Creating custom plugins is straightforward. Below is an example of a plugin that transforms results to
+camelCase notation (using ActiveSupport's core extensions):
+
+```ruby
 module CamelizeResult
-  extend Zen::Service::Plugin
+  extend Zen::Service::Plugins::Plugin
 
   def self.used(service_class)
     service_class.prepend(Extension)
@@ -149,8 +185,8 @@ module CamelizeResult
 
   def self.camelize(obj)
     case obj
-    when Array then obj.map { camelize(_1) }
-    when Hash then obj.deep_transform_keys { _1.to_s.camelize(:lower).to_sym }
+    when Array then obj.map { |item| camelize(item) }
+    when Hash then obj.deep_transform_keys { |key| key.to_s.camelize(:lower).to_sym }
     else obj
     end
   end
@@ -161,11 +197,7 @@ module CamelizeResult
     end
   end
 end
-```
-
-and then
 
-```rb
 class Todos::Show < Zen::Service
   attributes :todo
 
@@ -182,22 +214,79 @@ end
 Todos::Show[todo] # => { id: 1, isCompleted: true }
 ```
 
-**Note**: Custom plugins need to be registered before they can be used. Plugins that extend
-`Zen::Service::Plugin` are automatically registered when the module is loaded. Alternatively,
-you can register plugins manually:
+#### Plugin Registration
 
-```rb
+Plugins that extend `Zen::Service::Plugins::Plugin` are automatically registered when the module is loaded.
+You can also register plugins manually:
+
+```ruby
 # Register a plugin module
 Zen::Service::Plugins.register(:my_plugin, MyPlugin)
 
-# Register by class name (useful when autoload isn't available yet, e.g., during Rails boot)
+# Register by class name (useful when autoload isn't available yet, e.g., during Rails initialization)
 Zen::Service::Plugins.register(:my_plugin, "MyApp::Services::MyPlugin")
 ```
 
+#### Plugin Lifecycle
+
+When using a plugin on a service class:
+
+- **First use**: Both `used` and `configure` callbacks are invoked, and the module is included
+- **Inheritance**: If a plugin was already used by an ancestor class, only `configure` is called,
+  allowing reconfiguration without re-including the module
+
+This design enables child classes to customize inherited plugin behavior:
+
+```ruby
+class BaseService < Zen::Service
+  use :persisted_result, call_unless_called: false
+end
+
+class ChildService < BaseService
+  use :persisted_result, call_unless_called: true  # Reconfigures without re-including
+end
+```
+
+#### Plugin DSL
+
+Plugins can use several DSL methods when extending `Zen::Service::Plugins::Plugin`:
+
+```ruby
+module MyPlugin
+  extend Zen::Service::Plugins::Plugin
+
+  # Override the auto-generated registration name
+  register_as :custom_name
+
+  # Set default options
+  default_options foo: 5, bar: false
+
+  # Called when plugin is first used on a class
+  def self.used(service_class, **options, &block)
+    # Include/prepend modules, add class methods, etc.
+  end
+
+  # Called every time the plugin is used (including on child classes)
+  def self.configure(service_class, **options, &block)
+    # Configure behavior based on options
+  end
+end
+```
+
+## Testing
+
+The gem has 100% test coverage with both line and branch coverage. To run the test suite:
+
+```bash
+bundle exec rspec
+```
+
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests.
-You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rspec` to run
+the tests. You can also run `bin/console` for an interactive prompt that allows you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
 
 ## Contributing
 

data/lib/zen/service/plugins/attributes.rb

@@ -13,7 +13,7 @@ module Zen
 
       def initialize_clone(*)
         super
-        @attributes = @attributes.dup unless @attributes.nil?
+        @attributes = @attributes.dup
       end
 
       def with_attributes(attributes)
@@ -84,7 +84,7 @@ module Zen
         end
 
         def from(service)
-          new(service.send(:attributes))
+          new(**service.send(:attributes))
         end
       end
     end

data/lib/zen/service/plugins/callable.rb

@@ -5,13 +5,13 @@ module Zen
     module Callable
       extend Plugin
 
-      def call
+      def call(&)
         # No-op by default
       end
 
       module ClassMethods
-        def call(...)
-          new(...).call
+        def call(*attrs, &block)
+          new(*attrs).call(&block)
         end
         alias [] call
       end

data/lib/zen/service/plugins/pluggable.rb

@@ -13,6 +13,7 @@ module Zen
 
         if plugins.key?(name)
           extension.configure(self, **opts, &block) if extension.respond_to?(:configure)
+          service_plugins[name] = Reflection.new(extension, opts, block)
           return extension
         end
 

data/lib/zen/service/version.rb

@@ -2,6 +2,6 @@
 
 module Zen
   class Service
-    VERSION = "2.2.1"
+    VERSION = "2.2.3"
   end
 end

data/zen-service.gemspec

@@ -27,11 +27,4 @@ Gem::Specification.new do |spec|
   spec.bindir        = "exe"
   spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
-
-  spec.add_development_dependency "pry"
-  spec.add_development_dependency "pry-nav"
-  spec.add_development_dependency "rake", "~> 13.0"
-  spec.add_development_dependency "rspec", "~> 3.0"
-  spec.add_development_dependency "rspec-its", "~> 1.2"
-  spec.add_development_dependency "rubocop", "~> 1.81"
 end

metadata

@@ -1,99 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: zen-service
 version: !ruby/object:Gem::Version
-  version: 2.2.1
+  version: 2.2.3
 platform: ruby
 authors:
 - Artem Kuzko
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2025-12-29 00:00:00.000000000 Z
-dependencies:
-- !ruby/object:Gem::Dependency
-  name: pry
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: pry-nav
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '13.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '13.0'
-- !ruby/object:Gem::Dependency
-  name: rspec
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.0'
-- !ruby/object:Gem::Dependency
-  name: rspec-its
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.2'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.2'
-- !ruby/object:Gem::Dependency
-  name: rubocop
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.81'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.81'
+date: 2026-01-19 00:00:00.000000000 Z
+dependencies: []
 description: Flexible and highly extensible Services for business logic organization
 email:
 - a.kuzko@gmail.com
@@ -102,12 +18,14 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".github/copilot-instructions.md"
+- ".github/workflows/ci.yml"
 - ".gitignore"
 - ".rspec"
 - ".rubocop.yml"
 - ".tool-versions"
+- CHANGELOG.md
 - Gemfile
-- LICENSE.txt
+- LICENSE
 - README.md
 - Rakefile
 - bin/console