decoders

When designing decoders for your application, follow these architectural principles:

1. Name decoders after Data Types, not Fields

Avoid naming a decoder after the property it validates (e.g., labelsDecoder). Instead, name it after the shape of the data it describes (e.g., commaSeparated). This makes the decoder reusable across different parts of your schema.

2. Keep edge cases outside decoders

To maintain composability, keep decoders focused on a single responsibility. Instead of building a decoder that handles both a specific format AND null values, build a decoder for the format and wrap it in nullable() or nullish() at the call site (inside your object() definition).

Bad (Low Reusability): const messyString = string.transform(s => s.trim()).nullable(); (Harder to reuse the trim logic elsewhere)

Good (High Reusability): const trimmedString = string.transform(s => s.trim()); const field = nullable(trimmedString);

To define a custom decoder, start with an existing decoder that accepts the desired input types, then use .refine() to narrow what is accepted or .transform() to change what is returned.

• Narrowing acceptance: Use .refine() to add extra validation criteria.
• Changing return type: Use .transform() to modify the value before it is returned.

Understanding Acceptance vs. Return

It is critical to distinguish between what a decoder accepts (input) and what it returns (output). The type Decoder<T> tells you what it returns, but not what it accepts.

// Pattern for creating a custom decoder
const myDecoder = existingDecoder
  .refine(value => /* validation logic */)
  .transform(value => /* transformation logic */);

The Decoder<T> class is the core abstraction used to validate and transform untrusted input data into typed values. It is reusable and composable.

Decoding Strategies

Choose a decoding method based on how you want to handle failures:

DecodeResult Format

When using .decode(), the result is a discriminated union:

type DecodeResult<T> =
  | { ok: true; value: T }
  | { ok: false; error: Annotation };

If ok is false, the error property contains an Annotation (a structured copy of the input with error details) which can be formatted using formatInline or formatShort.

number.decode(3); // { ok: true, value: 3 }
number.decode('hi'); // { ok: false, error: ... }

Because decoders implement the Standard Schema v1 interface, they can be used directly as validators in TanStack Form. You can pass a decoder to the validators property of a form.Field (e.g., using the onChange key) to handle field-level validation.

import { useForm } from '@tanstack/react-form';
import { nonEmptyString, positiveInteger } from 'decoders';

function MyForm() {
  const form = useForm({
    defaultValues: { name: '', age: 0 },
    onSubmit: ({ value }) => console.log(value),
  });

  return (
    <form
      onSubmit={(e) => {
        e.preventDefault();
        form.handleSubmit();
      }}
    >
      <form.Field name="name" validators={{ onChange: nonEmptyString }}>
        {(field) => (
          <input
            value={field.state.value}
            onChange={(e) => field.handleChange(e.target.value)}
          />
        )}
      </form.Field>
      <form.Field name="age" validators={{ onChange: positiveInteger }}>
        {(field) => (
          <input
            type="number"
            value={field.state.value}
            onChange={(e) => field.handleChange(Number(e.target.value))}
          />
        )}
      </form.Field>
    </form>
  );
}