yes-core 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c43247d2dbf4c79fac0069c1fb4887a9fba4b38f845736b67dbb9ee2f213e96f
+  data.tar.gz: f78fa82e84433fb209a0e0dc5258ee7569e1993af11436112c590c7094f73b9c
+SHA512:
+  metadata.gz: 1c82e17ddceef537ce4f473577e318032b71c46c090ae70b44ea0264e29ad28b6eedef7115db1aafba3f1878a238a7269d533eb0b06ba07de17422b5e2ce9d70
+  data.tar.gz: 1ed596dba1c9b64292a3a517f823163fb2d1e36261b35fc96812be85abd919ab6b4d537da353114f45f799e0d33a47edd313d0731ec35c014d7cabd86ea8b396

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## [1.0.0] - 2026-03-21
+
+- Initial open-source release (see root CHANGELOG.md for details)

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 ncri
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,69 @@
+# Yes Core
+
+Core event sourcing framework providing the aggregate DSL, commands, events, read models, and supporting infrastructure for the [Yes](https://github.com/yousty/yes) framework.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'yes-core'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+## Usage
+
+See the [root README](../README.md) for the full DSL documentation and usage examples.
+
+## Development
+
+### Prerequisites
+
+- Docker and Docker Compose
+- Ruby >= 3.2.0
+- Bundler
+
+### Setup
+
+Start PostgreSQL from the **repository root**:
+
+```shell
+docker compose up -d
+```
+
+Install dependencies:
+
+```shell
+bundle install
+```
+
+Set up the EventStore database:
+
+```shell
+PG_EVENTSTORE_URI="postgresql://postgres:postgres@localhost:5532/eventstore_test" bundle exec rake pg_eventstore:create pg_eventstore:migrate
+```
+
+Set up the test database:
+
+```shell
+RAILS_ENV=test bundle exec rake db:create db:migrate
+```
+
+### Running Specs
+
+```shell
+bundle exec rspec
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/yousty/yes.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/yes/core/active_job_serializers/command_group_serializer.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    module ActiveJobSerializers
+      # ActiveJob serializer for CommandGroup objects.
+      class CommandGroupSerializer < ActiveJob::Serializers::ObjectSerializer
+        # @param argument [Object] the argument to check
+        # @return [Boolean] true if the argument can be serialized
+        def serialize?(argument)
+          argument.is_a? Yes::Core::Commands::Group
+        end
+
+        # @param command_group [Yes::Core::Commands::Group] the command group to serialize
+        # @return [Hash] the serialized representation
+        def serialize(command_group)
+          super(command_group.to_h.merge(_type: command_group.class.name))
+        end
+
+        # @param hash [Hash] the serialized representation
+        # @return [Yes::Core::Commands::Group] the deserialized command group
+        def deserialize(hash)
+          symbolized_hash = hash.deep_symbolize_keys
+          Object.const_get(symbolized_hash[:_type]).new(symbolized_hash.except(:_aj_serialized, :_type))
+        end
+      end
+    end
+  end
+end

data/lib/yes/core/active_job_serializers/dry_struct_serializer.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    module ActiveJobSerializers
+      # ActiveJob serializer for Dry::Struct objects (including Commands).
+      class DryStructSerializer < ActiveJob::Serializers::ObjectSerializer
+        # @param argument [Object] the argument to check
+        # @return [Boolean] true if the argument can be serialized
+        def serialize?(argument)
+          argument.is_a? Dry::Struct
+        end
+
+        # @param dry_struct [Dry::Struct] the dry struct to serialize
+        # @return [Hash] the serialized representation
+        def serialize(dry_struct)
+          super(dry_struct.attributes.merge(_type: dry_struct.class.name).as_json)
+        end
+
+        # @param hash [Hash] the serialized representation
+        # @return [Dry::Struct] the deserialized object
+        def deserialize(hash)
+          symbolized_hash = hash.deep_symbolize_keys
+          object = Object.const_get(symbolized_hash[:_type])
+
+          if object < Yes::Core::Command
+            deserialize_command(symbolized_hash, object)
+          else
+            object.new(symbolized_hash.except(:_aj_serialized, :_type))
+          end
+        end
+
+        private
+
+        # @param symbolized_hash [Hash] the symbolized hash
+        # @param object [Class] the command class
+        # @return [Yes::Core::Command] the deserialized command
+        def deserialize_command(symbolized_hash, object)
+          if symbolized_hash[:transaction].is_a?(Hash) && symbolized_hash[:transaction][:otl_contexts].present?
+            symbolized_hash[:transaction] = Yes::Core::TransactionDetails.new(
+              **symbolized_hash[:transaction].except(:otl_contexts),
+              otl_contexts: Yes::Core::TransactionDetailsTypes::OtlContexts.new(
+                symbolized_hash[:transaction][:otl_contexts]
+              )
+            )
+
+            return object.new(symbolized_hash.except(:_aj_serialized, :_type))
+          end
+
+          symbolized_hash[:transaction] = Yes::Core::TransactionDetails.new(symbolized_hash[:transaction]) if symbolized_hash[:transaction].is_a?(Hash)
+
+          object.new(symbolized_hash.except(:_aj_serialized, :_type))
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    class Aggregate
+      # Provides draftable functionality for aggregates
+      #
+      # @example Include in an aggregate
+      #   class UserAggregate < Yes::Core::Aggregate
+      #     draftable
+      #   end
+      module Draftable
+        extend ActiveSupport::Concern
+
+        included do
+          class << self
+            attr_accessor :_draft_context, :_draft_aggregate, :_changes_read_model_name,
+                          :_draft_foreign_key, :_is_draftable, :_changes_read_model_public
+          end
+        end
+
+        class_methods do
+          # Configures the aggregate as draftable
+          #
+          # @param draft_aggregate [Hash, nil] The draft aggregate configuration with :context and :aggregate keys
+          # @param changes_read_model [String, Symbol, nil] The changes read model name (defaults to "<read_model>_change")
+          # @param changes_read_model_public [Boolean] Whether the changes read model should be public via read API (default: true)
+          # @return [void]
+          #
+          # @example Use defaults
+          #   draftable
+          #
+          # @example Override all parameters
+          #   draftable draft_aggregate: { context: 'ApprenticeshipPresentation', aggregate: 'MyAggregateDraft' },
+          #             changes_read_model: 'custom_change', changes_read_model_public: false
+          #
+          # @example Override only context
+          #   draftable draft_aggregate: { context: 'CustomContext' }
+          #
+          # @example Override only aggregate
+          #   draftable draft_aggregate: { aggregate: 'CustomDraft' }
+          #
+          # @example Override only changes_read_model
+          #   draftable changes_read_model: :article_change
+          #
+          # @example Make changes read model private
+          #   draftable changes_read_model_public: false
+          def draftable(draft_aggregate: nil, changes_read_model: nil, changes_read_model_public: true)
+            self._is_draftable = true
+
+            draft_config = draft_aggregate || {}
+            self._draft_context = draft_config[:context] || context
+            self._draft_aggregate = draft_config[:aggregate] || "#{aggregate}Draft"
+
+            self._changes_read_model_name = if changes_read_model
+                                              changes_read_model.to_s
+                                            else
+                                              "#{read_model_name}_change"
+                                            end
+
+            self._changes_read_model_public = changes_read_model_public
+          end
+
+          # Checks if the aggregate is draftable
+          #
+          # @return [Boolean] true if draftable, false otherwise
+          def draftable?
+            _is_draftable == true
+          end
+
+          # Returns the draft context
+          #
+          # @return [String, nil] the draft context
+          def draft_context
+            _draft_context
+          end
+
+          # Returns the draft aggregate name
+          #
+          # @return [String, nil] the draft aggregate name
+          def draft_aggregate
+            _draft_aggregate
+          end
+
+          # Returns the changes read model name
+          #
+          # @return [String, nil] the changes read model name
+          def changes_read_model_name
+            _changes_read_model_name
+          end
+
+          # Returns the changes read model class
+          #
+          # @return [Class, nil] the changes read model class
+          def changes_read_model_class
+            return nil unless changes_read_model_name
+
+            Yes::Core::Aggregate::Dsl::ClassResolvers::ReadModel.new(
+              changes_read_model_name,
+              context,
+              aggregate,
+              draft: true
+            ).call
+          end
+
+          # Returns whether the changes read model is public
+          #
+          # @return [Boolean] true if public, false otherwise
+          def changes_read_model_public?
+            _changes_read_model_public.nil? || _changes_read_model_public
+          end
+
+          private
+
+          def draft_aggregate_class
+            "#{draft_context}::#{draft_aggregate}::Aggregate".constantize
+          end
+
+          def draft_read_model_class
+            "::#{draft_aggregate}".constantize
+          end
+
+          def main_changes_model_foreign_key
+            if draft_aggregate_class.respond_to?(:changes_read_model_foreign_key)
+              draft_aggregate_class.changes_read_model_foreign_key
+            else
+              draft_aggregate.to_s.underscore.sub(/_(draft|batch)$/, '_change_id')
+            end
+          end
+        end
+
+        # Override read_model to return changes read model when initialized as draft
+        #
+        # @return [ApplicationRecord] The read model or draft read model instance
+        def read_model
+          return super unless draft? && self.class.draftable?
+
+          @read_model ||= changes_read_model_class.find_or_create_by(id:)
+        end
+
+        # Updates the read model and handles draft aggregate updates
+        #
+        # @param attributes [Hash] The attributes to update
+        # @return [Boolean] true if successful
+        def update_read_model(attributes)
+          result = super
+
+          update_draft_aggregate if self.class.draftable? && draft?
+
+          result
+        end
+
+        # Checks if this instance is a draft
+        #
+        # @return [Boolean] true if draft, false otherwise
+        def draft?
+          @draft == true
+        end
+
+        private
+
+        # Returns the changes read model class
+        #
+        # @return [Class] the changes read model class
+        def changes_read_model_class
+          @changes_read_model_class ||= resolve_changes_read_model_class
+        end
+
+        # Resolves the changes read model class
+        #
+        # @return [Class] the resolved changes read model class
+        def resolve_changes_read_model_class
+          changes_read_model_name = self.class.changes_read_model_name
+          return self.class.read_model_class unless changes_read_model_name
+
+          Yes::Core::Aggregate::Dsl::ClassResolvers::ReadModel.new(
+            changes_read_model_name,
+            self.class.context,
+            self.class.aggregate
+          ).call
+        end
+
+        # Updates the connected draft aggregate's read model
+        #
+        # @return [void]
+        def update_draft_aggregate
+          main_id_method = :"#{self.class.read_model_name}_id"
+
+          # Check if the changes read model has a foreign key that relates it to the main read model
+          #
+          # e.g. ApprenticeshipDraft is a draft for Apprenticeship, so main_read_model_id is :apprenticeship_id
+          #
+          return unless read_model.respond_to?(main_id_method)
+
+          main_changes_model_id = read_model.send(main_id_method)
+
+          # e.g. ::ApprenticeshipBatch.find_by(apprenticeship_edit_template_id: apprenticeship_id)&.state_draft!
+          self.class.send(:draft_read_model_class).find_by(
+            self.class.send(:main_changes_model_foreign_key) => main_changes_model_id
+          )&.state_draft!
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    class Aggregate
+      module Dsl
+        # Data object that holds information about an attribute definition in an aggregate
+        #
+        # @example
+        #   AttributeData.new(:name, :string, MyAggregate, context: 'users', aggregate: 'user')
+        #
+        class AttributeData
+          attr_reader :name, :type, :context_name,
+                      :aggregate_name, :aggregate_class, :localized, :encrypted
+
+          # @param name [Symbol] The name of the attribute
+          # @param type [Symbol] The type of the attribute
+          # @param aggregate_class [Class] The aggregate class this attribute belongs to
+          # @param options [Hash] Additional options for the attribute
+          # @option options [String] :context The context name for the attribute
+          # @option options [String] :aggregate The aggregate name
+          # @option options [Boolean] :localized Whether the attribute is localized
+          # @option options [Boolean] :encrypted Whether the attribute should be encrypted
+          def initialize(name, type, aggregate_class, options = {})
+            @name = name
+            @type = type
+            @aggregate_class = aggregate_class
+            @context_name = options.delete(:context)
+            @aggregate_name = options.delete(:aggregate)
+            @localized = options.delete(:localized) || false
+            @encrypted = options.delete(:encrypted) || false
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    class Aggregate
+      module Dsl
+        # Factory class that creates the appropriate attribute definer based on the attribute type
+        #
+        # @example
+        #   attribute_data = AttributeData.new(name: :name, type: :string, aggregate_class: User, validate: true)
+        #   AttributeDefiner.new(attribute_data).call do
+        #     guard :no_change do
+        #       payload.name == name
+        #     end
+        #   end
+        #
+        class AttributeDefiner
+          # @return [AttributeData] the data object containing attribute configuration
+          attr_reader :attribute_data
+          private :attribute_data
+
+          # Initializes a new AttributeDefiner instance
+          #
+          # @param attribute_data [AttributeData] the data object containing attribute configuration
+          # @return [AttributeDefiner] a new instance of AttributeDefiner
+          def initialize(attribute_data)
+            @attribute_data = attribute_data
+          end
+
+          # Creates the appropriate definer and calls it to generate the necessary classes and methods
+          #
+          # @yield Block for defining guards and other attribute configurations
+          # @yieldreturn [void]
+          # @return [void]
+          def call(&)
+            definer_for_type.new(attribute_data).call(&)
+          end
+
+          private
+
+          # Returns the appropriate definer class based on the attribute type
+          #
+          # @return [Class] The definer class to use
+          def definer_for_type
+            case attribute_data.type
+            when :aggregate then AttributeDefiners::Aggregate
+            else AttributeDefiners::Standard
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    class Aggregate
+      module Dsl
+        module AttributeDefiners
+          # Handles the definition and generation of aggregate attribute-related classes and methods
+          class Aggregate
+            # @return [AttributeData] the data object containing attribute configuration
+            attr_reader :attribute_data, :guard_evaluator_class
+
+            private :attribute_data, :guard_evaluator_class
+
+            # Initializes a new Base instance
+            #
+            # @param attribute_data [AttributeData] the data object containing attribute configuration
+            # @return [Base] a new instance of Base
+            def initialize(attribute_data)
+              @attribute_data = attribute_data
+            end
+
+            # Generates and registers all necessary classes for the attribute.
+            #
+            # @yield Block for defining guards and other attribute configurations
+            # @yieldreturn [void]
+            # @return [void]
+            def call
+              MethodDefiners::Attribute::AggregateAccessor.new(attribute_data).call
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yes/core/aggregate/dsl/attribute_definers/standard.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    class Aggregate
+      module Dsl
+        module AttributeDefiners
+          # Handles the definition and generation of standard attribute-related classes and methods
+          class Standard
+            # @return [AttributeData] the data object containing attribute configuration
+            attr_reader :attribute_data, :guard_evaluator_class
+
+            private :attribute_data, :guard_evaluator_class
+
+            # Initializes a new Base instance
+            #
+            # @param attribute_data [AttributeData] the data object containing attribute configuration
+            # @return [Base] a new instance of Base
+            def initialize(attribute_data)
+              @attribute_data = attribute_data
+            end
+
+            # Generates and registers all necessary classes for the attribute.
+            #
+            # @yield Block for defining guards and other attribute configurations
+            # @yieldreturn [void]
+            # @return [void]
+            def call
+              MethodDefiners::Attribute::Accessor.new(attribute_data).call
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    class Aggregate
+      module Dsl
+        # Handles the naming conventions for aggregate-related classes
+        #
+        # @example
+        #   convention = ClassNameConvention.new(context: 'MyContext', aggregate: 'User')
+        #   convention.command_class_name('change_name') # => "MyContext::User::Commands::ChangeName::Command"
+        #
+        class ClassNameConvention
+          # @param context [String] The context name
+          # @param aggregate [String] The aggregate name
+          def initialize(context:, aggregate:)
+            @context = context
+            @aggregate = aggregate
+          end
+
+          # Returns the conventional class name for a given type and name
+          #
+          # @param type [Symbol] The type of class (:command, :event, or :guard_evaluator, ...)
+          # @param name [Symbol, String] The name of the class
+          # @return [String] The conventional class name
+          def class_name_for(type, name)
+            send(:"#{type}_class_name", name)
+          end
+
+          private
+
+          attr_reader :context, :aggregate
+
+          def command_class_name(name)
+            "#{context}::#{aggregate}::Commands::#{name.to_s.camelize}::Command"
+          end
+
+          def event_class_name(name)
+            "#{context}::#{aggregate}::Events::#{name.to_s.camelize}"
+          end
+
+          def guard_evaluator_class_name(name)
+            "#{context}::#{aggregate}::Commands::#{name.to_s.camelize}::GuardEvaluator"
+          end
+
+          def state_updater_class_name(name)
+            "#{context}::#{aggregate}::Commands::#{name.to_s.camelize}::StateUpdater"
+          end
+
+          def read_model_class_name(name)
+            name.to_s.camelize
+          end
+
+          def read_model_filter_class_name(name)
+            "ReadModels::#{name.to_s.camelize}::Filter"
+          end
+
+          def read_model_serializer_class_name(name)
+            "ReadModels::#{name.to_s.camelize}::Serializers::#{name.to_s.camelize}"
+          end
+
+          # Returns the conventional authorizer class name.
+          #
+          # If +name+ is nil, it refers to the aggregate-level authorizer:
+          #   <Context>::<Aggregate>::Commands::<Aggregate>Authorizer
+          # Otherwise it refers to a command-level authorizer:
+          #   <Context>::<Aggregate>::Commands::<CommandName>::Authorizer
+          #
+          # @param name [Symbol, String, nil] the command name (optional)
+          # @return [String]
+          def authorizer_class_name(name)
+            return "#{context}::#{aggregate}::Commands::#{aggregate}Authorizer" if name.nil? || name.to_s.empty?
+
+            "#{context}::#{aggregate}::Commands::#{name.to_s.camelize}::Authorizer"
+          end
+        end
+      end
+    end
+  end
+end