# 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`

```ts
defaulted(string(), 'Untitled')

object({
  id: defaulted(number(), () => i++),
  name: string(),
  role: defaulted(enums(['admin', 'member', 'guest']), 'guest'),
})
```

`defaulted` augments a struct to add coercion logic for default values, which are applied when the input is `undefined`.

> 🤖 If you add `defaulted` to an `object` struct with a dictionary of values, those values will be mixed in one-by-one, so the input doesn't need to be `undefined`, but certain properties can be `undefined`.

### `trimmed`

```ts
trimmed(string())
```

`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:

```ts
import { coerce, number, string, create } from 'superstruct'

const MyNumber = coerce(number(), string(), (value) => parseFloat(value))

const a = create(42, MyNumber) // 42
const b = create('42', MyNumber) // 42
const c = create(false, MyNumber) // error thrown!
```

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 function 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 the `unknown()` struct to run it in all cases.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.superstructjs.org/api-reference/coercions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.