action_figure 0.5.0 → 0.6.2

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

@@ -6,13 +6,11 @@ module ActionFigure
       # Simple resource serialization
       class Resource
         def self.serialize(resource)
-          if resource.is_a?(Hash)
-            resource
-          elsif resource.respond_to?(:attributes)
+          if resource.respond_to?(:attributes)
             serialize_one(resource)
-          elsif resource.respond_to?(:each)
+          elsif !resource.is_a?(Hash) && resource.respond_to?(:each)
             resource.map { |r| serialize(r) }
-          else # rubocop:disable Lint/DuplicateBranch
+          else
             resource
           end
         end
@@ -20,7 +18,7 @@ module ActionFigure
         def self.serialize_one(resource)
           {
             type: resource.class.model_name.element,
-            id: resource.id.to_s,
+            id: resource.id&.to_s,
             attributes: resource.attributes.except("id")
           }
         end

data/lib/action_figure/formatters/json_api.rb

@@ -38,17 +38,30 @@ module ActionFigure
         { json: { errors: convert_errors(errors, "403") }, status: :forbidden }
       end
 
+      def Conflict(errors:)
+        { json: { errors: convert_errors(errors, "409") }, status: :conflict }
+      end
+
+      def PaymentRequired(errors:)
+        { json: { errors: convert_errors(errors, "402") }, status: :payment_required }
+      end
+
       private
 
-      def convert_errors(errors, status)
+      def convert_errors(errors, status, prefix = "/data/attributes")
         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 }
-            }
+          pointer = field.to_sym == :base ? "/data" : "#{prefix}/#{field}"
+
+          if messages.is_a?(Hash)
+            convert_errors(messages, status, pointer)
+          else
+            messages.map do |message|
+              {
+                status: status,
+                detail: message,
+                source: { pointer: pointer }
+              }
+            end
           end
         end
       end

data/lib/action_figure/formatters/wrapped.rb

@@ -36,6 +36,14 @@ module ActionFigure
       def Forbidden(errors:)
         { json: { data: nil, errors: errors, status: "error" }, status: :forbidden }
       end
+
+      def Conflict(errors:)
+        { json: { data: nil, errors: errors, status: "error" }, status: :conflict }
+      end
+
+      def PaymentRequired(errors:)
+        { json: { data: nil, errors: errors, status: "error" }, status: :payment_required }
+      end
     end
   end
 end

data/lib/action_figure/testing/minitest.rb

@@ -38,6 +38,14 @@ module ActionFigure
         assert_status(:forbidden, result, msg)
       end
 
+      def assert_Conflict(result, msg = nil)
+        assert_status(:conflict, result, msg)
+      end
+
+      def assert_PaymentRequired(result, msg = nil)
+        assert_status(:payment_required, result, msg)
+      end
+
       private
 
       def assert_status(expected, result, msg)

data/lib/action_figure/testing/rspec.rb

@@ -13,6 +13,7 @@ module ActionFigure
     #   RSpec.describe Users::Create do
     #     it "returns ok" do
     #       expect(Users::Create.call(params: ...)).to be_Ok
+    #       expect(Users::Create.call(params: ...)).to have_action_json(status: "success")
     #     end
     #   end
     module RSpec
@@ -23,7 +24,9 @@ module ActionFigure
         NoContent: :no_content,
         UnprocessableContent: :unprocessable_content,
         NotFound: :not_found,
-        Forbidden: :forbidden
+        Forbidden: :forbidden,
+        Conflict: :conflict,
+        PaymentRequired: :payment_required
       }.freeze
 
       MATCHERS.each do |name, status|
@@ -32,11 +35,38 @@ module ActionFigure
           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}"
+          failure_message_when_negated do
+            "expected result not to have status #{status.inspect}"
           end
         end
       end
+
+      # Asserts against +result[:json]+ using +a_hash_including+ (nested matchers allowed).
+      ::RSpec::Matchers.define :have_action_json do |expected_fragment|
+        include ::RSpec::Matchers
+
+        match do |result|
+          @inner_matcher ||= a_hash_including(expected_fragment)
+          next false unless result.is_a?(Hash) && result.key?(:json)
+
+          @inner_matcher.matches?(result[:json])
+        end
+
+        failure_message do |result|
+          if !result.is_a?(Hash)
+            "expected an ActionFigure result hash, got #{result.inspect}"
+          elsif !result.key?(:json)
+            "expected #{result.inspect} to include key :json (ActionFigure render hash)"
+          else
+            "expected result[:json] to #{@inner_matcher.description}"
+          end
+        end
+
+        failure_message_when_negated do |result|
+          @inner_matcher ||= a_hash_including(expected_fragment)
+          "#{result.inspect} was expected not to match #{@inner_matcher.description}"
+        end
+      end
     end
   end
 end

data/lib/action_figure/version.rb

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

data/lib/action_figure.rb

@@ -9,13 +9,24 @@ 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
 
+  class IndeterminateEntryPointError < StandardError; end
+
+  # Backwards-compatible alias for the misspelled constant shipped through 0.6.0.
+  # Remove in the next minor release after Unreleased.
+  IndeterminantEntryPointError = IndeterminateEntryPointError
+  deprecate_constant :IndeterminantEntryPointError
+
+  # Raised when an action class defines +initialize+. ActionFigure builds instances with
+  # +new+ and passes no constructor arguments; use keyword arguments on the entry method
+  # or class-level state instead of custom initializers.
+  class InitializationNotSupportedError < StandardError; end
+
   register_formatter(jsend: Formatters::Jsend)
   register_formatter(jsonapi: Formatters::JsonApi)
   register_formatter(default: Formatters::Default)

data/sig/action_figure.rbs

@@ -1,4 +1,179 @@
+# Type definitions for the ActionFigure gem
+
+# Response hash returned by formatter methods
+type ActionFigure::response = { json: Hash[Symbol, untyped], status: Symbol } | { status: Symbol }
+
+# Error hash mapping field names to arrays of error messages
+type ActionFigure::error_hash = Hash[Symbol, Array[String]]
+
 module ActionFigure
   VERSION: String
-  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+
+  class IndeterminateEntryPointError < StandardError
+  end
+
+  # Deprecated alias for IndeterminateEntryPointError (misspelled constant from <= 0.6.0).
+  IndeterminantEntryPointError: Class
+
+  class InitializationNotSupportedError < StandardError
+  end
+
+  extend Configuration
+  extend FormatRegistry
+
+  def self.[]: (?Symbol format) -> Module
+  def self.included: (Module base) -> void
+  def self.register_formatter: (**Module formatters) -> void
+  def self.clear_format_module_cache: (Symbol name) -> void
+
+  # Provides global configuration via ActionFigure.configure
+  module Configuration
+    class Settings
+      attr_accessor format: Symbol
+      attr_accessor whiny_extra_params: bool
+      attr_accessor api_version: untyped
+      attr_accessor activesupport_notifications: bool
+
+      def initialize: () -> void
+      def configure: () { (Settings) -> void } -> void
+      def register: (**Module formatters) -> void
+    end
+
+    def configure: () { (Settings) -> void } -> void
+    def configuration: () -> Settings
+  end
+
+  # Provides formatter registration and lookup
+  module FormatRegistry
+    class Formats
+      def initialize: () -> void
+      def register_formatter: (**Module formatters) -> void
+      def fetch: (Symbol name) -> Module
+    end
+
+    def register_formatter: (**Module formatters) -> void
+    def fetch: (Symbol name) -> Module
+  end
+
+  # Base module for response formatters
+  module Formatter
+    REQUIRED_METHODS: Array[Symbol]
+
+    def NoContent: () -> ActionFigure::response
+  end
+
+  # Validation pipeline and DSL mixed into action classes
+  module Core
+    # Cross-parameter rule helpers for dry-validation contracts
+    module CrossParamRuleHelpers
+      def exclusive_rule: (*Symbol fields, String message) -> void
+      def any_rule: (*Symbol fields, String message) -> void
+      def one_rule: (*Symbol fields, String message) -> void
+      def all_rule: (*Symbol fields, String message) -> void
+    end
+
+    # Class-level DSL extended into action classes
+    module ClassMethods
+      def params_schema: () { () -> void } -> void
+      def rules: () { () -> void } -> void
+      def entry_point: (Symbol name) -> void
+      def entry_point_name: () -> Symbol?
+      def api_version: (?untyped value) -> untyped
+      def contract: () -> untyped
+    end
+
+    def entry_point_name: () -> Symbol?
+    def contract: () -> untyped
+    def validated_call: (**untyped kwargs) -> ActionFigure::response
+
+    # ActiveSupport::Notifications instrumentation
+    module Notifications
+      private
+
+      def notify: () { () -> ActionFigure::response } -> ActionFigure::response
+    end
+  end
+
+  module Formatters
+    # Rails-style responses with { data: } envelope
+    module Default
+      include ActionFigure::Formatter
+
+      def Ok: (resource: untyped, ?meta: untyped?) -> ActionFigure::response
+      def Created: (resource: untyped, ?meta: untyped?) -> ActionFigure::response
+      def Accepted: (?resource: untyped?, ?meta: untyped?) -> ActionFigure::response
+      def UnprocessableContent: (errors: ActionFigure::error_hash) -> ActionFigure::response
+      def NotFound: (errors: ActionFigure::error_hash) -> ActionFigure::response
+      def Forbidden: (errors: ActionFigure::error_hash) -> ActionFigure::response
+      def Conflict: (errors: ActionFigure::error_hash) -> ActionFigure::response
+      def PaymentRequired: (errors: ActionFigure::error_hash) -> ActionFigure::response
+    end
+
+    # JSend-formatted responses
+    module Jsend
+      include ActionFigure::Formatter
+
+      def Ok: (resource: untyped, ?meta: untyped?) -> ActionFigure::response
+      def Created: (resource: untyped, ?meta: untyped?) -> ActionFigure::response
+      def Accepted: (?resource: untyped?, ?meta: untyped?) -> ActionFigure::response
+      def UnprocessableContent: (errors: ActionFigure::error_hash) -> ActionFigure::response
+      def NotFound: (errors: ActionFigure::error_hash) -> ActionFigure::response
+      def Forbidden: (errors: ActionFigure::error_hash) -> ActionFigure::response
+      def Conflict: (errors: ActionFigure::error_hash) -> ActionFigure::response
+      def PaymentRequired: (errors: ActionFigure::error_hash) -> ActionFigure::response
+    end
+
+    # JSON:API-formatted responses
+    module JsonApi
+      include ActionFigure::Formatter
+
+      def Ok: (resource: untyped, ?meta: untyped?) -> ActionFigure::response
+      def Created: (resource: untyped, ?meta: untyped?) -> ActionFigure::response
+      def Accepted: (?resource: untyped?, ?meta: untyped?) -> ActionFigure::response
+      def UnprocessableContent: (errors: ActionFigure::error_hash) -> ActionFigure::response
+      def NotFound: (errors: ActionFigure::error_hash) -> ActionFigure::response
+      def Forbidden: (errors: ActionFigure::error_hash) -> ActionFigure::response
+      def Conflict: (errors: ActionFigure::error_hash) -> ActionFigure::response
+      def PaymentRequired: (errors: ActionFigure::error_hash) -> ActionFigure::response
+
+      # Simple resource serialization for JSON:API
+      class Resource
+        def self.serialize: (untyped resource) -> untyped
+      end
+    end
+
+    # Uniform { data:, errors:, status: } envelope
+    module Wrapped
+      include ActionFigure::Formatter
+
+      def Ok: (resource: untyped, ?meta: untyped?) -> ActionFigure::response
+      def Created: (resource: untyped, ?meta: untyped?) -> ActionFigure::response
+      def Accepted: (?resource: untyped?, ?meta: untyped?) -> ActionFigure::response
+      def UnprocessableContent: (errors: ActionFigure::error_hash) -> ActionFigure::response
+      def NotFound: (errors: ActionFigure::error_hash) -> ActionFigure::response
+      def Forbidden: (errors: ActionFigure::error_hash) -> ActionFigure::response
+      def Conflict: (errors: ActionFigure::error_hash) -> ActionFigure::response
+      def PaymentRequired: (errors: ActionFigure::error_hash) -> ActionFigure::response
+    end
+  end
+
+  module Testing
+    # Minitest assertions for action response results
+    module Minitest
+      def assert_Ok: (ActionFigure::response result, ?String? msg) -> void
+      def assert_Created: (ActionFigure::response result, ?String? msg) -> void
+      def assert_Accepted: (ActionFigure::response result, ?String? msg) -> void
+      def assert_NoContent: (ActionFigure::response result, ?String? msg) -> void
+      def assert_UnprocessableContent: (ActionFigure::response result, ?String? msg) -> void
+      def assert_NotFound: (ActionFigure::response result, ?String? msg) -> void
+      def assert_Forbidden: (ActionFigure::response result, ?String? msg) -> void
+      def assert_Conflict: (ActionFigure::response result, ?String? msg) -> void
+      def assert_PaymentRequired: (ActionFigure::response result, ?String? msg) -> void
+    end
+
+    # RSpec custom matchers (be_Ok, be_Created, etc.)
+    module RSpec
+      MATCHERS: Hash[Symbol, Symbol]
+    end
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: action_figure
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.2
 platform: ruby
 authors:
 - Tad Thorley
@@ -9,6 +9,20 @@ bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: concurrent-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: dry-validation
   requirement: !ruby/object:Gem::Requirement
@@ -29,6 +43,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - LICENSE.txt
 - README.md
 - Rakefile
@@ -38,6 +53,7 @@ files:
 - docs/custom-formatters.md
 - docs/integration-patterns.md
 - docs/response-formatters.md
+- docs/status-codes.md
 - docs/testing.md
 - docs/validation.md
 - lib/action_figure.rb
@@ -60,6 +76,7 @@ licenses:
 metadata:
   homepage_uri: https://github.com/phaedryx/action_figure
   source_code_uri: https://github.com/phaedryx/action_figure
+  changelog_uri: https://github.com/phaedryx/action_figure/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
@@ -75,7 +92,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.8
+rubygems_version: 4.0.3
 specification_version: 4
 summary: Fully-articulated controller actions
 test_files: []