可以从Zod推断的类型中获得更漂亮的类型在我的Typedoc文档中吗?

huangapple go评论48阅读模式
英文:

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&lt;typeof schemaName&gt;, which isn't helpful in itself (thankfully schemaName is clickable)
  • The schemas come out with all sorts of Zod types in the way, e.g. ZodObject&lt;{ name: ZodOptional&lt;ZodString&gt;}&gt; instead of the expected { name?: string }
  • Optional object properties in schemas come out as e.g. name: undefined | string rather than name?: 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 &#39;zod&#39;

export const userSchema = z.object({
  name: z.string().optional()
})

export type ZodUser = z.infer&lt;typeof userSchema&gt;

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&lt;typeof userSchema&gt;

file:///…/zod-typedoc-ugly/docs/variables/userSchema.html:

userSchema: ZodObject&lt;{
    name: ZodOptional&lt;ZodString&gt;;
}, &quot;strip&quot;, ZodTypeAny, {
    name: undefined | string;
}, {
    name: undefined | string;
}&gt; = ...

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)

huangapple
  • 本文由 发表于 2023年3月12日 07:23:54
  • 转载请务必保留本文链接:https://go.coder-hub.com/75710188.html
匿名

发表评论

匿名网友

:?: :razz: :sad: :evil: :!: :smile: :oops: :grin: :eek: :shock: :???: :cool: :lol: :mad: :twisted: :roll: :wink: :idea: :arrow: :neutral: :cry: :mrgreen:

确定