action_figure 0.1.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5b25804b8a5e0781e689bfcf6b9cf93c15feb8a2616d33e2fcfe01f59c86a97f
-  data.tar.gz: 0ce167d5c40eedda9d2cb7aaa98e0f7fb063aa56bac5e8da8cfe5d3038e56ff2
+  metadata.gz: 6c29461ca24fe48d0143c6c861a738e37fa04fa9954b0fcc3336f8154dc16a30
+  data.tar.gz: 93e527838e129363aafbba74751660831a54084cb159571fa71f0b9ef11322fc
 SHA512:
-  metadata.gz: d79e820da891b146d1a0de45d1a5460862b39e0013fc44f3393ce40910a7e80187e1a05e60c5e2e24199e9bd52bf940af63fa12beac6830ed0a7d04e5658d8e0
-  data.tar.gz: c4afb1571646c7ac0a7f2e5968604fdeba0809976f2e18dddbc8e102b60fd886e6f12b2a60e4c6af8bceaa5fd71d22dec10dc95f9ee044f67075a93797d23152
+  metadata.gz: 311b1a051ee7caec1aece62143607ed2484720ab6a04398b66f091087a0febccacc91e1478c438bbca98b93d0d13cf57da6f12d8ae3caf47dd8bbb0b642c7994
+  data.tar.gz: 4bd0d145727af9f7373301ad26abc7b65a08041071c07317cf3fb88a818961be09e834de1b857a5256c6012b2965e0aa2bf1da24943cd2219689416d14be5a22

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2026 Tad Thorley
+Copyright (c) 2026 Thomas (Tad) Thorley
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,38 +1,241 @@
 # ActionFigure
 
-TODO: Delete this and the text below, and describe your gem
+Fully-articulated controller actions.
+
+---
+> #### Table of Contents
+> [Installation](#installation)<br>
+> [How It Works](#how-it-works)<br>
+> [Features](#features)<br>
+> [Quick Start](#quick-start)<br>
+> [Design Philosophy](#design-philosophy)<br>
+> [Requirements](#requirements)<br>
+> [License](#license)
+---
+
+**ActionFigure** extracts controller actions into classes that validate params, orchestrate work, and return render-ready responses. Your controller becomes:
+
+```ruby
+class OrdersController < ApplicationController
+  def create
+    render Orders::CreateAction.create(params:, current_user:)
+  end
+end
+```
+
+The action class owns everything that used to be scattered across the controller method, strong params, model callbacks, and ad-hoc response building:
+
+```ruby
+class Orders::CreateAction
+  include ActionFigure[:wrapped]
+
+  params_schema do
+    required(:item_id).filled(:integer)
+    required(:quantity).filled(:integer)
+    optional(:coupon_code).filled(:string)
+    optional(:gift_message).filled(:string)
+    optional(:gift_recipient_email).filled(:string)
+  end
+
+  rules do
+    all_rule(:gift_message, :gift_recipient_email,
+             "gift fields must be provided together or not at all")
+  end
+
+  def create(params:, current_user:)
+    if current_user.unpaid_balance?
+      return Forbidden(errors: { base: ["unpaid balance on account"] })
+    end
+
+    item = Item.find_by(id: params[:item_id])
+    return NotFound(errors: { item_id: ["item not found"] }) unless item
+
+    order = current_user.orders.create(
+      item: item,
+      quantity: params[:quantity],
+      coupon_code: params[:coupon_code]
+    )
+    return UnprocessableContent(errors: order.errors.messages) if order.errors.any?
+
+    resource = OrderBlueprint.render_as_hash(order, view: :confirmation)
+    Created(resource:)
+  end
+end
+```
+
+Param validation, cross-field rules, authorization, error handling, and response formatting — all in one place, all testable without a request:
+
+```ruby
+class Orders::CreateActionTest < Minitest::Test
+  include ActionFigure::Testing::Minitest
+
+  def test_creates_an_order
+    user = User.create!(name: "Tad")
+    item = Item.create!(name: "Widget", price: 29.00)
+
+    result = Orders::CreateAction.create(
+      params: { item_id: item.id, quantity: 2 },
+      current_user: user
+    )
+
+    assert_Created(result)
+    assert_equal item.id, result[:json][:data]["item_id"]
+  end
+
+  def test_forbidden_with_unpaid_balance
+    user = User.create!(name: "Tad", balance: -1)
+
+    result = Orders::CreateAction.create(
+      params: { item_id: 1, quantity: 1 },
+      current_user: user
+    )
+
+    assert_Forbidden(result)
+    assert_includes result[:json][:errors][:base], "unpaid balance on account"
+  end
+
+  def test_not_found_when_item_missing
+    user = User.create!(name: "Tad")
+
+    result = Orders::CreateAction.create(
+      params: { item_id: 999, quantity: 1 },
+      current_user: user
+    )
+
+    assert_NotFound(result)
+    assert_includes result[:json][:errors][:item_id], "item not found"
+  end
+
+  def test_rejects_partial_gift_fields
+    user = User.create!(name: "Tad")
+    item = Item.create!(name: "Widget", price: 29.00)
+
+    result = Orders::CreateAction.create(
+      params: { item_id: item.id, quantity: 1, gift_message: "Enjoy!" },
+      current_user: user
+    )
+
+    assert_UnprocessableContent(result)
+    assert_includes result[:json][:errors][:gift_message],
+                    "gift fields must be provided together or not at all"
+  end
+end
+```
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/action_figure`. To experiment with that code, run `bin/console` for an interactive prompt.
+This isn't for everybody. If your controllers are already thin, or you validate through OpenAPI middleware like [committee](https://github.com/interagent/committee), you probably don't need this. ActionFigure is for teams whose controller actions have grown into tangled mixes of param wrangling, authorization checks, error handling, and response building.
 
 ## Installation
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+Add to your Gemfile and `bundle install`:
 
-Install the gem and add to the application's Gemfile by executing:
+```ruby
+gem "action_figure"
+```
+
+## How It Works
+
+Every action class has three responsibilities:
+
+1. **Check params** (optional) — when a `params_schema` is defined, it validates structure and types; `rules` enforces validation rules. If either fails, the formatter returns an error response and your action method is never invoked. Actions without a schema receive `params:` as-is.
+2. **Orchestrate** — your action method coordinates the work: creating records, calling service objects, enqueuing jobs, or anything else the action requires. The action is the entry point, not necessarily where all the logic lives.
+3. **Return a formatted response** — response helpers like `Created(resource:)` and `NotFound(errors:)` return render-ready hashes that go straight to `render` in your controller.
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| [Validation](docs/validation.md) | Two-layer validation powered by dry-validation: structural schemas with type coercion, plus validation rules. Includes cross-parameter helpers like `exclusive_rule`, `any_rule`, `one_rule`, and `all_rule`. |
+| [Response Formatters](docs/response-formatters.md) | Four built-in formats: Default, JSend, JSON:API, and Wrapped. Each provides response helpers (`Ok`, `Created`, `NotFound`, etc.) that return render-ready hashes. |
+| [Status Codes](docs/status-codes.md) | Which 4xx codes are domain concerns (handled by action classes) vs perimeter concerns (handled by middleware, router, or infrastructure). |
+| [Custom Formatters](docs/custom-formatters.md) | Define your own response envelope by implementing the formatter interface. Registration validates your module at load time. |
+| [Actions](docs/actions.md) | Automatic entry point discovery, context injection via keyword arguments, per-class API versioning, and `entry_point` for disambiguation. |
+| [Configuration](docs/configuration.md) | Global defaults for response format, parameter strictness, and API version. All overridable per-class. |
+| [Notifications](docs/activesupport-notifications.md) | Opt-in `ActiveSupport::Notifications` events for every action call. Emits action class, outcome status, and duration on the `process.action_figure` event. |
+| [Testing](docs/testing.md) | Minitest assertions (`assert_Ok`, `assert_Created`, ...) and RSpec matchers (`be_Ok`, `be_Created`, ...) for expressive status checks. |
+| [Integration Patterns](docs/integration-patterns.md) | Recipes for serializers (Blueprinter, Alba, Oj Serializers), authorization (Pundit, CanCanCan), and pagination (cursor, Pagy). |
+
+## Quick Start
+
+**1. Define the action class.**
+
+```ruby
+# app/actions/users/create_action.rb
+class Users::CreateAction
+  include ActionFigure[:jsend]
 
-```bash
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+  params_schema do
+    required(:user).hash do
+      required(:name).filled(:string)
+      required(:email).filled(:string)
+    end
+  end
+
+  def create(params:, company:)
+    user = company.users.create(params[:user])
+    return UnprocessableContent(errors: user.errors.messages) if user.errors.any?
+
+    Created(resource: user.as_json(only: %i[id name email]))
+  end
+end
 ```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+**2. Call it from your controller.**
 
-```bash
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+```ruby
+class UsersController < ApplicationController
+  def create
+    render Users::CreateAction.create(params:, company: current_company)
+  end
+end
 ```
 
-## Usage
+**3. Test it directly.**
+
+```ruby
+class Users::CreateActionTest < Minitest::Test
+  include ActionFigure::Testing::Minitest
+
+  def test_creates_a_user
+    company = Company.create!(name: "Acme")
+
+    result = Users::CreateAction.create(
+      params: { user: { name: "Tad", email: "tad@example.com" } },
+      company: company
+    )
 
-TODO: Write usage instructions here
+    assert_Created(result)
+    assert_equal "Tad", result[:json][:data]["name"]
+  end
+
+  def test_fails_when_name_is_missing
+    company = Company.create!(name: "Acme")
+
+    result = Users::CreateAction.create(
+      params: { user: { email: "tad@example.com" } },
+      company: company
+    )
+
+    assert_UnprocessableContent(result)
+    assert_includes result[:json][:data][:user][:name], "is missing"
+  end
+end
+```
 
-## Development
+## Design Philosophy
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+Unlike general-purpose service object libraries, ActionFigure is scoped to controller actions — it validates params, runs your logic, and returns a hash you pass directly to `render`.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+- **Purpose over convention** — each class does one thing and names it clearly
+- **Explicit over implicit** — no magic method resolution, no inherited callbacks
+- **Actions own their lifecycle** — validation, execution, and response formatting live together
+- **Controllers become boring** — one-line `render` calls that delegate to action classes
+- **Models and Controllers stay thin** — business logic moves to purpose-built action classes
 
-## Contributing
+## Requirements
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/action_figure.
+- Ruby >= 3.2
+- [dry-validation](https://dry-rb.org/gems/dry-validation/) ~> 1.10 — ActionFigure uses dry-validation for schema validation because it's the best tool for the job. There's no dependency injection container, no monads, no functional pipeline. Just a focused layer for controller actions.
+- Rails is not required, but ActionFigure is designed for Rails controller patterns
 
 ## License