servactory 3.0.0.rc1 → 3.0.0.rc3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a81d492854b21f7fec57aae3bfea4093da15b1e1ffb3cad330761983471bc39c
-  data.tar.gz: 54500fceb644df98c89d66d25ab53d9bc0317d0bde0f8216be364aaa630a710a
+  metadata.gz: 5972f03405d88ae923f1e000479449e281af67b9d22b52010d2131dc1023cc15
+  data.tar.gz: 6c7c495d158deee0453114fb637897a2431d7ce4efc4e522a0716ec28a7dd89b
 SHA512:
-  metadata.gz: 695eceb38259b25d69e04a2614256a65be9e49ee1b7ea56064cb67f9e11e2a71143545bedaa37d3d669897d3d36091416f1d98a2ca1606c556391801275ecd19
-  data.tar.gz: b4550c2c7c995049df7be5d6291e5b2f381b0647317b236d7cce91254f61fdbdbd29400cdbeb993da2bd63df88244c259eb26a6d662483b711ad3bebfd94d043
+  metadata.gz: 82e84edd70b3ee47a91944bd60e5d9bec1cf33b18ca5d008d40973685c796cfa31b48de2f0599764c864db535959cd86a073ed30725c1fe1af49a98ce4bd72ab
+  data.tar.gz: 585a53ba4491246e5e4aaec23568e074a2d142d467b9d44bc551d629bce2047fcfd99d89c0bdcb897e9a28e9f7037b9128396107fe6c01083ff0b4298ee11f71

data/lib/servactory/dsl.rb

@@ -16,17 +16,17 @@ module Servactory
       end
     end
 
-    Stroma::Registry.register(:configuration, Configuration::DSL)
-    Stroma::Registry.register(:info, Info::DSL)
-    Stroma::Registry.register(:context, Context::DSL)
-    Stroma::Registry.register(:inputs, Inputs::DSL)
-    Stroma::Registry.register(:internals, Internals::DSL)
-    Stroma::Registry.register(:outputs, Outputs::DSL)
-    Stroma::Registry.register(:actions, Actions::DSL)
-    Stroma::Registry.finalize!
+    ::Stroma::Registry.register(:configuration, Configuration::DSL)
+    ::Stroma::Registry.register(:info, Info::DSL)
+    ::Stroma::Registry.register(:context, Context::DSL)
+    ::Stroma::Registry.register(:inputs, Inputs::DSL)
+    ::Stroma::Registry.register(:internals, Internals::DSL)
+    ::Stroma::Registry.register(:outputs, Outputs::DSL)
+    ::Stroma::Registry.register(:actions, Actions::DSL)
+    ::Stroma::Registry.finalize!
 
     def self.included(base)
-      base.include(Stroma::DSL)
+      base.include(::Stroma::DSL)
 
       Extensions.registry.each { |extension| base.include(extension) }
     end

data/lib/servactory/maintenance/attributes/option.rb

@@ -136,11 +136,7 @@ module Servactory
           return if @define_methods.blank?
 
           @define_methods.map do |define_method|
-            <<-RUBY.squish
-              def #{define_method.name};
-                #{define_method.content.call(option: @body)};
-              end
-            RUBY
+            "def #{define_method.name}; #{define_method.content.call(option: @body)}; end"
           end.join("; ")
         end
       end

data/lib/servactory/maintenance/attributes/options_collection.rb

@@ -3,19 +3,64 @@
 module Servactory
   module Maintenance
     module Attributes
+      # Collection wrapper for managing Option objects.
+      #
+      # ## Purpose
+      #
+      # OptionsCollection provides a unified interface for storing and querying
+      # Option instances associated with service attributes (inputs, internals, outputs).
+      # It wraps a Set to ensure uniqueness and delegates common enumeration methods.
+      #
+      # ## Usage
+      #
+      # The collection is used internally by Input, Internal, and Output classes
+      # to manage their registered options:
+      #
+      # ```ruby
+      # collection = OptionsCollection.new
+      # collection << Option.new(name: :required, ...)
+      # collection << Option.new(name: :types, ...)
+      #
+      # collection.names              # => [:required, :types]
+      # collection.find_by(name: :required)  # => Option instance
+      # ```
+      #
+      # ## Performance
+      #
+      # The collection uses memoization for frequently accessed data:
+      # - `validation_classes` - cached list of unique validation classes
+      # - `options_for_checks` - cached hash for validation pipeline
+      # - `options_index` - cached hash for O(1) lookups by name
+      #
       class OptionsCollection
         extend Forwardable
 
-        def_delegators :@collection, :<<, :filter, :each, :map, :flat_map, :find, :empty?, :size
+        def_delegators :@collection,
+                       :<<,
+                       :filter,
+                       :each, :each_with_object,
+                       :map, :flat_map,
+                       :find,
+                       :size,
+                       :empty?
 
+        # Initializes an empty collection.
+        #
+        # @return [OptionsCollection]
         def initialize
           @collection = Set.new
         end
 
+        # Returns all option names in the collection.
+        #
+        # @return [Array<Symbol>] list of option names
         def names
           map(&:name)
         end
 
+        # Returns unique validation classes from all options.
+        #
+        # @return [Array<Class>] deduplicated list of validation classes
         def validation_classes
           @validation_classes ||=
             filter { |option| option.validation_class.present? }
@@ -23,24 +68,47 @@ module Servactory
             .uniq
         end
 
+        # Returns options that need validation checks as a hash.
+        #
+        # @return [Hash{Symbol => Object}] option names mapped to normalized bodies
         def options_for_checks
-          filter(&:need_for_checks?).to_h do |option|
+          @options_for_checks ||= filter(&:need_for_checks?).to_h do |option|
             [option.name, extract_normalized_body_from(option:)]
           end
         end
 
+        # Returns the first conflict code found among options.
+        #
+        # @return [Object, nil] conflict code or nil if no conflicts
         def defined_conflict_code
           flat_map { |option| resolve_conflicts_from(option:) }
             .reject(&:blank?)
             .first
         end
 
+        # Finds an option by its name using indexed lookup.
+        #
+        # @param name [Symbol] the option name to find
+        # @return [Option, nil] the found option or nil
         def find_by(name:)
-          find { |option| option.name == name }
+          options_index[name]
         end
 
         private
 
+        # Builds and caches a hash index for O(1) option lookups.
+        #
+        # @return [Hash{Symbol => Option}] option names mapped to Option instances
+        def options_index
+          @options_index ||= each_with_object({}) do |option, index|
+            index[option.name] = option
+          end
+        end
+
+        # Extracts the normalized body value from an option.
+        #
+        # @param option [Option] the option to extract from
+        # @return [Object] the :is value if body is a Hash with :is key, otherwise the full body
         def extract_normalized_body_from(option:)
           body = option.body
           return body unless body.is_a?(Hash)
@@ -48,6 +116,10 @@ module Servactory
           body.key?(:is) ? body.fetch(:is) : body
         end
 
+        # Resolves conflict codes from an option's define_conflicts.
+        #
+        # @param option [Option] the option to check for conflicts
+        # @return [Array<Object>] array of conflict codes (may contain nils/blanks)
         def resolve_conflicts_from(option:)
           return [] unless option.define_conflicts
 

data/lib/servactory/tool_kit/dynamic_options/target.rb

@@ -3,15 +3,15 @@
 module Servactory
   module ToolKit
     module DynamicOptions
-      # Validates that attribute value matches one of the target values.
+      # Validates that Class-typed attribute value matches one of the target classes.
       #
       # ## Purpose
       #
-      # Target provides exact value matching validation for attributes.
-      # It ensures that the value is one of the specified target values,
-      # supporting both single values and arrays of acceptable values.
-      # This is useful for enum-like validations where only specific
-      # values are allowed.
+      # Target provides class matching validation for Class-typed attributes.
+      # It ensures that the passed class is one of the specified target classes,
+      # supporting both single class and arrays of acceptable classes.
+      # This is useful for validating service classes, strategy patterns,
+      # or any scenario where specific classes are expected.
       #
       # ## Usage
       #
@@ -38,22 +38,18 @@ module Servactory
       #
       # ```ruby
       # class ProcessOrderService < ApplicationService::Base
-      #   input :status, type: Symbol, target: { in: [:pending, :processing, :complete] }
-      #   input :priority, type: Integer, target: { in: [1, 2, 3] }
-      #   input :model_class, type: Class, target: { in: [User, Admin] }
+      #   input :service_class, type: Class, target: UserService
+      #   input :handler_class, type: Class, target: [CreateHandler, UpdateHandler]
       # end
       # ```
       #
       # ## Simple Mode
       #
-      # Specify target values directly:
+      # Specify target class directly or as an array:
       #
       # ```ruby
-      # class ProcessOrderService < ApplicationService::Base
-      #   input :status, type: Symbol, target: :pending
-      #   input :priority, type: Integer, target: [1, 2, 3]
-      #   input :model_class, type: Class, target: [User, Admin]
-      # end
+      # input :service_class, type: Class, target: UserService
+      # input :handler_class, type: Class, target: [CreateHandler, UpdateHandler]
       # ```
       #
       # ## Advanced Mode
@@ -64,19 +60,19 @@ module Servactory
       # With static message:
       #
       # ```ruby
-      # input :status, type: Symbol, target: {
-      #   in: [:pending, :processing, :complete],
-      #   message: "Input `status` must be one of: pending, processing, complete"
+      # input :handler_class, type: Class, target: {
+      #   in: [CreateHandler, UpdateHandler],
+      #   message: "Input `handler_class` must be one of: CreateHandler, UpdateHandler"
       # }
       # ```
       #
       # With dynamic lambda message:
       #
       # ```ruby
-      # input :status, type: Symbol, target: {
-      #   in: [:pending, :processing, :complete],
+      # input :handler_class, type: Class, target: {
+      #   in: [CreateHandler, UpdateHandler],
       #   message: lambda do |input:, value:, option_value:, **|
-      #     "Input `#{input.name}` has invalid value `#{value}`, expected: #{option_value.inspect}"
+      #     "Input `#{input.name}` received `#{value}`, expected: #{Array(option_value).map(&:name).join(', ')}"
       #   end
       # }
       # ```
@@ -88,8 +84,8 @@ module Servactory
       #
       # ## Validation Rules
       #
-      # - Value must exactly match one of the target values
-      # - Supports single value or array of values
+      # - Class must exactly match one of the target classes
+      # - Supports single class or array of classes
       # - Optional inputs with nil value validate against default
       #
       # ## Important Notes

data/lib/servactory/version.rb

@@ -5,7 +5,7 @@ module Servactory
     MAJOR = 3
     MINOR = 0
     PATCH = 0
-    PRE = "rc1"
+    PRE = "rc3"
 
     STRING = [MAJOR, MINOR, PATCH, PRE].compact.join(".")
   end

data/lib/servactory.rb

@@ -2,6 +2,8 @@
 
 require "zeitwerk"
 
+require "stroma"
+
 require "active_support/all"
 
 require "uri"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: servactory
 version: !ruby/object:Gem::Version
-  version: 3.0.0.rc1
+  version: 3.0.0.rc3
 platform: ruby
 authors:
 - Anton Sokolov
@@ -23,34 +23,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '5.1'
-- !ruby/object:Gem::Dependency
-  name: base64
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0.2'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0.2'
-- !ruby/object:Gem::Dependency
-  name: bigdecimal
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '3.1'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '3.1'
 - !ruby/object:Gem::Dependency
   name: i18n
   requirement: !ruby/object:Gem::Requirement
@@ -66,7 +38,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '1.14'
 - !ruby/object:Gem::Dependency
-  name: mutex_m
+  name: stroma
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -312,23 +284,6 @@ files:
 - lib/servactory/outputs/dsl.rb
 - lib/servactory/outputs/output.rb
 - lib/servactory/result.rb
-- lib/servactory/stroma/dsl.rb
-- lib/servactory/stroma/entry.rb
-- lib/servactory/stroma/exceptions/base.rb
-- lib/servactory/stroma/exceptions/invalid_hook_type.rb
-- lib/servactory/stroma/exceptions/key_already_registered.rb
-- lib/servactory/stroma/exceptions/registry_frozen.rb
-- lib/servactory/stroma/exceptions/registry_not_finalized.rb
-- lib/servactory/stroma/exceptions/unknown_hook_target.rb
-- lib/servactory/stroma/hooks/applier.rb
-- lib/servactory/stroma/hooks/collection.rb
-- lib/servactory/stroma/hooks/factory.rb
-- lib/servactory/stroma/hooks/hook.rb
-- lib/servactory/stroma/registry.rb
-- lib/servactory/stroma/settings/collection.rb
-- lib/servactory/stroma/settings/registry_settings.rb
-- lib/servactory/stroma/settings/setting.rb
-- lib/servactory/stroma/state.rb
 - lib/servactory/test_kit/fake_type.rb
 - lib/servactory/test_kit/result.rb
 - lib/servactory/test_kit/rspec/helpers.rb

data/lib/servactory/stroma/dsl.rb

@@ -1,118 +0,0 @@
-# frozen_string_literal: true
-
-module Servactory
-  module Stroma
-    # Main integration point between Stroma and service classes.
-    #
-    # ## Purpose
-    #
-    # Module that provides the core Stroma functionality to service classes:
-    # - Includes all registered DSL modules
-    # - Provides extensions block for hook registration
-    # - Handles inheritance with proper state copying
-    #
-    # ## Usage
-    #
-    # ```ruby
-    # class MyService
-    #   include Servactory::Stroma::DSL
-    #
-    #   extensions do
-    #     before :actions, MyExtension
-    #   end
-    # end
-    # ```
-    #
-    # ## Extension Settings Access
-    #
-    # Extensions access their settings through the stroma.settings hierarchy:
-    #
-    # ```ruby
-    # # In ClassMethods:
-    # stroma.settings[:actions][:authorization][:method_name] = :authorize
-    #
-    # # In InstanceMethods:
-    # self.class.stroma.settings[:actions][:authorization][:method_name]
-    # ```
-    #
-    # ## Integration
-    #
-    # Included by Servactory::DSL which is included by Servactory::Base.
-    # Provides ClassMethods with: stroma, inherited, extensions.
-    module DSL
-      def self.included(base)
-        base.extend(ClassMethods)
-
-        Registry.entries.each do |entry|
-          base.include(entry.extension)
-        end
-      end
-
-      # Class-level methods for Stroma integration.
-      #
-      # ## Purpose
-      #
-      # Provides access to Stroma state and hooks DSL at the class level.
-      # Handles proper duplication during inheritance.
-      #
-      # ## Key Methods
-      #
-      # - `stroma` - Access the State container
-      # - `inherited` - Copy state to child classes
-      # - `extensions` - DSL block for hook registration
-      module ClassMethods
-        def self.extended(base)
-          base.instance_variable_set(:@stroma, State.new)
-        end
-
-        # Handles inheritance by duplicating Stroma state.
-        #
-        # Creates an independent copy of hooks and settings for the child class,
-        # then applies all registered hooks to the child.
-        #
-        # @param child [Class] The child class being created
-        # @return [void]
-        def inherited(child)
-          super
-
-          child.instance_variable_set(:@stroma, stroma.dup)
-
-          Hooks::Applier.new(child, child.stroma.hooks).apply!
-        end
-
-        # Returns the Stroma state for this service class.
-        #
-        # @return [State] The Stroma state container
-        #
-        # @example Accessing hooks
-        #   stroma.hooks.before(:actions)
-        #
-        # @example Accessing settings
-        #   stroma.settings[:actions][:authorization][:method_name]
-        def stroma
-          @stroma ||= State.new
-        end
-
-        private
-
-        # DSL block for registering hooks.
-        #
-        # Evaluates the block in the context of a Hooks::Factory,
-        # allowing before/after hook registration.
-        #
-        # @yield Block with before/after DSL calls
-        # @return [void]
-        #
-        # @example
-        #   extensions do
-        #     before :actions, AuthorizationExtension
-        #     after :outputs, LoggingExtension
-        #   end
-        def extensions(&block)
-          @stroma_hooks_factory ||= Hooks::Factory.new(stroma.hooks)
-          @stroma_hooks_factory.instance_eval(&block)
-        end
-      end
-    end
-  end
-end

data/lib/servactory/stroma/entry.rb

@@ -1,32 +0,0 @@
-# frozen_string_literal: true
-
-module Servactory
-  module Stroma
-    # Represents a registered DSL entry in the Stroma registry.
-    #
-    # ## Purpose
-    #
-    # Immutable value object that holds information about a DSL module
-    # registered in the Stroma system. Each entry has a unique key
-    # and references a Module that will be included in service classes.
-    #
-    # ## Attributes
-    #
-    # - `key` (Symbol): Unique identifier for the DSL module (:inputs, :outputs, :actions)
-    # - `extension` (Module): The actual DSL module to be included
-    #
-    # ## Usage
-    #
-    # Entries are created internally by Registry.register:
-    #
-    # ```ruby
-    # Stroma::Registry.register(:inputs, Servactory::Inputs::DSL)
-    # # Creates: Entry.new(key: :inputs, extension: Servactory::Inputs::DSL)
-    # ```
-    #
-    # ## Immutability
-    #
-    # Entry is immutable (Data object) - once created, it cannot be modified.
-    Entry = Data.define(:key, :extension)
-  end
-end

data/lib/servactory/stroma/exceptions/base.rb

@@ -1,45 +0,0 @@
-# frozen_string_literal: true
-
-module Servactory
-  module Stroma
-    module Exceptions
-      # Base exception class for all Stroma-specific exceptions
-      #
-      # ## Purpose
-      #
-      # Serves as the parent class for all custom exceptions in the Stroma subsystem.
-      # Allows catching all Stroma-related exceptions with a single rescue clause.
-      #
-      # ## Usage
-      #
-      # All Stroma exceptions inherit from this base class:
-      #
-      # ```ruby
-      # begin
-      #   Servactory::Stroma::Registry.register(:custom, CustomModule)
-      # rescue Servactory::Stroma::Exceptions::Base => e
-      #   # Catches any Stroma-specific exception
-      #   handle_stroma_error(e)
-      # end
-      # ```
-      #
-      # ## Integration
-      #
-      # Can be used in application error handlers for centralized error handling:
-      #
-      # ```ruby
-      # rescue_from Servactory::Stroma::Exceptions::Base, with: :handle_stroma_error
-      # ```
-      #
-      # ## Subclasses
-      #
-      # - RegistryFrozen - Raised when modifying a finalized registry
-      # - RegistryNotFinalized - Raised when accessing registry before finalization
-      # - KeyAlreadyRegistered - Raised when registering a duplicate key
-      # - UnknownHookTarget - Raised when using an invalid hook target key
-      # - InvalidHookType - Raised when using an invalid hook type (:before/:after)
-      class Base < StandardError
-      end
-    end
-  end
-end

data/lib/servactory/stroma/exceptions/invalid_hook_type.rb

@@ -1,29 +0,0 @@
-# frozen_string_literal: true
-
-module Servactory
-  module Stroma
-    module Exceptions
-      # Raised when an invalid hook type is provided.
-      #
-      # ## Purpose
-      #
-      # Ensures that only valid hook types (:before, :after) are used
-      # when creating Servactory::Stroma::Hooks::Hook objects. Provides fail-fast
-      # behavior during class definition rather than silent failures at runtime.
-      #
-      # ## Usage
-      #
-      # ```ruby
-      # # This will raise InvalidHookType:
-      # Servactory::Stroma::Hooks::Hook.new(
-      #   type: :invalid,
-      #   target_key: :actions,
-      #   extension: MyModule
-      # )
-      # # => Servactory::Stroma::Exceptions::InvalidHookType:
-      # #    Invalid hook type: :invalid. Valid types: :before, :after
-      # ```
-      class InvalidHookType < Base; end
-    end
-  end
-end

data/lib/servactory/stroma/exceptions/key_already_registered.rb

@@ -1,32 +0,0 @@
-# frozen_string_literal: true
-
-module Servactory
-  module Stroma
-    module Exceptions
-      # Raised when registering a duplicate key in the registry
-      #
-      # ## Purpose
-      #
-      # Indicates that a DSL module key has already been registered.
-      # Each DSL module must have a unique key in the registry.
-      #
-      # ## Usage
-      #
-      # Raised when attempting to register a duplicate key:
-      #
-      # ```ruby
-      # Servactory::Stroma::Registry.register(:inputs, Inputs::DSL)
-      # Servactory::Stroma::Registry.register(:inputs, AnotherModule)
-      # # Raises: Servactory::Stroma::Exceptions::KeyAlreadyRegistered
-      # ```
-      #
-      # ## Integration
-      #
-      # This exception typically indicates a configuration error - each
-      # DSL module should only be registered once. Check for duplicate
-      # registrations in your initialization code.
-      class KeyAlreadyRegistered < Base
-      end
-    end
-  end
-end

data/lib/servactory/stroma/exceptions/registry_frozen.rb

@@ -1,33 +0,0 @@
-# frozen_string_literal: true
-
-module Servactory
-  module Stroma
-    module Exceptions
-      # Raised when attempting to modify a finalized registry
-      #
-      # ## Purpose
-      #
-      # Indicates that the Stroma::Registry has been finalized and cannot accept
-      # new module registrations. The registry is finalized once during gem
-      # initialization and remains immutable thereafter.
-      #
-      # ## Usage
-      #
-      # Raised when attempting to register modules after finalize!:
-      #
-      # ```ruby
-      # Servactory::Stroma::Registry.finalize!
-      # Servactory::Stroma::Registry.register(:custom, CustomModule)
-      # # Raises: Servactory::Stroma::Exceptions::RegistryFrozen
-      # ```
-      #
-      # ## Integration
-      #
-      # This exception typically indicates a programming error - module
-      # registration should only occur during application boot, before
-      # any service classes are defined.
-      class RegistryFrozen < Base
-      end
-    end
-  end
-end