Should transforms on output schemas also be applied to examples?

[niklashigi]

We've got an output field like this on one of our endpoints:

start_date: z
  .dateOut()
  .describe('The date this absence starts in the `yyyy-MM-dd` format.')
  .transform(str => str.slice(0, 'yyyy-MM-dd'.length))
  .nullable(),

We need to return this as a plain date because it has to be clear to API consumers that this field contains no time (or timezone) information whatsoever.

Because the "backing" data structure is sadly still a regular Date object, the example object also contains a regular date:

start_date: new Date('2022-08-04'),

When calling this endpoint the date is correctly returned in its "truncated" form:

"start_date": "2022-08-04",

The example object in our docs, however, still shows the full date string:

"start_date": "2022-08-04T00:00:00.000Z",

That's why I'm wondering: Should transforms on output schemas also be applied to examples? 🤔

[RobinTail]

I'm not sure... I thought that something like that was already implemented in OpenApi helpers... I need to check why it doesn't work well in this case

[RobinTail]

Yeah, there is method getExample() in common-helpers. It should transform the examples for the output.
I'll check it against your case.

[RobinTail]

@shroudedcode , I don't see in your original message the way you specify the example.
There should be something withMeta().example(). Please share the code sample.

[niklashigi]

There you go:

withMeta(
  z.object({
    start_date: z
      .dateOut()
      .describe('The date this absence starts in the `yyyy-MM-dd` format.')
      .transform(str => str.slice(0, 'yyyy-MM-dd'.length)),
  }),
).example({
  start_date: new Date('2022-08-04'),
})

[RobinTail]

Thank you for the code sample, @shroudedcode .
I made a test for the function and it passed, so the function itself works well.
But maybe there is something else. I'm going to make another test for a complete endpoint setup.

    test("Discussion #694: should apply transformation to dateOut in case of output", () => {
      const schema = withMeta(
        z.object({
          start_date: z
            .dateOut()
            .describe(
              "The date this absence starts in the `yyyy-MM-dd` format."
            )
            .transform((str) => str.slice(0, "yyyy-MM-dd".length)),
        })
      ).example({
        start_date: new Date("2022-08-04"),
      });
      expect(getExamples(schema, true)).toEqual([{ start_date: "2022-08-04" }]); // passed
    });

[RobinTail]

@shroudedcode , I created a PR with a complete endpoint test:
#696

All tests passed. I'm not sure why you're experiencing the issue. Perhaps there is something else involved and requires more detailed investigation.

Are you using the defaultResultHandler/defaultEndpointsFactory or a custom one?
Which version of the library you are running?

Please let me know.

[RobinTail]

@shroudedcode ?

[niklashigi]

Hey @RobinTail, sorry for the late reply! Turns out the issue was caused by:

• ReadMe not displaying the raw (shortened) date string in their examples but instead reformatting the date because its format was still date-time and not date (it was correctly outputted in the YAML file the entire time, just not displayed like that)
• us having decided to also include example responses in the Markdown description of every endpoint (using a variant of getExamples that wasn't as feature-complete as we thought) because ReadMe makes the examples super hard to find

So case closed, there doesn't seem to be a bug here.