RBS for your actions
Actionable::RBS.generate(klass) gives back RBS source for a single named action, derived from its input and output schemas by way of FieldStruct’s metadata. A rake task is a good place for it, with the file committed beside your code. Struct types are covered in Introspection and tooling. The gem’s own signatures live in its sig/ directory, and generate is the only public contract. They name only field_struct and prism, so they load in an app without Rails or RuboCop; the framework parents and the methods only a framework calls are left out (see ProxyValidator for the one line to add if you need them).
Actionable::RBS.generate(klass) # => StringPass a named subclass of Actionable::Action. Anything else raises ArgumentError: Actionable::RBS.generate expects an Actionable::Action subclass, got <inspect> for a non-action, and cannot generate RBS for an anonymous action for an anonymous one.
class ReleaseMooring < Actionable::Action input do required :voyage_id, :integer optional :remark, :string end output { required :lines_freed, :integer }
fails :tide_too_low skips :already_cast_offend
rbs = Actionable::RBS.generate(ReleaseMooring)rbs.lines.first.chomp # => "class ReleaseMooring < ::Actionable::Action"rbs.include?('def self.run: (voyage_id: ::Integer, ?remark: ::String?) -> Result') # => truerbs.include?('@lines_freed: ::Integer?') # => truerbs.include?('type failure_code = :tide_too_low | :invalid_input | :invalid_output') # => truerbs.include?('type skip_code = :already_cast_off') # => truerbs.end_with?("end\n") # => trueWhat is emitted
Section titled “What is emitted”| Part | Emitted |
|---|---|
| ancestors | member-less declarations of every named ancestor between the class and Actionable::Action, outermost first; wrapped in their namespaces |
def self.run |
keywords from a fixed input schema, plus an overload taking a built (InputSchema input) |
input and InputSchema |
for a fixed input, def input: () -> InputSchema and a FieldStruct::Base subclass with a reader and writer per field |
| instance variables | one nullable @field per output field, so steps that assign them type-check |
Output and Result |
Output with readers and writers; Result < ::Actionable::Result with output and a reader per field |
| code aliases | type failure_code (declared codes, then the gem’s two, de-duplicated) and type skip_code (declared only) |
How run gets its keywords: a required field is name: Type, and one that may be left out is ?name: Type. Optional fields are nullable too (?name: Type?), and a required field with a default can be omitted. Free-form actions, and any action using an input_for dispatch, get (*untyped). The return type is Result when the output has a schema and ::Actionable::Result when it hasn’t. InputSchema, Output and Result exist in RBS only. If Ruby already resolves InputSchema on the class, an ancestor or an included module, generation raises ArgumentError and asks you to rename that constant. Output is indented two spaces, blank lines are empty, types are fully qualified, and the text ends with a newline.
class Freeform < Actionable::Action; end
Actionable::RBS.generate(Freeform).include?('def self.run: (*untyped) -> ::Actionable::Result') # => true
begin Actionable::RBS.generate(Class.new(Actionable::Action))rescue ArgumentError => e e.message # => "cannot generate RBS for an anonymous action"endTyped outcomes
Section titled “Typed outcomes”Typed outcomes add the result classes to the output: the success Output when there is one, an output class for every code that has a schema (<CamelCode>SkipOutput or <CamelCode>FailureOutput), and the Success, Skipped and Failure classes. run returns (Success | Skipped | Failure).
Successhascode: :success,output: Output(or a Hash when there is no schema) and a reader per success field.Skippedhascodetyped asskip_code(or::Symbolwhen none are declared) andoutputas the union of the skip output classes and the Hash.Failurehascodetyped asfailure_code,outputas the union of failure classes, skip classes,Outputand the Hash, and every reader nullable, since a broken output can lack a required field.- Bases are the parent action’s own classes when the parent has typed outcomes, else the gem classes.
A trailing ? or ! on a code turns into Predicate or Bang in the class name (:expired? gives ExpiredPredicate...). If two codes of one kind map to the same class name, or a name doesn’t begin with an ASCII capital, ArgumentError names both codes.
class Charter < Actionable::Action typed_outcomes
input { required :nights, :integer } output { required :arrives_in, :integer }
fails(:over_limit) { required :max_nights, :integer }end
typed = Actionable::RBS.generate(Charter)typed.include?('-> (Success | Skipped | Failure)') # => truetyped.include?('class OverLimitFailureOutput < ::FieldStruct::Base') # => truetyped.include?('class Success < ::Actionable::Success') # => truetyped.include?('def code: () -> failure_code') # => trueSee also
Section titled “See also”- Declared outcomes: where codes and typed outcomes are declared
- Input and output: the schemas the types come from
- Introspection and tooling:
FieldStruct::RBSfor structs
FieldStruct, Actionable and their adapters are open source under the MIT license.