input parameter of GET endpoint incorrectly parses a single-item array as a string

[tbrockmeyer-a]

To preface - nice lib! This is something I was looking for many years ago, and in the past, I wrote my own half-assed versions of just this before I learned that nice things like zod existed. It's like the lib I was always wanting to build haha.

Description

Anyway, I did find one issue while trying to build up a basic API:

If you call a GET endpoint that has a zod input parameter which is an array of strings,passing only a single value nets you an input validation error. It claims that you've passed a string when an array was expected, but then how can you pass an array with only one value?

Expected

I expect that if the generated documentation is capable of detecting that an array of strings is expected, then the input validation logic should also be able to detect the same thing, and make decisions based on that.

Given that an array is expected, it follows that if only a single string is sent as input, it should be treated as an array with only one element instead of a plain string.

Reproduction

Given this endpoint setup:

export const listUsers = defaultEndpointFactory.build({
  input: z.object({
    names: z.array(z.string()),
  }),
  output: z.object({
    users: z.array(z.object({id: z.number()})),
  }),
  handler: async () => {
    return { users: [{id: 1}] };
  },
})

export const routing: Routing = {
  users: new DependsOnMethod({
    get: listUsers,
  }),
};

And this test:

curl -X 'GET' \
  'http://localhost:3000/api/users?names=joe' \
  -H 'accept: application/json'

I get the following error:

{
  "status": "error",
  "error": {
    "message": "names: Invalid input: expected array, received string"
  }
}

Contrast that with the following, where multiple values are provided:

curl -X 'GET' \
  'http://localhost:3000/api/users?names=joe&names=bob' \
  -H 'accept: application/json'

There is no issue with this one, since when it sees multiple values, it assumes array by default.

{
  "status": "success",
  "data": {
    "users": [
      {
        "id": 1
      }
    ]
  }
}

Workaround

    names: z.union([z.array(z.string()), z.string()])
      .transform((value) => typeof value === 'string' ? value.split(',') : value),

By setting up any arrays as string[] | string, and then supplying a transformation function for handling the case where the value comes as a string, all cases can be handled well. This also handles the case where the client sends names=joe,bob instead of names=joe&names=bob, so both cases function correctly. Likely I would need this transformation function regardless, so I guess it's fine, but the type union makes it a little funky.

Context

• Node.js version: 22.14.0
• express-zod-api version: 25.5.3

[RobinTail]

Hello @tbrockmeyer-a

Please review this short article:
https://ez.robintail.cz/v25.5.3/query-string-parser

So, when you say ?names=joe the query parser does not have a chance to figure out that you imply an array.
In order to give it a hint, you should say ?names[]=joe instead and use extended query parser in your configuration.