JSDoc for schema and inferred type

[the-spyke]

Is there a way to attach JSDoc to the schema and inherit it with inferred types?

export const UserSchema = z.object({
  /** UTC ISO date time string */
  createdAt: z.string(),
});

So this documentation would be visible in the tool tips. And after getting the type:

export type User = z.infer<typeof User>;

I would see this JSDoc there as well, so it could be taken by TypeDoc and appear in the generated documentation?

[JacobWeisenburger]

I'm not sure that there is a way to do what you are asking for using JSdocs. However, you could do something like what I have below. Hopefully someone else will be able to chime in if this is possible with just JSdocs.

/** UTC ISO date time string */
type ISODateString = `${number}-${number}-${number}T${number}:${number}:${number}Z`
function isIsoDate ( string: string ): string is ISODateString {
    if ( !/\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}.\d{3}Z/.test( string ) ) return false
    return new Date( string ).toISOString() === string
}

const isoDateString = z.string().refine( isIsoDate )
const UserSchema = z.object( { createdAt: isoDateString } )
type User = z.infer<typeof UserSchema>
type CreatedAt = User[ 'createdAt' ]
//-> CreatedAt = `${number}-${number}-${number}T${number}:${number}:${number}Z`

Unfortunately, I'm not sure how to make CreatedAt show as ISODateString instead of ${number}-${number}-${number}T${number}:${number}:${number}Z.

Hope this helps.

[the-spyke]

Thanks, I understand that it might be technically feasible to encode an ISO date string as a type, but I really was asking about documentation.

[JacobWeisenburger]

I was mostly making the above suggestion, because I try to use self documenting code as much as possible. So in this case, I'm not sure that it's needed to have /** UTC ISO date time string */ when you can just have a type and/or function that documents what they are by their names. Granted if I were to see ${number}-${number}-${number}T${number}:${number}:${number}Z as a type, then I would be confused, so maybe there is a better way to do this.

[the-spyke]

Sorry, was't the best example.

/** Should be a fish, but Chicken was left for compatibility purposes */
z.enum(["Salmon", "Tuna", "Chicken"]);

I think it isn't that surprising that there're valid cases for documentation.

[JacobWeisenburger]

Sorry, I wasn't trying to say that I don't think you should document your code at all. But I think that documentation is better used for explaining why something needs to be done a certain way that isn't immediately obvious. So your example of leaving something in for compatibility purposes is a great example of where documentation could be used. I was trying to say before that /** UTC ISO date time string */ isn't really needed, because it's answering the question 'what is this property?' rather then answering 'why is this property something?'. I try to use variable names to answer the question 'what is this property?'. Hope this makes sense.

[JacobWeisenburger]

After digging into this some more, I'm pretty sure that not being able to see the JSdoc after z.infer is a problem with typescript and I don't think there is anything Zod can do to fix that.

const UserSchema = z.object( {
    /** UTC ISO date time string */
    createdAt: z.string()
} )
typeof UserSchema.shape[ 'createdAt' ]
// when you hover over 'createdAt' then the popup shows the JSdoc
// (property) createdAt: z.ZodString
// UTC ISO date time string

type CreatedAt = typeof UserSchema.shape[ 'createdAt' ]
// but unfortunately, when you make a type alias, it loses the JSdoc
//-> CreatedAt = z.ZodString