actionable

Actionable

Typed, composable Ruby service objects. Subclass Actionable::Action, declare an ordered list of steps, implement each as a method, and run it. A run returns a single value object — a Success, Failure, or Skipped — with a code, message, structured errors, a typed output, and an execution history.

• Pure-Ruby core — depends only on field_struct. Rails (transactions, validators) is an optional adapter.
• Typed in and out — declared input/output schemas, coerced and validated through FieldStruct, with full RBS via Sord + YARD.
• Three honest outcomes — success, failure, and skip (nothing to do — neither).

Installation

# Gemfile
gem 'actionable'

Requires Ruby 3.2+.

Quick start

class Greet < Actionable::Action
  output { required :greeting, :string }

  step :build

  def build
    @greeting = "Hello, #{name}!"
  end

  def name = 'World'
end

result = Greet.run
result.success?        # => true
result.greeting        # => "Hello, World!"
result.output.greeting # => "Hello, World!"

A step is just a method. Set instance variables that match declared output fields and they're captured, coerced, and surfaced on the result — and reachable directly off it (result.greeting). If no step records a result, the run auto-succeeds.

Control flow

Inside a step, five verbs record the outcome. The bang forms also halt the pipeline; the plain forms record and keep going (last write wins). Genuine exceptions are never swallowed — they propagate to the caller.

Verb	Records	Halts?
succeed(message = nil, **output)	Success	no
fail(code, message = nil, **errors)	Failure	no
fail_with(source, code: :invalid)	Failure absorbing source.errors	no
skip(code = :skipped, message = nil, **output)	Skipped	no
succeed! / fail! / fail_with! / skip!	as above	yes
halt!	— (keeps current)	yes

fail_with absorbs an arbitrary FieldStruct's validation errors into the failure — handy for validating a side struct in a step. skip takes output kwargs too, so an idempotent hit can return the existing record's data.

class Charge < Actionable::Action
  input { required :amount, :integer }

  step :validate
  step :charge

  def validate
    fail!(:invalid_amount, 'must be positive') unless input.amount.positive?
  end

  def charge
    succeed("charged #{input.amount}")
  end
end

ok = Charge.run(amount: 10)
ok.success?  # => true
ok.message   # => "charged 10"

bad = Charge.run(amount: -5)
bad.failure? # => true
bad.code     # => :invalid_amount

Three outcomes, not two

A skip means the action had nothing to do — a precondition wasn't ready, the work was already done. That's not a failure (no error, nothing to retry or alert) and not a success (no real work). Conflating it with either loses information; Actionable makes it a first-class outcome.

class Sync < Actionable::Action
  input { optional :ready, :boolean }

  step :guard
  step :perform

  def guard
    skip!(:not_ready, 'nothing to sync yet') unless input.ready
  end

  def perform
    succeed('synced')
  end
end

idle = Sync.run(ready: false)
idle.skipped? # => true
idle.success? # => false
idle.failure? # => false
idle.ok?      # => true
idle.code     # => :not_ready

Sync.run(ready: true).success? # => true

Predicates: success? / successful?, failure? / failed?, skipped?, and ok? (≡ "didn't fail" — true for both a success and a skip).

Typed output

output do … end builds a FieldStruct schema. Matching instance variables are captured at the end of the run, coerced through the schema, and exposed as result.output plus convenience delegation. Only a strict success is validated — a failed or skipped run captures output best-effort.

class Sum < Actionable::Action
  output { required :total, :integer }

  step :add

  def add
    @total = '42' # coerced through the schema
  end
end

Sum.run.total        # => 42
Sum.run.output.total # => 42

Typed input

input do … end makes .run coerce its keyword arguments into a typed struct, validate them, and expose input to the steps. A missing or invalid required input short-circuits to a Failure(:invalid_input) without running any steps. Without an input block, .run's arguments are forwarded to the constructor.

For a polymorphic payload, input_for picks the schema at run time from a discriminator — typed input without a single fixed shape:

input_for :event_type do
  on 'sale',   SaleShape
  on 'refund', RefundShape
  default      UnknownShape
end

Running a batch