action_figure 0.1.0 → 0.6.0

data/docs/custom-formatters.md

@@ -0,0 +1,185 @@
+# Custom Formatters
+
+## Overview
+
+Beyond the built-in formats, ActionFigure lets you define your own response format. A formatter is a Ruby module that translates action outcomes (success, creation, validation failure, etc.) into the response shape your API expects. Once registered, a custom formatter works exactly like the built-in ones.
+
+## The Formatter Interface
+
+A formatter is a module that includes `ActionFigure::Formatter` and defines methods for each outcome type.
+
+Including `ActionFigure::Formatter` gives you:
+
+- A default `NoContent` implementation that returns `{ status: :no_content }`.
+- A contract enforced at registration time: your module **must** define all 8 required methods.
+
+The required methods are:
+
+| Method                 | Purpose                                      |
+|------------------------|----------------------------------------------|
+| `Ok`                   | Successful retrieval or generic success      |
+| `Created`              | Resource was created                         |
+| `Accepted`             | Request accepted for background processing   |
+| `UnprocessableContent` | Validation or schema rule failure          |
+| `NotFound`             | Resource not found                           |
+| `Forbidden`            | Authorization failure                        |
+| `Conflict`             | Resource state conflict or duplicate         |
+| `PaymentRequired`      | Business billing or quota constraint         |
+
+`NoContent` is provided by the base module and does not need to be defined, but you can override it if your format requires a different shape.
+
+Each method receives keyword arguments and must return a hash. The exact keywords depend on the outcome -- success methods receive `resource:` (and optionally `meta:`), while failure methods receive `errors:`.
+
+## Building a Custom Formatter
+
+Here is the built-in `Wrapped` formatter as a reference. It wraps every response in a uniform `{ data:, errors:, status: }` envelope:
+
+```ruby
+module WrappedFormatter
+  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)
+    { json: { data: resource, errors: nil, status: "success" }, 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
+
+  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
+```
+
+All 8 required methods are defined. Success methods accept `resource:` and optionally `meta:`, while failure methods accept `errors:`. The `NoContent` method is inherited from the base `ActionFigure::Formatter` module and returns `{ status: :no_content }` with no JSON body -- override it if your format requires a different shape.
+
+## Registering Your Formatter
+
+There are two ways to register a custom formatter.
+
+**Direct registration:**
+
+```ruby
+ActionFigure.register_formatter(wrapped: WrappedFormatter)
+```
+
+**Via the configuration block:**
+
+```ruby
+ActionFigure.configure do |config|
+  config.register(wrapped: WrappedFormatter)
+end
+```
+
+Both approaches accept keyword arguments where the key is a symbol naming the format and the value is the formatter module. You can register multiple formatters in a single call:
+
+```ruby
+ActionFigure.register_formatter(
+  wrapped: WrappedFormatter,
+  legacy_v1: LegacyV1Formatter
+)
+```
+
+The name you choose (`:wrapped` in the examples above) is the symbol you will use everywhere else to reference this format.
+
+## Interface Validation
+
+Registration is not just bookkeeping -- ActionFigure validates every formatter module before accepting it. The validation checks that all methods listed in `ActionFigure::Formatter::REQUIRED_METHODS` are defined on the module:
+
+```ruby
+ActionFigure::Formatter::REQUIRED_METHODS
+# => [:Ok, :Created, :Accepted, :UnprocessableContent, :NotFound, :Forbidden, :Conflict, :PaymentRequired]
+```
+
+If any required method is missing, registration raises an `ArgumentError` that lists exactly which methods are absent:
+
+```ruby
+module IncompleteFormatter
+  include ActionFigure::Formatter
+
+  def Ok(resource:, **)
+    { status: :ok, json: resource }
+  end
+end
+
+ActionFigure.register_formatter(incomplete: IncompleteFormatter)
+# => ArgumentError: IncompleteFormatter is missing formatter methods: Created, Accepted,
+#    UnprocessableContent, NotFound, Forbidden, Conflict, PaymentRequired
+```
+
+Validation is **atomic** when registering multiple formatters at once. If any single module in the batch fails validation, none of them are registered -- this ensures your registry always remains in a consistent state.
+
+```ruby
+# Neither formatter is registered because LegacyV1Formatter is invalid.
+ActionFigure.register_formatter(
+  wrapped: WrappedFormatter,
+  legacy_v1: LegacyV1Formatter  # missing methods
+)
+# => ArgumentError (nothing was registered)
+```
+
+## Using Your Formatter
+
+Once registered, use a custom formatter exactly like a built-in one.
+
+**Per-action inclusion:**
+
+```ruby
+class Articles::PublishAction
+  include ActionFigure[:wrapped]
+
+  def call(id:)
+    article = Article.find(id)
+    article.publish!
+    Ok(resource: article)
+  end
+end
+```
+
+**As the global default:**
+
+```ruby
+ActionFigure.configure do |config|
+  config.register(wrapped: WrappedFormatter)
+  config.format = :wrapped
+end
+```
+
+```ruby
+class Articles::PublishAction
+  include ActionFigure # no format specified, global setting is used
+
+  def call(id:)
+    article = Article.find(id)
+    article.publish!
+    Ok(resource: article)
+  end
+end
+```
+
+Setting `config.format` makes every action use your formatter unless an individual action explicitly includes a different one. Per-action includes always take precedence over the global default.

data/docs/integration-patterns.md

@@ -0,0 +1,331 @@
+# Integration Patterns
+
+ActionFigure doesn't prescribe a serializer, authorization library, or pagination strategy. Pass any hash to `resource:` and it goes straight into the response envelope. This guide shows how popular gems plug into that pattern.
+
+---
+
+## Serialization
+
+Every example below uses the same action — creating a user — so you can compare the serialization step directly.
+
+### Plain Hashes
+
+No gem required. Use `as_json`, `slice`, or build the hash by hand:
+
+```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 call(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
+```
+
+For more control, build the hash yourself:
+
+```ruby
+def call(params:, company:)
+  user = company.users.create(params[:user])
+  return UnprocessableContent(errors: user.errors.messages) if user.errors.any?
+
+  resource = { id: user.id, name: user.name, email: user.email, initials: user.name.split.map(&:first).join }
+  Created(resource:)
+end
+```
+
+`as_json` and hand-rolled hashes work well for simple cases. When serialization logic grows — conditional fields, nested associations, computed attributes — a dedicated serializer keeps it out of the action.
+
+### Blueprinter
+
+[Blueprinter](https://github.com/procore-oss/blueprinter) defines serialization with a declarative DSL:
+
+```ruby
+class UserBlueprint < Blueprinter::Base
+  identifier :id
+  fields :name, :email
+end
+```
+
+```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 call(params:, company:)
+    user = company.users.create(params[:user])
+    return UnprocessableContent(errors: user.errors.messages) if user.errors.any?
+
+    Created(resource: UserBlueprint.render_as_hash(user))
+  end
+end
+```
+
+Blueprinter supports views for different contexts:
+
+```ruby
+class UserBlueprint < Blueprinter::Base
+  identifier :id
+  fields :name, :email
+
+  view :detailed do
+    association :company, blueprint: CompanyBlueprint
+    field :created_at
+  end
+end
+
+# In the action:
+resource = UserBlueprint.render_as_hash(user, view: :detailed)
+```
+
+### Alba
+
+[Alba](https://github.com/okuramasafumi/alba) is a fast serializer with a flexible DSL:
+
+```ruby
+class UserResource
+  include Alba::Resource
+
+  attributes :id, :name, :email
+end
+```
+
+```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 call(params:, company:)
+    user = company.users.create(params[:user])
+    return UnprocessableContent(errors: user.errors.messages) if user.errors.any?
+
+    Created(resource: UserResource.new(user).to_h)
+  end
+end
+```
+
+Alba supports conditional attributes and nested resources:
+
+```ruby
+class UserResource
+  include Alba::Resource
+
+  attributes :id, :name, :email
+
+  attribute :company do |user|
+    CompanyResource.new(user.company).to_h
+  end
+end
+```
+
+### Oj Serializers
+
+[Oj Serializers](https://github.com/ElMassimo/oj_serializers) is optimized for performance using Oj:
+
+```ruby
+class UserSerializer < Oj::Serializer
+  attributes :id, :name, :email
+end
+```
+
+```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 call(params:, company:)
+    user = company.users.create(params[:user])
+    return UnprocessableContent(errors: user.errors.messages) if user.errors.any?
+
+    Created(resource: UserSerializer.one(user))
+  end
+end
+```
+
+For collections, use `many`:
+
+```ruby
+class Users::IndexAction
+  include ActionFigure[:jsend]
+
+  def call(company:, **)
+    users = company.users.order(:name)
+    resource = UserSerializer.many(users)
+    Ok(resource:)
+  end
+end
+```
+
+---
+
+## Authorization
+
+Authorization gems work naturally with action classes. Inject the current user from the controller and call the authorization check during orchestration.
+
+### Pundit
+
+Call the [Pundit](https://github.com/varvet/pundit) policy directly inside the action:
+
+```ruby
+class Users::DestroyAction
+  include ActionFigure[:jsend]
+
+  params_schema do
+    required(:id).filled(:integer)
+  end
+
+  def call(params:, current_user:)
+    user = User.find(params[:id])
+    unless UserPolicy.new(current_user, user).destroy?
+      return Forbidden(errors: { base: ["not authorized to delete this user"] })
+    end
+    user.destroy!
+    NoContent()
+  end
+end
+```
+
+```ruby
+class UsersController < ApplicationController
+  def destroy
+    render Users::DestroyAction.call(params:, current_user: current_user)
+  end
+end
+```
+
+### CanCanCan
+
+With [CanCanCan](https://github.com/CanCanCommunity/cancancan), build the ability from the current user:
+
+```ruby
+class Users::DestroyAction
+  include ActionFigure[:jsend]
+
+  params_schema do
+    required(:id).filled(:integer)
+  end
+
+  def call(params:, current_user:)
+    user = User.find(params[:id])
+    if Ability.new(current_user).can?(:destroy, user)
+      user.destroy!
+      NoContent()
+    else
+      Forbidden(errors: { base: ["not authorized to delete this user"] })
+    end
+  end
+end
+```
+
+```ruby
+class UsersController < ApplicationController
+  def destroy
+    render Users::DestroyAction.call(params:, current_user: current_user)
+  end
+end
+```
+
+In both cases, authorization failures return a `Forbidden` response through the same formatter pipeline as everything else -- no exceptions, no controller rescue needed.
+
+---
+
+## Pagination
+
+### Cursor Pagination
+
+For paginated lists, accept cursor params and delegate the query logic to a service object. The action orchestrates -- the service does the heavy lifting:
+
+```ruby
+class Users::IndexAction
+  include ActionFigure[:jsend]
+
+  params_schema do
+    optional(:cursor).filled(:integer)
+    optional(:limit).filled(:integer)
+  end
+
+  def call(params:, company:, **)
+    page = UserQuery.page(company.users, cursor: params[:cursor], limit: params[:limit] || 20)
+    resource = UserSerializer.many(page.records)
+    Ok(resource:, meta: { next_cursor: page.next_cursor })
+  end
+end
+```
+
+```ruby
+class UsersController < ApplicationController
+  def index
+    render Users::IndexAction.call(params:, company: current_company)
+  end
+end
+```
+
+The action checks params, delegates to `UserQuery` for the actual query, and formats the response. `UserQuery` is a plain Ruby class that knows how to paginate -- the action doesn't need to.
+
+### activerecord_cursor_paginate
+
+The same pattern works with [activerecord_cursor_paginate](https://github.com/fatkodima/activerecord_cursor_paginate):
+
+```ruby
+class Users::IndexAction
+  include ActionFigure[:jsend]
+
+  params_schema do
+    optional(:cursor).filled(:string)
+    optional(:limit).filled(:integer)
+  end
+
+  def call(params:, company:, **)
+    page = company.users
+      .cursor_paginate(after: params[:cursor], limit: params[:limit] || 20, order: :name)
+      .fetch
+    resource = UserSerializer.many(page.records)
+    Ok(resource:, meta: { next_cursor: page.next_cursor, has_next: page.has_next? })
+  end
+end
+```
+
+### Pagy
+
+Or with [pagy](https://github.com/ddnexus/pagy):
+
+```ruby
+class Users::IndexAction
+  include ActionFigure[:jsend]
+  include Pagy::Backend
+
+  def call(request:, company:, **)
+    pagy, users = pagy(:keyset, company.users.order(:name), request:)
+    resource = UserSerializer.many(users)
+    Ok(resource:, meta: { next: pagy.next })
+  end
+end
+```