Coercion versus validation
Feed a leaf-count field the string "abc". Two separate things can be wrong with that input, and the gem tells them apart.
class Canopy < FieldStruct::Base optional :leaves, :integer, in: 1..99end
Canopy.new(leaves: '12').leaves # => 12Canopy.new(leaves: '500').errors[:leaves] # => ["is invalid"]Canopy.new(leaves: 'abc').errors[:leaves].first.start_with?('could not be coerced') # => true'500' was read without trouble and then judged: it is an integer, but outside the range. That is validation, and the message is "is invalid". 'abc' never got read, so there is no integer to judge. That is coercion, and the message says so.
Two steps, two errors
Section titled “Two steps, two errors”Coercion turns input into a value of the type, or fails. Validation judges a value that already exists. They ask different questions and a client needs different answers, since “send a number” is not the advice “send a smaller number” gives. One merged message would lose that.
The order is fixed too. A coercion failure ends the pipeline for that field, so a required field given garbage gets the coercion message alone, without an “is required” stacked on it.
What happens when coercion fails
Section titled “What happens when coercion fails”This is where the gem has a policy, with three choices, because outside data is often wrong and the object should live long enough to say why.
class Keep < FieldStruct::Base optional :leaves, :integerend
class Replace < FieldStruct::Base coercion_policy :replace optional :leaves, :integerend
class Strict < FieldStruct::Base coercion_policy :raise optional :leaves, :integerend
Keep.new(leaves: 'abc').leaves # => "abc"Replace.new(leaves: 'abc').leaves # => nil
begin Strict.new(leaves: 'abc')rescue FieldStruct::CoercionError => e e.field_name # => :leavesend
Keep.new(leaves: 'abc').valid? # => falseReplace.new(leaves: 'abc').valid? # => false:keep_rawis the default. Nothing gets lost, you can inspect what arrived, and the error records the refusal. The cost is that an invalid object may hold a value of the wrong class, so checkvalid?before using it.:replacestoresnil. The field never has the wrong class, but the original input is gone. It always storesnil, never a type-specific null, so there is just one thing to remember.:raiseraisesCoercionErrorfrom the setter and keeps the old value. It suits code that would rather stop, and the price is arescuearound every build.
One field can override the class policy, which helps when a single field is the odd one out.
Lenient by default
Section titled “Lenient by default”The defaults follow what ActiveModel readers expect, so a Rails client sees familiar values. That is lenient, on purpose. strict: true opts in to narrower :integer and string types, and anything it accepts the lenient default accepts too. Our lean is lenient by default and strict on request, and the spec holds the default lenient until a major release.
Messages never echo input
Section titled “Messages never echo input”No error message holds the offending value, only its class. That covers coercion errors, CoercionError, union and array messages, from_json errors and the cause chain. The reason is plain: the bad value is the one that turns out to be a password pasted into the wrong box. Errors get logged and sent back to clients, so they must be safe to log.
The price is a less helpful message, since the value is the first thing you want while debugging. We pay it. Look at the input where it came in.
See also
Section titled “See also”FieldStruct, Actionable and their adapters are open source under the MIT license.