Best practice for accepting numbers in query params

[niklashigi]

If I want to accept a number as a query parameter (for example, page_size), what's the best way to define its schema? z.number() doesn't seem to work (it returns an Expected number, received string error).

I also tried the following:

z
  .preprocess(
    value =>
      typeof value === 'string' ? Number.parseInt(value) : undefined,
    z.number().int().min(1).max(100),
  )

This works, but the generated OpenAPI schema is strange...

schema:
  description: The number of results to return per page
  format: int64 (preprocessed)
  minimum: 1
  exclusiveMinimum: false
  maximum: 100
  exclusiveMaximum: false

...and confuses code generators and documentation portals (note the json and the multi-line text field on the right):

Is there a better way to do this?

[RobinTail]

The problem with the query params is that they're always strings.
I believe that the best way would be describe it as a numeric string, that has a transformation into number.

Try this, should work fine:

z.string()
  .trim().regex(/\d+/)
  .transform((id) => parseInt(id, 10))

In the latest version (that has zod v3.20), also the following possible:

z.string().regex(/\d+/).pipe(
  z.number({ coerce: true }).int().positive()
);

@shroudedcode

[niklashigi]

That works and is definitely cleaner when looking at just the parsing behavior, but it results in the OpenAPI schema being just string.

This is not "wrong" as query parameters don't really have types and are always strings, but OpenAPI does allow specifying non-string types for query (and path) parameters. In fact, the first example on this page uses type: integer, and I'm pretty confident that any code generators for OpenAPI will properly take this into account.

I ended up just using z.coerce.number(), which has the downside of not giving very helpful error messages when the input is not a valid number, but it does generate the more "helpful" schema.

[RobinTail]

That works and is definitely cleaner

👍🏽

but it results in the OpenAPI schema being just string

Numeric string, if you also add .regex(/\d+/).
And actually this is exactly what it is being a part of an URL.

I ended up just using z.coerce.number()

Nice. That should also be fine.

has the downside of not giving very helpful error messages

You can add more validations into it:
z.coerce.number().int('must be integer').positive('must be positive')

[niklashigi]

Numeric string, if you also add .regex(/\d+/).

True, it's just that I don't have control over the code generation tools the consumers of my API use and type: integer will always be more clear than the regex.

You can add more validations into it: z.coerce.number().int('must be integer').positive('must be positive')

Doing that. Just talking about the Expected number, received nan error that's returned when the string isn't a number. Considering how rarely someone would accidentally not pass a number, though, I think this is negligible.