zen-service 2.1.0 → 2.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 83f9ef4ebaca920508cb7aa96f3ce4eea6b899338b000c5a38edc6cacf342473
-  data.tar.gz: 86a27632c1fc83f7ba7c735bea83c41a1b0d9e52b2d546bfdd3054e4766c447d
+  metadata.gz: 207425486ecb408db660e845768e30e9cd19aa3ed1d6a7214d41fc0eecd46590
+  data.tar.gz: 74787fb37ce4bc2e6d7c139e7ca7b245c25fcafd6711a1aba434c0e681007b9b
 SHA512:
-  metadata.gz: 755c8e023bed8067af7fd509018ff8a001cb5618cde43fc00aa6b0244165482d58fadea79becc7b4ebb9f6a1e87aef9d9901aebd54e2218390553c2fcd71edbc
-  data.tar.gz: 55ae83ddff091119dff6b1448e37e704dcdf39cdc616fcc11b51cccd3c979113e41df8396c1cb5688c459dcc3002534ea2f512c54815a3ceecf85cc74e89d8b5
+  metadata.gz: 4bc0fe9454e82c5b49f9ab87e3812e002691002d1476b9258417fa12ddae5419ea3621de952c821b27716078e9008745acf02e00946a5538570dd89c3a020972
+  data.tar.gz: e26b152b882e1fc74ef35a99644bcc3b976c8710eb8c5833b5393edf0843f190006a019c157ba2958a082d03cedcf4c989fd2b6d5788c0bb27f36d0e9f63391f

data/.github/copilot-instructions.md

@@ -0,0 +1,141 @@
+# 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 (first use): `used(service_class)` → includes module → `configure(service_class)` if defined
+- Plugin reconfiguration (ancestor already used): only `configure(service_class)` is called, module not re-included
+- 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
+- Blocks passed to `use` are stored in `reflection.block`, separate from options (not polluting options hash)
+
+### Plugin Inheritance & Reconfiguration
+
+- When a child class uses a plugin already used by an ancestor, only `configure` callback is invoked (not `used`)
+- This allows child classes to reconfigure plugin behavior without re-including the module
+- Example: `BaseService` uses `:persisted_result` with default options, `ChildService` can reconfigure with different options
+
+### 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

@@ -116,6 +116,26 @@ However, `zen-service` still provides a couple of helpfull plugins out-of-the-bo
     end
   ```
 
+#### Plugin Lifecycle
+
+When using a plugin on a service class:
+
+- 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
+
+This design allows child classes to customize plugin behavior inherited from parent classes:
+
+```rb
+class BaseService < Zen::Service
+  use :persisted_result, call_unless_called: false
+end
+
+class ChildService < BaseService
+  use :persisted_result, call_unless_called: true  # Only reconfigures, doesn't re-include
+end
+```
+
 Bellow you can see sample implementation of a plugin that transforms resulting objects
 to camel-case notation (relying on ActiveSupport's core extensions)
 
@@ -162,6 +182,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/pluggable.rb

@@ -3,7 +3,7 @@
 module Zen
   module Service::Plugins
     module Pluggable
-      Reflection = Struct.new(:extension, :options)
+      Reflection = Struct.new(:extension, :options, :block)
 
       def use(name, **opts, &block)
         extension = Service::Plugins.fetch(name)
@@ -11,7 +11,7 @@ module Zen
         defaults = extension.config[:default_options]
         opts = defaults.merge(opts) unless defaults.nil?
 
-        if service_plugins.key?(name)
+        if plugins.key?(name)
           extension.configure(self, **opts, &block) if extension.respond_to?(:configure)
           return extension
         end
@@ -45,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)
 
-        service_plugins[name] = Reflection.new(extension, opts.merge(block:))
+        service_plugins[name] = Reflection.new(extension, opts, block)
 
         extension
       end

data/lib/zen/service/plugins.rb

@@ -3,9 +3,10 @@
 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_or_hash, extension = nil)
@@ -28,6 +29,12 @@ module Zen
     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.1.0"
+    VERSION = "2.2.1"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zen-service
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 2.2.1
 platform: ruby
 authors:
 - Artem Kuzko
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2025-12-20 00:00:00.000000000 Z
+date: 2025-12-29 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"