在 JSDoc 中使用 TypeScript 类型

这是一个用于探索在 React 应用中使用各种类型方式的实验性仓库。

请查看 ./src 文件夹中的示例

全局启用 TS 检查

要在所有地方启用 TS 运行，请在 VSCode 工作区或用户设置中使用 js/ts.implicitProjectConfig.checkJS 设置。

"js/ts.implicitProjectConfig.checkJs": true

TypeScript 忽略错误

专业提示：自动添加忽略注释的 CLI 工具

//@ts-ignore 告诉 TypeScript 忽略注释后一行的 TypeScript 错误。

function mapValues(object, mapFunction) {
  // @ts-ignore
  return Object.fromEntries(Object.entries(object).map(([key, value]) => [key, mapFunction(value)]))
}

//@ts-expect-error 将忽略下一行的任何类型检查失败，但如果没有错误，类型检查将失败

function mapValues(object, mapFunction) {
  //@ts-expect-error
  return Object.fromEntries(Object.entries(object).map(([key, value]) => [key, mapFunction(value)]))
}

忽略多行

// @ts-ignore-start
// @ts-ignore-end

在文件中禁用的核心选项

// @ts-nocheck

示例

• 一系列示例 https://github.com/voxpelli/types-in-js/discussions/11
• https://github.com/wooorm/dead-or-alive/blob/main/lib/index.js
• https://github.com/Rich-Harris/devalue
• https://github.com/meduzen/datetime-attribute
• https://github.com/geut/deluge/blob/main/src/deluge.js#L1-L29
• https://github.com/ds300/lazyrepo/
• https://github.com/sveltejs/kit/

资源与文章

• JSDoc 类型：TypeScript 的所有优点，没有缺点 + giltayar/jsdoc-typing
• 在 JavaScript 中使用类型的技巧和诀窍。voxpelli/types-in-js
• JSDoc 速查表
• Joshua's Docs 上的 JSDoc 速查表和类型安全技巧
• Jacob Paris 的 JSDoc 速查表
• jsdoc-examples：使用 JSDoc 记录 JavaScript 的示例
• 文档和 JSDoc
• brettz9/awesome-jsdoc：awesome jsdoc 工具、资源等列表
• TSConfig.json 参考
• 通过代码理解 JSDoc 的使用
• JSDoc 和 React。JSDoc 是一个非常versatile的工具... | 作者：Anton Krinitsyn | Medium
• jsdoc-templates-demo：知名 jsdoc3 模板演示 和 示例
• 用 TS 检查你的 JS
• JSDoc 和 React
• TypeScript-JSDoc-Guides
• https://dev.to/t7yang/type-safety-in-javascript-with-jsdoc-and-vscode-1a28
• https://medium.com/@antonkrinitsyn/jsdoc-generic-types-typescript-db213cf48640
• 不用 TypeScript 的 TypeScript -- JSDoc 超能力
• BeyondCodeBootcamp/jsdoc-typescript-starter：充分利用 JSDoc + tsserver（无需 TypeScript 的类型检查）
• https://github.com/simone-sanfratello/do-typescript-without-typescript + https://www.youtube.com/watch?v=xLDVfBUgD8U
• 无需转译的 TypeScript
• 是时候摘掉 TypeScript 的辅助轮了，明天就使用//@ts-check
• JSDoc：JavaScript 内部的 TypeScript，而不是相反 🤯
• 使用 JSDoc 实现类型安全的 JavaScript
• 切换到使用"默认导出"以满足 tsserver
• 利用 JSDoc 注释标签，让 VSCode 智能感知效果更佳！
• JSDoc 速成课程 2021
• https://github.com/ipfs/aegir/blob/master/md/ts-jsdoc.md
• andreidmt/tpl-ts-jsdoc：利用 TypeScript 的 JSDoc 支持实现纯 JavaScript 类型
• https://github.com/stereobooster/type-o-rama
• 使用 AJV Standalone 实现 TypeScript 类型安全 + https://github.com/rehanvdm/ajv-standalone-type-saftey
• 得票最多的 'jsdoc' 问题 - Stack Overflow
• 使用 Zod 和 JSDoc 在 JavaScript 中实现类型

工具

文档解析器

• https://github.com/ccontrols/structured-types
• https://github.com/yashag/jsdoctor/
• https://github.com/jsdoc-type-pratt-parser/jsdoc-type-pratt-parser
• https://github.com/hegemonic/catharsis
• https://github.com/jsdoctypeparser/jsdoctypeparser
• https://github.com/reactjs/react-docgen
• https://github.com/syavorsky/comment-parser
• https://api-extractor.com/pages/tsdoc/tag_example/
• https://github.com/eslint/doctrine
• https://github.com/DavidWells/jsdoc-parser - dox 的更新版本
• https://github.com/jonschlinkert/parse-comments 解析 JavaScript 代码注释。
• https://github.com/jonschlinkert/tokenize-comment
• https://github.com/jsdoc2md/jsdoc-api - jsdoc3 的程序化接口，带有一些额外功能

格式化工具

• hosseinmd/prettier-plugin-jsdoc：用于格式化 Jsdoc 的 prettier 插件。
• JSdoc 的 Prettier

转换工具

• https://transform.tools 转换各种东西！
• https://github.com/vega/ts-json-schema-generator 或 https://github.com/horiuchi/dtsgenerator 从JSON Schema文件生成TypeScript d.ts文件
• https://github.com/YousefED/typescript-json-schema
• https://github.com/LinbuduLab/json-to-type-graphql JSON / 对象 / 请求 ---> TypeGraphQL 类！
• https://github.com/develar/ts2jsdoc - 从TypeScript生成JSDoc
• 对象转schema https://github.com/unjs/untyped
• 从SQL schema生成TS类型 https://github.com/vramework/schemats
• 从JSON响应生成TS类型 https://github.com/ThePrimeagen/undefined
• https://github.com/rmp135/sql-ts 从SQL数据库生成TypeScript接口。
• OpenAPI转TS https://github.com/drwpow/openapi-typescript
• 从openapi规范生成type.d https://github.com/sigoden/openapi/tree/main/packages/typegen-openapi
• protocol buffer消息转TS https://github.com/thesayyn/protoc-gen-ts
• Protobuff转JSON schema https://github.com/devongovett/protobuf-jsonschema
• 将TS转换为flow https://github.com/zxbodya/flowts/blob/master/packages/tsflow/src/convertToFlow.ts
• CSS模块的Typescript https://github.com/mrmckeb/typescript-plugin-css-modules
• JS doc转json schema https://github.com/brettz9/jsdoc-jsonschema
• https://github.com/Surnet/swagger-jsdoc + https://github.com/ajmnz/swagger-jsdoc-indent - 基于jsDoc注释和YAML文件生成swagger/openapi规范。
• https://github.com/stereobooster/type-o-rama 转换工具目录
• https://github.com/quicktype/quicktype - 从JSON、Schema和GraphQL生成类型和转换器
• TS转JS带JSdoc
• JSON转JSDoc
• https://github.com/unjs/untyped
• GraphQL转JSONSchema https://github.com/charlypoly/graphql-to-json-schema
• https://github.com/nijikokun/generate-schema 将JSON对象转换为MySQL、JSON Schema、Mongoose、Google BigQuery、Swagger
• https://github.com/xiaobebe/extract-typescript-types

额外导入的类型

• https://github.com/ThomasAribart/json-schema-to-ts
• https://github.com/krzkaczor/ts-essentials
• https://github.com/millsp/ts-toolbelt
• https://github.com/sindresorhus/type-fest
• https://github.com/Col0ring/types-kit
• https://github.com/alii/typestr
• https://github.com/ghoullier/awesome-template-literal-types
• https://github.com/jrylan/json-schema-typed JSON schema类型
• https://github.com/jrylan/http-method-enum HTTP方法作为TypeScript枚举。
• https://github.com/jrylan/enum-utils/
• https://github.com/ronami/meta-typing
• https://github.com/piotrwitek/utility-types
• https://github.com/Lucifier129/coproduct
• https://github.com/garronej/tsafe
• https://github.com/g-plane/typed-query-selector 类型化的querySelector和querySelectorAll
• https://github.com/g-plane/type-gymnastics

文档生成器

• https://github.com/galvez/typejuice
• https://github.com/jsdoc2md/jsdoc-to-markdown#readme
• https://github.com/yashag/jsdoctor 智能jsdoc生成器
• https://github.com/documentationjs/documentation
• https://github.com/DavidWells/microsoft-api-documenter-example 使用@microsoft/api-extractor + @microsoft/api-documenter
• https://github.com/TypeStrong/typedoc + https://github.com/panva/oauth4webapi/blob/51866b3d65a7ac92a8811e26e55c320f4828a7fc/package.json#L25
• https://github.com/LinusU/ts-readme-generator
• https://github.com/marijnh/getdocs-ts + https://github.com/marijnh/builddocs

运行时类型检查器

• https://github.com/moltar/typescript-runtime-type-benchmarks#packages-compared
• https://github.com/David-Kunz/derive-type 通过运行测试动态推导类型以捕获值组合
• https://github.com/brielov/typed
• https://github.com/grantila/typeconv 用于 https://github.com/grantila/suretype
• https://github.com/druc/intus
• https://github.com/spaceteams/zap 具有函数式API的验证优先schema库
• https://github.com/colinhacks/zod/ + https://github.com/fabien0102/ts-to-zod + https://github.com/alii/azs
• 小型zod https://github.com/davidmdm/myzod
• https://github.com/ianstormtaylor/superstruct
• https://github.com/artalar/rtcad
• https://github.com/skarab42/tson - 类型安全对象表示法和验证
• https://github.com/pelotom/runtypes
• https://github.com/vedantroy/typecheck.macro
• https://github.com/sindresorhus/is + https://github.com/sindresorhus/ts-extras
• https://github.com/samchon/typescript-json 超快的运行时验证器（类型检查器），只需一行代码
• https://github.com/sindresorhus/ow
• https://github.com/shigma/schemastery
• https://github.com/justinyaodu/caketype
• https://github.com/yona3/typescanner
• https://github.com/rhys-vdw/ts-auto-guard
• https://github.com/imbrn/v8n
• https://github.com/d-kimuson/type-predicates-generator
• https://github.com/milesj/optimal
• https://github.com/jquense/yup
• https://github.com/sideway/joi
• https://github.com/drummer1992/sito
• https://github.com/vitalets/micro-schema
• https://github.com/daniel7grant/dvali
• https://github.com/crinklesio/schemas
• https://github.com/facebook/prop-types
• https://github.com/elierotenberg/typed-assert
• https://github.com/suchipi/serializable-types
• https://github.com/gcanti/io-ts
• https://github.com/thenativeweb/typedescriptor
• https://github.com/thenativeweb/ensurethat
• https://github.com/thenativeweb/formats
• https://github.com/suchipi/pheno
• https://github.com/markwylde/vamlid - 一种根据纯JavaScript schema验证对象的简单方法。

VScode扩展

• https://github.com/Perkovec/JSDocLivePreview
• https://github.com/zachhardesty7/jsdoc-comment-toggler/blob/master/src/extension.ts

杂项

• @jitl/ts-simple-type - 提供一个简单、类型安全的API，用于分析类型、构造新类型和基于类型生成代码。
• typesync 为package.json中的依赖项安装缺失的TypeScript类型定义。
• type-coverage 一个用于检查TypeScript代码类型覆盖率的命令行工具。
• typescript-error-reporter-action GitHub Action，用于诊断TypeScript错误并在PR上报告结果。
• JavaScript的类型检测工具 https://github.com/sapphiredev/type / https://github.com/pkdev08/klasa-v13/blob/master/src/lib/util/Type.js
• Zod转TS https://github.com/sachinraja/zod-to-ts
• eslint配置 https://github.com/Agoric/agoric-sdk/blob/20c4ff00adbffff067858c3c5702ae7a9e0522b8/packages/eslint-config/eslint-config.json + https://github.com/homer0/packages/tree/main/packages/personal/eslint-plugin
• https://github.com/benawad/gen-env-types - 从.env文件生成.d.ts和.env.example文件
• 将JSON Schema转换为JSDoc https://github.com/n3ps/json-schema-to-jsdoc 或 https://github.com/mizuka-wu/json-schema-to-jsdoc/blob/master/src/plugins/jsonschema2jsdoc.js
• https://github.com/livingdocsIO/microschema 无依赖的小型库，用于创建JSON Schemas。
• https://github.com/stereobooster/type-o-rama
• https://github.com/johnthecat/babel-plugin-jsdoc-runtime-typecheck/
• https://github.com/heavenshell/ts-lehre
• 简洁主题 https://github.com/cdaringe/jsdock
• https://github.com/homer0/jsdoc-ts-utils/
• https://github.com/vytenisu/npm-dts 生成index.d.ts文件
• 移除TypeScript类型 https://github.com/cyco130/detype
• Babel遍历mobx生成jsdoc https://github.com/Feverqwe/mst-jsdoc-gen/blob/master/getJsDoc.js
• https://github.com/zacanger/jsdoctap 使用JSDoc示例和node-tap的文档测试运行器。或 https://github.com/TechQuery/test-example/blob/master/source/TestFile.js 或 https://github.com/kiwicopple/doctest-js
• 生成单一dts包的工具 https://github.com/timocov/dts-bundle-generator
• https://github.com/garbles/json-schema-multi-compiler
• https://github.com/json-schema-faker/json-schema-faker
• https://github.com/typescript-cheatsheets/react
• https://github.com/gendocu-com/grpc-docs - 交互式gRPC API文档
• https://github.com/2fd/graphtype 从GraphQL生成TypeScript定义
• https://github.com/rawrmaan/restyped REST API的TypeScript端到端类型定义
• https://github.com/etienne-dldc/zensql TypeScript类型安全的SQL系统
• https://github.com/Ff00ff/mammoth TypeScript的类型安全Postgres查询构建器。
• https://github.com/JoshuaKGoldberg/TypeStat 将JavaScript转换为TypeScript，将TypeScript转换为更好的TypeScript。
• https://github.com/airtasker/spot 将API编写为代码，并生成其他API契约格式（OpenAPI、Swagger、JSON Schema）
• https://github.com/readmeio/oas 通过代码注释轻松创建和管理OpenAPI文档
• https://github.com/Akryum/vue-typegen 扫描组件并生成类型
• https://github.com/deanshub/data-from-types 从TypeScript类型生成数据
• https://github.com/chasefleming/enum-xyz 通过代理在原生JS中使用枚举
• https://github.com/apidoc/apidoc RESTful Web API文档生成器。
• https://github.com/twentyfourg/jest-apidoc 从jest测试生成API文档
• https://github.com/thenativeweb/is-typescript 检查项目是否为TypeScript
• https://github.com/suchipi/convert-to-dts

示例

• https://github.com/Ethan-Arrowood/lego-world-map-designer/blob/main/index.js
• https://gitlab.com/jugglinmike/friend-off/-/blob/main/src/server/room.js
• https://github.com/Kr1an/react-jsdoc-sample + https://github.com/Kr1an/jsdoc-react-express-sample/blob/master/src/Single.js
• https://github.com/wooorm/f-ck
• https://github.com/micromark/micromark/blob/edbfa7a2d358d3264bd4524e947698cd7f7b480f/packages/micromark-util-types/index.js
• https://github.com/fenomas/noa/blob/master/src/index.js
• https://github.com/apollographql/apollo-server/issues/5097#issuecomment-822867819 + https://github.com/jaydenseric/graphql-upload/blob/master/package.json
• https://github.com/MrShoenel/orchestration-tools + https://mrshoenel.github.io/orchestration-tools/
• https://github.com/rubengomex/js-spotify-api/blob/master/src/index.js
• https://github.com/homer0/parserror/blob/c12b20e3a321e1e01f41178eceb1d3210991d40f/src/parserror.js#L240
• https://github.com/knockaway/loan-calculator/blob/master/lib/calculate-apr.js#L5-L19

使用测试代码作为文档

• https://github.com/linear/linear/blob/bc39d23af232f9fdbe7df458b0aaa9554ca83c57/packages/sdk/src/_tests/readme.test.ts#L57-L70 + https://github.com/linear/linear/blob/94af540244864fbe466fb933256278e04e87513e/docs/markdown-magic.config.js + https://github.com/linear/linear/blob/94af540244864fbe466fb933256278e04e87513e/docs/transforms/code-section.js
• 将Markdown的子部分引入其他文件 https://github.com/linear/linear/blob/93981d3a3db571e2f8efdce9f5271ea678941c43/packages/codegen-doc/README.md#L32

• https://github.com/linear/linear/blob/93981d3a3db571e2f8efdce9f5271ea678941c43/docs/transforms/text-section.js + https://github.com/linear/linear/blame/bc39d23af232f9fdbe7df458b0aaa9554ca83c57/README.md#L42