action_figure 0.1.0 → 0.5.0

data/lib/action_figure/core.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+require "dry/validation"
+
+module ActionFigure
+  # Provides the validation pipeline and DSL mixed into action classes via ActionFigure.[].
+  module Core
+    # Extended into dry-validation contract classes to provide cross-param rule helpers.
+    module CrossParamRuleHelpers
+      def exclusive_rule(*fields, message)
+        rule(*fields) do
+          present = fields.select { |f| values.key?(f) && !values[f].nil? }
+          present.each { |f| key(f).failure(message) } if present.size > 1
+        end
+      end
+
+      def any_rule(*fields, message)
+        rule(*fields) do
+          present = fields.select { |f| values.key?(f) && !values[f].nil? }
+          fields.each { |f| key(f).failure(message) } if present.empty?
+        end
+      end
+
+      def one_rule(*fields, message)
+        rule(*fields) do
+          present = fields.select { |f| values.key?(f) && !values[f].nil? }
+          fields.each { |f| key(f).failure(message) } unless present.size == 1
+        end
+      end
+
+      def all_rule(*fields, message)
+        rule(*fields) do
+          present = fields.select { |f| values.key?(f) && !values[f].nil? }
+          fields.each { |f| key(f).failure(message) } unless present.empty? || present.size == fields.size
+        end
+      end
+    end
+
+    # DSL class methods extended into action classes: params_schema, rules, entry_point, call.
+    #
+    # Note: ActionFigure does not support class inheritance. +params_schema+, +rules+, and
+    # +entry_point+ store state in class-level instance variables that are not inherited by
+    # subclasses. Define each action class independently.
+    module ClassMethods
+      def params_schema(&block)
+        @params_schema_block = block
+        @contract = nil
+      end
+
+      def rules(&block)
+        raise ArgumentError, "rules requires params_schema to be defined" unless @params_schema_block
+
+        @rules_block = block
+        @contract = nil
+      end
+
+      # Declares an alternative entry point method name (e.g. +entry_point :search+).
+      # May only be called once per class. Inheritance of action classes is not supported —
+      # +params_schema+, +rules+, and +entry_point+ are not inherited by subclasses.
+      def entry_point(name)
+        if @entry_point_name
+          raise ArgumentError,
+                "entry_point already defined as '#{@entry_point_name}' — " \
+                "each action class may declare only one entry point"
+        end
+
+        @entry_point_name = name
+        singleton_class.define_method(name) do |**kwargs|
+          notify { new.validated_call(**kwargs) }
+        end
+      end
+
+      def entry_point_name
+        @entry_point_name
+      end
+
+      def api_version(value = :_unset)
+        value == :_unset ? @api_version : (@api_version = value)
+      end
+
+      def call(**)
+        if @entry_point_name
+          raise NoMethodError, "undefined method 'call' for #{self} (use '#{@entry_point_name}' instead)"
+        end
+
+        notify { new.validated_call(**) }
+      end
+
+      def contract
+        return nil unless @params_schema_block
+
+        @contract ||= build_contract
+      end
+
+      private
+
+      # no-op when notifications aren't turned on
+      def notify
+        yield
+      end
+
+      def build_contract
+        schema_block = @params_schema_block
+        rules_block = @rules_block
+
+        contract_class = Class.new(Dry::Validation::Contract) do
+          extend ActionFigure::Core::CrossParamRuleHelpers
+
+          params(&schema_block)
+          class_eval(&rules_block) if rules_block
+        end
+
+        contract_class.new
+      end
+    end
+
+    def entry_point_name
+      self.class.entry_point_name || :call
+    end
+
+    def contract
+      self.class.contract
+    end
+
+    def validated_call(**kwargs)
+      raise ArgumentError, "params: passed but no params_schema defined" if kwargs.key?(:params) && !contract
+
+      if kwargs.key?(:params)
+        call_with_params(**kwargs)
+      else
+        call_without_params(**kwargs)
+      end
+    end
+
+    # Overrides ClassMethods#notify with ActiveSupport::Notifications when available.
+    # Extended onto action classes at include-time so the check happens once, not per call.
+    module Notifications
+      private
+
+      def notify
+        payload = { action: name }
+        ActiveSupport::Notifications.instrument("process.action_figure", payload) do
+          result = yield
+          payload[:status] = result[:status]
+          result
+        end
+      end
+    end
+
+    private
+
+    def call_with_params(**kwargs)
+      raw_params = kwargs[:params]
+      raw_params = raw_params.to_unsafe_h if raw_params.respond_to?(:to_unsafe_h)
+
+      result = contract.call(raw_params)
+
+      return UnprocessableContent(errors: result.errors.to_h) if result.failure?
+
+      extra_params_error = check_extra_params(raw_params, result)
+      return extra_params_error if extra_params_error
+
+      public_send(entry_point_name, **kwargs, params: result.to_h)
+    end
+
+    def check_extra_params(raw_params, result)
+      return unless ActionFigure.configuration.whiny_extra_params
+
+      extra_keys = raw_params.keys.map(&:to_sym) - result.to_h.keys
+      return if extra_keys.empty?
+
+      errors = extra_keys.to_h { |k| [k, ["is not allowed"]] }
+      UnprocessableContent(errors: errors)
+    end
+
+    def call_without_params(**)
+      public_send(entry_point_name, **)
+    end
+  end
+end

data/lib/action_figure/format_registry.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module ActionFigure
+  # Provides formatter registration and lookup for ActionFigure.
+  module FormatRegistry
+    # Stores the mapping of format names to formatter modules.
+    class Formats
+      def initialize
+        @formats = {}
+      end
+
+      def register_formatter(**formatters)
+        @formats.merge!(formatters)
+      end
+
+      def fetch(name)
+        @formats.fetch(name) do
+          raise ArgumentError,
+                "Unknown formatter: #{name}. Register it with ActionFigure.register_formatter(#{name}: MyFormatter)."
+        end
+      end
+    end
+
+    def register_formatter(**formatters)
+      format_registry.register_formatter(**formatters)
+    end
+
+    def fetch(name)
+      format_registry.fetch(name)
+    end
+
+    private
+
+    def format_registry
+      @format_registry ||= Formats.new
+    end
+  end
+end

data/lib/action_figure/formatter.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module ActionFigure
+  # Base module for ActionFigure response formatters.
+  # Include this in your formatter module to get a NoContent default
+  # and to signal that your module implements the formatter interface.
+  module Formatter
+    REQUIRED_METHODS = %i[Ok Created Accepted UnprocessableContent NotFound Forbidden].freeze
+
+    def NoContent
+      { status: :no_content }
+    end
+  end
+end

data/lib/action_figure/formatters/default.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module ActionFigure
+  module Formatters
+    # Implements Rails-style response helpers for use in action classes.
+    # Resource is the top-level JSON on success; errors live under an "errors" key on failure.
+    module Default
+      include ActionFigure::Formatter
+
+      def Ok(resource:, meta: nil)
+        body = meta ? { data: resource, meta: meta } : resource
+        { json: body, status: :ok }
+      end
+
+      def Created(resource:, meta: nil)
+        body = meta ? { data: resource, meta: meta } : resource
+        { json: body, status: :created }
+      end
+
+      def Accepted(resource: nil, meta: nil)
+        body = resource.nil? ? {} : resource
+        body = { data: body, meta: meta } if meta
+        { json: body, status: :accepted }
+      end
+
+      def UnprocessableContent(errors:)
+        { json: { errors: errors }, status: :unprocessable_content }
+      end
+
+      def NotFound(errors:)
+        { json: { errors: errors }, status: :not_found }
+      end
+
+      def Forbidden(errors:)
+        { json: { errors: errors }, status: :forbidden }
+      end
+    end
+  end
+end

data/lib/action_figure/formatters/jsend.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module ActionFigure
+  module Formatters
+    # Implements JSend response helpers for use in action classes.
+    module Jsend
+      include ActionFigure::Formatter
+
+      def Ok(resource:, meta: nil)
+        body = { status: "success", data: resource }
+        body[:meta] = meta if meta
+        { json: body, status: :ok }
+      end
+
+      def Created(resource:, meta: nil)
+        body = { status: "success", data: resource }
+        body[:meta] = meta if meta
+        { json: body, status: :created }
+      end
+
+      def Accepted(resource: nil, meta: nil)
+        body = { status: "success" }
+        body[:data] = resource unless resource.nil?
+        body[:meta] = meta if meta
+        { json: body, status: :accepted }
+      end
+
+      def UnprocessableContent(errors:)
+        { json: { status: "fail", data: errors }, status: :unprocessable_content }
+      end
+
+      def NotFound(errors:)
+        { json: { status: "fail", data: errors }, status: :not_found }
+      end
+
+      def Forbidden(errors:)
+        { json: { status: "fail", data: errors }, status: :forbidden }
+      end
+    end
+  end
+end

data/lib/action_figure/formatters/json_api/resource.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module ActionFigure
+  module Formatters
+    module JsonApi
+      # Simple resource serialization
+      class Resource
+        def self.serialize(resource)
+          if resource.is_a?(Hash)
+            resource
+          elsif resource.respond_to?(:attributes)
+            serialize_one(resource)
+          elsif resource.respond_to?(:each)
+            resource.map { |r| serialize(r) }
+          else # rubocop:disable Lint/DuplicateBranch
+            resource
+          end
+        end
+
+        def self.serialize_one(resource)
+          {
+            type: resource.class.model_name.element,
+            id: resource.id.to_s,
+            attributes: resource.attributes.except("id")
+          }
+        end
+
+        private_class_method :serialize_one
+      end
+    end
+  end
+end

data/lib/action_figure/formatters/json_api.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative "json_api/resource"
+
+module ActionFigure
+  module Formatters
+    # Implements JSON:API response helpers for use in action classes.
+    module JsonApi
+      include ActionFigure::Formatter
+
+      def Ok(resource:, meta: nil)
+        body = { data: Resource.serialize(resource) }
+        body[:meta] = meta if meta
+        { json: body, status: :ok }
+      end
+
+      def Created(resource:, meta: nil)
+        body = { data: Resource.serialize(resource) }
+        body[:meta] = meta if meta
+        { json: body, status: :created }
+      end
+
+      def Accepted(resource: nil, meta: nil)
+        body = resource.nil? ? {} : { data: Resource.serialize(resource) }
+        body[:meta] = meta if meta
+        { json: body, status: :accepted }
+      end
+
+      def UnprocessableContent(errors:)
+        { json: { errors: convert_errors(errors, "422") }, status: :unprocessable_content }
+      end
+
+      def NotFound(errors:)
+        { json: { errors: convert_errors(errors, "404") }, status: :not_found }
+      end
+
+      def Forbidden(errors:)
+        { json: { errors: convert_errors(errors, "403") }, status: :forbidden }
+      end
+
+      private
+
+      def convert_errors(errors, status)
+        errors.flat_map do |field, messages|
+          pointer = field.to_sym == :base ? "/data" : "/data/attributes/#{field}"
+          messages.map do |message|
+            {
+              status: status,
+              detail: message,
+              source: { pointer: pointer }
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/action_figure/formatters/wrapped.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module ActionFigure
+  module Formatters
+    # Implements uniform envelope response helpers for use in action classes.
+    # Every response uses the same { data:, errors:, status: } shape.
+    module Wrapped
+      include ActionFigure::Formatter
+
+      def Ok(resource:, meta: nil)
+        body = { data: resource, errors: nil, status: "success" }
+        body[:meta] = meta if meta
+        { json: body, status: :ok }
+      end
+
+      def Created(resource:, meta: nil)
+        body = { data: resource, errors: nil, status: "success" }
+        body[:meta] = meta if meta
+        { json: body, status: :created }
+      end
+
+      def Accepted(resource: nil, meta: nil)
+        body = { data: resource, errors: nil, status: "success" }
+        body[:meta] = meta if meta
+        { json: body, status: :accepted }
+      end
+
+      def UnprocessableContent(errors:)
+        { json: { data: nil, errors: errors, status: "error" }, status: :unprocessable_content }
+      end
+
+      def NotFound(errors:)
+        { json: { data: nil, errors: errors, status: "error" }, status: :not_found }
+      end
+
+      def Forbidden(errors:)
+        { json: { data: nil, errors: errors, status: "error" }, status: :forbidden }
+      end
+    end
+  end
+end

data/lib/action_figure/testing/minitest.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module ActionFigure
+  module Testing
+    # Minitest assertions for ActionFigure response results.
+    #
+    # Include in your test class to get assert_Ok, assert_Created, etc.:
+    #
+    #   class Users::CreateTest < Minitest::Test
+    #     include ActionFigure::Testing::Minitest
+    #   end
+    module Minitest
+      def assert_Ok(result, msg = nil)
+        assert_status(:ok, result, msg)
+      end
+
+      def assert_Created(result, msg = nil)
+        assert_status(:created, result, msg)
+      end
+
+      def assert_Accepted(result, msg = nil)
+        assert_status(:accepted, result, msg)
+      end
+
+      def assert_NoContent(result, msg = nil)
+        assert_status(:no_content, result, msg)
+      end
+
+      def assert_UnprocessableContent(result, msg = nil)
+        assert_status(:unprocessable_content, result, msg)
+      end
+
+      def assert_NotFound(result, msg = nil)
+        assert_status(:not_found, result, msg)
+      end
+
+      def assert_Forbidden(result, msg = nil)
+        assert_status(:forbidden, result, msg)
+      end
+
+      private
+
+      def assert_status(expected, result, msg)
+        actual = result[:status]
+        message = msg || "Expected result status to be #{expected.inspect}, but got #{actual.inspect}"
+        assert actual == expected, message
+      end
+    end
+  end
+end

data/lib/action_figure/testing/rspec.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "rspec/matchers"
+
+module ActionFigure
+  module Testing
+    # RSpec custom matchers for ActionFigure response results.
+    #
+    # Require in your spec_helper.rb to get be_Ok, be_Created, etc.:
+    #
+    #   require 'action_figure/testing/rspec'
+    #
+    #   RSpec.describe Users::Create do
+    #     it "returns ok" do
+    #       expect(Users::Create.call(params: ...)).to be_Ok
+    #     end
+    #   end
+    module RSpec
+      MATCHERS = {
+        Ok: :ok,
+        Created: :created,
+        Accepted: :accepted,
+        NoContent: :no_content,
+        UnprocessableContent: :unprocessable_content,
+        NotFound: :not_found,
+        Forbidden: :forbidden
+      }.freeze
+
+      MATCHERS.each do |name, status|
+        ::RSpec::Matchers.define :"be_#{name}" do
+          match { |result| result[:status] == status }
+          failure_message do |result|
+            "expected result status to be #{status.inspect}, but got #{result[:status].inspect}"
+          end
+          failure_message_when_negated do |_result|
+            "expected result status not to be #{status.inspect}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/action_figure/version.rb

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

data/lib/action_figure.rb

@@ -1,6 +1,73 @@
 # frozen_string_literal: true
 
 require_relative "action_figure/version"
+require_relative "action_figure/configuration"
+require_relative "action_figure/format_registry"
+require_relative "action_figure/formatter"
+require_relative "action_figure/core"
+require_relative "action_figure/formatters/jsend"
+require_relative "action_figure/formatters/json_api"
+require_relative "action_figure/formatters/default"
+require_relative "action_figure/formatters/wrapped"
+require "concurrent/map"
 
+# ActionFigure provides explicit, purpose-driven operation classes for Rails controller actions.
 module ActionFigure
+  extend Configuration
+  extend FormatRegistry
+
+  register_formatter(jsend: Formatters::Jsend)
+  register_formatter(jsonapi: Formatters::JsonApi)
+  register_formatter(default: Formatters::Default)
+  register_formatter(wrapped: Formatters::Wrapped)
+
+  def self.[](format = configuration.format)
+    format_modules.compute_if_absent(format) { build_format_module(format, fetch(format)) }
+  end
+
+  def self.included(base)
+    base.include(self[])
+  end
+
+  def self.register_formatter(**formatters)
+    formatters.each_value do |mod|
+      missing = Formatter::REQUIRED_METHODS.reject { |m| mod.method_defined?(m) }
+      raise ArgumentError, "#{mod} is missing formatter methods: #{missing.join(", ")}" if missing.any?
+    end
+    formatters.each_key { |name| clear_format_module_cache(name) }
+    super
+  end
+
+  def self.clear_format_module_cache(name)
+    format_modules.delete(name)
+  end
+
+  def self.build_format_module(name, formatter)
+    mod = new_format_module(formatter)
+    const_name = :"Format_#{name}"
+    remove_const(const_name) if const_defined?(const_name, false)
+    const_set(const_name, mod)
+  end
+  private_class_method :build_format_module
+
+  def self.new_format_module(formatter)
+    Module.new do
+      def self.included(base)
+        base.extend(ActionFigure::Core::ClassMethods)
+        return unless defined?(ActiveSupport::Notifications) &&
+                      ActionFigure.configuration.activesupport_notifications
+
+        base.extend(ActionFigure::Core::Notifications)
+      end
+
+      include ActionFigure::Core
+      include formatter
+    end
+  end
+  private_class_method :new_format_module
+
+  def self.format_modules
+    @format_modules ||= Concurrent::Map.new
+  end
+  private_class_method :format_modules
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: action_figure
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Tad Thorley
@@ -23,8 +23,8 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.10'
-description: Replaces general service objects with classes specifically for use in
-  Rails controller action methods
+description: Replaces service objects with explicit, purpose-driven classes for Rails
+  controller actions
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -32,7 +32,26 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- docs/actions.md
+- docs/activesupport-notifications.md
+- docs/configuration.md
+- docs/custom-formatters.md
+- docs/integration-patterns.md
+- docs/response-formatters.md
+- docs/testing.md
+- docs/validation.md
 - lib/action_figure.rb
+- lib/action_figure/configuration.rb
+- lib/action_figure/core.rb
+- lib/action_figure/format_registry.rb
+- lib/action_figure/formatter.rb
+- lib/action_figure/formatters/default.rb
+- lib/action_figure/formatters/jsend.rb
+- lib/action_figure/formatters/json_api.rb
+- lib/action_figure/formatters/json_api/resource.rb
+- lib/action_figure/formatters/wrapped.rb
+- lib/action_figure/testing/minitest.rb
+- lib/action_figure/testing/rspec.rb
 - lib/action_figure/version.rb
 - sig/action_figure.rbs
 homepage: https://github.com/phaedryx/action_figure
@@ -41,6 +60,7 @@ licenses:
 metadata:
   homepage_uri: https://github.com/phaedryx/action_figure
   source_code_uri: https://github.com/phaedryx/action_figure
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib
@@ -48,7 +68,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.1.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -57,5 +77,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.8
 specification_version: 4
-summary: Explicit, purpose-driven operation classes for Rails controller actions
+summary: Fully-articulated controller actions
 test_files: []