stroma 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 73bb516679b54a0f43b33efffc0719d76211dda900024976ef6398e0b0911564
-  data.tar.gz: 34301bc64ab57e7f5f3b0fbf9bd9d71d3a23887d83dd652706b5184d4d6237a4
+  metadata.gz: 3651f535308d76dc210bfb0d49b87179e20ea806e4bb8032eee5165c7f23d635
+  data.tar.gz: 5083f7bc1e8541832be170ee35eb9ddf4852b5fd90e76af8c6d7303066e2a927
 SHA512:
-  metadata.gz: 2ee5cfa5a9f5f54aa8cb2b713a29cf1802abb6b98cd70f2e89eb3697652ce631e4f77017c0c8207309877e7e2289275caeabcda123d48cebd1527a0e397185d8
-  data.tar.gz: d8f0362ad411eea72508423e3a931e360924c996d88c011924a6ca0d483d45ddbdbd83bd590fc90cc5b466785bcac232c853a9dcc40fc8eefbfb154b90444180
+  metadata.gz: 2b56c004b08152484972a38b47919c5b1b299d9316bbbcebc2c533190ea766dee62a9882d81ca97281874c4d47bf8e4447fa31142bd51d9329d2c8a17fe9c0da
+  data.tar.gz: cee73e3a9040cf6da488c3326333618d30128dc448179e9d184b991d8602ea7da3ebfcbd50eab9e1d6559b5b14214aaed90f42ad1a6e3757d435933ba3f4f12b

data/README.md

@@ -1,4 +1,12 @@
-<h1 align="center">Stroma</h1>
+<p align="center">
+  <a href="https://servactory.com" target="_blank">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/servactory/stroma/main/.github/logo-dark.svg">
+      <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/servactory/stroma/main/.github/logo-light.svg">
+      <img alt="Stroma" src="https://raw.githubusercontent.com/servactory/stroma/main/.github/logo-light.svg" width="350" height="70" style="max-width: 100%;">
+    </picture>
+  </a>
+</p>
 
 <p align="center">
   A foundation for building modular, extensible DSLs in Ruby.
@@ -75,8 +83,24 @@ end
 
 ### Usage
 
+Create an intermediate class with lifecycle hooks:
+
 ```ruby
-class UserService < MyLib::Base
+class ApplicationService < MyLib::Base
+  # Add lifecycle hooks (optional)
+  extensions do
+    before :actions, ApplicationService::Extensions::Rollbackable::DSL
+  end
+end
+```
+
+Build services that inherit extension functionality:
+
+```ruby
+class UserService < ApplicationService
+  # DSL method from Rollbackable extension
+  on_rollback(...)
+
   input :email, type: String
 
   make :create_user
@@ -89,6 +113,12 @@ class UserService < MyLib::Base
 end
 ```
 
+Extensions allow you to add cross-cutting concerns like transactions, authorization, and rollback support. See [extension examples](https://github.com/servactory/servactory/tree/main/examples/application_service/extensions) for implementation details.
+
+## 💎 Projects Using Stroma
+
+- [Servactory](https://github.com/servactory/servactory) — Service objects framework for Ruby applications
+
 ## 🤝 Contributing
 
 We welcome contributions! Check out our [Contributing Guide](https://github.com/servactory/stroma/blob/main/CONTRIBUTING.md) to get started.

data/lib/stroma/dsl/generator.rb

@@ -16,6 +16,19 @@ module Stroma
     # - ServiceClass gets @stroma_matrix (same reference)
     # - ServiceClass gets @stroma (unique State per class)
     #
+    # ## Deferred Entry Inclusion
+    #
+    # Entry extensions are NOT included via `Module#include` at the base class level.
+    # Instead, only the `self.included` callback is fired (via `send(:included, base)`)
+    # to set up ClassMethods, constants, etc. The actual module insertion into the
+    # ancestor chain (`append_features`) is deferred until {Hooks::Applier} interleaves
+    # entries with hooks in child classes.
+    #
+    # **Contract:** Entry extensions MUST implement `self.included` as idempotent.
+    # The callback fires twice per entry per class hierarchy:
+    # 1. At base class creation (deferred, via `send(:included, base)`)
+    # 2. At child class creation (real, via `include` in {Hooks::Applier})
+    #
     # ## Usage
     #
     # ```ruby
@@ -59,11 +72,11 @@ module Stroma
       # - extensions DSL for registering hooks
       #
       # @return [Module] The generated DSL module
-      def generate # rubocop:disable Metrics/MethodLength
+      def generate # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
         matrix = @matrix
         class_methods = build_class_methods
 
-        Module.new do
+        mod = Module.new do
           @stroma_matrix = matrix
 
           class << self
@@ -75,12 +88,23 @@ module Stroma
               base.instance_variable_set(:@stroma_matrix, mtx)
               base.instance_variable_set(:@stroma, State.new)
 
-              mtx.entries.each { |entry| base.include(entry.extension) }
+              # Deferred inclusion: triggers `included` callback without `append_features`.
+              # The callback runs ClassMethods/Workspace setup on base.
+              # `append_features` (actual module insertion into ancestors) is deferred
+              # until Applier interleaves entries with hooks in child classes.
+              # NOTE: `included` will fire again when Applier calls `include` on child,
+              # so entry extensions must design `self.included` as idempotent.
+              mtx.entries.each { |entry| entry.extension.send(:included, base) }
             end
           end
 
           const_set(:ClassMethods, class_methods)
         end
+
+        Utils.name_module(mod, "Stroma::DSL(#{matrix.name})")
+        Utils.name_module(class_methods, "Stroma::DSL(#{matrix.name})::ClassMethods")
+
+        mod
       end
 
       private

data/lib/stroma/hooks/applier.rb

@@ -2,13 +2,15 @@
 
 module Stroma
   module Hooks
-    # Applies registered hooks to a target class.
+    # Applies registered hooks to a target class with deferred entry inclusion.
     #
     # ## Purpose
     #
-    # Includes hook extension modules into target class.
-    # Maintains order based on matrix registry entries.
-    # For each entry: before hooks first, then after hooks.
+    # Manages hook and entry module inclusion into the target class.
+    # Operates in three modes depending on current state:
+    # - No hooks: returns immediately (entries stay deferred)
+    # - Entries already in ancestors: includes only new hooks
+    # - Entries not in ancestors: interleaves entries with hooks for correct MRO
     #
     # ## Usage
     #
@@ -50,16 +52,59 @@ module Stroma
 
       # Applies all registered hooks to the target class.
       #
-      # For each registry entry, includes before hooks first,
-      # then after hooks. Does nothing if hooks collection is empty.
+      # Three modes based on current state:
+      # - No hooks: return immediately (defer entry inclusion)
+      # - Entries already in ancestors: include only hooks
+      # - Entries not in ancestors: interleave entries with hooks
       #
       # @return [void]
       def apply!
         return if @hooks.empty?
 
+        if entries_in_ancestors?
+          include_hooks_only
+        else
+          include_entries_with_hooks
+        end
+      end
+
+      private
+
+      # Checks whether all entry extensions are already in the target class ancestors.
+      #
+      # Uses all? so that partial inclusion (some entries present, some not)
+      # falls through to include_entries_with_hooks where Ruby skips
+      # already-included modules (idempotent) and interleaves the rest.
+      #
+      # @return [Boolean]
+      def entries_in_ancestors?
+        ancestors = @target_class.ancestors
+        @matrix.entries.all? { |e| ancestors.include?(e.extension) }
+      end
+
+      # Includes entries interleaved with their hooks.
+      #
+      # For each entry: after hooks first (reversed), then entry, then before hooks (reversed).
+      # reverse_each ensures first registered = outermost in MRO.
+      #
+      # @return [void]
+      def include_entries_with_hooks
+        @matrix.entries.each do |entry|
+          @hooks.after(entry.key).reverse_each { |hook| @target_class.include(hook.extension) }
+          @target_class.include(entry.extension)
+          @hooks.before(entry.key).reverse_each { |hook| @target_class.include(hook.extension) }
+        end
+      end
+
+      # Includes only hook extensions without entries.
+      #
+      # Used when entries are already in ancestors (multi-level inheritance).
+      #
+      # @return [void]
+      def include_hooks_only
         @matrix.entries.each do |entry|
-          @hooks.before(entry.key).each { |hook| @target_class.include(hook.extension) }
-          @hooks.after(entry.key).each { |hook| @target_class.include(hook.extension) }
+          @hooks.before(entry.key).reverse_each { |hook| @target_class.include(hook.extension) }
+          @hooks.after(entry.key).reverse_each { |hook| @target_class.include(hook.extension) }
         end
       end
     end

data/lib/stroma/hooks/collection.rb

@@ -59,7 +59,7 @@ module Stroma
       # @return [void]
       def initialize_dup(original)
         super
-        @collection = original.instance_variable_get(:@collection).dup
+        @collection = original.collection.dup
       end
 
       # Adds a new hook to the collection.
@@ -96,6 +96,10 @@ module Stroma
       def after(key)
         @collection.select { |hook| hook.after? && hook.target_key == key }
       end
+
+      protected
+
+      attr_reader :collection
     end
   end
 end

data/lib/stroma/hooks/hook.rb

@@ -46,7 +46,7 @@ module Stroma
       # @param extension [Module] Extension module to include
       # @raise [Exceptions::InvalidHookType] If type is invalid
       def initialize(type:, target_key:, extension:)
-        if VALID_HOOK_TYPES.exclude?(type)
+        unless VALID_HOOK_TYPES.include?(type)
           raise Exceptions::InvalidHookType,
                 "Invalid hook type: #{type.inspect}. Valid types: #{VALID_HOOK_TYPES.map(&:inspect).join(', ')}"
         end

data/lib/stroma/registry.rb

@@ -70,6 +70,7 @@ module Stroma
       return if @finalized
 
       @entries.freeze
+      @keys = @entries.map(&:key).freeze
       @finalized = true
     end
 
@@ -88,7 +89,7 @@ module Stroma
     # @return [Array<Symbol>] The registry keys
     def keys
       ensure_finalized!
-      @entries.map(&:key)
+      @keys
     end
 
     # Checks if a key is registered.
@@ -98,7 +99,7 @@ module Stroma
     # @return [Boolean] true if the key is registered
     def key?(key)
       ensure_finalized!
-      @entries.any? { |e| e.key == key.to_sym }
+      @keys.include?(key.to_sym)
     end
 
     private

data/lib/stroma/settings/collection.rb

@@ -61,7 +61,7 @@ module Stroma
       # @return [void]
       def initialize_dup(original)
         super
-        @storage = original.instance_variable_get(:@storage).transform_values(&:dup)
+        @storage = original.storage.transform_values(&:dup)
       end
 
       # Accesses or creates RegistrySettings for a registry key.
@@ -83,6 +83,10 @@ module Stroma
       def to_h
         @storage.transform_values(&:to_h)
       end
+
+      protected
+
+      attr_reader :storage
     end
   end
 end

data/lib/stroma/settings/registry_settings.rb

@@ -59,7 +59,7 @@ module Stroma
       # @return [void]
       def initialize_dup(original)
         super
-        @storage = original.instance_variable_get(:@storage).transform_values(&:dup)
+        @storage = original.storage.transform_values(&:dup)
       end
 
       # Accesses or creates a Setting for an extension.
@@ -81,6 +81,10 @@ module Stroma
       def to_h
         @storage.transform_values(&:to_h)
       end
+
+      protected
+
+      attr_reader :storage
     end
   end
 end

data/lib/stroma/settings/setting.rb

@@ -69,7 +69,7 @@ module Stroma
       # @return [void]
       def initialize_dup(original)
         super
-        @data = deep_dup(original.instance_variable_get(:@data))
+        @data = deep_dup(original.data)
       end
 
       # Converts to a plain Hash.
@@ -93,6 +93,10 @@ module Stroma
         @data.fetch(key.to_sym, *args, &block)
       end
 
+      protected
+
+      attr_reader :data
+
       private
 
       # Recursively duplicates nested Hash and Array structures.

data/lib/stroma/state.rb

@@ -60,8 +60,8 @@ module Stroma
     # @return [void]
     def initialize_dup(original)
       super
-      @hooks = original.instance_variable_get(:@hooks).dup
-      @settings = original.instance_variable_get(:@settings).dup
+      @hooks = original.hooks.dup
+      @settings = original.settings.dup
     end
   end
 end

data/lib/stroma/utils.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Stroma
+  # Shared utility methods for the Stroma framework.
+  #
+  # ## Purpose
+  #
+  # Provides common helper methods used across multiple Stroma components.
+  # All methods are module functions - callable as both module methods
+  # and instance methods when included.
+  module Utils
+    module_function
+
+    # Assigns a temporary name to an anonymous module for debugging clarity.
+    # Uses set_temporary_name (Ruby 3.3+) when available.
+    #
+    # TODO: Remove the else branch when Ruby 3.2 support is dropped.
+    #       The define_singleton_method fallback is a temporary workaround
+    #       that only affects #inspect and #to_s. Unlike set_temporary_name,
+    #       it does not set #name, so the module remains technically anonymous.
+    #
+    # @param mod [Module] The module to name
+    # @param name [String] The temporary name
+    # @return [void]
+    def name_module(mod, name)
+      if mod.respond_to?(:set_temporary_name)
+        mod.set_temporary_name(name)
+      else
+        mod.define_singleton_method(:inspect) { name }
+        mod.define_singleton_method(:to_s) { name }
+      end
+    end
+  end
+end

data/lib/stroma/version.rb

@@ -3,7 +3,7 @@
 module Stroma
   module VERSION
     MAJOR = 0
-    MINOR = 4
+    MINOR = 5
     PATCH = 0
     PRE = nil
 

data/lib/stroma.rb

@@ -2,8 +2,6 @@
 
 require "zeitwerk"
 
-require "active_support/all"
-
 loader = Zeitwerk::Loader.for_gem
 loader.ignore("#{__dir__}/stroma/test_kit/rspec")
 loader.inflector.inflect(

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: stroma
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Anton Sokolov
@@ -9,20 +9,6 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
-- !ruby/object:Gem::Dependency
-  name: activesupport
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '5.1'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '5.1'
 - !ruby/object:Gem::Dependency
   name: zeitwerk
   requirement: !ruby/object:Gem::Requirement
@@ -151,6 +137,7 @@ files:
 - lib/stroma/settings/registry_settings.rb
 - lib/stroma/settings/setting.rb
 - lib/stroma/state.rb
+- lib/stroma/utils.rb
 - lib/stroma/version.rb
 homepage: https://github.com/servactory/stroma
 licenses:
@@ -174,7 +161,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.6
 specification_version: 4
 summary: Foundation for building modular, extensible DSLs
 test_files: []