action_figure 0.1.0 → 0.6.0

data/docs/status-codes.md

@@ -0,0 +1,35 @@
+# HTTP 4xx Status Codes
+
+Rows in **bold** are status codes with built-in formatter methods — action classes can return these directly via helpers like `NotFound(errors:)` or `Conflict(errors:)`. All other 4xx codes are handled outside action classes by the perimeter (middleware, router, Rack, or infrastructure).
+
+| Status | Name                             | Category  | Responsibility  | Description / Logic Example                                          |
+|--------|----------------------------------|-----------|-----------------|----------------------------------------------------------------------|
+| 400    | Bad Request                      | Perimeter | Controller/Rack | Malformed syntax or missing top-level structure.                     |
+| 401    | Unauthorized                     | Perimeter | Middleware/Auth  | Authentication failed or missing credentials.                        |
+| **402** | **Payment Required**            | **Domain** | **Action Class** | **Business state: "Subscription overdue" or "Quota exceeded."**     |
+| **403** | **Forbidden**                   | **Domain** | **Action Class** | **Authenticated, but lacks permissions for this specific task.**    |
+| **404** | **Not Found**                   | **Domain** | **Action Class** | **The requested resource ID does not exist in the database.**       |
+| 405    | Method Not Allowed               | Perimeter | Rails Router     | Sending a POST to a GET route.                                       |
+| 406    | Not Acceptable                   | Perimeter | Controller       | Client requested a format (e.g., XML) the server won't provide.     |
+| 407    | Proxy Auth Required              | Perimeter | Infrastructure   | Similar to 401, but for a proxy server.                              |
+| 408    | Request Timeout                  | Perimeter | Server/Nginx     | The client took too long to send the request.                        |
+| **409** | **Conflict**                    | **Domain** | **Action Class** | **Resource already exists, or the state is in conflict.**           |
+| 410    | Gone                             | Domain    | Action Class     | The resource is permanently deleted (not just 404).                  |
+| 411    | Length Required                  | Perimeter | Server/Rack      | The request didn't specify a Content-Length.                         |
+| 412    | Precondition Failed              | Perimeter | Controller/Rack  | If-Match headers don't match (usually for caching).                  |
+| 413    | Payload Too Large                | Perimeter | Server/Nginx     | The request body is bigger than the server allows.                   |
+| 414    | URI Too Long                     | Perimeter | Server/Nginx     | The URL is too long for the server to process.                       |
+| 415    | Unsupported Media Type           | Perimeter | Controller       | Sending text/plain instead of application/json.                      |
+| 416    | Range Not Satisfiable            | Perimeter | Server/Rack      | Invalid Range header (usually for file downloads).                   |
+| 417    | Expectation Failed               | Perimeter | Server           | The server can't meet the Expect header requirements.                |
+| 418    | I'm a teapot                     | Domain    | Action Class     | An IETF April Fools joke (rarely used in production).                |
+| 421    | Misdirected Request              | Perimeter | Infrastructure   | The server can't produce a response for this connection.             |
+| **422** | **Unprocessable Content**       | **Domain** | **Action Class** | **Semantic errors (validation, business rules).**                   |
+| 423    | Locked                           | Domain    | Action Class     | The resource is being accessed by another process.                   |
+| 424    | Failed Dependency                | Domain    | Action Class     | The request failed due to a failure of a previous request.           |
+| 425    | Too Early                        | Perimeter | Server/Rack      | The server is unwilling to process a request that might be replayed. |
+| 426    | Upgrade Required                 | Perimeter | Server/Rack      | The client must switch to a different protocol (e.g., TLS).          |
+| 428    | Precondition Required            | Perimeter | Controller/Rack  | The server requires the request to be conditional.                   |
+| 429    | Too Many Requests                | Perimeter | Rack::Attack     | Infrastructure-level rate limiting (IP-based, etc.).                 |
+| 431    | Request Header Fields Too Large  | Perimeter | Server/Rack      | HTTP headers are too large.                                          |
+| 451    | Unavailable For Legal Reasons    | Domain    | Action Class     | Resource censored/blocked for legal/regional reasons.                |

data/docs/testing.md

@@ -0,0 +1,272 @@
+# Testing
+
+## Overview
+
+ActionFigure actions return plain hashes, making them straightforward to test without controller setup or request scaffolding. You call the action directly, receive a result, and assert against it.
+
+Both Minitest and RSpec helpers are provided. They wrap status checks in expressive, intention-revealing assertions so your tests read clearly.
+
+---
+
+## Minitest
+
+### Setup
+
+Require the helper and include the module in your test class:
+
+```ruby
+require "action_figure/testing/minitest"
+
+class Users::CreateActionTest < Minitest::Test
+  include ActionFigure::Testing::Minitest
+end
+```
+
+### Assertions
+
+| Assertion                             | Expected status          |
+|---------------------------------------|--------------------------|
+| `assert_Ok(result)`                   | `:ok`                    |
+| `assert_Created(result)`              | `:created`               |
+| `assert_Accepted(result)`             | `:accepted`              |
+| `assert_NoContent(result)`            | `:no_content`            |
+| `assert_UnprocessableContent(result)` | `:unprocessable_content` |
+| `assert_NotFound(result)`             | `:not_found`             |
+| `assert_Forbidden(result)`            | `:forbidden`             |
+| `assert_Conflict(result)`             | `:conflict`              |
+| `assert_PaymentRequired(result)`      | `:payment_required`      |
+
+All assertions accept an optional second argument for a custom failure message:
+
+```ruby
+assert_Ok(result, "expected the user to be created successfully")
+```
+
+When a status assertion fails, the default message shows the expected and actual status:
+
+```
+Expected result status to be :ok, but got :unprocessable_content
+```
+
+---
+
+## RSpec
+
+### Setup
+
+Require the helper in your spec support file. No `include` is needed -- the matchers are registered globally:
+
+```ruby
+# spec/spec_helper.rb
+require "action_figure/testing/rspec"
+```
+
+### Matchers
+
+| Matcher                   | Expected status          |
+|---------------------------|--------------------------|
+| `be_Ok`                   | `:ok`                    |
+| `be_Created`              | `:created`               |
+| `be_Accepted`             | `:accepted`              |
+| `be_NoContent`            | `:no_content`            |
+| `be_UnprocessableContent` | `:unprocessable_content` |
+| `be_NotFound`             | `:not_found`             |
+| `be_Forbidden`            | `:forbidden`             |
+| `be_Conflict`             | `:conflict`              |
+| `be_PaymentRequired`      | `:payment_required`      |
+
+Matchers support negation:
+
+```ruby
+expect(result).to be_Ok
+expect(result).not_to be_Forbidden
+```
+
+Failure messages mirror the Minitest style:
+
+```
+expected result status to be :ok, but got :unprocessable_content
+```
+
+---
+
+## Testing Patterns
+
+The examples below use Minitest, but the same patterns apply to RSpec with the corresponding matchers.
+
+The examples below use the JSend formatter (`ActionFigure[:jsend]`) for consistency. The structure of `result[:json]` depends on your chosen formatter — see [Response Formatters](response-formatters.md) for the shape each format produces.
+
+### Testing a Successful Action
+
+Call your class and assert both the status and the returned data:
+
+```ruby
+class Users::CreateActionTest < Minitest::Test
+  include ActionFigure::Testing::Minitest
+
+  def test_creates_a_user
+    result = Users::CreateAction.create(params: { email: "jane@example.com", name: "Jane" })
+
+    assert_Ok(result)
+    assert_equal "jane@example.com", result[:json][:data][:email]
+    assert_equal "Jane", result[:json][:data][:name]
+  end
+end
+```
+
+### Testing Validation Failure
+
+When testing validation failures, assert both the status and the error message content. Testing only the status is insufficient -- it does not prove the correct validation failed.
+
+```ruby
+class Users::CreateActionTest < Minitest::Test
+  include ActionFigure::Testing::Minitest
+
+  def test_rejects_missing_email
+    result = Users::CreateAction.create(params: { name: "Jane" })
+
+    assert_UnprocessableContent(result)
+    assert_includes result[:json][:data][:email], "is missing"
+  end
+end
+```
+
+### Testing with Context Injection
+
+Actions often receive context such as `current_user:` as keyword arguments alongside `params:`. Pass them directly in the test:
+
+```ruby
+class Posts::CreateActionTest < Minitest::Test
+  include ActionFigure::Testing::Minitest
+
+  def test_creates_a_post_for_the_current_user
+    user = users(:jane)
+    result = Posts::CreateAction.create(params: { title: "Hello", body: "World" }, current_user: user)
+
+    assert_Created(result)
+    assert_equal user.id, result[:json][:data][:author_id]
+  end
+end
+```
+
+### Testing an Action with a Named Method
+
+Call the action using its discovered method name:
+
+```ruby
+class Products::SearchActionTest < Minitest::Test
+  include ActionFigure::Testing::Minitest
+
+  # class SearchAction
+  #   include ActionFigure[:jsend]
+  #
+  #   params_schema do
+  #     required(:query).filled(:string)
+  #   end
+  #
+  #   def search(params:, **)
+  #     products = Product.where("name ILIKE ?", "%#{params[:query]}%")
+  #     Ok(resource: products)
+  #   end
+  # end
+  def test_finds_matching_products
+    result = SearchAction.search(params: { query: "keyboard" })
+
+    assert_Ok(result)
+    assert result[:json][:data].any?, "expected at least one matching product"
+  end
+end
+```
+
+### Testing NoContent
+
+Actions that perform side effects without returning data use `NoContent()`:
+
+```ruby
+class Sessions::DestroyActionTest < Minitest::Test
+  include ActionFigure::Testing::Minitest
+
+  # class Sessions::DestroyAction
+  #   include ActionFigure[:jsend]
+  #
+  #   def destroy(session:)
+  #     session.destroy!
+  #     NoContent()
+  #   end
+  # end
+  def test_destroys_the_session
+    session = sessions(:active)
+    result = Sessions::DestroyAction.destroy(session: session)
+
+    assert_NoContent(result)
+  end
+end
+```
+
+---
+
+## Standalone Validation with `.contract`
+
+Every action that defines a `params_schema` exposes the underlying validation contract via `.contract`. This returns a `Dry::Validation::Contract` instance that you can call directly -- useful for validating input without executing the action.
+
+```ruby
+contract = Users::CreateAction.contract
+result = contract.call(email: "jane@example.com", name: "Jane")
+
+result.success?    # => true
+result.to_h        # => { email: "jane@example.com", name: "Jane" }
+```
+
+When validation fails, inspect the errors:
+
+```ruby
+result = Users::CreateAction.contract.call(email: "", name: "Jane")
+
+result.failure?      # => true
+result.errors.to_h   # => { email: ["must be filled"] }
+```
+
+This runs both the schema and any `rules` defined on the action -- the same validation pipeline that the class-level trigger uses, without the side effects.
+
+Actions that do not define a `params_schema` return `nil` from `.contract`.
+
+### Inspecting schema and rules
+
+The contract exposes the schema and rules for introspection:
+
+```ruby
+contract = Users::CreateAction.contract
+
+contract.schema                        # => the Dry::Schema::Params instance
+contract.schema.key_map.map(&:name)    # => ["email", "name"]
+
+contract.rules                         # => array of Dry::Validation::Rule objects
+contract.rules.map(&:keys)            # => [[:email]]
+```
+
+This is useful for building documentation generators, admin panels, or debugging which validations an action enforces.
+
+### When to use `.contract` directly
+
+- **Form validation endpoints** -- validate input and return errors without creating or modifying resources.
+- **Testing validation rules in isolation** -- assert that specific inputs produce specific errors without needing to stub dependencies that `#call` would use.
+- **REPL exploration** -- inspect what an action expects by calling its contract interactively.
+
+```ruby
+class Users::CreateActionTest < Minitest::Test
+  def test_email_is_required
+    result = Users::CreateAction.contract.call(name: "Jane")
+
+    assert result.failure?
+    assert_includes result.errors.to_h[:email], "is missing"
+  end
+end
+```
+
+---
+
+## Conventions
+
+- **Assert fully** -- for validation and rule failures, assert both the HTTP status and the error message. Testing only the status does not prove the correct validation failed.
+- **Named locals, not subject** -- use a descriptive local variable (`result`, `action`) in each test instead of a shared `subject` helper method.
+- **Use return values for assertions** -- assert on what `Ok(resource: ...)` returns rather than capturing outer variables with closures.

data/docs/validation.md

@@ -0,0 +1,294 @@
+# Validation
+
+## Overview
+
+ActionFigure provides a two-layer validation pipeline powered by [dry-validation](https://dry-rb.org/gems/dry-validation/). The pipeline runs **before** your `#call` method, so if validation fails, your operation logic is never executed. The caller receives an `UnprocessableContent` result containing structured errors.
+
+The two layers are:
+
+1. **`params_schema`** -- structural validation and type coercion (powered by dry-schema)
+2. **`rules`** -- validation rules that run only after the schema passes
+
+If no `params_schema` is defined, `params:` passes through to your `#call` method as-is — no validation, no coercion, no stripping of extra keys. This lets you rely on upstream validation (e.g., Rack middleware like `committee`) while still using ActionFigure for orchestration and response formatting.
+
+---
+
+## params_schema
+
+`params_schema` accepts a block written in the [dry-schema](https://dry-rb.org/gems/dry-schema/) DSL. It defines the shape of your input: which keys are allowed, which are required, and what types they must be.
+
+```ruby
+class Users::CreateAction
+  include ActionFigure[:jsend]
+
+  params_schema do
+    required(:email).filled(:string)
+    required(:name).filled(:string)
+    optional(:age).filled(:integer)
+    optional(:newsletter).filled(:bool)
+  end
+
+  def call(params:, **)
+    user = User.create(params)
+    return UnprocessableContent(errors: user.errors.messages) if user.errors.any?
+
+    resource = UserBlueprint.render_as_hash(user)
+    Ok(resource:)
+  end
+end
+```
+
+### required vs optional
+
+- `required(:field)` -- the key **must** be present in the input. If missing, validation fails before rules ever run.
+- `optional(:field)` -- the key may be omitted. If present, it still must satisfy the declared type and predicates.
+
+### Type coercion
+
+Because ActionFigure uses a **params** schema (not a plain schema), dry-schema automatically coerces string values into their declared types. This is essential for web requests where everything arrives as a string.
+
+```ruby
+params_schema do
+  required(:quantity).filled(:integer)
+  required(:price).filled(:float)
+  required(:active).filled(:bool)
+end
+
+# Input:  { quantity: "25", price: "9.99", active: "true" }
+# Output: { quantity: 25,   price: 9.99,   active: true }
+```
+
+Common coercible types: `:string`, `:integer`, `:float`, `:decimal`, `:bool`, `:date`, `:time`, `:date_time`.
+
+---
+
+## rules
+
+`rules` run **after** the schema passes, giving you access to fully validated and coerced values. Use `rules` for constraints that span multiple fields or require context that the schema DSL cannot express (e.g., database lookups). ActionFigure includes several cross-parameter helpers (documented below) to simplify common multi-field rules.
+
+```ruby
+class Users::CreateAction
+  include ActionFigure[:jsend]
+
+  params_schema do
+    required(:email).filled(:string)
+    required(:name).filled(:string)
+  end
+
+  rules do
+    rule(:email) do
+      if values[:email] && User.exists?(email: values[:email])
+        key.failure("is already taken")
+      end
+    end
+  end
+
+  def call(params:, **)
+    user = User.create(params)
+    return UnprocessableContent(errors: user.errors.messages) if user.errors.any?
+
+    Ok(resource: user)
+  end
+end
+```
+
+### Key details
+
+- `rules` **must** be declared after `params_schema`. Declaring it without a schema raises:
+
+  ```
+  ArgumentError: rules requires params_schema to be defined
+  ```
+
+- Inside a rule block, access validated values with `values[:field]`.
+- Add an error to a specific field with `key(:field).failure("message")`, or `key.failure("message")` when the rule is scoped to a single field via `rule(:field)`.
+- Multiple rules can target the same field. All rules run even if earlier ones fail -- errors accumulate.
+
+---
+
+## Cross-Param Rule Helpers
+
+ActionFigure ships four helpers for common multi-field constraints. They are available inside `rules` blocks and save you from writing the same boilerplate patterns repeatedly.
+
+All helpers share a consistent definition of **"present"**: a field is considered present when its key exists in the validated values **and** its value is not `nil`. Notably, `false` counts as present -- only `nil` (or a missing key) counts as absent.
+
+### exclusive_rule
+
+At most one of the listed fields may be present. If multiple are present, each **present** field receives the error message.
+
+```ruby
+class Orders::SearchAction
+  include ActionFigure[:jsend]
+  params_schema do
+    optional(:order_id).filled(:string)
+    optional(:tracking_number).filled(:string)
+    optional(:customer_email).filled(:string)
+  end
+
+  rules do
+    exclusive_rule(:order_id, :tracking_number, :customer_email,
+                   "provide only one search criterion")
+  end
+
+  def call(params:, **)
+    # exactly zero or one search key is guaranteed here
+  end
+end
+```
+
+Given `{ order_id: "123", tracking_number: "TRK-456" }`, both `order_id` and `tracking_number` receive the error. Passing zero fields is fine -- use `any_rule` if you need at least one.
+
+### any_rule
+
+At least one of the listed fields must be present. If none are present, **every** listed field receives the error message.
+
+```ruby
+class Orders::SearchAction
+  include ActionFigure[:jsend]
+  params_schema do
+    optional(:order_id).filled(:string)
+    optional(:tracking_number).filled(:string)
+    optional(:customer_email).filled(:string)
+  end
+
+  rules do
+    any_rule(:order_id, :tracking_number, :customer_email,
+             "at least one search criterion is required")
+  end
+
+  def call(params:, **)
+    # guaranteed at least one search field is present
+  end
+end
+```
+
+Given `{}`, all three fields receive the error. Given `{ order_id: "123", tracking_number: "TRK-456" }`, validation passes -- multiple present fields are fine.
+
+### one_rule
+
+Exactly one of the listed fields must be present. If zero or more than one are present, **every** listed field receives the error message.
+
+```ruby
+class Payments::CreateAction
+  include ActionFigure[:jsend]
+  params_schema do
+    required(:amount).filled(:integer)
+    optional(:credit_card_token).filled(:string)
+    optional(:bank_account_id).filled(:string)
+    optional(:wallet_id).filled(:string)
+  end
+
+  rules do
+    one_rule(:credit_card_token, :bank_account_id, :wallet_id,
+             "exactly one payment method is required")
+  end
+
+  def call(params:, **)
+    # exactly one payment method is guaranteed
+  end
+end
+```
+
+Given `{ amount: 5000, credit_card_token: "tok_123", wallet_id: "wal_456" }`, all three payment method fields receive the error. Given `{ amount: 5000 }` with no payment method, all three also receive the error.
+
+### all_rule
+
+All listed fields must be present together, or all must be absent. A partial set causes **every** listed field to receive the error message.
+
+```ruby
+class Users::CreateAction
+  include ActionFigure[:jsend]
+
+  params_schema do
+    required(:name).filled(:string)
+    optional(:street).filled(:string)
+    optional(:city).filled(:string)
+    optional(:zip).filled(:string)
+  end
+
+  rules do
+    all_rule(:street, :city, :zip,
+             "address fields must be provided together or not at all")
+  end
+
+  def call(params:, **)
+    # address is either complete or entirely absent
+  end
+end
+```
+
+Given `{ name: "Jane", street: "123 Main St" }`, all three address fields receive the error because only one of three is present. Given `{ name: "Jane" }` (none present) or `{ name: "Jane", street: "123 Main St", city: "Portland", zip: "97201" }` (all present), validation passes.
+
+---
+
+## Extra Parameter Handling
+
+By default, dry-validation silently strips any keys that are not declared in the schema. Your `#call` method only ever sees the declared fields:
+
+```ruby
+class Users::CreateAction
+  include ActionFigure[:jsend]
+
+  params_schema do
+    required(:email).filled(:string)
+  end
+
+  def call(params:, **)
+    params #=> { email: "jane@example.com" }
+    # :admin was silently removed
+  end
+end
+
+# Called with: { email: "jane@example.com", admin: true }
+```
+
+### whiny_extra_params
+
+If you prefer to reject unexpected parameters outright, enable the `whiny_extra_params` configuration option:
+
+```ruby
+ActionFigure.configure do |config|
+  config.whiny_extra_params = true
+end
+```
+
+With this enabled, passing undeclared parameters returns an `UnprocessableContent` result with a 422 status. The error shape is consistent with all other validation errors:
+
+```ruby
+# Called with: { email: "jane@example.com", admin: true, role: "superuser" }
+
+# Result errors:
+{
+  admin: ["is not allowed"],
+  role: ["is not allowed"]
+}
+```
+
+Each extra key receives its own `"is not allowed"` error message. This check runs **after** schema validation succeeds, so you will see schema errors or extra-param errors, never both at the same time.
+
+---
+
+## ActionController::Parameters
+
+In Rails controllers, form data arrives as `ActionController::Parameters` rather than a plain `Hash`. ActionFigure handles this automatically: when it detects an object that responds to `to_unsafe_h`, it calls that method to convert it to a regular hash before validation.
+
+This means you can pass `params` from a controller directly without calling `permit`, `require`, or `to_h` yourself -- the action's `params_schema` handles all of that:
+
+```ruby
+class UsersController < ApplicationController
+  def create
+    render Users::CreateAction.call(
+      params:,
+      current_user: current_user
+    )
+  end
+end
+```
+
+Plain hashes work identically -- ActionFigure only calls `to_unsafe_h` when the method is available. This makes actions easy to test without constructing `ActionController::Parameters` objects:
+
+```ruby
+result = Users::CreateAction.call(
+  params: { user: { email: "jane@example.com", name: "Jane" } }
+)
+```

data/lib/action_figure/configuration.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module ActionFigure
+  # Provides global configuration for ActionFigure via ActionFigure.configure.
+  module Configuration
+    # Holds ActionFigure configuration values.
+    class Settings
+      attr_accessor :format, :whiny_extra_params, :api_version, :activesupport_notifications
+
+      def initialize
+        @format = :default
+        @whiny_extra_params = false
+        @activesupport_notifications = false
+      end
+
+      def configure
+        yield self
+      end
+
+      def register(**formatters)
+        ActionFigure.register_formatter(**formatters)
+      end
+    end
+
+    def configure(&)
+      configuration.configure(&)
+    end
+
+    def configuration
+      @configuration ||= Settings.new
+    end
+  end
+end