dexkit 0.8.0 → 0.10.0

data/lib/dex/operation/test_helpers.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require_relative "../test_log"
+
+module Dex
+  class Operation
+    module TestWrapper
+      @_installed = false
+
+      class << self
+        def install!
+          return if @_installed
+
+          Dex::Operation.prepend(self)
+          @_installed = true
+        end
+
+        def installed?
+          @_installed
+        end
+
+        # Stub registry
+
+        def stubs
+          @_stubs ||= {}
+        end
+
+        def find_stub(klass)
+          stubs[klass]
+        end
+
+        def register_stub(klass, **options)
+          stubs[klass] = options
+        end
+
+        def clear_stub(klass)
+          stubs.delete(klass)
+        end
+
+        def clear_all_stubs!
+          stubs.clear
+        end
+      end
+
+      def call
+        stub = Dex::Operation::TestWrapper.find_stub(self.class)
+        return _test_apply_stub(stub) if stub
+
+        started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        result = nil
+        err = nil
+
+        begin
+          result = super
+        rescue Exception => e # rubocop:disable Lint/RescueException
+          err = e
+          raise
+        ensure
+          duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at
+          _test_record_to_log(result, err, duration)
+        end
+
+        result
+      end
+
+      private
+
+      def _test_apply_stub(stub)
+        if stub[:error]
+          err_opts = stub[:error]
+          case err_opts
+          when Symbol
+            raise Dex::Error.new(err_opts)
+          when Hash
+            raise Dex::Error.new(err_opts[:code], err_opts[:message], details: err_opts[:details])
+          end
+        else
+          stub[:returns]
+        end
+      end
+
+      def _test_safe_params
+        respond_to?(:to_h) ? to_h : {}
+      rescue
+        {}
+      end
+
+      def _test_record_to_log(result, err, duration)
+        safe_result = if err
+          dex_err = if err.is_a?(Dex::Error)
+            err
+          else
+            Dex::Error.new(:exception, err.message, details: { exception_class: err.class.name })
+          end
+          Dex::Operation::Err.new(dex_err)
+        else
+          Dex::Operation::Ok.new(result)
+        end
+
+        trace = Dex::Trace.current + [{
+          type: :operation,
+          id: @_dex_execution_id,
+          class: self.class.name || self.class.to_s
+        }]
+
+        entry = Dex::TestLog::Entry.new(
+          type: "Operation",
+          name: self.class.name || self.class.to_s,
+          operation_class: self.class,
+          params: _test_safe_params,
+          result: safe_result,
+          duration: duration,
+          caller_location: caller_locations(4, 1)&.first,
+          execution_id: @_dex_execution_id,
+          trace_id: @_dex_trace_id,
+          trace: trace
+        )
+        Dex::TestLog.record(entry)
+      end
+    end
+
+    module TestHelpers
+      extend Dex::Concern
+
+      def self.included(base)
+        Dex::Operation::TestWrapper.install!
+        super
+      end
+
+      def setup
+        super
+        Dex::Trace.clear!
+        Dex::TestLog.clear!
+        Dex::Operation::TestWrapper.clear_all_stubs!
+      end
+
+      module ClassMethods
+        def testing(klass)
+          @_dex_test_subject = klass
+        end
+
+        def _dex_test_subject
+          return @_dex_test_subject if defined?(@_dex_test_subject) && @_dex_test_subject
+
+          superclass._dex_test_subject if superclass.respond_to?(:_dex_test_subject)
+        end
+      end
+
+      private
+
+      def _dex_test_subject
+        self.class._dex_test_subject
+      end
+    end
+  end
+end
+
+require_relative "test_helpers/execution"
+require_relative "test_helpers/assertions"
+require_relative "test_helpers/stubbing"

data/lib/dex/operation/trace_wrapper.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Dex
+  module TraceWrapper
+    extend Dex::Concern
+
+    def _trace_wrap
+      @_dex_execution_id ||= Dex::Id.generate("op_")
+
+      Dex::Trace.with_frame(
+        type: :operation,
+        id: @_dex_execution_id,
+        class: self.class.name
+      ) do
+        @_dex_trace_id = Dex::Trace.trace_id
+        yield
+      end
+    end
+  end
+end

data/lib/dex/operation/transaction_adapter.rb

@@ -3,25 +3,44 @@
 module Dex
   class Operation
     module TransactionAdapter
+      KNOWN_ADAPTERS = %i[active_record].freeze
+
       def self.for(adapter_name)
-        case adapter_name&.to_sym
+        case normalize_name(adapter_name)
         when :active_record
           ActiveRecordAdapter
-        when :mongoid
-          MongoidAdapter
         when nil
           detect
-        else
-          raise ArgumentError, "Unknown transaction adapter: #{adapter_name}"
         end
       end
 
+      def self.known_adapters
+        KNOWN_ADAPTERS
+      end
+
+      def self.normalize_name(adapter_name)
+        return nil if adapter_name.nil?
+
+        normalized = adapter_name.to_sym
+        return normalized if KNOWN_ADAPTERS.include?(normalized)
+
+        raise ArgumentError,
+          "unknown transaction adapter: #{adapter_name.inspect}. " \
+          "Known: #{KNOWN_ADAPTERS.map(&:inspect).join(", ")}"
+      end
+
       def self.detect
-        if defined?(ActiveRecord::Base)
-          ActiveRecordAdapter
-        elsif defined?(Mongoid)
-          MongoidAdapter
-        end
+        return unless defined?(ActiveRecord::Base)
+        return unless active_record_pool?
+
+        ActiveRecordAdapter
+      end
+
+      def self.active_record_pool?
+        !ActiveRecord::Base.connection_handler.retrieve_connection_pool(
+          ActiveRecord::Base.connection_specification_name,
+          strict: false
+        ).nil?
       end
 
       module ActiveRecordAdapter
@@ -44,64 +63,6 @@ module Dex
           ActiveRecord::Rollback
         end
       end
-
-      module MongoidAdapter
-        AFTER_COMMIT_KEY = :_dex_mongoid_after_commit
-
-        def self.wrap(&block)
-          unless defined?(Mongoid)
-            raise LoadError, "Mongoid is required for transactions"
-          end
-
-          callbacks = Thread.current[AFTER_COMMIT_KEY]
-          outermost = callbacks.nil?
-
-          unless outermost
-            snapshot = callbacks.length
-            begin
-              return block.call
-            rescue rollback_exception_class
-              callbacks.slice!(snapshot..)
-              return nil
-            rescue StandardError # rubocop:disable Style/RescueStandardError
-              callbacks.slice!(snapshot..)
-              raise
-            end
-          end
-
-          Thread.current[AFTER_COMMIT_KEY] = []
-          block_completed = false
-          result = Mongoid.transaction do
-            value = block.call
-            block_completed = true
-            value
-          end
-
-          if block_completed
-            Thread.current[AFTER_COMMIT_KEY].each(&:call)
-          end
-
-          result
-        ensure
-          Thread.current[AFTER_COMMIT_KEY] = nil if outermost
-        end
-
-        # NOTE: Only detects transactions opened via MongoidAdapter.wrap (i.e. Dex operations).
-        # Ambient Mongoid.transaction blocks opened outside Dex are invisible here —
-        # the callback will fire immediately instead of deferring to the outer commit.
-        def self.after_commit(&block)
-          callbacks = Thread.current[AFTER_COMMIT_KEY]
-          if callbacks
-            callbacks << block
-          else
-            block.call
-          end
-        end
-
-        def self.rollback_exception_class
-          Mongoid::Errors::Rollback
-        end
-      end
     end
   end
 end

data/lib/dex/operation/transaction_wrapper.rb

@@ -7,10 +7,10 @@ module Dex
     DEFERRED_CALLBACKS_KEY = :_dex_after_commit_queue
 
     def _transaction_wrap
-      deferred = Thread.current[DEFERRED_CALLBACKS_KEY]
+      deferred = Fiber[DEFERRED_CALLBACKS_KEY]
       outermost = deferred.nil?
-      Thread.current[DEFERRED_CALLBACKS_KEY] = [] if outermost
-      snapshot = Thread.current[DEFERRED_CALLBACKS_KEY].length
+      Fiber[DEFERRED_CALLBACKS_KEY] = [] if outermost
+      snapshot = Fiber[DEFERRED_CALLBACKS_KEY].length
 
       result, interceptor = if _transaction_enabled?
         _transaction_run_adapter(snapshot) { yield }
@@ -23,16 +23,16 @@ module Dex
       interceptor&.rethrow!
       result
     rescue # rubocop:disable Style/RescueStandardError -- explicit for clarity
-      Thread.current[DEFERRED_CALLBACKS_KEY]&.slice!(snapshot..)
+      Fiber[DEFERRED_CALLBACKS_KEY]&.slice!(snapshot..)
       raise
     ensure
-      Thread.current[DEFERRED_CALLBACKS_KEY] = nil if outermost
+      Fiber[DEFERRED_CALLBACKS_KEY] = nil if outermost
     end
 
     def after_commit(&block)
       raise ArgumentError, "after_commit requires a block" unless block
 
-      deferred = Thread.current[DEFERRED_CALLBACKS_KEY]
+      deferred = Fiber[DEFERRED_CALLBACKS_KEY]
       if deferred
         deferred << block
       else
@@ -40,8 +40,6 @@ module Dex
       end
     end
 
-    TRANSACTION_KNOWN_ADAPTERS = %i[active_record mongoid].freeze
-
     module ClassMethods
       def transaction(enabled_or_options = nil, **options)
         validate_options!(options, %i[adapter], :transaction)
@@ -66,11 +64,7 @@ module Dex
       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
+        Operation::TransactionAdapter.normalize_name(adapter)
       end
     end
 
@@ -85,7 +79,7 @@ module Dex
       end
 
       if interceptor&.error?
-        Thread.current[DEFERRED_CALLBACKS_KEY]&.slice!(snapshot..)
+        Fiber[DEFERRED_CALLBACKS_KEY]&.slice!(snapshot..)
         interceptor.rethrow!
       end
 
@@ -96,7 +90,7 @@ module Dex
       interceptor = Operation::HaltInterceptor.new { yield }
 
       if interceptor.error?
-        Thread.current[DEFERRED_CALLBACKS_KEY]&.slice!(snapshot..)
+        Fiber[DEFERRED_CALLBACKS_KEY]&.slice!(snapshot..)
         interceptor.rethrow!
       end
 
@@ -117,7 +111,7 @@ module Dex
     end
 
     def _transaction_flush_deferred
-      callbacks = Thread.current[DEFERRED_CALLBACKS_KEY]
+      callbacks = Fiber[DEFERRED_CALLBACKS_KEY]
       return if callbacks.empty?
 
       flush = -> { callbacks.each(&:call) }

data/lib/dex/operation.rb

@@ -4,6 +4,7 @@
 require_relative "operation/result_wrapper"
 require_relative "operation/once_wrapper"
 require_relative "operation/record_wrapper"
+require_relative "operation/trace_wrapper"
 require_relative "operation/transaction_wrapper"
 require_relative "operation/lock_wrapper"
 require_relative "operation/async_wrapper"
@@ -139,6 +140,7 @@ module Dex
     include AsyncWrapper
     include SafeWrapper
 
+    use TraceWrapper, at: :outer
     use ResultWrapper
     use GuardWrapper
     use OnceWrapper

data/lib/dex/query/backend.rb

@@ -76,16 +76,29 @@ module Dex
       module_function
 
       def apply_strategy(scope, strategy, column, value)
+        scope = normalize_scope(scope)
         adapter_for(scope).apply(scope, strategy, column, value)
       end
 
       def adapter_for(scope)
+        scope = normalize_scope(scope)
+
         if defined?(Mongoid::Criteria) && scope.is_a?(Mongoid::Criteria)
           MongoidAdapter
         else
           ActiveRecordAdapter
         end
       end
+
+      def normalize_scope(scope)
+        return scope unless defined?(Mongoid::Criteria)
+        return scope if scope.is_a?(Mongoid::Criteria)
+
+        criteria = scope.criteria if scope.respond_to?(:criteria)
+        criteria.is_a?(Mongoid::Criteria) ? criteria : scope
+      rescue
+        scope
+      end
     end
   end
 end

data/lib/dex/query/export.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Dex
+  class Query
+    module Export
+      module_function
+
+      def build_hash(source)
+        h = {}
+        h[:name] = source.name if source.name
+        desc = source.description
+        h[:description] = desc if desc
+        h[:props] = _serialize_props(source)
+        ctx = _serialize_context(source)
+        h[:context] = ctx unless ctx.empty?
+        h[:filters] = source.filters unless source.filters.empty?
+        h[:sorts] = source.sorts unless source.sorts.empty?
+        h
+      end
+
+      def build_json_schema(source) # rubocop:disable Metrics/MethodLength
+        descs = source.respond_to?(:prop_descriptions) ? source.prop_descriptions : {}
+        properties = {}
+        required = []
+
+        if source.respond_to?(:literal_properties)
+          source.literal_properties.each do |prop|
+            prop_desc = descs[prop.name]
+            schema = TypeSerializer.to_json_schema(prop.type, desc: prop_desc)
+            properties[prop.name.to_s] = schema
+            required << prop.name.to_s if prop.required?
+          end
+        end
+
+        result = { "$schema": "https://json-schema.org/draft/2020-12/schema" }
+        result[:title] = source.name if source.name
+        desc = source.description
+        result[:description] = desc if desc
+        result[:type] = "object"
+        result[:properties] = properties unless properties.empty?
+        result[:required] = required unless required.empty?
+        result[:additionalProperties] = false
+        result
+      end
+
+      def _serialize_props(source)
+        return {} unless source.respond_to?(:literal_properties)
+
+        descs = source.respond_to?(:prop_descriptions) ? source.prop_descriptions : {}
+        source.literal_properties.each_with_object({}) do |prop, hash|
+          entry = { type: TypeSerializer.to_string(prop.type), required: prop.required? }
+          entry[:desc] = descs[prop.name] if descs[prop.name]
+          hash[prop.name] = entry
+        end
+      end
+
+      def _serialize_context(source)
+        source.respond_to?(:context_mappings) ? source.context_mappings.presence || {} : {}
+      end
+
+      private_class_method :_serialize_props, :_serialize_context
+    end
+  end
+end

data/lib/dex/query.rb

@@ -3,6 +3,7 @@
 require "active_model"
 
 require_relative "query/backend"
+require_relative "query/export"
 require_relative "query/filtering"
 require_relative "query/sorting"
 
@@ -17,7 +18,11 @@ module Dex
     extend ActiveModel::Naming
     include ActiveModel::Conversion
 
+    extend Registry
+
     class << self
+      include ContextDSL
+
       def scope(&block)
         raise ArgumentError, "scope requires a block." unless block
 
@@ -31,6 +36,14 @@ module Dex
       end
 
       def new(scope: nil, sort: nil, **kwargs)
+        mappings = context_mappings
+        unless mappings.empty?
+          ambient = Dex.context
+          mappings.each do |prop_name, context_key|
+            next if kwargs.key?(prop_name)
+            kwargs[prop_name] = ambient[context_key] if ambient.key?(context_key)
+          end
+        end
         instance = super(**kwargs)
         instance.instance_variable_set(:@_injected_scope, scope)
         sort_str = sort&.to_s
@@ -96,6 +109,30 @@ module Dex
         subclass.instance_variable_set(:@_sort_default, _sort_default) if _sort_default
       end
 
+      # Export
+
+      def to_h
+        Export.build_hash(self)
+      end
+
+      def to_json_schema
+        Export.build_json_schema(self)
+      end
+
+      def export(format: :hash)
+        unless %i[hash json_schema].include?(format)
+          raise ArgumentError, "unknown format: #{format.inspect}. Known: :hash, :json_schema"
+        end
+
+        sorted = registry.sort_by(&:name)
+        sorted.map do |klass|
+          case format
+          when :hash then klass.to_h
+          when :json_schema then klass.to_json_schema
+          end
+        end
+      end
+
       def from_params(params, scope: nil, **overrides)
         pk = model_name.param_key
         nested = _extract_nested_params(params, pk)
@@ -139,6 +176,10 @@ module Dex
 
       private
 
+      def _context_prop_declared?(name)
+        respond_to?(:literal_properties) && literal_properties.any? { |p| p.name == name }
+      end
+
       def _extract_nested_params(params, pk)
         hash = if params.respond_to?(:to_unsafe_h)
           params.to_unsafe_h
@@ -209,9 +250,10 @@ module Dex
     end
 
     def resolve
-      base = _evaluate_scope
+      base = Query::Backend.normalize_scope(_evaluate_scope)
       base = _merge_injected_scope(base)
       base = _apply_filters(base)
+      base = Query::Backend.normalize_scope(base)
       _apply_sort(base)
     end
 
@@ -253,19 +295,22 @@ module Dex
     def _merge_injected_scope(base)
       return base unless @_injected_scope
 
+      base = Query::Backend.normalize_scope(base)
+      injected_scope = Query::Backend.normalize_scope(@_injected_scope)
+
       unless base.respond_to?(:klass)
         raise ArgumentError, "Scope block must return a queryable scope (ActiveRecord relation or Mongoid criteria), got #{base.class}."
       end
 
-      unless @_injected_scope.respond_to?(:klass)
+      unless injected_scope.respond_to?(:klass)
         raise ArgumentError, "Injected scope must be a queryable scope (ActiveRecord relation or Mongoid criteria), got #{@_injected_scope.class}."
       end
 
-      unless base.klass == @_injected_scope.klass
-        raise ArgumentError, "Scope model mismatch: expected #{base.klass}, got #{@_injected_scope.klass}."
+      unless base.klass == injected_scope.klass
+        raise ArgumentError, "Scope model mismatch: expected #{base.klass}, got #{injected_scope.klass}."
       end
 
-      base.merge(@_injected_scope)
+      base.merge(injected_scope)
     end
   end
 end

data/lib/dex/ref_type.rb

@@ -7,6 +7,10 @@ module Dex
     attr_reader :model_class, :lock
 
     def initialize(model_class, lock: false)
+      if lock && !model_class.respond_to?(:lock)
+        raise ArgumentError, "_Ref(lock: true) requires a model class that responds to .lock"
+      end
+
       @model_class = model_class
       @lock = lock
     end