light-services 3.1.0 → 3.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 14b80318915db3dc20bd40365dc9ad00160938bb6836c1cda14bfba5301c7d7a
-  data.tar.gz: 80515890786ed055972e5b52bbc6cdee8e79b85d4fa1227b217f4b746c9fb899
+  metadata.gz: a7b40ae2a9930c6ee5831c6d5f64f84aeab383b4f35295a41faf8ae9e0735c82
+  data.tar.gz: 8bb7c192556ec28c904bd931abbf502c2533b39137c2d7d989469c11c61cd70d
 SHA512:
-  metadata.gz: 454b6f2cd8fdf8615bc29c6b69e16fe704a3b19abd8f7e48fbd1e848505038db013e41396399dd5caa721d7179ae1bc3a6a99989a3adfc0f6868e9fe49a63c85
-  data.tar.gz: 50dbf071f72a242c0c36daeb83db94db5826dca4e3e2bbe7a47f9c81006b4d2c2266731715e1948b6528df86633735839f6eee525abde302a76b7a046e484b72
+  metadata.gz: 671d913a895af97d0c37e45d21e930794317d60fac03bd46df3e43ef3dc6190617b5b5522f445f57143d96434104df636f5d29cf9c6c35d60604f61f54781dfa
+  data.tar.gz: eacef0ee6679653963d6b09a6c660c9ee503e8edc3df04411547f36e07bea91210d2683ff02ed1ee6d96924062c6e1620f95b87959e40ac80e78a211c7048f96

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 3.1.1 (2025-12-13)
+
+### Added
+
+- Better IDE support for callbacks DSL
+
 ## 3.1.0 (2025-12-13)
 
 ### Breaking changes

data/docs/{summary.md → SUMMARY.md}

@@ -1,8 +1,13 @@
-# Table of contents
+# Summary​
+
+## Introduction
 
 * [Light Services](README.md)
 * [Quickstart](quickstart.md)
 * [Concepts](concepts.md)
+
+## Deep Dive
+
 * [Arguments](arguments.md)
 * [Steps](steps.md)
 * [Outputs](outputs.md)
@@ -14,6 +19,9 @@
 * [Rails Generators](generators.md)
 * [RuboCop Integration](rubocop.md)
 * [Ruby LSP Integration](ruby-lsp.md)
+
+## Examples
+
 * [Best Practices](best-practices.md)
 * [Recipes](recipes.md)
   * [CRUD](crud.md)

data/docs/concepts.md

@@ -7,39 +7,39 @@ This section covers the core concepts of Light Services: **Arguments**, **Steps*
 When you call `MyService.run(args)`, the following happens:
 
 ```
-┌─────────────────────────────────────────────────────────────┐
+┌──────────────────────────────────────────────────────────────┐
 │                      Service.run(args)                       │
-├─────────────────────────────────────────────────────────────┤
+├──────────────────────────────────────────────────────────────┤
 │  1. Load default values for arguments and outputs            │
 │  2. Validate argument types                                  │
 │  3. Run before_service_run callbacks                         │
-├─────────────────────────────────────────────────────────────┤
+├──────────────────────────────────────────────────────────────┤
 │  4. Begin around_service_run callback                        │
 │  5. Begin database transaction (if use_transactions: true)   │
-│     ┌─────────────────────────────────────────────────────┐ │
-│     │  6. Execute steps in order                          │ │
-│     │     - Run before_step_run / around_step_run         │ │
-│     │     - Execute step method                           │ │
-│     │     - Run after_step_run / on_step_success          │ │
-│     │     - Skip if condition (if:/unless:) not met       │ │
-│     │     - Stop if errors.break? is true                 │ │
-│     │     - Stop if stop! was called                      │ │
-│     ├─────────────────────────────────────────────────────┤ │
-│     │  7. On error → Rollback transaction                 │ │
-│     │     On success → Commit transaction                 │ │
-│     └─────────────────────────────────────────────────────┘ │
+│     ┌─────────────────────────────────────────────────────┐  │
+│     │  6. Execute steps in order                          │  │
+│     │     - Run before_step_run / around_step_run         │  │
+│     │     - Execute step method                           │  │
+│     │     - Run after_step_run / on_step_success          │  │
+│     │     - Skip if condition (if:/unless:) not met       │  │
+│     │     - Stop if errors.break? is true                 │  │
+│     │     - Stop if stop! was called                      │  │
+│     ├─────────────────────────────────────────────────────┤  │
+│     │  7. On error → Rollback transaction                 │  │
+│     │     On success → Commit transaction                 │  │
+│     └─────────────────────────────────────────────────────┘  │
 │  8. End around_service_run callback                          │
-├─────────────────────────────────────────────────────────────┤
+├──────────────────────────────────────────────────────────────┤
 │  9. Run steps marked with always: true (unless stop! called) │
 │ 10. Validate output types (if success)                       │
 │ 11. Copy errors/warnings to parent service (if in context)   │
 │ 12. Run after_service_run callback                           │
 │ 13. Run on_service_success or on_service_failure callback    │
-├─────────────────────────────────────────────────────────────┤
+├──────────────────────────────────────────────────────────────┤
 │ 14. Return service instance                                  │
 │     - service.success? / service.failed?                     │
 │     - service.outputs / service.errors                       │
-└─────────────────────────────────────────────────────────────┘
+└──────────────────────────────────────────────────────────────┘
 ```
 
 ## Arguments

data/lib/light/services/base.rb

@@ -43,6 +43,7 @@ module Light
     #   result.success? # => true
     #   result.user     # => #<User id: 1, name: "John">
     class Base
+      extend CallbackDsl
       include Callbacks
       include Dsl::ArgumentsDsl
       include Dsl::OutputsDsl

data/lib/light/services/callbacks.rb

@@ -48,64 +48,6 @@ module Light
         :on_service_failure,
       ].freeze
 
-      def self.included(base)
-        base.extend(ClassMethods)
-      end
-
-      # Class methods for registering callbacks.
-      #
-      # Each callback event has a corresponding class method:
-      # - {before_step_run} - before each step executes
-      # - {after_step_run} - after each step executes
-      # - {around_step_run} - wraps step execution (must yield)
-      # - {on_step_success} - when a step completes without adding errors
-      # - {on_step_failure} - when a step adds errors
-      # - {on_step_crash} - when a step raises an exception
-      # - {before_service_run} - before the service starts
-      # - {after_service_run} - after the service completes
-      # - {around_service_run} - wraps service execution (must yield)
-      # - {on_service_success} - when service completes without errors
-      # - {on_service_failure} - when service completes with errors
-      module ClassMethods
-        # Define DSL methods for each callback event
-        EVENTS.each do |event|
-          define_method(event) do |method_name = nil, &block|
-            callback = method_name || block
-            raise ArgumentError, "#{event} requires a method name (symbol) or a block" unless callback
-
-            unless callback.is_a?(Symbol) || callback.is_a?(Proc)
-              raise ArgumentError,
-                    "#{event} callback must be a Symbol or Proc"
-            end
-
-            callbacks_for(event) << callback
-          end
-        end
-
-        # Get callbacks defined in this class for a specific event.
-        #
-        # @param event [Symbol] the callback event name
-        # @return [Array<Symbol, Proc>] callbacks for this event
-        def callbacks_for(event)
-          @callbacks ||= {}
-          @callbacks[event] ||= []
-        end
-
-        # Get all callbacks for an event including inherited ones.
-        #
-        # @param event [Symbol] the callback event name
-        # @return [Array<Symbol, Proc>] all callbacks for this event
-        def all_callbacks_for(event)
-          if superclass.respond_to?(:all_callbacks_for)
-            inherited = superclass.all_callbacks_for(event)
-          else
-            inherited = []
-          end
-
-          inherited + callbacks_for(event)
-        end
-      end
-
       # Run all callbacks for a given event.
       #
       # @param event [Symbol] the callback event name
@@ -153,5 +95,261 @@ module Light
         end
       end
     end
+
+    # Class methods for registering callbacks.
+    # Extend this module in your service class to get callback DSL methods.
+    #
+    # @example
+    #   class MyService < Light::Services::Base
+    #     before_service_run :setup
+    #     after_service_run :cleanup
+    #   end
+    module CallbackDsl
+      # Registers a callback to run before each step executes.
+      #
+      # @param method_name [Symbol, nil] name of the instance method to call
+      # @yield [service, step_name] block to execute if no method name provided
+      # @yieldparam service [Light::Services::Base] the service instance
+      # @yieldparam step_name [Symbol] the name of the step about to run
+      # @return [void]
+      # @raise [ArgumentError] if neither method name nor block is provided
+      #
+      # @example With method name
+      #   before_step_run :log_step_start
+      #
+      # @example With block
+      #   before_step_run { |service, step_name| puts "Starting #{step_name}" }
+      def before_step_run(method_name = nil, &block)
+        register_callback(:before_step_run, method_name, &block)
+      end
+
+      # Registers a callback to run after each step executes.
+      #
+      # @param method_name [Symbol, nil] name of the instance method to call
+      # @yield [service, step_name] block to execute if no method name provided
+      # @yieldparam service [Light::Services::Base] the service instance
+      # @yieldparam step_name [Symbol] the name of the step that just ran
+      # @return [void]
+      # @raise [ArgumentError] if neither method name nor block is provided
+      #
+      # @example With method name
+      #   after_step_run :log_step_complete
+      #
+      # @example With block
+      #   after_step_run { |service, step_name| puts "Finished #{step_name}" }
+      def after_step_run(method_name = nil, &block)
+        register_callback(:after_step_run, method_name, &block)
+      end
+
+      # Registers an around callback that wraps each step execution.
+      # The callback must yield to execute the step.
+      #
+      # @param method_name [Symbol, nil] name of the instance method to call
+      # @yield [service, step_name] block to execute if no method name provided
+      # @yieldparam service [Light::Services::Base] the service instance
+      # @yieldparam step_name [Symbol] the name of the step being wrapped
+      # @return [void]
+      # @raise [ArgumentError] if neither method name nor block is provided
+      #
+      # @example With method name
+      #   around_step_run :with_step_timing
+      #
+      #   def with_step_timing(service, step_name)
+      #     start = Time.now
+      #     yield
+      #     puts "#{step_name} took #{Time.now - start}s"
+      #   end
+      def around_step_run(method_name = nil, &block)
+        register_callback(:around_step_run, method_name, &block)
+      end
+
+      # Registers a callback to run when a step completes successfully (without adding errors).
+      #
+      # @param method_name [Symbol, nil] name of the instance method to call
+      # @yield [service, step_name] block to execute if no method name provided
+      # @yieldparam service [Light::Services::Base] the service instance
+      # @yieldparam step_name [Symbol] the name of the successful step
+      # @return [void]
+      # @raise [ArgumentError] if neither method name nor block is provided
+      #
+      # @example With method name
+      #   on_step_success :track_step_success
+      #
+      # @example With block
+      #   on_step_success { |service, step_name| Analytics.track("step.success", step: step_name) }
+      def on_step_success(method_name = nil, &block)
+        register_callback(:on_step_success, method_name, &block)
+      end
+
+      # Registers a callback to run when a step fails (adds errors).
+      #
+      # @param method_name [Symbol, nil] name of the instance method to call
+      # @yield [service, step_name] block to execute if no method name provided
+      # @yieldparam service [Light::Services::Base] the service instance
+      # @yieldparam step_name [Symbol] the name of the failed step
+      # @return [void]
+      # @raise [ArgumentError] if neither method name nor block is provided
+      #
+      # @example With method name
+      #   on_step_failure :handle_step_error
+      #
+      # @example With block
+      #   on_step_failure { |service, step_name| Rails.logger.error("Step #{step_name} failed") }
+      def on_step_failure(method_name = nil, &block)
+        register_callback(:on_step_failure, method_name, &block)
+      end
+
+      # Registers a callback to run when a step raises an exception.
+      #
+      # @param method_name [Symbol, nil] name of the instance method to call
+      # @yield [service, step_name, exception] block to execute if no method name provided
+      # @yieldparam service [Light::Services::Base] the service instance
+      # @yieldparam step_name [Symbol] the name of the crashed step
+      # @yieldparam exception [Exception] the exception that was raised
+      # @return [void]
+      # @raise [ArgumentError] if neither method name nor block is provided
+      #
+      # @example With method name
+      #   on_step_crash :report_crash
+      #
+      # @example With block
+      #   on_step_crash { |service, step_name, error| Sentry.capture_exception(error) }
+      def on_step_crash(method_name = nil, &block)
+        register_callback(:on_step_crash, method_name, &block)
+      end
+
+      # Registers a callback to run before the service starts executing.
+      #
+      # @param method_name [Symbol, nil] name of the instance method to call
+      # @yield [service] block to execute if no method name provided
+      # @yieldparam service [Light::Services::Base] the service instance
+      # @return [void]
+      # @raise [ArgumentError] if neither method name nor block is provided
+      #
+      # @example With method name
+      #   before_service_run :log_start
+      #
+      # @example With block
+      #   before_service_run { |service| Rails.logger.info("Starting #{service.class.name}") }
+      def before_service_run(method_name = nil, &block)
+        register_callback(:before_service_run, method_name, &block)
+      end
+
+      # Registers a callback to run after the service completes (regardless of success/failure).
+      #
+      # @param method_name [Symbol, nil] name of the instance method to call
+      # @yield [service] block to execute if no method name provided
+      # @yieldparam service [Light::Services::Base] the service instance
+      # @return [void]
+      # @raise [ArgumentError] if neither method name nor block is provided
+      #
+      # @example With method name
+      #   after_service_run :cleanup
+      #
+      # @example With block
+      #   after_service_run { |service| Rails.logger.info("Done!") }
+      def after_service_run(method_name = nil, &block)
+        register_callback(:after_service_run, method_name, &block)
+      end
+
+      # Registers an around callback that wraps the entire service execution.
+      # The callback must yield to execute the service.
+      #
+      # @param method_name [Symbol, nil] name of the instance method to call
+      # @yield [service] block to execute if no method name provided
+      # @yieldparam service [Light::Services::Base] the service instance
+      # @return [void]
+      # @raise [ArgumentError] if neither method name nor block is provided
+      #
+      # @example With method name
+      #   around_service_run :with_timing
+      #
+      #   def with_timing(service)
+      #     start = Time.now
+      #     yield
+      #     puts "Took #{Time.now - start}s"
+      #   end
+      def around_service_run(method_name = nil, &block)
+        register_callback(:around_service_run, method_name, &block)
+      end
+
+      # Registers a callback to run when the service completes successfully (without errors).
+      #
+      # @param method_name [Symbol, nil] name of the instance method to call
+      # @yield [service] block to execute if no method name provided
+      # @yieldparam service [Light::Services::Base] the service instance
+      # @return [void]
+      # @raise [ArgumentError] if neither method name nor block is provided
+      #
+      # @example With method name
+      #   on_service_success :send_notification
+      #
+      # @example With block
+      #   on_service_success { |service| NotificationMailer.success(service.user).deliver_later }
+      def on_service_success(method_name = nil, &block)
+        register_callback(:on_service_success, method_name, &block)
+      end
+
+      # Registers a callback to run when the service completes with errors.
+      #
+      # @param method_name [Symbol, nil] name of the instance method to call
+      # @yield [service] block to execute if no method name provided
+      # @yieldparam service [Light::Services::Base] the service instance
+      # @return [void]
+      # @raise [ArgumentError] if neither method name nor block is provided
+      #
+      # @example With method name
+      #   on_service_failure :log_error
+      #
+      # @example With block
+      #   on_service_failure { |service| Rails.logger.error(service.errors.full_messages) }
+      def on_service_failure(method_name = nil, &block)
+        register_callback(:on_service_failure, method_name, &block)
+      end
+
+      # Get callbacks defined in this class for a specific event.
+      #
+      # @param event [Symbol] the callback event name
+      # @return [Array<Symbol, Proc>] callbacks for this event
+      def callbacks_for(event)
+        @callbacks ||= {}
+        @callbacks[event] ||= []
+      end
+
+      # Get all callbacks for an event including inherited ones.
+      #
+      # @param event [Symbol] the callback event name
+      # @return [Array<Symbol, Proc>] all callbacks for this event
+      def all_callbacks_for(event)
+        if superclass.respond_to?(:all_callbacks_for)
+          inherited = superclass.all_callbacks_for(event)
+        else
+          inherited = []
+        end
+
+        inherited + callbacks_for(event)
+      end
+
+      private
+
+      # Registers a callback for a given event.
+      #
+      # @param event [Symbol] the callback event name
+      # @param method_name [Symbol, nil] name of the instance method to call
+      # @yield block to execute if no method name provided
+      # @return [void]
+      # @raise [ArgumentError] if neither method name nor block is provided
+      # @api private
+      def register_callback(event, method_name = nil, &block)
+        callback = method_name || block
+        raise ArgumentError, "#{event} requires a method name (symbol) or a block" unless callback
+
+        unless callback.is_a?(Symbol) || callback.is_a?(Proc)
+          raise ArgumentError, "#{event} callback must be a Symbol or Proc"
+        end
+
+        callbacks_for(event) << callback
+      end
+    end
   end
 end

data/lib/light/services/version.rb

@@ -2,6 +2,6 @@
 
 module Light
   module Services
-    VERSION = "3.1.0"
+    VERSION = "3.1.1"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: light-services
 version: !ruby/object:Gem::Version
-  version: 3.1.0
+  version: 3.1.1
 platform: ruby
 authors:
 - Andrew Kodkod
@@ -34,6 +34,8 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
+- docs/README.md
+- docs/SUMMARY.md
 - docs/arguments.md
 - docs/best-practices.md
 - docs/callbacks.md
@@ -46,13 +48,11 @@ files:
 - docs/outputs.md
 - docs/pundit-authorization.md
 - docs/quickstart.md
-- docs/readme.md
 - docs/recipes.md
 - docs/rubocop.md
 - docs/ruby-lsp.md
 - docs/service-rendering.md
 - docs/steps.md
-- docs/summary.md
 - docs/testing.md
 - lib/generators/light_services/install/USAGE
 - lib/generators/light_services/install/install_generator.rb