yes-core 1.0.0

data/lib/yes/core/aggregate/dsl/command_shortcut_expander.rb

@@ -0,0 +1,233 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    class Aggregate
+      module Dsl
+        #
+        # Class which converts attributes passed to Yes::Core::Aggregate::command in shorthand
+        # form to list of attributes and commands to define
+        #
+        class CommandShortcutExpander
+          ExpandedCommandShortcut = Data.define(:attributes, :commands)
+          CommandSpecification = Data.define(:name, :block)
+          AttributeSpecification = Data.define(:name, :type, :options)
+          class InvalidShortcut < Yes::Core::Error; end
+
+          SPECIAL_CASE_NAMES = {
+            change: :change,
+            enable: :enable,
+            activate: :enable,
+            publish: :publish
+          }.freeze
+
+          class << self
+            #
+            # Detects basic usage of command invocation, so the aggregate knows it's not a shortcut
+            #
+            # @param [Array<Object>] *args
+            # @param [Hash<Object, Object>] **kwargs
+            # @param [Proc] &block
+            #
+            # @return [Boolean]
+            #
+            def base_case?(*args, **kwargs, &block)
+              args.size == 1 && kwargs.empty? && block.present?
+            end
+          end
+
+          attr_reader :args, :kwargs, :block
+
+          #
+          # Takes all parameters passed to command invocation
+          #
+          # @param [Array<Object>] *args
+          # @param [Hash<Object, Object>] **kwargs
+          # @param [Proc] &block
+          #
+          def initialize(*args, **kwargs, &block)
+            @args = args
+            @kwargs = kwargs
+            @block = block
+          end
+
+          #
+          # Expands shortcut to Data object with list of attributes and commands
+          #
+          # @raise [InvalidShortcut] if shortcut is not recognized
+          # @return [ExpandedCommandShortcut] list of attributes and commands to
+          # generate
+          #
+          def call
+            case args
+            in [[Symbol, Symbol], Symbol]
+              handle_toggle_commands
+            in [Symbol => name, *]
+              raise InvalidShortcut unless SPECIAL_CASE_NAMES.include?(name)
+
+              send(:"handle_#{SPECIAL_CASE_NAMES[name]}_command")
+            else
+              raise InvalidShortcut
+            end
+          end
+
+          private
+
+          def handle_toggle_commands
+            raise InvalidShortcut if block.present?
+
+            command_subject = args.second
+            attribute_name = kwargs[:attribute].presence || command_subject
+
+            set_flag_command, unset_flag_command = args.first
+
+            attributes =
+              if kwargs[:attribute] == false
+                []
+              else
+                [
+                  AttributeSpecification.new(
+                    name: attribute_name,
+                    type: :boolean,
+                    options: {}
+                  )
+                ]
+              end
+
+            commands = [
+              CommandSpecification.new(
+                name: :"#{set_flag_command}_#{command_subject}",
+                block: proc do
+                  guard(:no_change) { !send(attribute_name) }
+                  update_state do
+                    send(attribute_name) { true }
+                  end
+                end
+              ),
+              CommandSpecification.new(
+                name: :"#{unset_flag_command}_#{command_subject}",
+                block: proc do
+                  guard(:no_change) { send(attribute_name) }
+                  update_state do
+                    send(attribute_name) { false }
+                  end
+                end
+              )
+            ]
+
+            ExpandedCommandShortcut.new(attributes:, commands:)
+          end
+
+          def handle_change_command
+            raise InvalidShortcut if args.size > 3
+
+            command_subject = args[1]
+            attribute_name = kwargs[:attribute].presence || command_subject
+            attribute_type = args[2].presence || :string
+            localized = kwargs[:localized] || false
+            should_encrypt = kwargs[:encrypt] || false
+            additional_block = block # needs to be captured in a local variable to ensure proper closure in this scope
+
+            payload_options = { attribute_name => attribute_type }
+            payload_options[:locale] = :locale if localized
+
+            attributes =
+              if kwargs[:attribute] == false
+                []
+              else
+                [
+                  AttributeSpecification.new(
+                    name: attribute_name,
+                    type: attribute_type,
+                    options: { localized: }
+                  )
+                ]
+              end
+
+            commands = [
+              CommandSpecification.new(
+                name: :"change_#{command_subject}",
+                block: proc do
+                  guard(:no_change) { value_changed?(send(attribute_name), payload.send(attribute_name)) }
+                  payload(**payload_options)
+                  encrypt(attribute_name) if should_encrypt
+                  instance_eval(&additional_block) if additional_block.present?
+                end
+              )
+            ]
+
+            ExpandedCommandShortcut.new(attributes:, commands:)
+          end
+
+          def handle_enable_command
+            raise InvalidShortcut if args.size > 2
+
+            command_verb = args.first
+            command_subject = args.second
+            attribute_name = kwargs[:attribute].presence || command_subject
+            additional_block = block
+
+            attributes =
+              if kwargs[:attribute] == false
+                []
+              else
+                [
+                  AttributeSpecification.new(
+                    name: attribute_name,
+                    type: :boolean,
+                    options: {}
+                  )
+                ]
+              end
+
+            commands = [
+              CommandSpecification.new(
+                name: :"#{command_verb}_#{command_subject}",
+                block: proc do
+                  guard(:no_change) { !send(attribute_name) }
+                  update_state do
+                    send(attribute_name) { true }
+                  end
+                  instance_eval(&additional_block) if additional_block.present?
+                end
+              )
+            ]
+
+            ExpandedCommandShortcut.new(attributes:, commands:)
+          end
+
+          def handle_publish_command
+            raise InvalidShortcut if args.size > 1 || block.present?
+
+            attribute_name = kwargs[:attribute].presence || :published
+
+            attributes =
+              if kwargs[:attribute] == false
+                []
+              else
+                [
+                  AttributeSpecification.new(
+                    name: attribute_name,
+                    type: :boolean,
+                    options: {}
+                  )
+                ]
+              end
+
+            commands = [
+              CommandSpecification.new(
+                name: :publish,
+                block: proc do
+                  guard(:no_change) { !send(attribute_name) }
+                  update_state { send(attribute_name) { true } }
+                end
+              )
+            ]
+
+            ExpandedCommandShortcut.new(attributes:, commands:)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yes/core/aggregate/dsl/constant_resolver.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    class Aggregate
+      module Dsl
+        # Handles finding and setting constants based on conventional naming
+        #
+        # @api private
+        class ConstantResolver
+          # @param class_name_convention [ClassNameConvention] Convention for generating class names
+          def initialize(class_name_convention)
+            @class_name_convention = class_name_convention
+          end
+
+          # Attempts to find a class based on conventional naming
+          #
+          # @param type [Symbol] The type of class to find (:command, :event, or :handler)
+          # @param name [Symbol] The name of the class
+          # @return [Class, nil] The found class or nil if not found
+          def find_conventional_class(type, name)
+            class_name = class_name_convention.class_name_for(type, name)
+            class_name.constantize
+          rescue NameError
+            nil
+          end
+
+          # Sets the generated class as a constant in the appropriate module path
+          #
+          # @param type [Symbol] The type of class (:command, :event, or :handler, ...)
+          # @param name [Symbol] The name for the class
+          # @param klass [Class] The class to set as constant
+          # @return [Class] The set class
+          def set_constant_for(type, name, klass)
+            class_name = class_name_convention.class_name_for(type, name)
+            modules = class_name.split('::')
+            class_name = modules.pop
+
+            parent_module = create_module_hierarchy(modules)
+            parent_module.const_set(class_name, klass)
+          end
+
+          private
+
+          attr_reader :class_name_convention
+
+          def create_module_hierarchy(modules)
+            # Start with the root namespace if the path is absolute (starts with ::)
+            base = if modules.first && modules.first.empty?
+                     Object.tap { modules.shift }
+                   else
+                     Object
+                   end
+
+            modules.inject(base) do |mod, module_name|
+              if mod.const_defined?(module_name, false)
+                mod.const_get(module_name, false)
+              else
+                mod.const_set(module_name, Module.new)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yes/core/aggregate/dsl/method_definers/attribute/accessor.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    class Aggregate
+      module Dsl
+        module MethodDefiners
+          module Attribute
+            # Defines the accessor method for an attribute
+            class Accessor < Base
+              # Defines a reader method for the attribute that reads from the read model
+              # @return [void]
+              def call
+                name = @name
+
+                aggregate_class.define_method(name) do
+                  return nil unless self.class.read_model_enabled?
+
+                  read_model.public_send(name)
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yes/core/aggregate/dsl/method_definers/attribute/aggregate_accessor.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    class Aggregate
+      module Dsl
+        module MethodDefiners
+          module Attribute
+            # Defines the accessor methods for an aggregate attribute
+            class AggregateAccessor < Base
+              # Defines reader methods for the aggregate attribute that reads from the read model
+              # @return [void]
+              def call
+                name = @name
+                id_name = :"#{name}_id"
+
+                # Define the id accessor
+                aggregate_class.define_method(id_name) do
+                  read_model.public_send(id_name)
+                end
+
+                # Define the aggregate accessor
+                aggregate_class.define_method(name) do
+                  id = read_model.public_send(id_name)
+                  return nil unless id
+
+                  "#{self.class.context}::#{name.to_s.camelize}::Aggregate".constantize.new(id)
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yes/core/aggregate/dsl/method_definers/attribute/base.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    class Aggregate
+      module Dsl
+        module MethodDefiners
+          module Attribute
+            # Base class for attribute method definers that provides common functionality
+            # for defining attribute-related methods on aggregate classes.
+            #
+            # @abstract Subclass and override {#call} to implement custom attribute method definition
+            class Base
+              # Initializes a new attribute method definer
+              #
+              # @param attribute_data [Object] Object containing attribute configuration
+              # @option attribute_data [Symbol] :name The attribute name
+              # @option attribute_data [Class] :aggregate_class The target aggregate class where methods will be defined
+              def initialize(attribute_data)
+                @name = attribute_data.name
+                @aggregate_class = attribute_data.aggregate_class
+              end
+
+              # Defines the attribute-related methods on the aggregate class
+              #
+              # @abstract
+              # @raise [NotImplementedError] when called on the base class
+              # @return [void]
+              def call
+                raise NotImplementedError, "#{self.class} must implement #call"
+              end
+
+              private
+
+              attr_reader :name, :aggregate_class
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yes/core/aggregate/dsl/method_definers/command/base.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    class Aggregate
+      module Dsl
+        module MethodDefiners
+          module Command
+            # Base class for command method definers that provides common functionality
+            # for defining command-related methods on aggregate classes.
+            #
+            # @abstract Subclass and override {#call} to implement custom command method definition
+            class Base
+              # Initializes a new command method definer
+              #
+              # @param command_data [Object] Object containing command configuration
+              # @option command_data [Symbol] :name The command name
+              # @option command_data [Class] :aggregate_class The target aggregate class where methods will be defined
+              def initialize(command_data)
+                @name = command_data.name
+                @aggregate_class = command_data.aggregate_class
+              end
+
+              # Defines the command-related methods on the aggregate class
+              #
+              # @abstract
+              # @raise [NotImplementedError] when called on the base class
+              # @return [void]
+              def call
+                raise NotImplementedError, "#{self.class} must implement #call"
+              end
+
+              private
+
+              attr_reader :name, :aggregate_class
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yes/core/aggregate/dsl/method_definers/command/can_command.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    class Aggregate
+      module Dsl
+        module MethodDefiners
+          module Command
+            # Defines a can_<command_name>? method on the aggregate class
+            class CanCommand < Base
+              # @return [void]
+              def call
+                can_change_method = :"can_#{name}?"
+                error_method = :"#{name}_error"
+
+                aggregate_class.attr_accessor error_method
+                command_name = @name
+
+                aggregate_class.define_method(can_change_method) do |payload = {}|
+                  payload = command_utilities.prepare_default_payload(command_name, payload, self.class)
+                  payload = command_utilities.prepare_command_payload(command_name, payload, self.class)
+                  payload = command_utilities.prepare_assign_command_payload(command_name, payload)
+                  cmd = command_utilities.build_command(command_name, payload)
+                  guard_evaluator_class = command_utilities.fetch_guard_evaluator_class(command_name)
+
+                  Yes::Core::CommandHandling::GuardRunner.new(self).call(
+                    cmd, command_name, guard_evaluator_class, skip_guards: false
+                  ).present?
+                rescue Yes::Core::CommandHandling::GuardEvaluator::InvalidTransition,
+                       Yes::Core::CommandHandling::GuardEvaluator::NoChangeTransition,
+                       Yes::Core::Command::Invalid
+                  false
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yes/core/aggregate/dsl/method_definers/command/command.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    class Aggregate
+      module Dsl
+        module MethodDefiners
+          module Command
+            # Defines a command method on the aggregate class
+            class Command < Base
+              # @return [void]
+              def call
+                command_name = @name
+
+                aggregate_class.define_method(command_name) do |payload = nil, **options|
+                  payload = payload.clone if payload.is_a?(Hash)
+
+                  # Extract and remove guards option from options, default to true
+                  guards = options.delete(:guards)
+                  guards = true if guards.nil?
+
+                  # Extract and remove metadata option from options if present
+                  metadata = options.delete(:metadata)
+
+                  # Handle different calling patterns:
+                  # 1. command(value) or command(value, guards: false) - shorthand form with single value
+                  # 2. command({attr: value}) or command({attr: value}, guards: false) - hash form
+                  # 3. command(attr: value) - ALL kwargs are treated as payload (no options)
+                  # 4. command() - no arguments (for commands without payload)
+
+                  # If no positional argument was provided but kwargs were given (after removing guards/metadata),
+                  # treat all remaining kwargs as payload
+                  if payload.nil? && !options.empty?
+                    payload = options
+                    {}
+                  elsif payload.nil?
+                    payload = {}
+                  end
+
+                  # Pass metadata to CommandHandler which will merge it into the event metadata
+                  Yes::Core::CommandHandling::CommandHandler.new(self).call(command_name, payload, guards:, metadata:)
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yes/core/aggregate/has_authorizer.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    class Aggregate
+      # Provides authorizer functionality for aggregates.
+      #
+      # This concern automatically sets up an authorizer class for the aggregate
+      # using `Yes::Core::Aggregate::Dsl::ClassResolvers::Authorizer`.
+      # The authorizer class is typically used for command authorization via Cerbos.
+      #
+      module HasAuthorizer
+        extend ActiveSupport::Concern
+
+        # Mutable struct for holding authorizer options
+        AuthorizerOptions = Struct.new(
+          :authorizer_base_class,
+          :context,
+          :aggregate,
+          :read_model_class,
+          :resource_name,
+          :authorizer_block,
+          :draftable,
+          :changes_read_model_class,
+          keyword_init: true
+        )
+
+        included do
+          class << self
+            # @!attribute [rw] authorizer_class
+            #   @return [Class] The resolved authorizer class used for command authorization.
+            #
+            # @!attribute [rw] authorizer_options
+            #   @return [AuthorizerOptions] Options used when building the authorizer.
+            attr_accessor :authorizer_class, :authorizer_options
+          end
+        end
+
+        class_methods do
+          # Finds or generates the authorizer class using `ClassResolvers::Authorizer`,
+          # passing the authorizer parameters.
+          # Registers the authorizer in the configuration and stores the resolved class internally.
+          # @return [Class] The resolved authorizer class.
+          def setup_authorizer_classes
+            return unless authorizer_options
+
+            authorizer_options.read_model_class ||= read_model_class
+            authorizer_options.resource_name ||= aggregate.underscore
+
+            # Set draftable and changes read model class if the aggregate is draftable
+            authorizer_options.draftable ||= draftable?
+            authorizer_options.changes_read_model_class ||= changes_read_model_class if draftable?
+
+            self.authorizer_class = Yes::Core::Aggregate::Dsl::ClassResolvers::Authorizer.new(authorizer_options).call
+
+            commands.each_value do |command_data|
+              Dsl::ClassResolvers::Command::AuthorizerFactory.create(command_data)&.call
+            end
+          end
+
+          # @param cerbos [Boolean] Whether to use Cerbos authorizer.
+          # @param read_model_class [Class] The read model class to use for the authorizer.
+          # @param resource_name [String] The resource name to use for the authorizer.
+          # @param block [Proc] The block to use for the authorizer.
+          # @return [Class] The authorizer class.
+          def authorize(cerbos: false, read_model_class: nil, resource_name: nil, &block)
+            authorizer_base_class = if cerbos
+                                      Yes::Core::Authorization::CommandCerbosAuthorizer
+                                    else
+                                      Yes::Core::Authorization::CommandAuthorizer
+                                    end
+
+            self.authorizer_options = AuthorizerOptions.new(
+              authorizer_base_class:,
+              context:,
+              aggregate:,
+              read_model_class:,
+              resource_name:,
+              authorizer_block: block
+            )
+          end
+        end
+      end
+    end
+  end
+end