Results
A run hands back one result. Actionable::Result itself is abstract. The concrete classes are Success, Failure and Skipped, all FieldStruct classes carrying code, message, output and history, with metadata added on failures and skips. The outcomes exclude each other, so for any concrete result exactly one predicate is true.
Attributes
Section titled “Attributes”| Attribute | Success | Failure | Skipped | Default |
|---|---|---|---|---|
code |
yes | yes | yes | :success, :error, :skipped |
message |
yes | yes | yes | nil |
output |
yes | yes | yes | a fresh {} |
history |
yes | yes | yes | a fresh [] |
errors |
yes | yes | yes | empty |
metadata |
no | yes | yes | a fresh {} |
code gets coerced to a Symbol. errors is the FieldStruct collection and not a field, which means errors[:field] gives an Array of Strings and errors.to_h and errors.full_messages behave as on any struct. A Success carries no metadata, and asking for it raises NoMethodError.
Actionable::Success.new.code # => :successActionable::Failure.new.code # => :errorActionable::Skipped.new.code # => :skippedActionable::Failure.new(code: 'adrift').code # => :adriftActionable::Failure.new.metadata # => {}Actionable::Success.new.respond_to?(:metadata) # => falsePredicates
Section titled “Predicates”| Method | True for |
|---|---|
success?, successful? |
Success |
failure?, failed? |
Failure |
skipped? |
Skipped |
ok? |
Success and Skipped (not a failure) |
status |
:success, :failure or :skipped |
status tells you which outcome it was, and code gives the specific reason.
failure = Actionable::Failure.new(code: :adrift)failure.failure? # => truefailure.failed? # => truefailure.ok? # => falsefailure.status # => :failureActionable::Success.new.successful? # => trueActionable::Skipped.new.skipped? # => trueActionable::Skipped.new.ok? # => trueSerialization
Section titled “Serialization”A result is a report, so its plain forms carry everything a reader needs. to_h gives {status:, code:, message:, output:, history:, errors:}, plus metadata: for a failure or skip. A struct output goes through its own to_h, the history through History#as_json, and errors through errors.to_h.
as_json has the same keys in the same order, with JSON-ready values: status and code become Strings and a struct output becomes its own as_json, so its serialize :json names apply. to_json is as_json dumped through Oj.
A failure or a skip never serializes a live object. When a step leaves an ActiveRecord row in an output that then fails its schema, or calls fail! with one in place, to_h, as_json and to_json write it as "#<Kiln id=4>": just the class and the id, without calling the object’s own as_json. The same goes for objects in metadata. The output itself keeps the object, so result.output.kiln still returns it for debugging. A success is written in full.
class Kiln attr_reader :id def initialize(id) = @id = id def as_json(*) = { 'id' => id, 'firing_code' => 'k-77' }end
class FireBatch < Actionable::Action output { required :kiln, :integer } step :load def load = @kiln = Kiln.new(4)end
result = FireBatch.runresult.code # => :invalid_outputresult.as_json[:output] # => {kiln: "#<Kiln id=4>"}result.output.kiln.class # => Kilnto_api_h(index: nil, id_field: :id) gives exactly {index:, status:, id:, errors:}. For id the gem reads id_field off the output: a declared field when the output is a struct, a key when it is a Hash, and nil otherwise.
failure = Actionable::Failure.new(code: :adrift)failure.to_h.keys # => [:status, :code, :message, :output, :history, :errors, :metadata]failure.as_json # => {status: "failure", code: "adrift", message: nil, output: {}, history: [], errors: {}, metadata: {}}failure.to_api_h(index: 2) # => {index: 2, status: :failure, id: nil, errors: {}}Actionable::Success.new(output: { id: 31 }).to_api_h # => {index: nil, status: :success, id: 31, errors: {}}Actionable::Success.new.to_h.key?(:metadata) # => falseA result that .run returns is frozen, after the last hook ran. The freeze reaches the plain data inside: errors, the output struct and its errors, history, metadata and every String, Array, Hash and struct under them, but never a foreign object such as a record. valid?, to_h, as_json and errors.paths still answer. with(...) returns a new result frozen the same way. A result you build yourself (Actionable::Failure.new, test stubs) is not frozen. Inside a step, @result = OtherAction.run is taken as an unfrozen copy, so the run can still fill it in.
inspect and to_s produce #<ClassName name=value ...>, listing every attribute and errors sorted by name. That differs from FieldStruct’s own inspect on purpose.
Actionable::Failure.new(code: :adrift).inspect # => "#<Actionable::Failure code=:adrift errors={} history=[] message=nil metadata={} output={}>"Output delegation
Section titled “Output delegation”Any declared field of a struct output can be read from the result itself: result.fare_pence equals result.output.fare_pence, and respond_to? says the same. Undeclared names, and outputs that are not FieldStruct instances (a free-form Hash, {}), don’t delegate and give the usual NoMethodError. A name that collides with a Result method can’t be an output field at all (see Input and output).
output_fields_set lists which output fields a run really set (instance variables plus verb keywords). On a hand-built result it is nil. It’s a plain accessor and not a field, so equality ignores it.
class TallyFare < Actionable::Action output { required :fare_pence, :integer }
step :tally
private
def tally = @fare_pence = '350'.to_i + 25end
result = TallyFare.runresult.fare_pence # => 375result.output.fare_pence # => 375result.output_fields_set # => [:fare_pence]result.respond_to?(:fare_pence) # => trueActionable::Success.new.output_fields_set # => nilErrors
Section titled “Errors”Failure#absorb_errors_from(source) takes each field => messages pair from source.errors.to_h, adds every message to the failure one by one, and returns the failure. Any object whose errors answers to_h will do.
class Crossing < FieldStruct::Base required :harbour, :stringend
failure = Actionable::Failure.new(code: :invalid)failure.absorb_errors_from(Crossing.new).equal?(failure) # => truefailure.errors.to_h # => {harbour: ["is required"]}failure.errors.full_messages # => ["Harbour is required"]Equality and pattern matching
Section titled “Equality and pattern matching”Equality looks at the exact class and the attributes. A Success is never equal to a Failure with matching attributes, while two results built alike are equal. With typed outcomes, a result equals only one from its own action’s class.
A result is a FieldStruct, so case/in can deconstruct code, message, output, history (and metadata on failures and skips), and class patterns work too. errors and status are methods rather than fields, so a hash pattern that names either never matches.
Actionable::Success.new == Actionable::Success.new # => trueActionable::Success.new == Actionable::Skipped.new # => false
outcome = case Actionable::Failure.new(code: :adrift) in Actionable::Failure(code:) then "failed with #{code}" endoutcome # => "failed with adrift"See also
Section titled “See also”- Control flow: the verbs that build results
- Input and output: what ends up in
output - Hooks and history: the
historyattribute
FieldStruct, Actionable and their adapters are open source under the MIT license.