Custom Types for Integrations and Documentation

[shawncarr]

In our project, we have a couple of custom ZodTypes to handle specific requirements we have. For example, we have ZodDecimal which validates that the inputted data doesn't exceed decimal place value limits. Which does work great, but if we generate an integration or documentation for each ZodDecimal typed property we get:

amount: any

Which while not wrong, is not right and not helpful on the client side.

What would be nice is if as part of IntegrationParams there was an option for additionalProducers which you would pass to zodToTS to be used to extend the rules property.

rules: { ...producers, ...(additionalProducers ?? {}),

Of course something similar for Documentation and additional depicters

[RobinTail]

Hello @shawncarr ,
I'd like to avoid that as much as possible.

Moreover, since version 16.3.0 I no longer use classes for creating custom types in favor of the zod's native API, and I'm suggesting you to consider it as well.

Instead of classes, you can use:

• refinements;
• z.custom() (which is a shorthand for z.any() plus a refinement);
• transformations;
• piping
• catching

Thus, you can base your custom type on already available types through additional checks, so that they will be depicted properly.

Let me know what you think about that approach.
Consider sharing your ZodDecimal implementation.

Examples of z.custom

express-zod-api/src/schema-helpers.ts

Lines 5 to 8 in de94703

	export const bufferSchema = z.custom<Buffer>(
	(subject) => Buffer.isBuffer(subject),
	{ message: "Expected Buffer" },
	);

Custom + safe parsing

express-zod-api/src/upload-schema.ts

Lines 11 to 28 in de94703

	z.custom<UploadedFile>(
	(subject) =>
	z
	.object({
	name: z.string(),
	encoding: z.string(),
	mimetype: z.string(),
	data: bufferSchema,
	tempFilePath: z.string(),
	truncated: z.boolean(),
	size: z.number(),
	md5: z.string(),
	mv: z.function(),
	})
	.safeParse(subject).success,
	(input) => ({
	message: `Expected file upload, received ${typeof input}`,
	}),

Refinement + transformation

express-zod-api/src/date-out-schema.ts

Lines 10 to 13 in de94703

	z
	.date()
	.refine(isValidDate)
	.transform((date) => date.toISOString()),

Refinement + transformation + piping

express-zod-api/src/date-in-schema.ts

Lines 10 to 14 in de94703

	z
	.string()
	.regex(isoDateRegex)
	.transform((str) => new Date(str))
	.pipe(z.date().refine(isValidDate)),

[RobinTail]

I'm not sure what exactly your ZodDecimal is, but let's assume that it's a numeric string that you'd like to check for the length of it's fraction part:

const makeDecimalSchema = 
  (fraction = 2) => 
    z.string()
      .regex(/^\d+\.\d+$/)
      .refine((str) => str.split(".")[1].length === fraction)

In case you also want it to be automatically transformed into number, then you can add:

      .transform((str) => parseFloat(str))

and optionally pipe it into a number type to ensure it's not NaN:

      .pipe(z.number())

Thus your schema could be depicted by a generator as a string with regex for the input flow, and as a number for the output, @shawncarr

[RobinTail]

Update on this topic.
The future v19, I hope, will be a complete zod plugin, according to recommendations from Zod's author.
A part of that plugin will be runtime distinguishable branded types.
It means that it will be possible to distunguish z.string().brand("A") from z.string().brand("B").
This should enable making the desired feature on extending Documentation and Integration with your custom types, by using .brand() on them.
CC @shawncarr && @kotsmile

[RobinTail]

The PR where I'm making this feature:
#1750

Most likely it will not be released immediately in v19.0.0, but rather in v19.1.0.

[RobinTail]

🚀 Version 19.1.0 having the feature is published, @shawncarr && @kotsmile