operandi 5.0.0

data/lib/generators/operandi/service/service_generator.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module Operandi
+  module Generators
+    class ServiceGenerator < ::Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      argument :name,
+               type: :string,
+               required: true,
+               desc: "The name of the service (e.g., user/create or CreateUser)"
+
+      class_option :args,
+                   type: :array,
+                   default: [],
+                   desc: "List of arguments for the service"
+      class_option :steps,
+                   type: :array,
+                   default: [],
+                   desc: "List of steps for the service"
+      class_option :outputs,
+                   type: :array,
+                   default: [],
+                   desc: "List of outputs for the service"
+      class_option :skip_spec,
+                   type: :boolean,
+                   default: false,
+                   desc: "Skip creating the spec file"
+      class_option :parent,
+                   type: :string,
+                   default: "ApplicationService",
+                   desc: "Parent class for the service"
+
+      desc "Creates a new service class"
+
+      def create_service_file
+        template "service.rb.tt", "app/services/#{file_path}.rb"
+      end
+
+      def create_spec_file
+        return if options[:skip_spec]
+        return unless rspec_installed?
+
+        template "service_spec.rb.tt", "spec/services/#{file_path}_spec.rb"
+      end
+
+      private
+
+      def file_path
+        name.underscore
+      end
+
+      def class_name
+        name.camelize
+      end
+
+      def parent_class
+        options[:parent]
+      end
+
+      def arguments
+        options[:args]
+      end
+
+      def steps
+        options[:steps]
+      end
+
+      def outputs
+        options[:outputs]
+      end
+
+      def rspec_installed?
+        File.directory?(File.join(destination_root, "spec"))
+      end
+    end
+  end
+end

data/lib/generators/operandi/service/templates/service.rb.tt

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+class <%= class_name %> < <%= parent_class %>
+<% if arguments.any? -%>
+  # Arguments
+<% arguments.each do |arg| -%>
+  arg :<%= arg %>
+<% end -%>
+
+<% end -%>
+<% if steps.any? -%>
+  # Steps
+<% steps.each do |step| -%>
+  step :<%= step %>
+<% end -%>
+
+<% end -%>
+<% if outputs.any? -%>
+  # Outputs
+<% outputs.each do |output| -%>
+  output :<%= output %>
+<% end -%>
+
+<% end -%>
+<% if steps.empty? -%>
+  # step :step_a
+  # step :step_b
+
+<% end -%>
+  private
+
+<% if steps.any? -%>
+<% steps.each_with_index do |step, index| -%>
+  def <%= step %>
+    # TODO: Implement <%= step %>
+  end
+<%= "\n" unless index == steps.length - 1 -%>
+<% end -%>
+<% else -%>
+  # def step_a
+  #   # TODO: Implement service logic
+  # end
+
+  # def step_b
+  #   # TODO: Implement service logic
+  # end
+<% end -%>
+end

data/lib/generators/operandi/service/templates/service_spec.rb.tt

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+
+# TODO: Add test implementation
+RSpec.describe <%= class_name %>, type: :service do
+<% if arguments.any? -%>
+  describe "arguments" do
+<% arguments.each do |arg| -%>
+    it { is_expected.to define_argument(:<%= arg %>) }
+<% end -%>
+  end
+
+<% end -%>
+<% if steps.any? -%>
+  describe "steps" do
+<% steps.each do |step| -%>
+    it { is_expected.to define_step(:<%= step %>) }
+<% end -%>
+  end
+
+<% end -%>
+<% if outputs.any? -%>
+  describe "outputs" do
+<% outputs.each do |output| -%>
+    it { is_expected.to define_output(:<%= output %>) }
+<% end -%>
+  end
+
+<% end -%>
+  describe "#run" do
+    subject(:service) { described_class.run(args) }
+
+    let(:args) { {} }
+
+    it "succeeds" do
+      expect(service).to be_successful
+    end
+  end
+end

data/lib/operandi/base.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+require "operandi/constants"
+require "operandi/message"
+require "operandi/messages"
+require "operandi/base_with_context"
+
+require "operandi/settings/step"
+require "operandi/settings/field"
+
+require "operandi/collection"
+
+require "operandi/dsl/arguments_dsl"
+require "operandi/dsl/outputs_dsl"
+require "operandi/dsl/steps_dsl"
+
+require "operandi/concerns/execution"
+require "operandi/concerns/state_management"
+require "operandi/concerns/parent_service"
+
+# Base class for all service objects
+module Operandi
+  # Base class for building service objects with arguments, outputs, and steps.
+  #
+  # @example Basic service
+  #   class CreateUser < Operandi::Base
+  #     arg :name, type: String
+  #     arg :email, type: String
+  #
+  #     output :user, type: User
+  #
+  #     step :create_user
+  #
+  #     private
+  #
+  #     def create_user
+  #       self.user = User.create!(name: name, email: email)
+  #     end
+  #   end
+  #
+  #   result = CreateUser.run(name: "John", email: "john@example.com")
+  #   result.success? # => true
+  #   result.user     # => #<User id: 1, name: "John">
+  class Base
+    extend CallbackDsl
+    include Callbacks
+    include Dsl::ArgumentsDsl
+    include Dsl::OutputsDsl
+    include Dsl::StepsDsl
+    include Concerns::Execution
+    include Concerns::StateManagement
+    include Concerns::ParentService
+
+    # @return [Collection::Base] collection of argument values
+    attr_reader :arg
+
+    # @return [Collection::Base] collection of output values
+    attr_reader :output
+
+    # @return [Messages] collection of error messages
+    attr_reader :errors
+
+    # @return [Messages] collection of warning messages
+    attr_reader :warnings
+
+    # Initialize a new service instance.
+    #
+    # @param args [Hash] arguments to pass to the service
+    # @param config [Hash] runtime configuration overrides
+    # @param parent_service [Base, nil] parent service for nested calls
+    def initialize(args = {}, config = {}, parent_service = nil)
+      @config = Operandi.config.merge(self.class.class_config || {}).merge(config)
+      @parent_service = parent_service
+
+      @output = Collection::Base.new(self, CollectionTypes::OUTPUTS)
+      @arg = Collection::Base.new(self, CollectionTypes::ARGUMENTS, args.dup)
+
+      @stopped = false
+      @launched_steps = []
+
+      initialize_errors
+      initialize_warnings
+    end
+
+    # Check if the service completed without errors.
+    #
+    # @return [Boolean] true if no errors were added
+    def success?
+      !errors?
+    end
+    alias successful? success?
+
+    # Check if the service completed with errors.
+    #
+    # @return [Boolean] true if any errors were added
+    def failed?
+      errors?
+    end
+
+    # Check if the service has any errors.
+    #
+    # @return [Boolean] true if errors collection is not empty
+    def errors?
+      @errors.any?
+    end
+
+    # Check if the service has any warnings.
+    #
+    # @return [Boolean] true if warnings collection is not empty
+    def warnings?
+      @warnings.any?
+    end
+
+    # Stop executing remaining steps after the current step completes.
+    #
+    # @return [Boolean] true
+    def stop!
+      @stopped = true
+    end
+
+    # Check if the service has been stopped.
+    #
+    # @return [Boolean] true if stop! was called
+    def stopped?
+      @stopped
+    end
+
+    # Stop execution immediately, skipping any remaining code in the current step.
+    #
+    # @raise [StopExecution] always raises to halt execution
+    # @return [void]
+    def stop_immediately!
+      @stopped = true
+      raise Operandi::StopExecution
+    end
+
+    # Add an error to the :base key.
+    #
+    # @param message [String] the error message
+    # @return [void]
+    def fail!(message)
+      errors.add(:base, message)
+    end
+
+    # Add an error and stop execution immediately, causing transaction rollback.
+    # Steps marked with `always: true` will still run after this method is called.
+    #
+    # @param message [String] the error message
+    # @raise [FailExecution] always raises to halt execution and rollback
+    # @return [void]
+    def fail_immediately!(message)
+      errors.add(:base, message, rollback: false)
+      raise Operandi::FailExecution
+    end
+
+    # Execute the service steps.
+    #
+    # @return [void]
+    # @raise [StandardError] re-raises any exception after running always steps
+    def call
+      load_defaults_and_validate
+
+      run_callbacks(:before_service_run, self)
+
+      run_callbacks(:around_service_run, self) do
+        execute_service
+      end
+
+      run_service_result_callbacks
+    rescue StandardError => e
+      run_steps_with_always
+      raise e
+    end
+
+    class << self
+      # @return [Hash, nil] class-level configuration options
+      attr_accessor :class_config
+
+      # Set class-level configuration for this service.
+      #
+      # @param config [Hash] configuration options
+      # @return [Hash] the configuration hash
+      def config(config = {})
+        self.class_config = config
+      end
+
+      # Run the service and return the result.
+      #
+      # @param kwargs [Hash] keyword arguments matching service arguments
+      # @return [Base] the executed service instance
+      #
+      # @example
+      #   result = MyService.run(name: "test")
+      #   result.success? # => true
+      def run(**kwargs)
+        new(kwargs).tap(&:call)
+      end
+
+      # Run the service and raise an error if it fails.
+      #
+      # @param kwargs [Hash] keyword arguments matching service arguments
+      # @return [Base] the executed service instance
+      # @raise [RuntimeError] if the service fails
+      #
+      # @example
+      #   MyService.run!(name: "test") # raises if service fails
+      def run!(**kwargs)
+        new(kwargs, { raise_on_error: true }).tap(&:call)
+      end
+
+      # Create a context for running the service with a parent service or config.
+      #
+      # @param service_or_config [Base, Hash] parent service or configuration hash
+      # @param config [Hash] configuration hash (when first param is a service)
+      # @return [BaseWithContext] context wrapper for running the service
+      #
+      # @example With parent service
+      #   ChildService.with(self).run(data: value)
+      #
+      # @example With configuration
+      #   MyService.with(use_transactions: false).run(name: "test")
+      def with(service_or_config, config = {})
+        service = service_or_config.is_a?(Hash) ? nil : service_or_config
+        config = service_or_config unless service
+
+        BaseWithContext.new(self, service, config.dup)
+      end
+    end
+  end
+end

data/lib/operandi/base_with_context.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Operandi
+  # Wrapper for running a service with a parent context or custom configuration.
+  # Created via {Base.with} method.
+  #
+  # @example Running with parent service context
+  #   ChildService.with(self).run(data: value)
+  #
+  # @example Running with custom configuration
+  #   MyService.with(use_transactions: false).run(name: "test")
+  class BaseWithContext
+    # Initialize a new context wrapper.
+    #
+    # @param service_class [Class] the service class to run
+    # @param parent_service [Base, nil] parent service for error/warning propagation
+    # @param config [Hash] configuration overrides
+    # @raise [ArgTypeError] if parent_service is not a Base subclass
+    def initialize(service_class, parent_service, config)
+      @service_class = service_class
+      @config = config
+      @parent_service = parent_service
+
+      return if parent_service.nil? || parent_service.is_a?(Operandi::Base)
+
+      message = "#{parent_service.class} - must be a subclass of Operandi::Base"
+      raise Operandi::ArgTypeError.new(message, service_class: @service_class)
+    end
+
+    # Run the service with the configured context.
+    #
+    # @param kwargs [Hash] keyword arguments matching service arguments
+    # @return [Base] the executed service instance
+    def run(**kwargs)
+      @service_class.new(extend_arguments(kwargs), @config, @parent_service).tap(&:call)
+    end
+
+    # Run the service and raise an error if it fails.
+    #
+    # @param kwargs [Hash] keyword arguments matching service arguments
+    # @return [Base] the executed service instance
+    # @raise [RuntimeError] if the service fails
+    def run!(**kwargs)
+      @config[:raise_on_error] = true
+      run(**kwargs)
+    end
+
+    private
+
+    def extend_arguments(args)
+      args = @parent_service.arg.dup.extend_with_context(args) if @parent_service
+      args[:deepness] += 1 if args[:deepness]
+
+      args
+    end
+  end
+end