zen-service 2.2.4 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7c1c54fed5a49c87cdbdfbaf9cb369e8eed0ac2a0e1862eadd5edca95af1f931
-  data.tar.gz: 2c4d4efaaa636193e3d4daa6d94a375e1e67f7c8bfc0ab930d8cedbd36023012
+  metadata.gz: b540abd37b4fb43937241ab38aab9e143afc8afa80683002ccc32dace163ab7c
+  data.tar.gz: 9d0a5e5a0e6bbf2e2473bc8b3337edab1ea65773d163336a53a1ef9741a95745
 SHA512:
-  metadata.gz: 24394d2ecd8f0af333c82b23089b5c53b2481db6cee8ebffc78f9f69b80fc371c58020064d1650453f5a146bd789d76e6db62b90a4885ad34fcc7af57959ce07
-  data.tar.gz: 746b18aaa03abe11e5c194e6817da0b84e1e18c1226f2f67e7f6a981bf9dfc331ff422afc8518e08ea11bdb58ec6f79b0dac34b855335eb2cdb361e2912b85b5
+  metadata.gz: c5c28f74692f0ea39242111cf419c116d51586945f08e5523996f40d578884a8797934ca153251f08802b464569916e898b13687648b27ed100895baf528e011
+  data.tar.gz: a5fd404f08a6ea273d4a73bffdfeb9aec2a78cd9894ee600338de80f0b87892a825eeaf592d3f44772b137a5f3cea8c27f679140a093a80920575154ddca51dd

data/CHANGELOG.md

@@ -5,6 +5,29 @@ 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.3.0] - 2026-02-02
+
+### Added
+
+- Add `:inputs` plugin as an experimental alternative to `:attributes` for service initialization
+  - Provides keyword-only initialization with built-in runtime validation
+  - Supports per-input validation blocks with Ruby 3+ pattern matching
+  - Includes optional inputs with lazy-evaluated defaults
+  - Adds initialization blocks for computed attributes
+  - Designed for use with `Zen::Service::Callable` descendants
+- Add `Zen::Service::Callable` base class as service "blank slate"
+  - Inherits only `:callable` plugin without `:attributes`
+  - Enables alternative initialization strategies via plugins like `:inputs`
+- Add comprehensive benchmark comparison with `verbalize` gem in README
+  - Shows `zen-service` with `:attributes` is ~31% faster than `verbalize`
+  - Shows `:inputs` plugin is ~8% faster than `verbalize`
+
+### Changed
+
+- Update README with `:inputs` plugin documentation and usage examples
+- Update README with pattern matching validation examples
+- Improve documentation structure and clarity
+
 ## [2.2.4] - 2026-01-19
 
 ### Fixed
@@ -94,6 +117,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Most built-in plugins from v1.x for simplicity
 - Removed legacy plugin APIs
 
+[2.2.4]: https://github.com/akuzko/zen-service/compare/v2.2.3...v2.2.4
+[2.3.0]: https://github.com/akuzko/zen-service/compare/v2.2.4...v2.3.0
 [2.2.4]: https://github.com/akuzko/zen-service/compare/v2.2.3...v2.2.4
 [2.2.3]: https://github.com/akuzko/zen-service/compare/v2.2.2...v2.2.3
 [2.2.2]: https://github.com/akuzko/zen-service/compare/v2.2.1...v2.2.2

data/README.md

@@ -150,9 +150,11 @@ class Logger < Zen::Service
 
   # Will result with value return by `yield` expression
   def call
+    start_time = Time.now
     Rails.logger.info("Starting operation")
-    result = yield
-    Rails.logger.info("Operation completed: #{result.inspect}")
+    yield
+    time_taken = (Time.now - start_time) * 1000
+    Rails.logger.info("Operation completed in #{time_taken.round} ms")
   end
 end
 
@@ -170,6 +172,114 @@ class UpdateTodo < Zen::Service
 end
 ```
 
+#### `:inputs` (Experimental)
+
+Provides an alternative way to initialize services with keyword-only arguments and built-in runtime validation.
+
+**Key Features:**
+
+- Keyword-only initialization (no positional arguments)
+- Per-input validation blocks with Ruby 3+ pattern matching
+- Optional inputs with lazy-evaluated defaults
+- Initialization blocks for computed attributes
+
+**⚠️ Experimental Feature:** To avoid breaking changes, services using `:inputs` should inherit from
+`Zen::Service::Callable` instead of `Zen::Service`. The base `Zen::Service` class already includes the
+`:attributes` plugin, and these two plugins provide different initialization strategies.
+API of the plugin may be changed in future.
+
+```ruby
+# Base class for input-based services
+class ApplicationCallable < Zen::Service::Callable
+  use :inputs
+end
+
+# Service with input validation
+class CalculatePrice < ApplicationCallable
+  input(:quantity) { _1 => Integer }
+  input(:unit_price) { _1 => Numeric }
+  input(:discount, optional: true)
+
+  def call
+    total = quantity * unit_price
+    discount ? total * (1 - discount) : total
+  end
+end
+
+CalculatePrice.call(quantity: 10, unit_price: 5.0, discount: 0.1)
+# => 45.0
+
+CalculatePrice.call(quantity: "10", unit_price: 5.0)
+# => NoMatchingPatternError (Integer === "10" does not return true)
+```
+
+**Input Options:**
+
+- `optional: true` - Allow input to be omitted (defaults to `nil`)
+- `default: -> { value }` - Provide lazy-evaluated default value
+
+**Bulk Definition with Validation:**
+
+```ruby
+class ProcessCoordinates < ApplicationCallable
+  inputs(:x, :y) do |x_val, y_val|
+    x_val => Integer
+    y_val => Integer
+    raise ArgumentError, "coordinates out of bounds" if x_val.abs > 100 || y_val.abs > 100
+  end
+
+  def call
+    [x, y]
+  end
+end
+
+ProcessCoordinates.call(x: 10, y: 20) # => [10, 20]
+ProcessCoordinates.call(x: 150, y: 20) # => ArgumentError: coordinates out of bounds
+```
+
+**Default Values:**
+
+```ruby
+class CreateReport < ApplicationCallable
+  input :data
+  input :format, default: -> { :json }
+  input :timestamp, default: -> { Time.current }
+
+  def call
+    { data: data, format: format, timestamp: timestamp }
+  end
+end
+
+CreateReport.call(data: [1, 2, 3])
+# => { data: [1, 2, 3], format: :json, timestamp: 2026-02-02 10:30:00 UTC }
+```
+
+**Pattern Matching for Type Safety:**
+
+The primary use case for validation blocks is runtime type checking using Ruby's pattern matching:
+
+```ruby
+class UserRegistration < ApplicationCallable
+  input(:email) { _1 => String }
+  input(:age) { _1 => Integer if _1 >= 18 }
+  input(:role) { _1 => :admin | :user | :guest }
+
+  def call
+    # Your registration logic
+  end
+end
+
+# Valid calls
+UserRegistration.call(email: "user@example.com", age: 25, role: :user)
+
+# Pattern match failures
+UserRegistration.call(email: 123, age: 25, role: :user)
+# => NoMatchingPatternError
+
+UserRegistration.call(email: "user@example.com", age: 15, role: :user)
+# => NoMatchingPatternError
+```
+
 ### Creating Custom Plugins
 
 Creating custom plugins is straightforward. Below is an example of a plugin that transforms results to
@@ -273,6 +383,76 @@ module MyPlugin
 end
 ```
 
+## Comparison/Benchmark
+
+`zen-service` is designed to be both flexible and performant. Among similar service object gems,
+[verbalize](https://github.com/taylorzr/verbalize) is known for being the fastest implementation.
+The following benchmark compares `zen-service` with `verbalize` using a simple addition service:
+
+```ruby
+require 'benchmark/ips'
+require 'verbalize'
+require 'zen/service'
+
+class VerbalizeAdd
+  include Verbalize::Action
+
+  input :a, :b
+
+  def call
+    a + b
+  end
+end
+
+class ZenAdd < Zen::Service
+  attributes :a, :b
+
+  def call
+    a + b
+  end
+end
+
+class ZenInputsAdd < Zen::Service::Callable
+  use :inputs
+
+  inputs :a, :b
+
+  def call
+    a + b
+  end
+end
+
+Benchmark.ips do |x|
+  x.report('Verbalize       ') { VerbalizeAdd.call(a: 1, b: 2) }
+  x.report('Zen (attributes)') { ZenAdd.call(a: 1, b: 2) }
+  x.report('Zen (inputs)    ') { ZenInputsAdd.call(a: 1, b: 2) }
+  x.compare!
+end
+```
+
+**Results:**
+
+```
+Warming up --------------------------------------
+    Verbalize           66.313k i/100ms
+    Zen (attributes)    87.104k i/100ms
+    Zen (inputs)        62.857k i/100ms
+Calculating -------------------------------------
+    Verbalize           648.660k (± 2.4%) i/s    (1.54 μs/i) -      3.249M in   5.012220s
+    Zen (attributes)    848.953k (± 4.2%) i/s    (1.18 μs/i) -      4.268M in   5.037257s
+    Zen (inputs)        701.096k (± 3.1%) i/s    (1.43 μs/i) -      3.520M in   5.026014s
+
+Comparison:
+    Zen (attributes):   848952.8 i/s
+    Zen (inputs)    :   701095.7 i/s - 1.21x  slower
+    Verbalize       :   648660.4 i/s - 1.31x  slower
+```
+
+`zen-service` with the default `:attributes` plugin outperforms `verbalize` by ~31%, while the
+experimental `:inputs` plugin is ~8% faster than `verbalize`. These benchmarks demonstrate that
+`zen-service` provides excellent performance while offering superior extensibility through its
+plugin system.
+
 ## Testing
 
 The gem has 100% test coverage with both line and branch coverage. To run the test suite:

data/lib/zen/service/callable.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Zen
+  class Service
+    class Callable
+      extend Plugins::Pluggable
+
+      use :callable
+    end
+  end
+end

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

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Zen
+  module Service::Plugins
+    module Inputs
+      extend Plugin
+
+      class Input < Data.define(:name, :optional, :default, :block)
+        def default_or_raise!
+          return default&.call if optional?
+
+          raise(ArgumentError, "input #{name} is required")
+        end
+
+        def optional?
+          !default.nil? || optional
+        end
+      end
+
+      InitInputsBlock = Data.define(:input_names, :block)
+
+      module ClassMethods
+        def inherited(service_class)
+          service_class.inputs_list.replace(inputs_list.dup)
+          service_class.init_inputs_blocks.replace(init_inputs_blocks.dup)
+          super
+        end
+
+        def input(name, optional: false, default: nil, &block)
+          inputs_list.push(Input.new(name, optional, default, block))
+          define_method(name) { @inputs.fetch(name) }
+        end
+
+        def inputs(*args, **kwargs, &block)
+          args.each { input(_1) }
+          kwargs.each { |name, default| input(name, default: default) }
+          init_inputs_blocks.push(InitInputsBlock.new(args + kwargs.keys, block)) if block
+        end
+
+        def inputs_list
+          @inputs_list ||= []
+        end
+
+        def input_names
+          inputs_list.map(&:name)
+        end
+
+        def init_inputs_blocks
+          @init_inputs_blocks ||= []
+        end
+      end
+
+      attr_reader :inputs
+
+      def initialize(**kwargs)
+        @inputs = assert_valid_inputs!(kwargs)
+        self.class.init_inputs_blocks.each do |init_block|
+          instance_exec(*inputs.values_at(*init_block.input_names), &init_block.block)
+        end
+        super()
+      end
+
+      def initialize_clone(*)
+        super
+        @inputs = @inputs.dup
+      end
+
+      private
+
+      def assert_valid_inputs!(actual) # rubocop:disable Metrics/AbcSize
+        unexpected = actual.keys - self.class.input_names
+        raise(ArgumentError, "wrong inputs #{unexpected.join(', ')} given") if unexpected.any?
+
+        self.class.inputs_list.each_with_object({}) do |reflection, result|
+          input_name = reflection.name
+          result[input_name] = actual.key?(input_name) ? actual[input_name] : reflection.default_or_raise!
+          instance_exec(result[input_name], &reflection.block) if reflection.block
+        end
+      end
+    end
+  end
+end

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

@@ -30,7 +30,7 @@ module Zen
 
       def plugins
         ancestors
-          .select { |klass| klass <= ::Zen::Service }
+          .select { |klass| klass <= ::Zen::Service || klass <= ::Zen::Service::Callable }
           .flat_map(&:service_plugins)
           .reverse
           .reduce(&:merge)

data/lib/zen/service/plugins.rb

@@ -41,6 +41,7 @@ module Zen
   require_relative "plugins/pluggable"
   require_relative "plugins/callable"
   require_relative "plugins/attributes"
+  require_relative "plugins/inputs"
   require_relative "plugins/persisted_result"
   require_relative "plugins/result_yielding"
 end

data/lib/zen/service/version.rb

@@ -2,6 +2,6 @@
 
 module Zen
   class Service
-    VERSION = "2.2.4"
+    VERSION = "2.3.0"
   end
 end

data/lib/zen/service.rb

@@ -2,6 +2,7 @@
 
 require_relative "service/version"
 require_relative "service/plugins"
+require_relative "service/callable"
 
 module Zen
   class Service

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zen-service
 version: !ruby/object:Gem::Version
-  version: 2.2.4
+  version: 2.3.0
 platform: ruby
 authors:
 - Artem Kuzko
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2026-01-19 00:00:00.000000000 Z
+date: 2026-02-02 00:00:00.000000000 Z
 dependencies: []
 description: Flexible and highly extensible Services for business logic organization
 email:
@@ -31,9 +31,11 @@ files:
 - bin/console
 - bin/setup
 - lib/zen/service.rb
+- lib/zen/service/callable.rb
 - lib/zen/service/plugins.rb
 - lib/zen/service/plugins/attributes.rb
 - lib/zen/service/plugins/callable.rb
+- lib/zen/service/plugins/inputs.rb
 - lib/zen/service/plugins/persisted_result.rb
 - lib/zen/service/plugins/pluggable.rb
 - lib/zen/service/plugins/plugin.rb