light-services 2.2 → 3.0.0

data/lib/light/services/settings/field.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+# Unified settings class for arguments and outputs
+module Light
+  module Services
+    module Settings
+      class Field
+        attr_reader :name, :default_exists, :default, :context, :optional
+
+        def initialize(name, service_class, opts = {})
+          @name = name
+          @service_class = service_class
+          @field_type = opts.delete(:field_type) || :argument
+
+          @type = opts.delete(:type)
+          @context = opts.delete(:context)
+          @default_exists = opts.key?(:default)
+          @default = opts.delete(:default)
+          @optional = opts.delete(:optional)
+
+          define_methods
+        end
+
+        # Validate and optionally coerce the value
+        # Returns the (possibly coerced) value
+        def validate_type!(value)
+          return value unless @type
+
+          if dry_type?(@type)
+            coerce_and_validate_dry_type!(value)
+          else
+            validate_ruby_type!(value)
+            value
+          end
+        end
+
+        private
+
+        # Check if the type is a dry-types type
+        def dry_type?(type)
+          return false unless defined?(Dry::Types::Type)
+
+          type.is_a?(Dry::Types::Type)
+        end
+
+        # Validate and coerce value against dry-types
+        # Returns the coerced value
+        def coerce_and_validate_dry_type!(value)
+          @type[value]
+        rescue Dry::Types::ConstraintError, Dry::Types::CoercionError => e
+          raise Light::Services::ArgTypeError,
+                "#{@service_class} #{@field_type} `#{@name}` #{e.message}"
+        end
+
+        # Validate value against Ruby class types
+        def validate_ruby_type!(value)
+          return if [*@type].any? { |type| value.is_a?(type) }
+
+          raise Light::Services::ArgTypeError, type_error_message(value)
+        end
+
+        def type_error_message(value)
+          expected_types = [*@type].map(&:to_s).join(" or ")
+          "#{@service_class} #{@field_type} `#{@name}` must be #{expected_types}, \" \\
+            \"but got #{value.class} with value: #{value.inspect}"
+        end
+
+        def define_methods
+          name = @name
+          collection_instance_var = :"@#{@field_type}s"
+
+          @service_class.define_method(@name) { instance_variable_get(collection_instance_var).get(name) }
+          @service_class.define_method(:"#{@name}?") { !!instance_variable_get(collection_instance_var).get(name) }
+          @service_class.define_method(:"#{@name}=") do |value|
+            instance_variable_get(collection_instance_var).set(name, value)
+          end
+          @service_class.send(:private, "#{@name}=")
+        end
+      end
+
+      # Aliases for backwards compatibility
+      Argument = Field
+      Output = Field
+    end
+  end
+end

data/lib/light/services/settings/step.rb

@@ -17,33 +17,48 @@ module Light
           @always = opts[:always]
 
           if @if && @unless
-            raise Light::Services::TwoConditions, "#{service_class} `if` and `unless` cannot be specified " \
-                                                  "for the step `#{name}` at the same time"
+            raise Light::Services::Error, "#{service_class} `if` and `unless` cannot be specified " \
+                                          "for the step `#{name}` at the same time"
           end
         end
 
-        def run(instance, benchmark: false)
+        def run(instance) # rubocop:disable Naming/PredicateMethod
           return false unless run?(instance)
 
-          if instance.respond_to?(name, true)
-            if benchmark
-              time = Benchmark.ms do
-                instance.send(name)
-              end
+          unless instance.respond_to?(name, true)
+            available_steps = @service_class.steps.keys.join(", ")
+            raise Light::Services::Error,
+                  "Step method `#{name}` is not defined in #{@service_class}. " \
+                  "Defined steps: [#{available_steps}]"
+          end
 
-              instance.log "⏱️ Step #{name} took #{time}ms"
-            else
-              instance.send(name)
-            end
+          execute_with_callbacks(instance)
+          true
+        end
 
-            true
+        private
+
+        def execute_with_callbacks(instance)
+          errors_count_before = instance.errors.count
+
+          instance.run_callbacks(:before_step_run, instance, name)
+
+          instance.run_callbacks(:around_step_run, instance, name) do
+            instance.send(name)
+          end
+
+          instance.run_callbacks(:after_step_run, instance, name)
+
+          if instance.errors.count > errors_count_before
+            instance.run_callbacks(:on_step_failure, instance, name)
           else
-            raise Light::Services::NoStepError, "Cannot find step `#{name}` in service `#{@service_class}`"
+            instance.run_callbacks(:on_step_success, instance, name)
           end
+        rescue StandardError => e
+          instance.run_callbacks(:on_step_crash, instance, name, e)
+          raise e
         end
 
-        private
-
         def run?(instance)
           return false if instance.done?
 

data/lib/light/services/utils.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Light
+  module Services
+    # Utility module providing helper methods for the Light Services library
+    module Utils
+      module_function
+
+      # Creates a deep copy of an object to prevent mutation of shared references.
+      #
+      # @param object [Object] the object to duplicate
+      # @return [Object] a deep copy of the object
+      #
+      # @example Deep duping a hash
+      #   original = { a: { b: 1 } }
+      #   copy = Utils.deep_dup(original)
+      #   copy[:a][:b] = 2
+      #   original[:a][:b] # => 1
+      #
+      # @example Deep duping an array
+      #   original = [[1, 2], [3, 4]]
+      #   copy = Utils.deep_dup(original)
+      #   copy[0] << 5
+      #   original[0] # => [1, 2]
+      #
+      def deep_dup(object)
+        # Use ActiveSupport's deep_dup if available (preferred for Rails apps)
+        return object.deep_dup if object.respond_to?(:deep_dup)
+
+        # Fallback to Marshal for objects that support serialization
+        Marshal.load(Marshal.dump(object))
+      rescue TypeError
+        # Last resort: use dup if available, otherwise return original
+        object.respond_to?(:dup) ? object.dup : object
+      end
+    end
+  end
+end

data/lib/light/services/version.rb

@@ -2,6 +2,6 @@
 
 module Light
   module Services
-    VERSION = "2.2"
+    VERSION = "3.0.0"
   end
 end

data/lib/light/services.rb

@@ -3,6 +3,8 @@
 require "light/services/config"
 require "light/services/version"
 require "light/services/exceptions"
+require "light/services/utils"
+require "light/services/callbacks"
 require "light/services/base"
 
 module Light

data/light-services.gemspec

@@ -8,11 +8,11 @@ Gem::Specification.new do |spec|
   spec.authors       = ["Andrew Kodkod"]
   spec.email         = ["andrew@kodkod.me"]
 
-  spec.summary       = "Robust service architecture for Ruby frameworks"
-  spec.description   = "Robust service architecture for Ruby frameworks"
+  spec.summary       = "Robust service architecture for Ruby/Rails applications"
+  spec.description   = "Light Services is a simple yet powerful way to organize business logic in Ruby applications. Build services that are easy to test, maintain, and understand." # rubocop:disable Layout/LineLength
   spec.homepage      = "https://light-services-docs.vercel.app/"
   spec.license       = "MIT"
-  spec.required_ruby_version = Gem::Requirement.new(">= 2.7.0")
+  spec.required_ruby_version = Gem::Requirement.new(">= 3.0.0")
 
   spec.metadata["allowed_push_host"] = "https://rubygems.org"
 
@@ -26,10 +26,8 @@ Gem::Specification.new do |spec|
     `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
   end
 
-  spec.bindir        = "exe"
-  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
-  spec.require_paths = ["lib"]
+  spec.bindir                            = "exe"
+  spec.executables                       = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths                     = ["lib"]
   spec.metadata["rubygems_mfa_required"] = "true"
-
-  spec.add_dependency "benchmark", ">= 0.5"
 end

metadata

@@ -1,29 +1,16 @@
 --- !ruby/object:Gem::Specification
 name: light-services
 version: !ruby/object:Gem::Version
-  version: '2.2'
+  version: 3.0.0
 platform: ruby
 authors:
 - Andrew Kodkod
 bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies:
-- !ruby/object:Gem::Dependency
-  name: benchmark
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0.5'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0.5'
-description: Robust service architecture for Ruby frameworks
+dependencies: []
+description: Light Services is a simple yet powerful way to organize business logic
+  in Ruby applications. Build services that are easy to test, maintain, and understand.
 email:
 - andrew@kodkod.me
 executables: []
@@ -38,6 +25,7 @@ files:
 - ".rubocop.yml"
 - ".ruby-version"
 - CHANGELOG.md
+- CLAUDE.md
 - CODE_OF_CONDUCT.md
 - Gemfile
 - Gemfile.lock
@@ -46,21 +34,61 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
+- docs/arguments.md
+- docs/best-practices.md
+- docs/callbacks.md
+- docs/concepts.md
+- docs/configuration.md
+- docs/context.md
+- docs/crud.md
+- docs/errors.md
+- docs/generators.md
+- docs/outputs.md
+- docs/pundit-authorization.md
+- docs/quickstart.md
+- docs/readme.md
+- docs/recipes.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
+- lib/generators/light_services/install/templates/application_service.rb.tt
+- lib/generators/light_services/install/templates/application_service_spec.rb.tt
+- lib/generators/light_services/install/templates/initializer.rb.tt
+- lib/generators/light_services/service/USAGE
+- lib/generators/light_services/service/service_generator.rb
+- lib/generators/light_services/service/templates/service.rb.tt
+- lib/generators/light_services/service/templates/service_spec.rb.tt
 - lib/light/services.rb
 - lib/light/services/base.rb
 - lib/light/services/base_with_context.rb
-- lib/light/services/class_based_collection/base.rb
-- lib/light/services/class_based_collection/mount.rb
-- lib/light/services/collection/arguments.rb
-- lib/light/services/collection/base.rb
-- lib/light/services/collection/outputs.rb
+- lib/light/services/callbacks.rb
+- lib/light/services/collection.rb
+- lib/light/services/concerns/execution.rb
+- lib/light/services/concerns/parent_service.rb
+- lib/light/services/concerns/state_management.rb
 - lib/light/services/config.rb
+- lib/light/services/constants.rb
+- lib/light/services/dsl/arguments_dsl.rb
+- lib/light/services/dsl/outputs_dsl.rb
+- lib/light/services/dsl/steps_dsl.rb
+- lib/light/services/dsl/validation.rb
 - lib/light/services/exceptions.rb
 - lib/light/services/message.rb
 - lib/light/services/messages.rb
-- lib/light/services/settings/argument.rb
-- lib/light/services/settings/output.rb
+- lib/light/services/rspec.rb
+- lib/light/services/rspec/matchers/define_argument.rb
+- lib/light/services/rspec/matchers/define_output.rb
+- lib/light/services/rspec/matchers/define_step.rb
+- lib/light/services/rspec/matchers/execute_step.rb
+- lib/light/services/rspec/matchers/have_error_on.rb
+- lib/light/services/rspec/matchers/have_warning_on.rb
+- lib/light/services/rspec/matchers/trigger_callback.rb
+- lib/light/services/settings/field.rb
 - lib/light/services/settings/step.rb
+- lib/light/services/utils.rb
 - lib/light/services/version.rb
 - light-services.gemspec
 homepage: https://light-services-docs.vercel.app/
@@ -79,7 +107,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.7.0
+      version: 3.0.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -88,5 +116,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.9
 specification_version: 4
-summary: Robust service architecture for Ruby frameworks
+summary: Robust service architecture for Ruby/Rails applications
 test_files: []

data/lib/light/services/class_based_collection/base.rb

@@ -1,86 +0,0 @@
-# frozen_string_literal: true
-
-# Create class based collections for storing arguments settings, steps settings and outputs settings
-#
-# General functionality:
-#   1. Collection automatically loads data from parent classes
-#   2. It's possible to redefine items if needed (e.g. arguments)
-#   3. We can add items into collection after or before another items
-#
-module Light
-  module Services
-    module ClassBasedCollection
-      class Base
-        # TODO: Add `prepend: true`
-        def initialize(item_class, allow_redefine)
-          @item_class = item_class
-          @allow_redefine = allow_redefine
-          @collection = {}
-        end
-
-        def add(klass, name, opts = {})
-          @collection[klass] ||= all_from_superclass(klass)
-
-          validate_name!(klass, name)
-          validate_opts!(klass, name, opts)
-
-          item = @item_class.new(name, klass, opts)
-
-          if opts[:before] || opts[:after]
-            insert_item(klass, name, opts, item)
-          else
-            @collection[klass][name] = item
-          end
-        end
-
-        def find_index(klass, name)
-          index = @collection[klass].keys.index(name)
-
-          return index if index
-
-          # TODO: Update `NoStepError` because it maybe not only step
-          raise Light::Services::NoStepError, "Cannot find #{@item_class} `#{name}` in service #{klass}"
-        end
-
-        def remove(klass, name)
-          @collection[klass] ||= all_from_superclass(klass)
-          @collection[klass].delete(name)
-        end
-
-        def all(klass)
-          @collection[klass] || all_from_superclass(klass)
-        end
-
-        private
-
-        def all_from_superclass(klass)
-          if klass.superclass <= Light::Services::Base
-            all(klass.superclass).dup
-          else
-            {}
-          end
-        end
-
-        def validate_name!(klass, name)
-          if !@allow_redefine && all(klass).key?(name)
-            raise Light::Services::Error, "#{@item_class} with name `#{name}` already exists in service #{klass}"
-          end
-        end
-
-        def validate_opts!(klass, name, opts)
-          if opts[:before] && opts[:after]
-            raise Light::Services::Error, "You cannot specify `before` and `after` " \
-                                          "for #{@item_class} `#{name}` in service #{klass} at the same time"
-          end
-        end
-
-        def insert_item(klass, name, opts, item)
-          index = find_index(klass, opts[:before] || opts[:after])
-          index += 1 unless opts[:before]
-
-          @collection[klass] = @collection[klass].to_a.insert(index, [name, item]).to_h
-        end
-      end
-    end
-  end
-end

data/lib/light/services/class_based_collection/mount.rb

@@ -1,33 +0,0 @@
-# frozen_string_literal: true
-
-# This class allows to mount class based collections to service objects
-#
-# Usage:
-#
-#   mount_class_based_collection :steps,     klass: Settings::Step,     shortcut: :step
-#   mount_class_based_collection :outputs,   klass: Settings::Output,   shortcut: :output
-#   mount_class_based_collection :arguments, klass: Settings::Argument, shortcut: :arg, allow_redefine: true
-#
-module Light
-  module Services
-    module ClassBasedCollection
-      module Mount
-        def mount_class_based_collection(collection_name, item_class:, shortcut:, allow_redefine: false)
-          class_variable_set(:"@@#{collection_name}", ClassBasedCollection::Base.new(item_class, allow_redefine))
-
-          define_singleton_method shortcut do |item_name, opts = {}|
-            class_variable_get(:"@@#{collection_name}").add(self, item_name, opts)
-          end
-
-          define_singleton_method :"remove_#{shortcut}" do |item_name|
-            class_variable_get(:"@@#{collection_name}").remove(self, item_name)
-          end
-
-          define_singleton_method collection_name do
-            class_variable_get(:"@@#{collection_name}").all(self)
-          end
-        end
-      end
-    end
-  end
-end

data/lib/light/services/collection/arguments.rb

@@ -1,34 +0,0 @@
-# frozen_string_literal: true
-
-# Collection to store, merge and validate arguments
-module Light
-  module Services
-    module Collection
-      class Arguments < Base
-        def extend_with_context(args)
-          settings_collection.each do |name, settings|
-            next if !settings.context || args.key?(name) || !key?(name)
-
-            args[settings.name] = get(name)
-          end
-
-          args
-        end
-
-        def validate!
-          settings_collection.each do |name, settings|
-            next if settings.optional && (!key?(name) || get(name).nil?)
-
-            settings.validate_type!(get(name))
-          end
-        end
-
-        private
-
-        def settings_collection
-          @instance.class.arguments
-        end
-      end
-    end
-  end
-end

data/lib/light/services/collection/base.rb

@@ -1,59 +0,0 @@
-# frozen_string_literal: true
-
-# Collection to store arguments and outputs values
-module Light
-  module Services
-    module Collection
-      class Base
-        # Includes
-        extend Forwardable
-
-        # Settings
-        def_delegators :@storage, :key?, :to_h
-
-        def initialize(instance, storage = {})
-          @instance = instance
-          @storage = storage
-
-          return if storage.is_a?(Hash)
-
-          raise Light::Services::ArgTypeError, "#{instance.class} - arguments must be a Hash"
-        end
-
-        def set(key, value)
-          @storage[key] = value
-        end
-
-        def get(key)
-          @storage[key]
-        end
-
-        def [](key)
-          get(key)
-        end
-
-        def []=(key, value)
-          set(key, value)
-        end
-
-        def load_defaults
-          settings_collection.each do |name, settings|
-            next if !settings.default_exists || key?(name)
-
-            if settings.default.is_a?(Proc)
-              set(name, @instance.instance_exec(&settings.default))
-            else
-              set(name, deep_dup(settings.default))
-            end
-          end
-        end
-
-        private
-
-        def deep_dup(object)
-          Marshal.load(Marshal.dump(object))
-        end
-      end
-    end
-  end
-end

data/lib/light/services/collection/outputs.rb

@@ -1,16 +0,0 @@
-# frozen_string_literal: true
-
-# Collection to store outputs values
-module Light
-  module Services
-    module Collection
-      class Outputs < Base
-        private
-
-        def settings_collection
-          @instance.class.outputs
-        end
-      end
-    end
-  end
-end

data/lib/light/services/settings/argument.rb

@@ -1,68 +0,0 @@
-# frozen_string_literal: true
-
-# This class defines settings for argument
-module Light
-  module Services
-    module Settings
-      class Argument
-        # Getters
-        attr_reader :name, :default_exists, :default, :context, :optional, :arg_types_cache
-
-        def initialize(name, service_class, opts = {})
-          @name = name
-          @service_class = service_class
-
-          @type = opts.delete(:type)
-          @context = opts.delete(:context)
-          @default_exists = opts.key?(:default)
-          @default = opts.delete(:default)
-          @optional = opts.delete(:optional)
-
-          @arg_types_cache = {}
-
-          define_methods
-        end
-
-        def validate_type!(value)
-          return if !@type || [*@type].any? do |type|
-            case type
-            when :boolean
-              value.is_a?(TrueClass) || value.is_a?(FalseClass)
-            when Symbol
-              arg_type(value) == type
-            else
-              value.is_a?(type)
-            end
-          end
-
-          raise Light::Services::ArgTypeError, "#{@service_class} argument `#{name}` must be " \
-                                               "a #{[*@type].join(', ')} (currently: #{value.class})"
-        end
-
-        private
-
-        def arg_type(value)
-          klass = value.class
-
-          @arg_types_cache[klass] ||= klass
-            .name
-            .gsub("::", "/")
-            .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
-            .gsub(/([a-z\d])([A-Z])/, '\1_\2')
-            .tr("-", "_")
-            .downcase
-            .to_sym
-        end
-
-        def define_methods
-          name = @name
-
-          @service_class.define_method(@name) { @arguments.get(name) }
-          @service_class.define_method(:"#{@name}?") { !!@arguments.get(name) }
-          @service_class.define_method(:"#{@name}=") { |value| @arguments.set(name, value) }
-          @service_class.send(:private, "#{@name}=")
-        end
-      end
-    end
-  end
-end