Coercions
Superstruct allows structs to be augmented with coercion logic, letting you to transform input data before validating it. This is most commonly used to apply default values to an input, but it can be used for more complex cases like pre-trimming strings, or pre-parsing inputs.
defaulted
defaulted1
defaulted(string(), 'Untitled')
2
3
object({
4
id: defaulted(number(), () => i++),
5
name: string(),
6
role: defaulted(enums(['admin', 'member', 'guest']), 'guest'),
7
})
Copied!
defaulted augments a struct to add coercion logic for default values, which are applied when the input is undefined.🤖 If you adddefaultedto anobjectstruct with a dictionary of values, those values will be mixed in one-by-one, so the input doesn't need to beundefined, but certain properties can beundefined.
trimmed
trimmed1
trimmed(string())
Copied!
trimmed arguments a struct to ensure that any string input values are trimmed.Custom Coercions
You can also define your own custom coercions that are specific to your application's requirements, like so:
1
import { coerce, number, string, create } from 'superstruct'
2
3
const MyNumber = coerce(number(), string(), (value) => parseFloat(value))
4
5
const a = create(42, MyNumber) // 42
6
const b = create('42', MyNumber) // 42
7
const c = create(false, MyNumber) // error thrown!
Copied!
The second argument to
coerce is a struct narrowing the types of input values you want to try coercion. In the example above, the coercion functionn will only ever be called when the input is a string—booleans would ignore coercion and fail normally.🤖 If you want to run coercion for any type of input, use theunknown()struct to run it in all cases.
Last modified 1mo ago
Copy link