dexkit 0.1.0

data/lib/dex/error.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Dex
+  class Error < StandardError
+    attr_reader :code, :details
+
+    def initialize(code, message = nil, details: nil)
+      @code = code
+      @details = details
+      super(message || code.to_s)
+    end
+
+    def deconstruct_keys(keys)
+      { code: @code, message: message, details: @details }
+    end
+  end
+end

data/lib/dex/match.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Dex
+  # Top-level aliases for clean pattern matching
+  Ok = Operation::Ok
+  Err = Operation::Err
+
+  # Module for including Ok/Err constants without namespace prefix
+  module Match
+    Ok = Dex::Ok
+    Err = Dex::Err
+  end
+end

data/lib/dex/operation/async_proxy.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Dex
+  class Operation
+    class AsyncProxy
+      def initialize(operation, **runtime_options)
+        @operation = operation
+        @runtime_options = runtime_options
+      end
+
+      def call
+        _async_ensure_active_job_loaded!
+        if _async_use_record_strategy?
+          _async_enqueue_record_job
+        else
+          _async_enqueue_direct_job
+        end
+      end
+
+      private
+
+      def _async_enqueue_direct_job
+        job = _async_apply_options(Operation::DirectJob)
+        job.perform_later(class_name: _async_operation_class_name, params: _async_serialized_params)
+      end
+
+      def _async_enqueue_record_job
+        record = Dex.record_backend.create_record(
+          name: _async_operation_class_name,
+          params: _async_serialized_params,
+          status: "pending"
+        )
+        begin
+          job = _async_apply_options(Operation::RecordJob)
+          job.perform_later(class_name: _async_operation_class_name, record_id: record.id)
+        rescue => e
+          begin
+            record.destroy
+          rescue => destroy_error
+            _async_log_warning("Failed to clean up pending record #{record.id}: #{destroy_error.message}")
+          end
+          raise e
+        end
+      end
+
+      def _async_use_record_strategy?
+        return false unless Dex.record_backend
+        return false unless @operation.class.name
+
+        record_settings = @operation.class.settings_for(:record)
+        return false if record_settings[:enabled] == false
+        return false if record_settings[:params] == false
+
+        true
+      end
+
+      def _async_apply_options(job_class)
+        options = {}
+        options[:queue] = _async_queue if _async_queue
+        options[:wait_until] = _async_scheduled_at if _async_scheduled_at
+        options[:wait] = _async_scheduled_in if _async_scheduled_in
+        options.empty? ? job_class : job_class.set(**options)
+      end
+
+      def _async_ensure_active_job_loaded!
+        return if defined?(ActiveJob::Base)
+
+        raise LoadError, "ActiveJob is required for async operations. Add 'activejob' to your Gemfile."
+      end
+
+      def _async_merged_options
+        @operation.class.settings_for(:async).merge(@runtime_options)
+      end
+
+      def _async_queue = _async_merged_options[:queue]
+      def _async_scheduled_at = _async_merged_options[:at]
+      def _async_scheduled_in = _async_merged_options[:in]
+      def _async_operation_class_name = @operation.class.name
+
+      def _async_serialized_params
+        @_async_serialized_params ||= begin
+          hash = @operation._props_as_json
+          _async_validate_serializable!(hash)
+          hash
+        end
+      end
+
+      def _async_log_warning(message)
+        if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+          Rails.logger.warn "[Dex] #{message}"
+        end
+      end
+
+      def _async_validate_serializable!(hash, path: "")
+        hash.each do |key, value|
+          current = path.empty? ? key.to_s : "#{path}.#{key}"
+          case value
+          when String, Integer, Float, NilClass, TrueClass, FalseClass
+            next
+          when Hash
+            _async_validate_serializable!(value, path: current)
+          when Array
+            value.each_with_index do |v, i|
+              _async_validate_serializable!({ i => v }, path: current)
+            end
+          else
+            raise ArgumentError,
+              "Param '#{current}' (#{value.class}) is not JSON-serializable. " \
+              "Async operations require all params to be serializable."
+          end
+        end
+      end
+    end
+  end
+end

data/lib/dex/operation/async_wrapper.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Dex
+  module AsyncWrapper
+    ASYNC_KNOWN_OPTIONS = %i[queue in at].freeze
+
+    module ClassMethods
+      def async(**options)
+        unknown = options.keys - AsyncWrapper::ASYNC_KNOWN_OPTIONS
+        if unknown.any?
+          raise ArgumentError,
+            "unknown async option(s): #{unknown.map(&:inspect).join(", ")}. " \
+            "Known: #{AsyncWrapper::ASYNC_KNOWN_OPTIONS.map(&:inspect).join(", ")}"
+        end
+
+        set(:async, **options)
+      end
+    end
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    def async(**options)
+      unknown = options.keys - AsyncWrapper::ASYNC_KNOWN_OPTIONS
+      if unknown.any?
+        raise ArgumentError,
+          "unknown async option(s): #{unknown.map(&:inspect).join(", ")}. " \
+          "Known: #{AsyncWrapper::ASYNC_KNOWN_OPTIONS.map(&:inspect).join(", ")}"
+      end
+
+      Operation::AsyncProxy.new(self, **options)
+    end
+  end
+end

data/lib/dex/operation/callback_wrapper.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Dex
+  module CallbackWrapper
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      def before(callable = nil, &block)
+        _callback_validate!(callable, block)
+        entry = callable.is_a?(Symbol) ? [:method, callable] : [:proc, callable || block]
+        _callback_own(:before) << entry
+      end
+
+      def after(callable = nil, &block)
+        _callback_validate!(callable, block)
+        entry = callable.is_a?(Symbol) ? [:method, callable] : [:proc, callable || block]
+        _callback_own(:after) << entry
+      end
+
+      def around(callable = nil, &block)
+        _callback_validate!(callable, block)
+        entry = callable.is_a?(Symbol) ? [:method, callable] : [:proc, callable || block]
+        _callback_own(:around) << entry
+      end
+
+      def _callback_list(type)
+        parent_callbacks = superclass.respond_to?(:_callback_list) ? superclass._callback_list(type) : []
+        parent_callbacks + _callback_own(type)
+      end
+
+      def _callback_any?
+        %i[before after around].any? { |type| _callback_list(type).any? }
+      end
+
+      private
+
+      def _callback_validate!(callable, block)
+        return if callable.is_a?(Symbol)
+        return if callable.nil? && block
+        return if callable.is_a?(Proc)
+
+        if callable.nil?
+          raise ArgumentError, "callback requires a Symbol, Proc, or block"
+        else
+          raise ArgumentError, "callback must be a Symbol or Proc, got: #{callable.class}"
+        end
+      end
+
+      def _callback_own(type)
+        @_callbacks ||= { before: [], after: [], around: [] }
+        @_callbacks[type]
+      end
+    end
+
+    def _callback_wrap
+      return yield unless self.class._callback_any?
+
+      halted = nil
+      result = _callback_run_around(self.class._callback_list(:around)) do
+        _callback_run_before
+        caught = catch(:_dex_halt) { yield }
+        if caught.is_a?(Operation::Halt)
+          if caught.success?
+            halted = caught
+            _callback_run_after
+            caught.value
+          else
+            throw(:_dex_halt, caught)
+          end
+        else
+          _callback_run_after
+          caught
+        end
+      end
+      throw(:_dex_halt, halted) if halted
+      result
+    end
+
+    private
+
+    def _callback_run_before
+      self.class._callback_list(:before).each { |cb| _callback_invoke(cb) }
+    end
+
+    def _callback_run_after
+      self.class._callback_list(:after).each { |cb| _callback_invoke(cb) }
+    end
+
+    def _callback_invoke(cb)
+      kind, callable = cb
+      case kind
+      when :method then send(callable)
+      when :proc then instance_exec(&callable)
+      end
+    end
+
+    def _callback_run_around(chain, &core)
+      if chain.empty?
+        core.call
+      else
+        kind, callable = chain.first
+        rest = chain[1..]
+        continuation = -> { _callback_run_around(rest, &core) }
+        case kind
+        when :method then send(callable) { continuation.call }
+        when :proc then instance_exec(continuation, &callable)
+        end
+      end
+    end
+  end
+end

data/lib/dex/operation/jobs.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Dex
+  class Operation
+    # Job classes are defined lazily when ActiveJob is loaded
+    def self.const_missing(name)
+      return super unless defined?(ActiveJob::Base)
+
+      case name
+      when :DirectJob
+        const_set(:DirectJob, Class.new(ActiveJob::Base) do
+          def perform(class_name:, params:)
+            klass = class_name.constantize
+            klass.new(**klass.send(:_dex_coerce_serialized_hash, params)).call
+          end
+        end)
+      when :RecordJob
+        const_set(:RecordJob, Class.new(ActiveJob::Base) do
+          def perform(class_name:, record_id:)
+            klass = class_name.constantize
+            record = Dex.record_backend.find_record(record_id)
+            params = klass.send(:_dex_coerce_serialized_hash, record.params || {})
+
+            op = klass.new(**params)
+            op.instance_variable_set(:@_dex_record_id, record_id)
+
+            _dex_update_status(record_id, status: "running")
+            op.call
+          rescue => e
+            _dex_handle_failure(record_id, e)
+            raise
+          end
+
+          private
+
+          def _dex_update_status(record_id, **attributes)
+            Dex.record_backend.update_record(record_id, attributes)
+          rescue => e
+            _dex_log_warning("Failed to update record status: #{e.message}")
+          end
+
+          def _dex_handle_failure(record_id, exception)
+            error_value = if exception.is_a?(Dex::Error)
+              exception.code.to_s
+            else
+              exception.class.name
+            end
+            _dex_update_status(record_id, status: "failed", error: error_value)
+          end
+
+          def _dex_log_warning(message)
+            if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+              Rails.logger.warn "[Dex] #{message}"
+            end
+          end
+        end)
+      when :Job
+        const_set(:Job, const_get(:DirectJob))
+      else
+        super
+      end
+    end
+  end
+end

data/lib/dex/operation/lock_wrapper.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Dex
+  module LockWrapper
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    LOCK_KNOWN_OPTIONS = %i[timeout].freeze
+
+    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
+
+        lock_key = block || key
+
+        unless lock_key.nil? || lock_key.is_a?(String) || lock_key.is_a?(Symbol) || lock_key.is_a?(Proc)
+          raise ArgumentError, "advisory_lock key must be a String, Symbol, or Proc, got: #{lock_key.class}"
+        end
+
+        if options.key?(:timeout) && !options[:timeout].is_a?(Numeric)
+          raise ArgumentError, "advisory_lock :timeout must be Numeric, got: #{options[:timeout].inspect}"
+        end
+
+        set(:advisory_lock, enabled: true, key: lock_key, **options)
+      end
+    end
+
+    def _lock_wrap
+      _lock_enabled? ? _lock_execute { yield } : yield
+    end
+
+    private
+
+    def _lock_enabled?
+      self.class.settings_for(:advisory_lock).fetch(:enabled, false)
+    end
+
+    def _lock_key
+      key = self.class.settings_for(:advisory_lock)[:key]
+      case key
+      when String then key
+      when Symbol then send(key)
+      when Proc then instance_exec(&key)
+      when nil then self.class.name || raise(ArgumentError, "Anonymous classes must provide an explicit lock key")
+      else raise ArgumentError, "Unsupported advisory_lock key type: #{key.class}"
+      end
+    end
+
+    def _lock_options
+      opts = {}
+      timeout = self.class.settings_for(:advisory_lock)[:timeout]
+      opts[:timeout_seconds] = timeout if timeout
+      opts
+    end
+
+    def _lock_execute(&block)
+      _lock_ensure_loaded!
+      key = _lock_key
+      ActiveRecord::Base.with_advisory_lock!(key, **_lock_options, &block)
+    rescue WithAdvisoryLock::FailedToAcquireLock
+      raise Dex::Error.new(:lock_timeout, "Could not acquire advisory lock: #{key}")
+    end
+
+    def _lock_ensure_loaded!
+      return if ActiveRecord::Base.respond_to?(:with_advisory_lock!)
+
+      raise LoadError,
+        "with_advisory_lock gem is required for advisory locking. Add 'with_advisory_lock' to your Gemfile."
+    end
+  end
+end

data/lib/dex/operation/outcome.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Dex
+  class Operation
+    class Ok
+      attr_reader :value
+
+      def initialize(value)
+        @value = value
+      end
+
+      def ok? = true
+      def error? = false
+
+      def value! = @value
+
+      def method_missing(method, *args, &block)
+        if @value.respond_to?(method)
+          @value.public_send(method, *args, &block)
+        else
+          super
+        end
+      end
+
+      def respond_to_missing?(method, include_private = false)
+        @value.respond_to?(method, include_private) || super
+      end
+
+      def deconstruct_keys(keys)
+        return { value: @value } unless @value.respond_to?(:deconstruct_keys)
+        @value.deconstruct_keys(keys)
+      end
+    end
+
+    class Err
+      attr_reader :error
+
+      def initialize(error)
+        @error = error
+      end
+
+      def ok? = false
+      def error? = true
+
+      def value = nil
+      def value! = raise @error
+
+      def code = @error.code
+      def message = @error.message
+      def details = @error.details
+
+      def deconstruct_keys(keys)
+        { code: @error.code, message: @error.message, details: @error.details }
+      end
+    end
+
+    class SafeProxy
+      def initialize(operation)
+        @operation = operation
+      end
+
+      def call
+        result = @operation.call
+        Operation::Ok.new(result)
+      rescue Dex::Error => e
+        Operation::Err.new(e)
+      end
+    end
+  end
+end

data/lib/dex/operation/pipeline.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Dex
+  class Operation
+    class Pipeline
+      Step = Data.define(:name, :method)
+
+      def initialize(steps = [])
+        @steps = steps.dup
+      end
+
+      def dup
+        self.class.new(@steps)
+      end
+
+      def steps
+        @steps.dup.freeze
+      end
+
+      def add(name, method: :"_#{name}_wrap", before: nil, after: nil, at: nil)
+        _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)
+        else @steps.push(step)
+        end
+        self
+      end
+
+      def remove(name)
+        @steps.reject! { |s| s.name == name }
+        self
+      end
+
+      def execute(operation)
+        chain = @steps.reverse_each.reduce(-> { yield }) do |next_step, step|
+          -> { operation.send(step.method, &next_step) }
+        end
+        chain.call
+      end
+
+      private
+
+      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)
+        idx = @steps.index { |s| s.name == name }
+        raise ArgumentError, "pipeline step :#{name} not found" unless idx
+        idx
+      end
+    end
+  end
+end

data/lib/dex/operation/props_setup.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "set"
+
+module Dex
+  module PropsSetup
+    def self.included(base)
+      base.extend(Literal::Properties)
+      base.extend(Literal::Types)
+      base.extend(ClassMethods)
+    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)
+        options[:reader] = :public unless options.key?(:reader)
+        if type.is_a?(Dex::RefType) && !block
+          ref = type
+          block = ->(v) { ref.coerce(v) }
+        end
+        super(name, type, kind, **options, &block)
+      end
+
+      def prop?(name, type, kind = :keyword, **options, &block)
+        options[:reader] = :public unless options.key?(:reader)
+        options[:default] = nil unless options.key?(:default)
+        if type.is_a?(Dex::RefType) && !block
+          ref = type
+          block = ->(v) { v.nil? ? v : ref.coerce(v) }
+        end
+        prop(name, _Nilable(type), kind, **options, &block)
+      end
+
+      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/operation/record_backend.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Dex
+  class Operation
+    module RecordBackend
+      def self.for(record_class)
+        return nil unless record_class
+
+        if defined?(ActiveRecord::Base) && record_class < ActiveRecord::Base
+          ActiveRecordAdapter.new(record_class)
+        elsif defined?(Mongoid::Document) && record_class.include?(Mongoid::Document)
+          MongoidAdapter.new(record_class)
+        else
+          raise ArgumentError, "record_class must inherit from ActiveRecord::Base or include Mongoid::Document"
+        end
+      end
+
+      class Base
+        attr_reader :record_class
+
+        def initialize(record_class)
+          @record_class = record_class
+        end
+
+        def create_record(attributes)
+          record_class.create!(safe_attributes(attributes))
+        end
+
+        def find_record(id)
+          record_class.find(id)
+        end
+
+        def update_record(id, attributes)
+          record_class.find(id).update!(safe_attributes(attributes))
+        end
+
+        def safe_attributes(attributes)
+          attributes.select { |key, _| has_field?(key.to_s) }
+        end
+
+        def has_field?(field_name)
+          raise NotImplementedError
+        end
+      end
+
+      class ActiveRecordAdapter < Base
+        def initialize(record_class)
+          super
+          @column_set = record_class.column_names.to_set
+        end
+
+        def has_field?(field_name)
+          @column_set.include?(field_name.to_s)
+        end
+      end
+
+      class MongoidAdapter < Base
+        def has_field?(field_name)
+          record_class.fields.key?(field_name.to_s)
+        end
+      end
+    end
+  end
+end