A result is a report, not a handle
A passenger asks what it costs to take two cars across the harbour. The action that works it out does its job, and what comes back is a result:
class QuoteFare < Actionable::Action input do required :route, :string required :cars, :integer end
output { required :fare_cents, :integer }
fails :no_sailing, 'no sailing on that route', retry: false
step :price
private
def price fail!(:no_sailing) if input.route == 'nowhere' @fare_cents = 1800 * input.cars endend
quote = QuoteFare.run(route: 'harbour', cars: 2)quote.status # => :successquote.code # => :successquote.fare_cents # => 3600You never get the action instance back. The instance lived for that one run and is gone. What you hold is a report of what happened, and nothing on it reaches back into the action, its input or its steps.
quote.respond_to?(:input) # => falsequote.respond_to?(:price) # => falseWhat a report holds
Section titled “What a report holds”Every result has the same few things, whatever action made it:
status-:success,:failureor:skippedcode- the specific reason, like:no_sailingmessage- a sentence for a person, orniloutput- the declared output fieldserrors- field messages, the same object a struct usesmetadata- what the declaration attached to a failure or skip code
missed = QuoteFare.run(route: 'nowhere', cars: 1)missed.status # => :failuremissed.code # => :no_sailingmissed.message # => "no sailing on that route"missed.metadata # => {retry: false}
rejected = QuoteFare.run(route: 'harbour')rejected.code # => :invalid_inputrejected.errors.to_h # => {cars: ["is required"]}That shape is predictable on purpose. A controller, a job or a tool server can turn any result into a response without knowing which action made it: pick the HTTP status from status, show message, render errors next to the form. See Results for every reader.
It is a struct
Section titled “It is a struct”A result is a FieldStruct, so it behaves like any other value. Two results built the same way are equal, and as_json and to_h give you plain data.
quote.is_a?(FieldStruct::Base) # => truequote == QuoteFare.run(route: 'harbour', cars: 2) # => truequote.as_json # => {status: "success", code: "success", message: nil, output: {fare_cents: 3600}, history: [], errors: {}}as_json carries the whole report, status and errors included, so you can log it or send it as it is. to_h has the same keys with Symbols.
A report doesn’t change once it’s handed over. .run freezes the result after the last hook, so hooks can still adjust it, and from then on its fields, errors and output are read-only. with gives you a changed copy, frozen the same way.
quote.frozen? # => truequote.with(message: 'two cars').message # => "two cars"quote.with(message: 'two cars').frozen? # => truebegin quote.message = 'edited'rescue FrozenError :read_only # => :read_onlyendThe freeze covers plain data only: Strings, Arrays, Hashes and structs. A live object in a :value field stays as it was, which is the next section’s subject.
Where the promise holds, and where it does not
Section titled “Where the promise holds, and where it does not”A report is powerless as long as its output holds plain data. That part is your choice today, since the gem does not stop you from putting a live object in it.
An output field typed :value keeps whatever you give it. Give it an object with methods that change things, like an ActiveRecord record, and anyone holding the result can call them. Here a Vessel stands in for the record:
class Vessel attr_reader :name, :docked
def initialize(name) @name = name @docked = false end
def dock! = @docked = true def to_h = { name: name, docked: docked }end
PUFFIN = Vessel.new('Puffin')
class FindVessel < Actionable::Action output { required :vessel, :value }
step :find
private
def find = @vessel = PUFFINend
FindVessel.run.vessel.dock!PUFFIN.docked # => trueA struct-typed field does not save you from this either. A live object there fails the run with :invalid_output, but the failure still carries the object as it was given.
class VesselCard < FieldStruct::Base required :name, :string optional :docked, :booleanend
class HandOverVessel < Actionable::Action output { required :vessel, VesselCard }
step :find
private
def find = @vessel = PUFFINend
handed = HandOverVessel.runhanded.code # => :invalid_outputhanded.output.vessel.equal?(PUFFIN) # => trueIts as_json then goes through the object’s own serialization. For a record, that means every column, including the ones you never declared. A lazy query left in an output is the same story: it stays unloaded until something serializes the result, and then it runs.
So, for now, it is a convention: hand the output plain data. Give a struct-typed field a Hash, or a record’s attributes, and only the declared fields come through, as primitives.
class DescribeVessel < Actionable::Action output { required :vessel, VesselCard }
step :find
private
def find = @vessel = PUFFIN.to_hend
card = DescribeVessel.run.vesselcard.class # => VesselCardcard.respond_to?(:dock!) # => falsecard.as_json # => {name: "Puffin", docked: true}We are not sure yet how far the gem should go in enforcing this. Until it does, the edge is yours to keep: the layer that turns a result into a response is where a live object would leak, so that is the place to check.
See also
Section titled “See also”FieldStruct, Actionable and their adapters are open source under the MIT license.