Validation Execution Order (eg check array max length before validating items)

[pw-64]

import * as v from 'valibot';

const schema = v.pipe(v.array(v.number()), v.maxLength(5));

const safeParse = (input: unknown) => v.safeParse(schema, input, {abortPipeEarly: true}).issues?.[0]?.message;

console.log(safeParse([1,2,3]));          // undefined
console.log(safeParse([1,2,3,4,5,6]));    // Invalid length: Expected <=5 but received 6
console.log(safeParse([1,"2",3]));        // Invalid type: Expected number but received "2"
console.log(safeParse([1,2,3,4,5,"6"]));  // Invalid type: Expected number but received "6"

If there was a more processing-heavy item schema such as a db lookup or an expensive calculation, ideally we would be able to perform simple checks first such as maxLength to filter out the easier issues. If a user submitted 1000 array items, each one would be validated before the max length of 5 is checked, meaning a ton of extra processing for no reason.

const customPipe = v.pipe(
  v.custom<unknown>(input => Array.isArray(input), "Input is not an array"),
  v.custom<unknown[]>(input => (input as unknown[]).length <= 5, `Maximum array length is ${5}`),
  v.array(v.number())
);

v.parse(
  customPipe,
  [1,1,1,1,1,1,1,1,1,1,1,1,1,1,"5"],
  {abortPipeEarly: true},
)

let i: v.InferInput<typeof customPipe>; // unknown
let o: v.InferOutput<typeof customPipe>; // number[]

The above does seem to work, although it means copying some of the existing functionality of v.array, therefore duplicated code means:

1. double processing (eg Array.isArray in this case)
2. if v.array was updated, the custom function would be out of sync

It also means more work type hinting everything, which introduces more room for error.

I think overall it would be great to be able to specify the order of validations, for example:

const schema = v.pipe(
  v.array({
      schema: v.number({order: 2}),
      order: 1
  }),
  v.maxLength({length: 5, order: 0})
);

Very rough idea, just the first thing that came to mind. For each validator, the args could instead be an object which contains options, where one is the order in which they should be executed.

Then v.parse recurses through the schemas and collects all the validation in an array and runs them on each field, in order?

I have no experience with production-ready api design so this is likely the completely wrong way to do it, but I hope it helps get the idea across.

I'd love to know people's thoughts on an execution-order feature.

Thanks,
Peter

[pw-64]

Or maybe v.array could just take in an optional maxLength argument that it checks before validating all items? Devs could still use v.maxLength in a pipe if they specifically want to check the length after validating each item, so this wouldn't be a breaking change. It would just allow more flexibility.

Imo it makes far more sense to do easier validations first such as a length check, I can't currently think of a use case where doing them after more expensive checks would be useful.

[dosubot[bot]]

You're right—currently, valibot only supports maxLength as a separate validation action in a pipeline after v.array, so item validation always happens before length checks in that pattern. There's no built-in way to specify validation order or pass a maxLength option directly to v.array, and no mechanism for prioritizing simple checks before expensive ones in the core API. Your suggestion to add an optional maxLength argument to v.array is feasible and would improve performance for cases with costly item validation, while remaining backward-compatible since the pipeline approach would still be available for those who want length checks after item validation. No active development or prior proposals for this feature exist yet, but the codebase's structure would support such an extension if maintainers decide to pursue it. For now, your custom validation workaround is the best option, despite its drawbacks.
Documentation: maxLength usage
Discussion: execution order and maxLength in v.array

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[pw-64]

I would be happy to give implementing this a go if you'd be ok with the "extra maxLength optional param" idea?

[pw-64]

const customPipe2 = v.pipe(
  v.array(v.unknown()),
  v.maxLength(5),
  v.array(v.number())
);

console.log(v.safeParse(
  customPipe2,
  [1,1,1,1,1,1,1,1,1,1,1,1,1,1,"5"],
  {abortPipeEarly: true},
));

let i2: v.InferInput<typeof customPipe2>; // unknown[]
let o2: v.InferOutput<typeof customPipe2>; // number[]

This does also work, would it be the recommended solution / workaround?

[pw-64]

Maybe if v.array didn't require an item schema parameter, in which case it would only check that the input is an array? Since even v.unknown must have a small (likely unmeasureable) performance impact since it does still have some runtime code:

"~run"(dataset) {
      dataset.typed = true;
      return dataset;
    }

I'm not sure about implementing this one though, since I think it would also involve modifying ArraySchema to accept undefined as the TItem, I'm not sure how much of the codebase that would affect?

[fabian-hiller]

v.array(...) parses the array (creating a copy of it). So calling it twice is fine for small or medium size arrays but if you want to optimize for maximum performance you probably want to prevent that for large arrays.

[fabian-hiller]

What is your main motivation: deciding which error to return first or optimizing for maximum performance? If you're trying to maximize performance, have you encountered any noticeable performance issues? I also try to optimize as much as possible, but sometimes it doesn't matter.

Currently, Valibot uses a "depth-first" approach, parsing the deeper schemas first, which allows us to make the pipe fully type-safe.

Here is another workaround. Try it out in this playground.

import * as v from 'valibot';

const arrayOfMaxLenght = (length: number, message?: string) =>
  v.custom<unknown[]>(
    (input) => Array.isArray(input) && input.length <= length,
    message,
  );

const Schema = v.pipe(
  arrayOfMaxLenght(3, 'Custom error message'),
  v.array(v.number()),
);

[pw-64]

Hi Fabian,

Currently the main issue is the error messages, since they are directly sent to the frontend as-is. If a user sees deeply nested errors first, they will start updating the form inputs before being aware that they have too many items, which is bad for UX.

I've updated your code example to add an isArray check first so that non-array values don't trigger the "max length" message.

This looks to work well, and seems to have the correct in/out types.

Thanks,
Peter