actionable-rb 1.9.0

data/lib/actionable/rails/proxy_validator.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Actionable
+  # ActiveModel validations applied to a separate delegate object (decision
+  # D7). Subclass it, declare rules with the ActiveModel +validates+ DSL, and
+  # construct it with any object — a plain PORO or an ActiveRecord model — whose
+  # attributes the rules read. This keeps validation rules separate from the
+  # data they check.
+  #
+  #   class InvoiceRules < Actionable::ProxyValidator
+  #     validates :amount, presence: true, numericality: { greater_than: 0 }
+  #   end
+  #
+  #   rules = InvoiceRules.new(invoice)
+  #   fail(:invalid, **rules.formatted_errors) unless rules.valid?
+  #
+  # Part of the optional Rails adapter — available only after
+  # +require 'actionable/rails'+.
+  class ProxyValidator
+    include ActiveModel::Validations
+
+    # ActiveModel needs a model name to build i18n error messages; supply a
+    # fallback so anonymous subclasses (and the base) still produce messages.
+    #
+    # @return [ActiveModel::Name]
+    def self.model_name
+      @model_name ||= ActiveModel::Name.new(self, nil, name || 'ProxyValidator')
+    end
+
+    # @return [Object] the object whose attributes the rules validate
+    attr_reader :delegate
+
+    # @param delegate [Object] the object to validate
+    def initialize(delegate)
+      @delegate = delegate
+    end
+
+    # @return [Hash{Symbol=>Array<String>}] validation errors keyed by
+    #   attribute, after running the rules — ready to splat into +fail+
+    def formatted_errors
+      valid?
+      errors.to_hash
+    end
+
+    private
+
+    # Read attribute values from the delegate so the ActiveModel validators see
+    # the delegate's data.
+    def method_missing(name, *args, &block)
+      return @delegate.public_send(name, *args, &block) if @delegate.respond_to?(name)
+
+      super
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      @delegate.respond_to?(name, include_private) || super
+    end
+  end
+end

data/lib/actionable/rails/transactions.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Actionable
+  module Rails
+    # Internal signal raised inside a transaction block to trigger a rollback
+    # without surfacing as a genuine error. The runner wrapper swallows it; a
+    # real ActiveRecord transaction rolls back and re-raises it (as it does for
+    # any exception), and the wrapper catches it outside the block.
+    class Rollback < StandardError; end
+
+    # The +transactional+ class macro (decision D9). Extended onto
+    # {Actionable::Action} by +actionable/rails+.
+    module Transactions
+      # Wrap this action's run in +model.transaction(**options)+.
+      #
+      #   transactional model: :invoice
+      #   transactional model: Invoice, requires_new: false # join an outer one
+      #
+      # Run inside a transaction that is already open, the action gets its own
+      # savepoint (+requires_new: true+) unless +requires_new:+ is given, so a
+      # recorded +Failure+ rolls back its own writes rather than leaving them for
+      # the outer transaction to commit.
+      #
+      # @param model [Symbol, Class] the model whose +transaction+ is used; a
+      #   Symbol is resolved to a constant (+:invoice+ → +Invoice+)
+      # @param options [Object] options forwarded to +transaction+
+      # @return [void]
+      def transactional(model:, **options)
+        @transaction_config = {model: model, options: options}
+      end
+
+      # The transaction config for this action, inherited from ancestors when
+      # not set locally (decision D9: inherited, overridable).
+      #
+      # @return [Hash{Symbol=>Object}, nil] +{model:, options:}+, or +nil+ when
+      #   neither this action nor an ancestor is +transactional+
+      def transaction_config
+        return @transaction_config if defined?(@transaction_config) && @transaction_config
+        return superclass.transaction_config if superclass.respond_to?(:transaction_config)
+
+        nil
+      end
+    end
+
+    # Prepended onto {Actionable::Runner} so a +transactional+ action runs its
+    # whole pipeline inside a transaction. A raised exception or a recorded
+    # +Failure+ rolls everything back; a +Success+ commits (decision D9).
+    module RunnerTransaction
+      # @return [Result]
+      def run
+        config = transaction_config
+        return super unless config
+
+        result = nil
+        model = resolve_model(config[:model])
+        model.transaction(**transaction_options(model, config[:options])) do
+          result = super
+          raise Rollback if result.failure?
+        end
+        result
+      rescue Rollback
+        result
+      end
+
+      private
+
+      # @return [Hash{Symbol=>Object}, nil] the running action's transaction config
+      def transaction_config
+        klass = @instance.class
+        klass.respond_to?(:transaction_config) ? klass.transaction_config : nil
+      end
+
+      # The configured options, plus +requires_new: true+ when a transaction is
+      # already open and the action did not say otherwise. Joining the outer
+      # transaction would swallow this run's rollback, so a recorded failure's
+      # writes would commit with it (decision D9).
+      #
+      # @param model [Class]
+      # @param options [Hash{Symbol=>Object}]
+      # @return [Hash{Symbol=>Object}]
+      def transaction_options(model, options)
+        return options if options.key?(:requires_new)
+        return options unless model.respond_to?(:connection) && model.connection.transaction_open?
+
+        options.merge(requires_new: true)
+      end
+
+      # @param model [Symbol, Class]
+      # @return [Class] the resolved model class
+      def resolve_model(model)
+        model.is_a?(Class) ? model : model.to_s.camelize.constantize
+      end
+    end
+  end
+end

data/lib/actionable/rails.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# Optional Rails adapter (decisions D8/D9). This file is NEVER required by the
+# core entry point — load it explicitly with `require 'actionable/rails'` (in a
+# Rails app, the Railtie does so during boot). It is the only place that pulls
+# in active_*.
+require_relative '../actionable' # ensure the core is loaded (self-contained entry)
+require 'active_model'
+require 'active_support/core_ext/string/inflections' # camelize/constantize
+
+require_relative 'rails/transactions'
+require_relative 'rails/proxy_validator'
+require_relative 'rails/after_commit'
+
+# Wire the adapter into the core: the transactional and after_commit macros
+# onto Action, and their behavior onto the Runner. RunnerAfterCommit is
+# prepended last so it wraps RunnerTransaction: a run registers its
+# after_commit hooks only once its own transaction is over.
+Actionable::Action.extend(Actionable::Rails::Transactions)
+Actionable::Action.singleton_class.prepend(Actionable::Rails::AfterCommit)
+Actionable::Runner.prepend(Actionable::Rails::RunnerTransaction)
+Actionable::Runner.prepend(Actionable::Rails::RunnerAfterCommit)
+
+require_relative 'railtie' if defined?(Rails::Railtie)

data/lib/actionable/railtie.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Actionable
+  # Integrates the optional Rails adapter with the host application's boot
+  # process (decision D8). Loaded by +actionable/rails+ only when running inside
+  # a Rails application; it is the hook point for future Rails-specific wiring
+  # (generators, initializers). The core gem never references Rails.
+  class Railtie < ::Rails::Railtie
+  end
+end