dexkit 0.1.0 → 0.2.0

data/lib/dex/operation/lock_wrapper.rb

@@ -2,20 +2,11 @@
 
 module Dex
   module LockWrapper
-    def self.included(base)
-      base.extend(ClassMethods)
-    end
-
-    LOCK_KNOWN_OPTIONS = %i[timeout].freeze
+    extend Dex::Concern
 
     module ClassMethods
       def advisory_lock(key = nil, **options, &block)
-        unknown = options.keys - LockWrapper::LOCK_KNOWN_OPTIONS
-        if unknown.any?
-          raise ArgumentError,
-            "unknown advisory_lock option(s): #{unknown.map(&:inspect).join(", ")}. " \
-            "Known: #{LockWrapper::LOCK_KNOWN_OPTIONS.map(&:inspect).join(", ")}"
-        end
+        validate_options!(options, %i[timeout], :advisory_lock)
 
         lock_key = block || key
 

data/lib/dex/operation/pipeline.rb

@@ -18,13 +18,13 @@ module Dex
       end
 
       def add(name, method: :"_#{name}_wrap", before: nil, after: nil, at: nil)
-        _validate_positioning!(before, after, at)
+        validate_positioning!(before, after, at)
         step = Step.new(name: name, method: method)
 
         if at == :outer then @steps.unshift(step)
         elsif at == :inner then @steps.push(step)
-        elsif before then @steps.insert(_find_index!(before), step)
-        elsif after then @steps.insert(_find_index!(after) + 1, step)
+        elsif before then @steps.insert(find_index!(before), step)
+        elsif after then @steps.insert(find_index!(after) + 1, step)
         else @steps.push(step)
         end
         self
@@ -44,13 +44,13 @@ module Dex
 
       private
 
-      def _validate_positioning!(before, after, at)
+      def validate_positioning!(before, after, at)
         count = [before, after, at].count { |v| !v.nil? }
         raise ArgumentError, "specify only one of before:, after:, at:" if count > 1
         raise ArgumentError, "at: must be :outer or :inner" if at && !%i[outer inner].include?(at)
       end
 
-      def _find_index!(name)
+      def find_index!(name)
         idx = @steps.index { |s| s.name == name }
         raise ArgumentError, "pipeline step :#{name} not found" unless idx
         idx

data/lib/dex/operation/record_wrapper.rb

@@ -2,41 +2,26 @@
 
 module Dex
   module RecordWrapper
-    def self.included(base)
-      base.extend(ClassMethods)
-    end
+    extend Dex::Concern
 
     def _record_wrap
-      halted = nil
-      result = catch(:_dex_halt) { yield }
-
-      if result.is_a?(Operation::Halt)
-        halted = result
-        result = halted.success? ? halted.value : nil
-      end
+      interceptor = Operation::HaltInterceptor.new { yield }
 
-      if halted.nil? || halted.success?
+      if interceptor.success?
         if _record_has_pending_record?
-          _record_update_done!(result)
+          _record_update_done!(interceptor.result)
         elsif _record_enabled?
-          _record_save!(result)
+          _record_save!(interceptor.result)
         end
       end
 
-      throw(:_dex_halt, halted) if halted
-      result
+      interceptor.rethrow!
+      interceptor.result
     end
 
-    RECORD_KNOWN_OPTIONS = %i[params response].freeze
-
     module ClassMethods
       def record(enabled = nil, **options)
-        unknown = options.keys - RecordWrapper::RECORD_KNOWN_OPTIONS
-        if unknown.any?
-          raise ArgumentError,
-            "unknown record option(s): #{unknown.map(&:inspect).join(", ")}. " \
-            "Known: #{RecordWrapper::RECORD_KNOWN_OPTIONS.map(&:inspect).join(", ")}"
-        end
+        validate_options!(options, %i[params response], :record)
 
         if enabled == false
           set :record, enabled: false
@@ -101,7 +86,7 @@ module Dex
       success_type = self.class.respond_to?(:_success_type) && self.class._success_type
 
       if success_type
-        _record_serialize_typed_result(result, success_type)
+        result.nil? ? nil : self.class.send(:_serialize_value, success_type, result)
       else
         case result
         when nil then nil
@@ -111,25 +96,12 @@ module Dex
       end
     end
 
-    def _record_serialize_typed_result(result, type)
-      return nil if result.nil?
-
-      ref_type = self.class.send(:_dex_find_ref_type, type)
-      if ref_type && result.respond_to?(:id)
-        result.id
-      else
-        result.respond_to?(:as_json) ? result.as_json : result
-      end
-    end
-
     def _record_current_time
       Time.respond_to?(:current) ? Time.current : Time.now
     end
 
     def _record_handle_error(error)
-      if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
-        Rails.logger.warn "[Dex] Failed to record operation: #{error.message}"
-      end
+      Dex.warn("Failed to record operation: #{error.message}")
     end
   end
 end

data/lib/dex/operation/rescue_wrapper.rb

@@ -2,9 +2,7 @@
 
 module Dex
   module RescueWrapper
-    def self.included(base)
-      base.extend(ClassMethods)
-    end
+    extend Dex::Concern
 
     module ClassMethods
       def rescue_from(*exception_classes, as:, message: nil)

data/lib/dex/operation/result_wrapper.rb

@@ -32,23 +32,16 @@ module Dex
       end
     end
 
-    def self.included(base)
-      base.extend(ClassMethods)
-    end
+    extend Dex::Concern
 
     def _result_wrap
-      halted = catch(:_dex_halt) { yield }
-      if halted.is_a?(Operation::Halt)
-        if halted.success?
-          _result_validate_success_type!(halted.value)
-          halted.value
-        else
-          raise Dex::Error.new(halted.error_code, halted.error_message, details: halted.error_details)
-        end
-      else
-        _result_validate_success_type!(halted)
-        halted
+      interceptor = Operation::HaltInterceptor.new { yield }
+      if interceptor.error?
+        h = interceptor.halt
+        raise Dex::Error.new(h.error_code, h.error_message, details: h.error_details)
       end
+      _result_validate_success_type!(interceptor.result)
+      interceptor.result
     end
 
     def error!(code, message = nil, details: nil)

data/lib/dex/operation/settings.rb

@@ -8,6 +8,15 @@ module Dex
         @_settings[key] = (@_settings[key] || {}).merge(options)
       end
 
+      def validate_options!(options, known, dsl_name)
+        unknown = options.keys - known
+        return if unknown.empty?
+
+        raise ArgumentError,
+          "unknown #{dsl_name} option(s): #{unknown.map(&:inspect).join(", ")}. " \
+          "Known: #{known.map(&:inspect).join(", ")}"
+      end
+
       def settings_for(key)
         parent_settings = if superclass.respond_to?(:settings_for)
           superclass.settings_for(key) || {}
@@ -19,8 +28,6 @@ module Dex
       end
     end
 
-    def self.included(base)
-      base.extend(ClassMethods)
-    end
+    extend Dex::Concern
   end
 end

data/lib/dex/operation/transaction_wrapper.rb

@@ -2,40 +2,27 @@
 
 module Dex
   module TransactionWrapper
-    def self.included(base)
-      base.extend(ClassMethods)
-    end
+    extend Dex::Concern
 
     def _transaction_wrap
       return yield unless _transaction_enabled?
 
-      halted = nil
+      interceptor = nil
       result = _transaction_execute do
-        halted_value = catch(:_dex_halt) { yield }
-        if halted_value.is_a?(Operation::Halt)
-          halted = halted_value
-          raise _transaction_adapter.rollback_exception_class if halted.error?
-          halted.value
-        else
-          halted_value
-        end
+        interceptor = Operation::HaltInterceptor.new { yield }
+        raise _transaction_adapter.rollback_exception_class if interceptor.error?
+        interceptor.result
       end
 
-      throw(:_dex_halt, halted) if halted
+      interceptor&.rethrow!
       result
     end
 
     TRANSACTION_KNOWN_ADAPTERS = %i[active_record mongoid].freeze
-    TRANSACTION_KNOWN_OPTIONS = %i[adapter].freeze
 
     module ClassMethods
       def transaction(enabled_or_options = nil, **options)
-        unknown = options.keys - TransactionWrapper::TRANSACTION_KNOWN_OPTIONS
-        if unknown.any?
-          raise ArgumentError,
-            "unknown transaction option(s): #{unknown.map(&:inspect).join(", ")}. " \
-            "Known: #{TransactionWrapper::TRANSACTION_KNOWN_OPTIONS.map(&:inspect).join(", ")}"
-        end
+        validate_options!(options, %i[adapter], :transaction)
 
         case enabled_or_options
         when false

data/lib/dex/operation.rb

@@ -2,7 +2,6 @@
 
 # Wrapper modules (loaded before class body so `include`/`use` can find them)
 require_relative "operation/settings"
-require_relative "operation/props_setup"
 require_relative "operation/result_wrapper"
 require_relative "operation/record_wrapper"
 require_relative "operation/transaction_wrapper"
@@ -22,112 +21,81 @@ module Dex
       def error? = type == :error
     end
 
-    def self._serialized_coercions
-      @_serialized_coercions ||= {
-        Time => ->(v) { v.is_a?(String) ? Time.parse(v) : v },
-        Symbol => ->(v) { v.is_a?(String) ? v.to_sym : v }
-      }.tap do |h|
-        h[Date] = ->(v) { v.is_a?(String) ? Date.parse(v) : v } if defined?(Date)
-        h[DateTime] = ->(v) { v.is_a?(String) ? DateTime.parse(v) : v } if defined?(DateTime)
-        h[BigDecimal] = ->(v) { v.is_a?(String) ? BigDecimal(v) : v } if defined?(BigDecimal)
-      end.freeze
-    end
-
-    Contract = Data.define(:params, :success, :errors)
-
-    def self.contract
-      Contract.new(
-        params: _contract_params,
-        success: _success_type,
-        errors: _declared_errors
-      )
-    end
-
-    def self._contract_params
-      return {} unless respond_to?(:literal_properties)
-
-      literal_properties.each_with_object({}) do |prop, hash|
-        hash[prop.name] = prop.type
-      end
-    end
+    class HaltInterceptor
+      attr_reader :result, :halt
 
-    private_class_method :_contract_params
-
-    def self._dex_find_ref_type(type)
-      return type if type.is_a?(Dex::RefType)
-
-      if type.respond_to?(:type)
-        inner = type.type
-        return inner if inner.is_a?(Dex::RefType)
+      def initialize
+        raw = catch(:_dex_halt) { yield }
+        if raw.is_a?(Halt)
+          @halt = raw
+          @result = raw.success? ? raw.value : nil
+        else
+          @halt = nil
+          @result = raw
+        end
       end
-      nil
-    end
 
-    def self._dex_coerce_serialized_hash(hash)
-      return hash.transform_keys(&:to_sym) unless respond_to?(:literal_properties)
+      def halted? = !@halt.nil?
+      def success? = !error?
+      def error? = @halt&.error? || false
 
-      result = {}
-      literal_properties.each do |prop|
-        name = prop.name
-        raw = hash.key?(name) ? hash[name] : hash[name.to_s]
-        result[name] = _dex_coerce_value(prop.type, raw)
+      def rethrow!
+        throw(:_dex_halt, @halt) if halted?
       end
-      result
     end
 
-    def self._dex_resolve_base_class(type)
-      return type.model_class if type.is_a?(Dex::RefType)
-      return _dex_resolve_base_class(type.type) if type.respond_to?(:type)
+    RESERVED_PROP_NAMES = %i[call perform async safe initialize].to_set.freeze
 
-      type if type.is_a?(Class)
-    end
+    include PropsSetup
+    include TypeCoercion
 
-    def self._dex_coerce_value(type, value)
-      return value unless value
-      return value if _dex_find_ref_type(type)
+    Contract = Data.define(:params, :success, :errors)
 
-      if type.respond_to?(:type) && type.is_a?(Literal::Types::ArrayType)
-        return value.map { |v| _dex_coerce_value(type.type, v) } if value.is_a?(Array)
-        return value
+    class << self
+      def contract
+        Contract.new(
+          params: _contract_params,
+          success: _success_type,
+          errors: _declared_errors
+        )
       end
 
-      if type.respond_to?(:type) && type.is_a?(Literal::Types::NilableType)
-        return _dex_coerce_value(type.type, value)
+      def inherited(subclass)
+        subclass.instance_variable_set(:@_pipeline, pipeline.dup)
+        super
       end
 
-      base = _dex_resolve_base_class(type)
-      coercion = _serialized_coercions[base]
-      coercion ? coercion.call(value) : value
-    end
+      def pipeline
+        @_pipeline ||= Pipeline.new
+      end
 
-    private_class_method :_dex_resolve_base_class, :_dex_coerce_value, :_dex_find_ref_type, :_dex_coerce_serialized_hash
+      def use(mod, as: nil, wrap: nil, before: nil, after: nil, at: nil)
+        step_name = as || _derive_step_name(mod)
+        wrap_method = wrap || :"_#{step_name}_wrap"
+        pipeline.add(step_name, method: wrap_method, before: before, after: after, at: at)
+        include mod
+      end
 
-    def self.inherited(subclass)
-      subclass.instance_variable_set(:@_pipeline, pipeline.dup)
-      super
-    end
+      private
 
-    def self.pipeline
-      @_pipeline ||= Pipeline.new
-    end
+      def _contract_params
+        return {} unless respond_to?(:literal_properties)
 
-    def self.use(mod, as: nil, wrap: nil, before: nil, after: nil, at: nil)
-      step_name = as || _derive_step_name(mod)
-      wrap_method = wrap || :"_#{step_name}_wrap"
-      pipeline.add(step_name, method: wrap_method, before: before, after: after, at: at)
-      include mod
-    end
+        literal_properties.each_with_object({}) do |prop, hash|
+          hash[prop.name] = prop.type
+        end
+      end
 
-    def self._derive_step_name(mod)
-      base = mod.name&.split("::")&.last
-      raise ArgumentError, "anonymous modules require explicit as: parameter" unless base
+      def _derive_step_name(mod)
+        base = mod.name&.split("::")&.last
+        raise ArgumentError, "anonymous modules require explicit as: parameter" unless base
 
-      base.sub(/Wrapper\z/, "")
-        .gsub(/([a-z])([A-Z])/, '\1_\2')
-        .downcase
-        .to_sym
+        base.sub(/Wrapper\z/, "")
+          .gsub(/([a-z])([A-Z])/, '\1_\2')
+          .downcase
+          .to_sym
+      end
     end
-    private_class_method :_derive_step_name
 
     def perform(*, **)
     end
@@ -149,28 +117,9 @@ module Dex
       new(**kwargs).call
     end
 
-    # Serialization helpers
-
-    def _props_as_json
-      return {} unless self.class.respond_to?(:literal_properties)
-
-      result = {}
-      self.class.literal_properties.each do |prop|
-        value = public_send(prop.name)
-        ref = self.class.send(:_dex_find_ref_type, prop.type)
-        result[prop.name.to_s] = if ref && value
-          value.id
-        else
-          value.respond_to?(:as_json) ? value.as_json : value
-        end
-      end
-      result
-    end
-
     include Settings
     include AsyncWrapper
     include SafeWrapper
-    include PropsSetup
 
     use ResultWrapper
     use LockWrapper

data/lib/dex/{operation/props_setup.rb → props_setup.rb}

@@ -1,20 +1,26 @@
 # frozen_string_literal: true
 
-require "set"
-
 module Dex
+  # Shared prop DSL for Operation and Event.
+  #
+  # Wraps Literal::Properties' prop/prop? with three Dex-specific behaviors:
+  #   1. Reserved name validation — each class defines RESERVED_PROP_NAMES
+  #   2. reader: :public by default (Literal defaults to private)
+  #   3. Automatic RefType coercion — _Ref(Model) props auto-coerce IDs to records
   module PropsSetup
+    extend Dex::Concern
+
     def self.included(base)
       base.extend(Literal::Properties)
       base.extend(Literal::Types)
-      base.extend(ClassMethods)
+      super
     end
 
     module ClassMethods
-      RESERVED_PROP_NAMES = %i[call perform async safe initialize].to_set.freeze
-
       def prop(name, type, kind = :keyword, **options, &block)
-        _props_validate_name!(name)
+        if const_defined?(:RESERVED_PROP_NAMES) && self::RESERVED_PROP_NAMES.include?(name)
+          raise ArgumentError, "Property :#{name} is reserved."
+        end
         options[:reader] = :public unless options.key?(:reader)
         if type.is_a?(Dex::RefType) && !block
           ref = type
@@ -36,15 +42,6 @@ module Dex
       def _Ref(model_class, lock: false) # rubocop:disable Naming/MethodName
         Dex::RefType.new(model_class, lock: lock)
       end
-
-      private
-
-      def _props_validate_name!(name)
-        return unless RESERVED_PROP_NAMES.include?(name)
-
-        raise ArgumentError,
-          "Property :#{name} conflicts with core Operation methods."
-      end
     end
   end
 end

data/lib/dex/test_helpers.rb

@@ -110,9 +110,11 @@ module Dex
   end
 
   module TestHelpers
+    extend Dex::Concern
+
     def self.included(base)
       Dex::TestWrapper.install!
-      base.extend(ClassMethods)
+      super
     end
 
     def setup

data/lib/dex/type_coercion.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Dex
+  module TypeCoercion
+    extend Dex::Concern
+
+    module ClassMethods
+      def _serialized_coercions
+        @_serialized_coercions ||= {
+          Time => ->(v) { v.is_a?(String) ? Time.parse(v) : v },
+          Symbol => ->(v) { v.is_a?(String) ? v.to_sym : v }
+        }.tap do |h|
+          h[Date] = ->(v) { v.is_a?(String) ? Date.parse(v) : v } if defined?(Date)
+          h[DateTime] = ->(v) { v.is_a?(String) ? DateTime.parse(v) : v } if defined?(DateTime)
+          h[BigDecimal] = ->(v) { v.is_a?(String) ? BigDecimal(v) : v } if defined?(BigDecimal)
+        end.freeze
+      end
+
+      private
+
+      def _find_ref_type(type)
+        return type if type.is_a?(Dex::RefType)
+
+        if type.respond_to?(:type)
+          inner = type.type
+          return inner if inner.is_a?(Dex::RefType)
+        end
+        nil
+      end
+
+      def _resolve_base_class(type)
+        return type.model_class if type.is_a?(Dex::RefType)
+        return _resolve_base_class(type.type) if type.respond_to?(:type)
+
+        type if type.is_a?(Class)
+      end
+
+      def _coerce_value(type, value)
+        return value unless value
+
+        if type.is_a?(Literal::Types::ArrayType)
+          return value.map { |v| _coerce_value(type.type, v) } if value.is_a?(Array)
+
+          return value
+        end
+
+        return _coerce_value(type.type, value) if type.is_a?(Literal::Types::NilableType)
+
+        ref = _find_ref_type(type)
+        return ref.coerce(value) if ref
+
+        base = _resolve_base_class(type)
+        coercion = _serialized_coercions[base]
+        coercion ? coercion.call(value) : value
+      end
+
+      def _serialize_value(type, value)
+        return value unless value
+
+        if type.is_a?(Literal::Types::ArrayType) && value.is_a?(Array)
+          return value.map { |v| _serialize_value(type.type, v) }
+        end
+
+        return _serialize_value(type.type, value) if type.is_a?(Literal::Types::NilableType)
+
+        ref = _find_ref_type(type)
+        return value.id if ref
+
+        value.respond_to?(:as_json) ? value.as_json : value
+      end
+
+      def _coerce_serialized_hash(hash)
+        return hash.transform_keys(&:to_sym) unless respond_to?(:literal_properties)
+
+        result = {}
+        literal_properties.each do |prop|
+          name = prop.name
+          raw = hash.key?(name) ? hash[name] : hash[name.to_s]
+          result[name] = _coerce_value(prop.type, raw)
+        end
+        result
+      end
+    end
+
+    def _props_as_json
+      return {} unless self.class.respond_to?(:literal_properties)
+
+      result = {}
+      self.class.literal_properties.each do |prop|
+        value = public_send(prop.name)
+        result[prop.name.to_s] = self.class.send(:_serialize_value, prop.type, value)
+      end
+      result
+    end
+  end
+end

data/lib/dex/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Dex
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/dexkit.rb

@@ -10,21 +10,34 @@ loader.ignore("#{__dir__}/dex")
 loader.setup
 
 require_relative "dex/version"
+require_relative "dex/concern"
 require_relative "dex/ref_type"
+require_relative "dex/type_coercion"
+require_relative "dex/props_setup"
 require_relative "dex/error"
 require_relative "dex/operation"
+require_relative "dex/event"
 
 module Dex
   class Configuration
-    attr_accessor :record_class, :transaction_adapter
+    attr_accessor :record_class, :transaction_adapter, :event_store, :event_context, :restore_event_context
 
     def initialize
       @record_class = nil
       @transaction_adapter = nil
+      @event_store = nil
+      @event_context = nil
+      @restore_event_context = nil
     end
   end
 
   class << self
+    def warn(message)
+      return unless defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+
+      Rails.logger.warn("[Dex] #{message}")
+    end
+
     def configuration
       @configuration ||= Configuration.new
     end