英文:
Can I get prettier types out of Zod inferred types in my Typedoc documentation?
问题
我的问题
我首先使用z.infer
从Zod模式中生成类型,然后使用Typedoc生成这些类型的文档,但输出在某些方面不太理想:
- 类型以
TypeName: z.infer<typeof schemaName>
的形式呈现,这本身并不有帮助(幸运的是schemaName
可点击)。 - 模式以各种Zod类型的方式呈现,例如
ZodObject<{ name: ZodOptional<ZodString>}>
,而不是预期的{ name?: string }
。 - 模式中的可选对象属性以
name: undefined | string
的方式呈现,而不是name?: string
甚至是(optional) name?: string
,这是Typedoc用于常规(非-Zod)类型的方式。
示例
以下是一个示例(来自示例存储库):
index.ts
import z from 'zod';
export const userSchema = z.object({
name: z.string().optional()
})
export type ZodUser = z.infer<typeof userSchema>;
export type TypescriptUser = {
name?: string
}
一旦我在这上运行Typedoc,很明显,TypescriptUser比ZodUser的结果更好:
ZodUser
file:///…/zod-typedoc-ugly/docs/types/ZodUser.html:
ZodUser: z.infer<typeof userSchema>
file:///…/zod-typedoc-ugly/docs/variables/userSchema.html:
userSchema: ZodObject<{
name: ZodOptional<ZodString>;
}, "strip", ZodTypeAny, {
name: undefined | string;
}, {
name: undefined | string;
}> = ...
VS
TypescriptUser
file:///…/zod-typedoc-ugly/docs/types/TypescriptUser.html:
TypescriptUser: {
name?: string;
}
寻找解决方案
我正在寻找一种既能获得Zod的优点(我可以在运行时使用负责类型的模式来验证输入),又能获得无Zod的Typescript类型简单文档的方法。
我了解我可以分别维护这两者,但我宁愿这是自动的,而不会引入这两个版本不同步的风险。
是否有更好的方式,解决方法或替代方案?
英文:
My problem
I'm first using z.infer
to produce types from Zod schemas and then Typedoc to generate documentation for those types, but the output is less than ideal in a few ways:
- The types come out as type aliases in the form
TypeName: z.infer<typeof schemaName>
, which isn't helpful in itself (thankfullyschemaName
is clickable) - The schemas come out with all sorts of Zod types in the way, e.g.
ZodObject<{ name: ZodOptional<ZodString>}>
instead of the expected{ name?: string }
- Optional object properties in schemas come out as e.g.
name: undefined | string
rather thanname?: string
or even(optional) name?: string
, which Typedoc does for regular (non-Zod) types.
Example
Here's an example (from repro repo):
index.ts
import z from 'zod'
export const userSchema = z.object({
name: z.string().optional()
})
export type ZodUser = z.infer<typeof userSchema>
export type TypescriptUser = {
name?: string
}
Once I run Typedoc on this, it's fairly obvious that the results are better with TypescriptUser than with ZodUser:
ZodUser
file:///…/zod-typedoc-ugly/docs/types/ZodUser.html:
ZodUser: z.infer<typeof userSchema>
file:///…/zod-typedoc-ugly/docs/variables/userSchema.html:
userSchema: ZodObject<{
name: ZodOptional<ZodString>;
}, "strip", ZodTypeAny, {
name: undefined | string;
}, {
name: undefined | string;
}> = ...
VS
TypescriptUser
file:///…/zod-typedoc-ugly/docs/types/TypescriptUser.html:
TypescriptUser: {
name?: string;
}
Seeking Solution
I'm looking for a way to get the advantages of Zod (I can use the schema responsible for the type at runtime to validate inputs) along with the simpler docs of zod-less Typescript types.
I understand I can maintain the two separately, but I would rather that be automatic and not introduce a risk for both of these versions to fall out of sync.
Is there a better way, a workaround or an alternative here?
答案1
得分: 4
大约5分钟前是的。有一种方法。typedoc-plugin-zod 可以用于使 TypeDoc 在转换 z.infer
类型别名时使用推断的类型,而不是类型节点。它还将替换原始模式声明的类型,引用 ZodUser
类型。
(明显的免责声明,我刚刚写了这个)
英文:
As of approximately 5 minutes ago, yes. There is a way. typedoc-plugin-zod can be used to make TypeDoc use the inferred type instead of the type node when converting the z.infer
type aliases. It will also replace the original schema declaration's type to refer to the ZodUser
type.
(obvious disclaimer, I just wrote this)
通过集体智慧和协作来改善编程学习和解决问题的方式。致力于成为全球开发者共同参与的知识库,让每个人都能够通过互相帮助和分享经验来进步。
评论