zen-service 2.0.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 64770c881ffd916d2ae348ea1e0e1b2f50f0ae1ddfe77e4cb33488894800a241
-  data.tar.gz: 1cf89ac8571af9af101ddfe2458a0a09e371a40e6d1e6bab9a58be0c0eec1445
+  metadata.gz: 12dcff33c206c08f710f8cedf505f663387054b22aa6429556b20c47eac6b410
+  data.tar.gz: b314175b5a9a5634480ac0c4fbec0777fa895e68687eedbaad8382f1b26600fe
 SHA512:
-  metadata.gz: 6467ffcd8497764c8974f45cef7106865d3109c3a794a2b7cbefd6342a3d69599392f56a83386be728ecca753fdf247a554ebd8b20c726ccc723b767618f54eb
-  data.tar.gz: '034914344b92311d62df7eec453791f87b39111a1d6f29c5344761718468c6f103a012a8981a37b0e358f612ab581ec29d4bb2a65f2b86f3a1f88ce303628157'
+  metadata.gz: 3bb64af64bf4641e01b686bf4b8bda93e5efcd8188d1ed6d1a864c74e0f2d916b03383345476c0aa1a860b3bae9ba6fbf370f6e309905d7ef5cb1186fd561b7d
+  data.tar.gz: b2678a54e99637e8d1706a6ccd913346d9e64d7ea0ef46e2c7e5637683844ab21220b6c1422601fc8466178358377e6da092cc0320cc5f6e427052b5e1b786f1

data/.github/copilot-instructions.md

@@ -0,0 +1,133 @@
+# Copilot Instructions for zen-service
+
+## Project Overview
+
+`zen-service` is a Ruby gem providing a flexible, plugin-based service object pattern. The architecture emphasizes extensibility through a plugin system where even core functionality (callable, attributes) is implemented as plugins.
+
+## Architecture Fundamentals
+
+### Plugin System
+
+The entire gem is built around `Zen::Service::Plugins` - a dynamic plugin registration and loading system:
+
+- Plugins auto-register using `extend Zen::Service::Plugins::Plugin` (converts module name to snake_case key)
+- Services use plugins via `use :plugin_name, **options`
+- Plugin lifecycle: `used(service_class)` → includes module → `configure(service_class)` if defined
+- See [plugin.rb](lib/zen/service/plugins/plugin.rb) for the DSL: `register_as`, `default_options`, `service_extension`
+
+### Core Plugins Architecture
+
+Base `Zen::Service` uses two foundational plugins:
+
+- `:callable` - provides `.call` and `.[]` class methods that instantiate + call
+- `:attributes` - manages initialization parameters with runtime validation
+
+### Service Attributes Pattern
+
+Attributes are positional-or-named parameters resolved during initialization:
+
+```ruby
+attributes :foo, :bar
+new(1, bar: 2) # foo=1, bar=2
+new(foo: 1)    # foo=1, bar=nil
+```
+
+- Attributes generate reader methods dynamically in a dedicated `AttributeMethods` module
+- Each service class gets its own `AttributeMethods` constant to isolate attribute methods
+- `with_attributes(hash)` creates clones with merged attributes
+
+## Development Workflow
+
+### Running Tests
+
+```bash
+bundle exec rspec spec          # Run all specs
+bundle exec rspec spec/zen/service_spec.rb  # Single file
+rake                            # Run specs + rubocop
+```
+
+### Test Patterns
+
+- Use `def_service { ... }` helper to define service classes in specs (see [spec_helper.rb](spec/spec_helper.rb))
+- `build_service(*args, **kwargs)` instantiates service with attributes
+- Services are frozen_string_literal by convention
+
+### Building & Releasing
+
+```bash
+rake build                      # Build gem to pkg/
+rake install                    # Install locally
+rake release                    # Tag + push to rubygems.org
+```
+
+## Key Conventions
+
+### Plugin Implementation Pattern
+
+1. Create module in `lib/zen/service/plugins/`
+2. `extend Zen::Service::Plugins::Plugin` (auto-registers)
+3. Define `used(service_class, **opts, &block)` for one-time setup
+4. Define `configure(service_class, **opts, &block)` for reconfiguration
+5. Use `prepend Extension` (for wrapping `call`) or `include` (for adding methods)
+6. Add `ClassMethods` module for class-level functionality
+
+Example from [result_yielding.rb](lib/zen/service/plugins/result_yielding.rb):
+
+```ruby
+module ResultYielding
+  extend Plugin
+
+  module Extension
+    def call
+      return super unless block_given?
+      result = nil
+      super { result = yield }
+      result
+    end
+  end
+
+  def self.used(service_class)
+    service_class.prepend(Extension)
+  end
+end
+```
+
+### Plugin Option Handling
+
+- Use `default_options foo: 5` in plugin definition
+- Access via `self.class.plugins[:plugin_name].options[:foo]`
+- Options merge with defaults when using plugin
+
+### Inheritance Behavior
+
+- `attributes_list` is duplicated on inheritance
+- Each subclass gets its own `AttributeMethods` module
+- Plugin reflections accumulate through `ancestors.flat_map(&:service_plugins)`
+
+## Critical Implementation Details
+
+### Why Prepend vs Include
+
+- `prepend Extension` - use when wrapping `call` method (allows `super` to reach original)
+- `include` - use for adding new methods
+- See `:result_yielding` (prepend) vs `:persisted_result` (extend in initialize)
+
+### Attributes Resolution Edge Cases
+
+- Cannot pass same attribute as both positional and named
+- Cannot pass more attributes than declared
+- Args filled in declaration order, then kwargs merged
+
+### Plugin DSL Methods
+
+From [plugin.rb](lib/zen/service/plugins/plugin.rb):
+
+- `register_as :custom_name` - override auto-generated registration name
+- `default_options hash` - set default plugin options
+- `service_extension module` - extend `Zen::Service` base class globally
+
+## Files of Note
+
+- [plugins.rb](lib/zen/service/plugins.rb) - central plugin registry with `fetch` and `register`
+- [pluggable.rb](lib/zen/service/plugins/pluggable.rb) - `use` DSL and plugin reflection system
+- [spec_helper.rb](spec/spec_helper.rb) - `def_service` pattern for testing services

data/README.md

@@ -98,7 +98,9 @@ simplicity.
 However, `zen-service` still provides a couple of helpfull plugins out-of-the-box:
 
 - `:persisted_result` - provides `#result` method that returns value of the latest `#call`
-  method call. Also provides `#called?` helper method.
+  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`.
 
 - `: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:
@@ -160,6 +162,18 @@ 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:
+
+```rb
+# 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)
+Zen::Service::Plugins.register(:my_plugin, "MyApp::Services::MyPlugin")
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests.

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

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "ostruct"
-
 module Zen
   module Service::Plugins
     module Callable

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

@@ -1,20 +1,18 @@
 # frozen_string_literal: true
 
-require "ostruct"
-
 module Zen
   module Service::Plugins
     module PersistedResult
       extend Plugin
 
+      default_options call_unless_called: false
+
       module Extension
         def call
           @result = super
         end
       end
 
-      attr_reader :result
-
       def initialize(*, **)
         super
         extend(Extension)
@@ -23,6 +21,12 @@ module Zen
       def called?
         defined?(@result)
       end
+
+      def result
+        call if self.class.plugins[:persisted_result].options[:call_unless_called] && !called?
+
+        @result
+      end
     end
   end
 end

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

@@ -11,7 +11,7 @@ module Zen
         defaults = extension.config[:default_options]
         opts = defaults.merge(opts) unless defaults.nil?
 
-        if using?(name)
+        if service_plugins.key?(name)
           extension.configure(self, **opts, &block) if extension.respond_to?(:configure)
           return extension
         end
@@ -23,8 +23,16 @@ module Zen
         plugins.key?(name)
       end
 
+      def service_plugins
+        @service_plugins ||= {}
+      end
+
       def plugins
-        @plugins ||= {}
+        ancestors
+          .select { |klass| klass <= ::Zen::Service }
+          .flat_map(&:service_plugins)
+          .reverse
+          .reduce(&:merge)
       end
       alias extensions plugins
 
@@ -37,7 +45,7 @@ module Zen
         extension.used(self, **opts, &block) if extension.respond_to?(:used)
         extension.configure(self, **opts, &block) if extension.respond_to?(:configure)
 
-        plugins[name] = Reflection.new(extension, opts.merge(block:))
+        service_plugins[name] = Reflection.new(extension, opts.merge(block:))
 
         extension
       end

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

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "ostruct"
-
 module Zen
   module Service::Plugins
     module ResultYielding

data/lib/zen/service/plugins.rb

@@ -3,25 +3,38 @@
 module Zen
   module Service::Plugins
     def self.fetch(name)
-      require("zen/service/plugins/#{name}") unless plugins.key?(name)
+      raise("extension `#{name}` is not registered") unless plugins.key?(name)
 
-      plugins[name] || raise("extension `#{name}` is not registered")
+      extension = plugins[name]
+      extension.is_a?(String) ? constantize(extension) : extension
     end
 
-    def self.register(name, extension)
-      raise(ArgumentError, "extension `#{name}` is already registered") if plugins.key?(name)
-
-      plugins[name] =
-        if (old_name = plugins.key(extension))
-          plugins.delete(old_name)
-        else
-          extension
+    def self.register(name_or_hash, extension = nil)
+      if name_or_hash.is_a?(Hash)
+        name_or_hash.each do |name, ext|
+          register(name, ext)
         end
+      else
+        raise ArgumentError, "extension must be given" if extension.nil?
+
+        plugins[name_or_hash] =
+          if (old_name = plugins.key(extension))
+            plugins.delete(old_name)
+          else
+            extension
+          end
+      end
     end
 
     def self.plugins
       @plugins ||= {}
     end
+
+    def self.constantize(string)
+      return string.constantize if string.respond_to?(:constantize)
+
+      string.sub(/^::/, "").split("::").inject(Object) { |obj, const| obj.const_get(const) }
+    end
   end
 
   require_relative "plugins/plugin"

data/lib/zen/service/version.rb

@@ -2,6 +2,6 @@
 
 module Zen
   class Service
-    VERSION = "2.0.0"
+    VERSION = "2.2.0"
   end
 end

data/lib/zen/service.rb

@@ -5,8 +5,6 @@ require_relative "service/plugins"
 
 module Zen
   class Service
-    autoload :SpecHelpers, "zen/service/spec_helpers"
-
     extend Plugins::Pluggable
 
     use :callable

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zen-service
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.2.0
 platform: ruby
 authors:
 - Artem Kuzko
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2025-12-07 00:00:00.000000000 Z
+date: 2025-12-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: pry
@@ -101,6 +101,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/copilot-instructions.md"
 - ".gitignore"
 - ".rspec"
 - ".rubocop.yml"