servus 0.2.0 → 0.3.0

data/lib/servus/event_handler.rb

@@ -207,9 +207,9 @@ module Servus
       def collect_emitted_events
         events = Set.new
 
-        ObjectSpace.each_object(Class)
-                   .select { |klass| klass < Servus::Base }
-                   .each do |service_class|
+        services = ObjectSpace.each_object(Class).select { |klass| klass < Servus::Base }
+
+        services.each do |service_class|
           service_class.event_emissions.each_value do |emissions|
             emissions.each { |emission| events << emission[:event_name] }
           end
@@ -226,9 +226,9 @@ module Servus
       def find_orphaned_handlers(emitted_events)
         orphaned = []
 
-        ObjectSpace.each_object(Class)
-                   .select { |klass| klass < Servus::EventHandler && klass != Servus::EventHandler }
-                   .each do |handler_class|
+        handlers = ObjectSpace.each_object(Class).select { _1 < Servus::EventHandler && _1 != Servus::EventHandler }
+
+        handlers.each do |handler_class|
           next unless handler_class.event_name
           next if emitted_events.include?(handler_class.event_name)
 
@@ -245,15 +245,13 @@ module Servus
       # @return [Servus::Support::Response] the service result
       # @api private
       def invoke_service(invocation, payload)
-        service_kwargs = invocation[:mapper].call(payload)
-
-        async = invocation.dig(:options, :async) || false
-        queue = invocation.dig(:options, :queue) || nil
+        use_async = invocation.dig(:options, :async) || false
 
-        if async
-          service_kwargs = service_kwargs.merge(queue: queue) if queue
+        if use_async
+          service_kwargs = prepare_call_sync_args(invocation, payload)
           invocation[:service_class].call_async(**service_kwargs)
         else
+          service_kwargs = invocation[:mapper].call(payload)
           invocation[:service_class].call(**service_kwargs)
         end
       end
@@ -270,6 +268,23 @@ module Servus
 
         true
       end
+
+      # Prepares the service arguments by merging event payload with job options.
+      #
+      # @param invocation [Hash] the invocation configuration
+      # @param payload [Hash] the event payload
+      # @return [Hash] combined service arguments
+      def prepare_call_sync_args(invocation, payload)
+        mapper  = invocation[:mapper]
+        options = invocation[:options]
+
+        # Extract service arguments and merge with job options
+        job_opts = options.slice(:queue, :wait, :wait_until, :priority, :job_options).compact
+
+        mapper
+          .call(payload)
+          .merge(job_opts)
+      end
     end
   end
 end

data/lib/servus/extensions/lazily/call.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Servus
+  module Extensions
+    module Lazily
+      # Provides lazy record resolution for service inputs.
+      #
+      # This module extends {Servus::Base} with the {#lazily} class method, enabling
+      # services to accept either a record ID or an already-loaded record instance.
+      # Resolution happens lazily on first access and is memoized.
+      #
+      # @see Lazily#lazily
+      module Call
+        # Declares a lazy record resolver for a service input.
+        #
+        # Defines an accessor method that lazily resolves the input value to a record.
+        # If the value is already an instance of the target class, it is returned directly.
+        # If the value is an ID (or other lookup value), it is resolved via the target
+        # class's +.find+ or +.find_by!+ method. Arrays are resolved via +.where+.
+        #
+        # The resolved record is written back to the instance variable, so subsequent
+        # calls return the same object without re-querying.
+        #
+        # @param name [Symbol] the param/ivar name, also becomes the accessor method
+        # @param finds [Class] the model class to resolve against (e.g., +User+, +Account+)
+        # @param by [Symbol] the lookup column (default: +:id+). When +:id+, uses +.find+.
+        #   Otherwise uses +.find_by!(column: value)+.
+        # @return [void]
+        #
+        # @example Basic usage with .find
+        #   lazily :user, finds: User
+        #   # user: 123       → User.find(123)
+        #   # user: user_inst → returns user_inst directly
+        #
+        # @example Custom column lookup
+        #   lazily :account, finds: Account, by: :uuid
+        #   # account: "abc-def" → Account.find_by!(uuid: "abc-def")
+        #
+        # @example Array input
+        #   lazily :users, finds: User
+        #   # users: [1, 2, 3] → User.where(id: [1, 2, 3])
+        #
+        # @note Only available when ActiveRecord is loaded (via Railtie)
+        # @see Servus::Base.call
+        def lazily(name, finds:, by: :id)
+          (@lazy_resolvers ||= {})[name] = { klass: finds, by: by }
+          define_resolver_method(name, finds, by)
+        end
+
+        # Returns the hash of registered lazy resolvers for this service class.
+        #
+        # @return [Hash{Symbol => Hash}] resolver configurations keyed by name
+        # @api private
+        def lazy_resolvers
+          @lazy_resolvers || {}
+        end
+
+        private
+
+        # Defines a lazy accessor method on a prepended module.
+        #
+        # @param name [Symbol] the method/ivar name
+        # @param klass [Class] the target model class
+        # @param by [Symbol] the lookup column
+        # @api private
+        def define_resolver_method(name, klass, by)
+          mod = (@_resolver_module ||= Module.new)
+          prepend(mod) unless ancestors.include?(mod)
+
+          mod.define_method(name) do
+            @_lazily_resolved ||= {}
+            return instance_variable_get(:"@#{name}") if @_lazily_resolved[name]
+
+            resolved = Resolver.call(instance_variable_get(:"@#{name}"), klass: klass, by: by, name: name)
+            @_lazily_resolved[name] = true
+            instance_variable_set(:"@#{name}", resolved)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/servus/extensions/lazily/errors.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Servus
+  module Extensions
+    module Lazily
+      # Error classes for lazy record resolution.
+      #
+      # These errors are raised when lazy resolution fails, such as when
+      # a required record reference is nil.
+      module Errors
+        # Base error class for all lazily extension errors.
+        #
+        # All lazy resolution errors inherit from this class for easy rescue handling.
+        class LazilyError < StandardError; end
+
+        # Raised when a lazily-resolved record reference is nil.
+        #
+        # This occurs when a service declares +lazily :user, finds: User+ but
+        # receives +user: nil+. A nil reference is always a bug at the call site.
+        #
+        # @example
+        #   class MyService < Servus::Base
+        #     lazily :user, finds: User
+        #
+        #     def initialize(user:)
+        #       @user = user
+        #     end
+        #
+        #     def call
+        #       user # => raises NotFoundError if @user is nil
+        #     end
+        #   end
+        class NotFoundError < LazilyError; end
+      end
+    end
+  end
+end

data/lib/servus/extensions/lazily/ext.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Servus
+  module Extensions
+    # Lazy record resolution extensions for Servus services.
+    #
+    # This module provides the infrastructure for lazily resolving record
+    # references (IDs or instances) in service inputs. When loaded, it extends
+    # {Servus::Base} with the {Call#lazily} class method.
+    #
+    # @see Servus::Extensions::Lazily::Call
+    module Lazily
+      require 'servus/extensions/lazily/errors'
+      require 'servus/extensions/lazily/resolver'
+      require 'servus/extensions/lazily/call'
+
+      # Extension module for lazily functionality.
+      #
+      # @api private
+      module Ext; end
+    end
+  end
+end

data/lib/servus/extensions/lazily/resolver.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Servus
+  module Extensions
+    module Lazily
+      # Performs the actual record resolution for a lazily-declared input.
+      #
+      # Handles the decision logic: is the raw value already an instance,
+      # nil, an array, or a lookup value? Delegates to the appropriate
+      # finder method on the target class.
+      #
+      # @api private
+      class Resolver
+        # Resolves a raw value to a record (or collection of records).
+        #
+        # @param raw [Object] the raw input value (ID, instance, Array, or nil)
+        # @param klass [Class] the target model class
+        # @param by [Symbol] the lookup column
+        # @param name [Symbol] the param name (for error messages)
+        # @return [Object] the resolved record or collection
+        # @raise [Errors::NotFoundError] if raw is nil
+        def self.call(raw, klass:, by:, name:)
+          return raw if raw.is_a?(klass)
+          raise Errors::NotFoundError, "Couldn't find #{klass} (#{name} was nil)" if raw.nil?
+          return klass.where(by => raw) if raw.is_a?(Array)
+
+          by == :id ? klass.find(raw) : klass.find_by!(by => raw)
+        end
+      end
+    end
+  end
+end

data/lib/servus/railtie.rb

@@ -14,11 +14,17 @@ module Servus
     initializer 'servus.job_async' do
       ActiveSupport.on_load(:active_job) do
         require 'servus/extensions/async/ext'
-        # Extend the base service with the async call method
         Servus::Base.extend Servus::Extensions::Async::Call
       end
     end
 
+    initializer 'servus.lazily' do
+      ActiveSupport.on_load(:active_record) do
+        require 'servus/extensions/lazily/ext'
+        Servus::Base.extend Servus::Extensions::Lazily::Call
+      end
+    end
+
     # Load guards and event handlers, clear caches on reload
     config.to_prepare do
       # Load custom guards from guards_dir

data/lib/servus/support/data_object.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require 'delegate'
+
+module Servus
+  module Support
+    # A read-only wrapper around Hash data that provides accessor-style access.
+    #
+    # When service results contain Hash data, +DataObject+ wraps it so keys can be
+    # accessed as methods in addition to the standard bracket syntax. Nested Hashes
+    # are recursively wrapped, enabling chained access like +data.user.address.city+.
+    #
+    # Non-Hash values (nil, String, Integer, Array, model instances) pass through
+    # unwrapped. This means +data.user+ returns the original object when +user+ is
+    # an ActiveRecord model, allowing natural method chaining (+data.user.email+).
+    #
+    # +DataObject+ inherits from +SimpleDelegator+, so all standard Hash methods
+    # (+[]+, +keys+, +each+, +as_json+, +==+, etc.) are delegated transparently.
+    #
+    # @example Accessor-style access
+    #   data = DataObject.wrap({ user: { email: "alice@example.com" } })
+    #   data.user.email   # => "alice@example.com"
+    #   data[:user]        # => { email: "alice@example.com" } (plain Hash)
+    #
+    # @example Mixed values
+    #   data = DataObject.wrap({ user: user_model, metadata: { source: "api" } })
+    #   data.user.email       # => delegates to model's #email method
+    #   data.metadata.source  # => "api" (wrapped Hash accessor)
+    #
+    # @see Servus::Support::Response
+    class DataObject < SimpleDelegator
+      # Wraps a value in a DataObject if it is a Hash.
+      #
+      # Non-Hash values are returned unchanged. This is the preferred way to
+      # create DataObject instances, as it handles nil and non-Hash types safely.
+      #
+      # @param data [Object] the value to potentially wrap
+      # @return [DataObject] if data is a Hash
+      # @return [Array] with Hash elements wrapped if data is an Array
+      # @return [Object] the original value otherwise
+      def self.wrap(data)
+        case data
+        when Hash  then new(data)
+        when Array then data.map { |item| wrap(item) }
+        else data
+        end
+      end
+
+      private
+
+      # Provides accessor-style access to Hash keys.
+      #
+      # Only zero-argument, no-block calls trigger key lookup. Methods with
+      # arguments (e.g., +fetch+, +dig+) delegate to Hash normally.
+      # When the value is a Hash, it is recursively wrapped in a DataObject.
+      #
+      # @param method_name [Symbol] the method name to look up as a key
+      # @return [Object] the value for the key, wrapped if it is a Hash
+      # @raise [NoMethodError] if the key does not exist
+      def method_missing(method_name, *args, &block)
+        return super if args.any? || block
+
+        hash = __getobj__
+        if hash.key?(method_name.to_sym)
+          self.class.wrap(hash[method_name.to_sym])
+        elsif hash.key?(method_name.to_s)
+          self.class.wrap(hash[method_name.to_s])
+        else
+          super
+        end
+      end
+
+      # @api private
+      def respond_to_missing?(method_name, include_private = false)
+        hash = __getobj__
+        hash.key?(method_name.to_sym) || hash.key?(method_name.to_s) || super
+      end
+    end
+  end
+end