dexkit 0.1.0

data/lib/dex/operation/record_wrapper.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module Dex
+  module RecordWrapper
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    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
+
+      if halted.nil? || halted.success?
+        if _record_has_pending_record?
+          _record_update_done!(result)
+        elsif _record_enabled?
+          _record_save!(result)
+        end
+      end
+
+      throw(:_dex_halt, halted) if halted
+      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
+
+        if enabled == false
+          set :record, enabled: false
+        elsif enabled == true || enabled.nil?
+          merged = { enabled: true, params: true, response: true }.merge(options)
+          set :record, **merged
+        else
+          raise ArgumentError,
+            "record expects true, false, or nil, got: #{enabled.inspect}"
+        end
+      end
+    end
+
+    private
+
+    def _record_enabled?
+      return false unless Dex.record_backend
+      return false unless self.class.name
+
+      record_settings = self.class.settings_for(:record)
+      record_settings.fetch(:enabled, true)
+    end
+
+    def _record_has_pending_record?
+      defined?(@_dex_record_id) && @_dex_record_id
+    end
+
+    def _record_save!(result)
+      Dex.record_backend.create_record(_record_attributes(result))
+    rescue => e
+      _record_handle_error(e)
+    end
+
+    def _record_update_done!(result)
+      attrs = { status: "done", performed_at: _record_current_time }
+      attrs[:response] = _record_response(result) if _record_response?
+      Dex.record_backend.update_record(@_dex_record_id, attrs)
+    rescue => e
+      _record_handle_error(e)
+    end
+
+    def _record_attributes(result)
+      attrs = { name: self.class.name, performed_at: _record_current_time, status: "done" }
+      attrs[:params] = _record_params? ? _record_params : nil
+      attrs[:response] = _record_response? ? _record_response(result) : nil
+      attrs
+    end
+
+    def _record_params
+      _props_as_json
+    end
+
+    def _record_params?
+      self.class.settings_for(:record).fetch(:params, true)
+    end
+
+    def _record_response?
+      self.class.settings_for(:record).fetch(:response, true)
+    end
+
+    def _record_response(result)
+      success_type = self.class.respond_to?(:_success_type) && self.class._success_type
+
+      if success_type
+        _record_serialize_typed_result(result, success_type)
+      else
+        case result
+        when nil then nil
+        when Hash then result
+        else { value: result }
+        end
+      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
+    end
+  end
+end

data/lib/dex/operation/rescue_wrapper.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Dex
+  module RescueWrapper
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      def rescue_from(*exception_classes, as:, message: nil)
+        raise ArgumentError, "rescue_from requires at least one exception class" if exception_classes.empty?
+
+        invalid = exception_classes.reject { |k| k.is_a?(Module) && k <= Exception }
+        if invalid.any?
+          raise ArgumentError,
+            "rescue_from expects Exception subclasses, got: #{invalid.map(&:inspect).join(", ")}"
+        end
+
+        raise ArgumentError, "rescue_from :as must be a Symbol, got: #{as.inspect}" unless as.is_a?(Symbol)
+
+        exception_classes.each do |klass|
+          _rescue_own << { exception_class: klass, code: as, message: message }
+        end
+      end
+
+      def _rescue_handlers
+        parent = superclass.respond_to?(:_rescue_handlers) ? superclass._rescue_handlers : []
+        parent + _rescue_own
+      end
+
+      private
+
+      def _rescue_own
+        @_rescue_handlers ||= []
+      end
+    end
+
+    def _rescue_wrap
+      yield
+    rescue Dex::Error
+      raise
+    rescue => e
+      handler = _rescue_find_handler(e)
+      raise unless handler
+
+      _rescue_convert!(e, handler)
+    end
+
+    private
+
+    def _rescue_find_handler(exception)
+      self.class._rescue_handlers.reverse_each do |handler|
+        return handler if exception.is_a?(handler[:exception_class])
+      end
+      nil
+    end
+
+    def _rescue_convert!(exception, handler)
+      msg = handler[:message] || exception.message
+      raise Dex::Error.new(handler[:code], msg, details: { original: exception })
+    end
+  end
+end

data/lib/dex/operation/result_wrapper.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Dex
+  module ResultWrapper
+    module ClassMethods
+      def success(type)
+        @_success_type = type
+      end
+
+      def error(*codes)
+        invalid = codes.reject { |c| c.is_a?(Symbol) }
+        if invalid.any?
+          raise ArgumentError, "error codes must be Symbols, got: #{invalid.map(&:inspect).join(", ")}"
+        end
+
+        @_declared_errors ||= []
+        @_declared_errors.concat(codes)
+      end
+
+      def _success_type
+        @_success_type || (superclass.respond_to?(:_success_type) ? superclass._success_type : nil)
+      end
+
+      def _declared_errors
+        parent = superclass.respond_to?(:_declared_errors) ? superclass._declared_errors : []
+        own = @_declared_errors || []
+        (parent + own).uniq
+      end
+
+      def _has_declared_errors?
+        _declared_errors.any?
+      end
+    end
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    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
+      end
+    end
+
+    def error!(code, message = nil, details: nil)
+      if self.class._has_declared_errors? && !self.class._declared_errors.include?(code)
+        raise ArgumentError, "Undeclared error code: #{code.inspect}. Declared: #{self.class._declared_errors.inspect}"
+      end
+
+      throw(:_dex_halt, Operation::Halt.new(type: :error, error_code: code, error_message: message,
+        error_details: details))
+    end
+
+    def success!(value = nil, **attrs)
+      throw(:_dex_halt, Operation::Halt.new(type: :success, value: attrs.empty? ? value : attrs))
+    end
+
+    def assert!(*args, &block)
+      if block
+        code = args[0]
+        value = yield
+      else
+        value, code = args
+      end
+
+      error!(code) unless value
+      value
+    end
+
+    private
+
+    def _result_validate_success_type!(value)
+      return if value.nil?
+
+      success_type = self.class._success_type
+      return unless success_type
+      return if success_type === value
+
+      raise ArgumentError,
+        "#{self.class.name || "Operation"} declared `success #{success_type.inspect}` but returned #{value.class}"
+    end
+  end
+end

data/lib/dex/operation/safe_wrapper.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Dex
+  module SafeWrapper
+    def safe
+      Operation::SafeProxy.new(self)
+    end
+  end
+end

data/lib/dex/operation/settings.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Dex
+  module Settings
+    module ClassMethods
+      def set(key, **options)
+        @_settings ||= {}
+        @_settings[key] = (@_settings[key] || {}).merge(options)
+      end
+
+      def settings_for(key)
+        parent_settings = if superclass.respond_to?(:settings_for)
+          superclass.settings_for(key) || {}
+        else
+          {}
+        end
+        own_settings = @_settings&.dig(key) || {}
+        parent_settings.merge(own_settings)
+      end
+    end
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+  end
+end

data/lib/dex/operation/transaction_adapter.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Dex
+  class Operation
+    module TransactionAdapter
+      def self.for(adapter_name)
+        case adapter_name&.to_sym
+        when :active_record
+          ActiveRecordAdapter
+        when :mongoid
+          MongoidAdapter
+        when nil
+          detect
+        else
+          raise ArgumentError, "Unknown transaction adapter: #{adapter_name}"
+        end
+      end
+
+      def self.detect
+        if defined?(ActiveRecord::Base)
+          ActiveRecordAdapter
+        elsif defined?(Mongoid)
+          MongoidAdapter
+        end
+      end
+
+      module ActiveRecordAdapter
+        def self.wrap(&block)
+          unless defined?(ActiveRecord::Base)
+            raise LoadError, "ActiveRecord is required for transactions"
+          end
+          ActiveRecord::Base.transaction(&block)
+        end
+
+        def self.rollback_exception_class
+          ActiveRecord::Rollback
+        end
+      end
+
+      module MongoidAdapter
+        def self.wrap(&block)
+          unless defined?(Mongoid)
+            raise LoadError, "Mongoid is required for transactions"
+          end
+          Mongoid.transaction(&block)
+        end
+
+        def self.rollback_exception_class
+          Mongoid::Errors::Rollback
+        end
+      end
+    end
+  end
+end

data/lib/dex/operation/transaction_wrapper.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Dex
+  module TransactionWrapper
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    def _transaction_wrap
+      return yield unless _transaction_enabled?
+
+      halted = 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
+      end
+
+      throw(:_dex_halt, halted) if halted
+      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
+
+        case enabled_or_options
+        when false
+          set :transaction, enabled: false
+        when true, nil
+          _transaction_validate_adapter!(options[:adapter]) if options.key?(:adapter)
+          set :transaction, enabled: true, **options
+        when Symbol
+          _transaction_validate_adapter!(enabled_or_options)
+          set :transaction, enabled: true, adapter: enabled_or_options, **options
+        else
+          raise ArgumentError,
+            "transaction expects true, false, nil, or a Symbol adapter, got: #{enabled_or_options.inspect}"
+        end
+      end
+
+      private
+
+      def _transaction_validate_adapter!(adapter)
+        return if adapter.nil?
+
+        unless TransactionWrapper::TRANSACTION_KNOWN_ADAPTERS.include?(adapter.to_sym)
+          raise ArgumentError,
+            "unknown transaction adapter: #{adapter.inspect}. " \
+            "Known: #{TransactionWrapper::TRANSACTION_KNOWN_ADAPTERS.map(&:inspect).join(", ")}"
+        end
+      end
+    end
+
+    private
+
+    def _transaction_enabled?
+      settings = self.class.settings_for(:transaction)
+      return false unless settings.fetch(:enabled, true)
+
+      !_transaction_adapter.nil?
+    end
+
+    def _transaction_adapter
+      settings = self.class.settings_for(:transaction)
+      adapter_name = settings.fetch(:adapter, Dex.transaction_adapter)
+      Operation::TransactionAdapter.for(adapter_name)
+    end
+
+    def _transaction_execute(&block)
+      _transaction_adapter.wrap(&block)
+    end
+  end
+end

data/lib/dex/operation.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+# 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"
+require_relative "operation/lock_wrapper"
+require_relative "operation/async_wrapper"
+require_relative "operation/safe_wrapper"
+require_relative "operation/rescue_wrapper"
+require_relative "operation/callback_wrapper"
+
+# Pipeline (referenced inside class body)
+require_relative "operation/pipeline"
+
+module Dex
+  class Operation
+    Halt = Struct.new(:type, :value, :error_code, :error_message, :error_details, keyword_init: true) do
+      def success? = type == :success
+      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
+
+    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)
+      end
+      nil
+    end
+
+    def self._dex_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] = _dex_coerce_value(prop.type, raw)
+      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)
+
+      type if type.is_a?(Class)
+    end
+
+    def self._dex_coerce_value(type, value)
+      return value unless value
+      return value if _dex_find_ref_type(type)
+
+      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
+      end
+
+      if type.respond_to?(:type) && type.is_a?(Literal::Types::NilableType)
+        return _dex_coerce_value(type.type, value)
+      end
+
+      base = _dex_resolve_base_class(type)
+      coercion = _serialized_coercions[base]
+      coercion ? coercion.call(value) : value
+    end
+
+    private_class_method :_dex_resolve_base_class, :_dex_coerce_value, :_dex_find_ref_type, :_dex_coerce_serialized_hash
+
+    def self.inherited(subclass)
+      subclass.instance_variable_set(:@_pipeline, pipeline.dup)
+      super
+    end
+
+    def self.pipeline
+      @_pipeline ||= Pipeline.new
+    end
+
+    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
+
+    def self._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
+    end
+    private_class_method :_derive_step_name
+
+    def perform(*, **)
+    end
+
+    def call
+      self.class.pipeline.execute(self) { perform }
+    end
+
+    def self.method_added(method_name)
+      super
+      return unless method_name == :perform
+
+      private :perform
+    end
+
+    private :perform
+
+    def self.call(**kwargs)
+      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
+    use TransactionWrapper
+    use RecordWrapper
+    use RescueWrapper
+    use CallbackWrapper
+  end
+end
+
+# Nested classes (reopen Operation after it's defined)
+require_relative "operation/outcome"
+require_relative "operation/async_proxy"
+require_relative "operation/record_backend"
+require_relative "operation/transaction_adapter"
+require_relative "operation/jobs"
+
+# Top-level aliases (depend on Operation::Ok/Err)
+require_relative "match"

data/lib/dex/ref_type.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Dex
+  class RefType
+    include Literal::Type
+
+    attr_reader :model_class, :lock
+
+    def initialize(model_class, lock: false)
+      @model_class = model_class
+      @lock = lock
+    end
+
+    def ===(value)
+      value.is_a?(@model_class)
+    end
+
+    def >=(other, context: nil)
+      other.is_a?(RefType) && other.model_class <= @model_class
+    end
+
+    def coerce(value)
+      return value if value.is_a?(@model_class)
+      return value if value.nil?
+
+      scope = @lock ? @model_class.lock : @model_class
+      scope.find(value)
+    end
+
+    def inspect
+      @lock ? "_Ref(#{@model_class}, lock: true)" : "_Ref(#{@model_class})"
+    end
+  end
+end