action_figure 0.1.0 → 0.6.0

data/docs/actions.md

@@ -0,0 +1,495 @@
+# Actions
+
+## Overview
+
+An ActionFigure action class is a single-purpose operation. Each class encapsulates one thing your application does -- creating a user, searching orders, processing a refund. This guide covers how to declare action classes, customize their entry points, inject dependencies, and wire them into your controllers.
+
+---
+
+## Naming Your Action Method
+
+ActionFigure auto-discovers your action method by name. Define one public instance method on your action class and ActionFigure registers it as the entry point -- no macro required:
+
+```ruby
+class Users::CreateAction
+  include ActionFigure[:jsend]
+
+  params_schema do
+    required(:user).hash do
+      required(:email).filled(:string)
+      required(:name).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
+```
+
+Wire it into a controller using the discovered method name:
+
+```ruby
+class UsersController < ApplicationController
+  def create
+    render Users::CreateAction.create(params:, company: current_company)
+  end
+end
+```
+
+### How it works
+
+ActionFigure uses a `method_added` hook to watch for public instance methods defined on the class. The first public method defined becomes the registered entry point and a matching class-level method is created for it. The full validation pipeline (`params_schema` and `rules`) still runs through the discovered entry point before your method is invoked.
+
+### Disambiguation with `entry_point`
+
+If a class ends up with more than one public instance method, ActionFigure cannot determine which one to use and raises an `IndeterminantEntryPointError`:
+
+```
+ActionFigure::IndeterminantEntryPointError: Multiple public methods defined in Orders::SearchAction:
+:search and :format_results. Either make one private or declare
+`entry_point :search` to disambiguate.
+```
+
+Use the `entry_point` macro to resolve this:
+
+```ruby
+class Orders::SearchAction
+  include ActionFigure[:jsend]
+
+  entry_point :search
+
+  params_schema do
+    optional(:order_id).filled(:string)
+    optional(:tracking_number).filled(:string)
+    optional(:status).filled(:string)
+  end
+
+  def search(params:, company:)
+    orders = company.orders
+    orders = orders.where(id: params[:order_id]) if params[:order_id]
+    orders = orders.where(tracking_number: params[:tracking_number]) if params[:tracking_number]
+    orders = orders.where(status: params[:status]) if params[:status]
+    resource = orders.as_json(only: %i[id tracking_number status])
+    Ok(resource:)
+  end
+
+  private
+
+  def build_scope(company)
+    company.orders.active
+  end
+end
+```
+
+Only one entry point per class is allowed. A second `entry_point` declaration raises an `ArgumentError`:
+
+```
+ArgumentError: entry_point already defined as 'search' — each action class may declare only one entry point
+```
+
+---
+
+## Actions Without a Schema
+
+Actions that omit `params_schema` skip the validation pipeline entirely. Any `params:` passed through are delivered to your method as-is — no coercion, no stripping, no validation.
+
+This is useful when validation is handled upstream (e.g., Rack middleware like `committee` validating against an OpenAPI spec) or when the action simply doesn't need params:
+
+```ruby
+class HealthCheckAction
+  include ActionFigure[:jsend]
+
+  def check
+    Ok(resource: { status: "healthy", time: Time.current })
+  end
+end
+```
+
+```ruby
+class HealthController < ApplicationController
+  def show
+    render HealthCheckAction.check
+  end
+end
+```
+
+---
+
+## Context Injection
+
+Non-`params:` keyword arguments pass through to the instance method untouched. This is how you inject context from the controller -- the current user, the tenant, a logger, or any other collaborator -- without any special DSL.
+
+```ruby
+class Users::CreateAction
+  include ActionFigure[:jsend]
+
+  params_schema do
+    required(:user).hash do
+      required(:email).filled(:string)
+      required(:name).filled(:string)
+    end
+  end
+
+  def create(params:, company:, current_user:)
+    user = company.users.create(params[:user].merge(invited_by: current_user))
+    return UnprocessableContent(errors: user.errors.messages) if user.errors.any?
+
+    Created(resource: user.as_json(only: %i[id name email]))
+  end
+end
+```
+
+```ruby
+class UsersController < ApplicationController
+  def create
+    render Users::CreateAction.create(
+      params:,
+      company: current_company,
+      current_user: current_user
+    )
+  end
+end
+```
+
+---
+
+## CRUD Examples
+
+### Index
+
+A simple index action needs no params and no schema:
+
+```ruby
+class Users::IndexAction
+  include ActionFigure[:jsend]
+
+  def index(company:)
+    users = company.users.order(:name)
+    Ok(resource: users.as_json(only: %i[id name email]))
+  end
+end
+```
+
+```ruby
+class UsersController < ApplicationController
+  def index
+    render Users::IndexAction.index(company: current_company)
+  end
+end
+```
+
+### Show
+
+```ruby
+class Users::ShowAction
+  include ActionFigure[:jsend]
+
+  params_schema do
+    required(:id).filled(:integer)
+  end
+
+  def show(params:, company:)
+    user = company.users.find_by(id: params[:id])
+    return NotFound(errors: { base: ["user not found"] }) unless user
+
+    Ok(resource: user.as_json(only: %i[id name email]))
+  end
+end
+```
+
+```ruby
+class UsersController < ApplicationController
+  def show
+    render Users::ShowAction.show(params:, company: current_company)
+  end
+end
+```
+
+### Create
+
+```ruby
+class Users::CreateAction
+  include ActionFigure[:jsend]
+
+  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) unless user.persisted?
+
+    Created(resource: user.as_json(only: %i[id name email]))
+  end
+end
+```
+
+```ruby
+class UsersController < ApplicationController
+  def create
+    render Users::CreateAction.create(params:, company: current_company)
+  end
+end
+```
+
+### Update
+
+```ruby
+class Users::UpdateAction
+  include ActionFigure[:jsend]
+
+  params_schema do
+    required(:id).filled(:integer)
+    required(:user).hash do
+      optional(:name).filled(:string)
+      optional(:email).filled(:string)
+    end
+  end
+
+  def update(params:, company:)
+    user = company.users.find_by(id: params[:id])
+    return NotFound(errors: { base: ["user not found"] }) unless user
+
+    user.update(params[:user])
+    return UnprocessableContent(errors: user.errors.messages) unless user.errors.empty?
+
+    Ok(resource: user.as_json(only: %i[id name email]))
+  end
+end
+```
+
+```ruby
+class UsersController < ApplicationController
+  def update
+    render Users::UpdateAction.update(params:, company: current_company)
+  end
+end
+```
+
+### Destroy
+
+```ruby
+class Users::DestroyAction
+  include ActionFigure[:jsend]
+
+  params_schema do
+    required(:id).filled(:integer)
+  end
+
+  def destroy(params:, company:)
+    user = company.users.find_by(id: params[:id])
+    return NotFound(errors: { base: ["user not found"] }) unless user
+
+    user.destroy!
+    NoContent()
+  end
+end
+```
+
+```ruby
+class UsersController < ApplicationController
+  def destroy
+    render Users::DestroyAction.destroy(params:, company: current_company)
+  end
+end
+```
+
+For authorization, serialization, and pagination patterns, see [Integration Patterns](integration-patterns.md).
+
+---
+
+## Other Examples
+
+Actions aren't limited to CRUD. The pattern works anywhere you need to validate input, orchestrate work, and return a formatted response. In each case the action delegates to a service object and translates the result:
+
+```ruby
+class Users::BulkInviteAction
+  include ActionFigure[:jsend]
+
+  params_schema do
+    required(:emails).value(:array, min_size?: 1).each(:str?)
+  end
+
+  def invite(params:, company:)
+    result = BulkInviteService.call(emails: params[:emails], company: company)
+    return UnprocessableContent(errors: result.errors) if result.failures?
+
+    Created(resource: result.invitations)
+  end
+end
+```
+
+```ruby
+class Users::InvitesController < ApplicationController
+  def create
+    render Users::BulkInviteAction.invite(params:, company: current_company)
+  end
+end
+```
+
+Use `Accepted` when the real work happens asynchronously:
+
+```ruby
+class Reports::GenerateAction
+  include ActionFigure[:jsend]
+
+  params_schema do
+    required(:report).hash do
+      required(:type).filled(:string)
+      optional(:start_date).filled(:date)
+      optional(:end_date).filled(:date)
+    end
+  end
+
+  def generate(params:, current_user:)
+    result = ReportService.enqueue(params: params[:report], requested_by: current_user)
+    return UnprocessableContent(errors: result.errors) if result.failed?
+
+    Accepted(resource: { id: result.report_id, status: "queued" })
+  end
+end
+```
+
+```ruby
+class ReportsController < ApplicationController
+  def create
+    render Reports::GenerateAction.generate(params:, current_user: current_user)
+  end
+end
+```
+
+File imports work the same way — receive the file, hand it off, translate the outcome:
+
+```ruby
+class Products::ImportAction
+  include ActionFigure[:jsend]
+
+  def import(file:, company:)
+    result = ProductImportService.call(file: file, company: company)
+    return UnprocessableContent(errors: result.errors) if result.failed?
+
+    Ok(resource: { imported: result.imported_count, skipped: result.skipped_count })
+  end
+end
+```
+
+```ruby
+class Products::ImportsController < ApplicationController
+  def create
+    render Products::ImportAction.import(file: params[:file], company: current_company)
+  end
+end
+```
+
+---
+
+## API Versioning
+
+The `api_version` class macro attaches version metadata to an action class.
+
+```ruby
+class Users::CreateAction
+  include ActionFigure[:jsend]
+
+  api_version "2.0"
+
+  params_schema do
+    required(:user).hash do
+      required(:email).filled(:string)
+      required(:name).filled(:string)
+    end
+  end
+
+  def create(params:)
+    user = User.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
+```
+
+### Reading the version
+
+Call `api_version` with no arguments to read the stored value:
+
+```ruby
+Users::CreateAction.api_version  #=> "2.0"
+```
+
+Inside an action instance, access it through the class:
+
+```ruby
+def create(params:, **)
+  if self.class.api_version == "2.0"
+    # v2 behavior
+  end
+end
+```
+
+### Defaults
+
+If no `api_version` is declared on a class, it returns `nil` by default. A global version is available through configuration:
+
+```ruby
+ActionFigure.configure do |config|
+  config.api_version = "1.0"
+end
+```
+
+The global version is accessible via `ActionFigure.configuration.api_version` but is not used as an automatic fallback for class-level `api_version`. Version values are independent per class -- they are not inherited by subclasses because version state is stored in class-level instance variables.
+
+---
+
+## File Conventions
+
+Name action classes `ResourceName::VerbAction`. There are two common ways to organize them:
+
+**Standalone directory** — action classes live in `app/actions/`:
+
+```
+app/actions/
+  users/
+    create_action.rb
+    destroy_action.rb
+    index_action.rb
+    show_action.rb
+    update_action.rb
+  orders/
+    search_action.rb
+    cancel_action.rb
+```
+
+**Alongside controllers** — action classes live next to the controllers that use them:
+
+```
+app/controllers/
+  users_controller.rb
+  users/
+    create_action.rb
+    destroy_action.rb
+    index_action.rb
+    show_action.rb
+    update_action.rb
+  orders_controller.rb
+  orders/
+    search_action.rb
+    cancel_action.rb
+```
+
+Both work with Rails autoloading. The second option keeps related code together — when you open a controller, its actions are right there.
+
+---
+
+## Design Constraints
+
+Action classes are intentionally flat. The class-level state that powers `params_schema`, `rules`, and `entry_point` is stored in **class-level instance variables** and is **not inherited** by subclasses. If you subclass an action, the child class starts with a blank slate -- no schema, no rules, no custom entry point.
+
+This is by design. Each action class should be a self-contained, independently readable unit. If you find yourself wanting to share behavior across actions, extract shared logic into plain Ruby modules or service objects and compose them explicitly.

data/docs/activesupport-notifications.md

@@ -0,0 +1,113 @@
+# ActiveSupport Notifications
+
+## Overview
+
+ActionFigure can provide notifications in action execution via `ActiveSupport::Notifications`. When enabled, every `.call` (or custom entry point) emits a `process.action_figure` event with the action class name, outcome status, and timing.
+
+Notifications are **off by default** and requires both ActiveSupport and an explicit opt-in.
+
+---
+
+## Enabling ActiveSupport Notifications
+
+```ruby
+ActionFigure.configure do |c|
+  c.activesupport_notifications = true
+end
+```
+
+Because notification is resolved at include-time (when a class calls `include ActionFigure`), this setting must be configured before your action classes are loaded -- typically in an initializer.
+
+---
+
+## Event Name
+
+```
+process.action_figure
+```
+
+---
+
+## Payload
+
+| Key      | Type   | Description |
+|----------|--------|-------------|
+| `action` | String | The action class name, e.g. `"Users::CreateAction"` |
+| `status` | Symbol | The outcome status, e.g. `:ok`, `:created` |
+
+Timing (duration, start, end) is provided automatically by `ActiveSupport::Notifications`.
+
+---
+
+## Subscribing to ActionFigure Events
+
+```ruby
+ActiveSupport::Notifications.subscribe("process.action_figure") do |event|
+  Rails.logger.info(
+    "#{event.payload[:action]} => #{event.payload[:status]} (#{event.duration.round(1)}ms)"
+  )
+end
+```
+
+Output:
+
+```
+Users::CreateAction => :created (12.3ms)
+Orders::SearchAction => :ok (45.7ms)
+Users::CreateAction => :unprocessable_content (1.1ms)
+```
+
+---
+
+## What Gets Instrumented
+
+The event wraps the entire action lifecycle -- validation, the `#call` method, and the formatted response. Both successful and failed outcomes are captured:
+
+- Validation failures (e.g. missing required params) produce events with status `:unprocessable_content`
+- Successful calls produce events with whatever status the action returns (`:ok`, `:created`, etc.)
+- Custom entry points (declared with `entry_point`) are instrumented identically to `.call`
+
+---
+
+## Examples
+
+### Logging slow actions
+
+```ruby
+ActiveSupport::Notifications.subscribe("process.action_figure") do |event|
+  if event.duration > 500
+    Rails.logger.warn("[SLOW] #{event.payload[:action]} took #{event.duration.round}ms")
+  end
+end
+```
+
+### Tracking metrics
+
+```ruby
+ActiveSupport::Notifications.subscribe("process.action_figure") do |event|
+  StatsD.distribution(
+    "action_figure.duration",
+    event.duration,
+    tags: {
+      action: event.payload[:action],
+      status: event.payload[:status]
+    }
+  )
+end
+```
+
+### Counting failures
+
+```ruby
+ActiveSupport::Notifications.subscribe("process.action_figure") do |event|
+  unless event.payload[:status] == :ok || event.payload[:status] == :created
+    ErrorTracker.increment("action_figure.failure", action: event.payload[:action])
+  end
+end
+```
+
+---
+
+## How It Works
+
+Notification setup is resolved at include-time, not on every call. When a class includes an ActionFigure module (e.g. `include ActionFigure[:jsend]`), the `included` hook checks whether `ActiveSupport::Notifications` is defined and `activesupport_notifications` is enabled in the configuration. If both conditions are met, it extends the class with `ActionFigure::Core::Notifications`, which overrides the base `notify` method to wrap execution in an `ActiveSupport::Notifications.instrument` block. Otherwise, the base method passes through directly with zero overhead.

data/docs/configuration.md

@@ -0,0 +1,88 @@
+# Configuration
+
+## Overview
+
+ActionFigure exposes global defaults through `ActionFigure.configure`. Every setting can be overridden on a per-class basis, so the global configuration acts as a baseline for your application.
+
+## Configuration Block
+
+```ruby
+ActionFigure.configure do |c|
+  c.format = :jsend
+  c.whiny_extra_params = true
+end
+```
+
+The block yields an `ActionFigure::Configuration::Settings` instance. Call any combination of setters inside.
+
+## Settings Reference
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `format` | Symbol | `:default` | Default formatter name. Applies to any class that uses bare `include ActionFigure`. |
+| `whiny_extra_params` | Boolean | `false` | When `true`, returns an error response for undeclared params instead of silently stripping them. |
+| `activesupport_notifications` | Boolean | `false` | When `true`, enables `ActiveSupport::Notifications` events for action classes defined after the change. Requires ActiveSupport. |
+| `api_version` | String or nil | `nil` | Global API version tag, readable via `ActionFigure.configuration.api_version`. |
+
+## Registering Formatters via Config
+
+You can register custom formatters inside the configure block with `register`:
+
+```ruby
+ActionFigure.configure do |c|
+  c.register(custom_format: MyApp::CustomApiFormatter)
+end
+```
+
+This delegates to `ActionFigure.register_formatter`, making the `:custom_format` format available application-wide. Once registered, set it as the default or use it per-class:
+
+```ruby
+c.format = :custom_format
+```
+
+## Per-Class Overrides
+
+**Format** -- Pass the desired format when including the module:
+
+```ruby
+class Orders::CreateAction
+  include ActionFigure[:jsonapi]
+end
+```
+
+This overrides the global `format` for that single class, regardless of what `ActionFigure.configure` specifies.
+
+**API version** -- Declare a version inside the class body:
+
+```ruby
+class Orders::CreateAction
+  include ActionFigure
+
+  api_version "2.0"
+end
+```
+
+This sets the API version for that class. Class-level versions are independent of the global `api_version` setting.
+
+## Rails Initializer Example
+
+An example `config/initializers/action_figure.rb`:
+
+```ruby
+ActionFigure.configure do |c|
+  # Reject unexpected params with an error response (recommended for development)
+  c.whiny_extra_params = Rails.env.local?
+
+  # Tag all actions with the current API version
+  c.api_version = "1.0"
+
+  # Turn on ActiveSupport::Notifications events for every action call
+  c.activesupport_notifications = true
+
+  # Register a custom formatter
+  c.register(our_format: MyApp::OurFormatter)
+
+  # Use the custom formatter by default
+  c.format = :our_format
+end
+```