Passing arrays in query parameters

[zdllucky]

The small problem I encountered is when I build schema like

defaultEndpointsFactory.build({
  method: "get",
  input: z
    .object({
      states: z.nativeEnum(RecipientUploadState).array().optional(),
    })
   // ...
})

And do:

curl -X 'GET' \
  'http://localhost:3950/api?states=' \
  -H 'accept: application/json'

# or

curl -X 'GET' \
  'http://localhost:3950/api?states=created' \
  -H 'accept: application/json'

I get error

{
  "status": "error",
  "error": {
    "message": "states: Expected array, received string"
  }
}

It is interesting because it actually should be encountered like empty array or one item array, doesn't it?

I digged a bit deeper and found another one uncommon behavior, when I do choose multiple elements (via swagger) it prompts me to do request like

curl -X 'GET' \
  'http://localhost:3950/api?states=finished&states=cancelled' \
  -H 'accept: application/json'

# instead of more commonly used comma separation

curl -X 'GET' \
  'http://localhost:3950/api/v1/notification/recipient?states=finished,cancelled' \
  -H 'accept: application/json'

And comma separated array also sends me

{"status":"error","error":{"message":"states: Expected array, received string"}}

Is it intensional behavior? Or I encountered unexpected behavior, @RobinTail ? In my personal case I think to manage it via creating custom zod resolver, to restore comma like behavior, but maybe you have better suggestions?

[RobinTail]

Hello @zdllucky

I have 3 solutions for you

Encode properly

When you send arrays in query parameters, they have to be distinguishable from regular strings.
Comma separation does not do that, it's not a conventional way for encoding arrays.
Though there are many of them, the most common one looks a bit more weird, but it works (I checked it):

curl -X 'GET' \
  'http://localhost:3950/api?states[]=created&states[]=removed&states[]=changed' \
  -H 'accept: application/json'

So you have to repeat states[] with brackets for multiple elements — this is for express 4.
⚠️ In express 5 they changed "extended" query parser to "simple" and states must be repeated without brackets.
This will be made configurable in #2922

Use body

If possible, consider switching to a method having request.body, thus you can pass over the array in JSON.

Make a transformation

If you'd like to have a comma separated array encoding of query parameter, you'd need to implement it yourself using transformation from string (by utilizing its split method), and then pipe it into the enum array schema you had before:

z.string()
  .transform( (str) => str.split(",") )
  .pipe(
    z.nativeEnum(RecipientUploadState).array()
  )

[RobinTail]

In my personal case I think to manage it via creating custom zod resolver, to restore comma like behavior, but maybe you have better suggestions?

You don't have to go custom, just use transform + pipe.
If you gonna have a lot of these, you can make a function to avoid repeating yourself:

const withCSV = <T extends z.ZodTypeAny>(arraySchema: z.ZodArray<T>) =>
  z
    .string()
    .transform((str) => str.split(","))
    .pipe(arraySchema);

, @zdllucky , I hope this will help you.

[zdllucky]

Wow, did not know about it: states[]=created&states[]=remove.... It really works but swagger-ui goes nah.
Solved it with transform + piping also, but I guess will think a bit more,

Thanks a lot! Really informative

[zdllucky]

For anyone who would want their openapi config and swagger-ui to work well (adding [] by default) you can use this parser:

const getOptimizedDocs = (docs: any) => {
  // Here it adds [] to most related places
  const updatedPaths = mapValues(docs.paths, (path) => {
    return mapValues(path, (method) => {
      return {
        ...method,
        parameters: method.parameters?.map((param: any) => {
          return param.schema.type === "array" && param.in === "query"
            ? { ...param, name: `${param.name}[]` }
            : param;
        }),
      };
    });
  });

  const updatedDocs = {
    ...docs,
    paths: updatedPaths,
  };

  // Here it removes "/" signs to make regex work properly
  return JSON.stringify(updatedDocs).replace(
    /"pattern":\s*"\/(.*?)\/"/g,
    (_, group1) => `"pattern": "${group1}"`,
  );
};

const docs = JSON.parse(meta.getOpenApiDocs().getSpecAsJson());
console.log(getOptimizedDocs(docs))