jsdoc-types
Type-check plain .js files using JSDoc comments instead of migrating to TypeScript. Use when enabling or debugging checkJs/allowJs/`// @ts-check`, adding @type/@param/@typedef/@template annotations, typing a constructor function or ES6 class through JSDoc, or fixing a checkJs-only error (open-ended object literal, optional-by-default parameter, any-typed null/[] initializer). Not for .d.ts files shipped with a package (declaration-contracts), tsconfig option selection beyond checkJs/allowJs (tsconfig), or type-level generic utilities (advanced-types).
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- jsdoc-types
- metadata
- { "category": "reference" }
- description
- Type-check plain .js files using JSDoc comments instead of migrating to TypeScript. Use when enabling or debugging checkJs/allowJs/`// @ts-check`, adding @type/@param/@typedef/@template annotations, typing a constructor function or ES6 class through JSDoc, or fixing a checkJs-only error (open-ended object literal, optional-by-default parameter, any-typed null/[] initializer). Not for .d.ts files shipped with a package (declaration-contracts), tsconfig option selection beyond checkJs/allowJs (tsconfig), or type-level generic utilities (advanced-types).
02 资源文件 1
- 参考文档REFERENCE.md8.3 KB
03 SKILL.md 正文
Typed JavaScript with JSDoc
A .js file has no .ts syntax available — every annotation lives in a comment, and everything left unannotated infers looser than the same code would in .ts.
Turn checking on
Project-wide: allowJs: true plus checkJs: true in tsconfig.json/jsconfig.json — checkJs alone does nothing, since .js files aren't in the program without allowJs. Per-file: // @ts-check as the first line, // @ts-nocheck to exempt one file from a project-wide checkJs. Errors are silent without these even when annotations are present.
The loop
-
Model the shape.
@typefor a variable's type;@param/@returnsfor a function's signature (@param {string} [p]marks it optional,@param {string} [p="x"]gives a default);@typedef/@callbackfor a shape reused across signatures;@templatefor a generic,@template {string} Kto constrain it,@template [T=object]to default it. Reference a type from another file with@import {Pet} from "./types"or inlineimport("./types").Pet— neither imports at runtime, only into the type space. Full tag syntax in REFERENCE.md.Done when every exported function and object has a
@param/@returns/@typenaming a concrete type, none left to bare inference. -
Anchor classes and constructor functions. A property's type is inferred from every
this.x = …assignment inside the constructor; assignments only in methods are optional, and a property never assigned is untyped. Precede an assignment with/** @type {string | undefined} */where the constructor sets it tonull/undefined/nothing meaningful.@constructorplus@thismakes a plain function checked as a class. There is no.jssyntax for a type argument in anextends/implementsclause — use@extends/@augments {Base<Arg>}and@implements {Iface<Arg>}, or the argument silently defaults toany.@overrideneedsnoImplicitOverride: truein tsconfig to actually be checked.Done when every class field, base-class generic argument, and access modifier (
@public/@private/@protected/@readonly/@override) is declared rather than left to inference. -
Close the loose defaults.
.jsrelaxes checks.tsenforces; each is closed by one explicit annotation:- object literal is open-ended (implicit
[x: string]: any) unless the variable it initializes carries a JSDoc type - a
null/undefined/[]initializer types asany/any[]regardless ofstrictNullChecks, unless annotated - every parameter is optional — calling with fewer arguments never errors — unless the function carries
@param; calling with more arguments than declared still errors either way - a function body referencing
argumentsgets an implicit(...args: any[]) => any;@param {...number} argstypes it - a type argument the compiler can't infer (unconstrained generic call, or the extends-clause case above) defaults to
any
Done when a
checkJsrun shows no gap from this list — each object literal, nullable initializer, parameter list, and generic call site carries an explicit type instead of the JS-mode default. - object literal is open-ended (implicit
-
Prove it. Run the project's
tsc/editor diagnostics withcheckJson.// @ts-expect-errorworks in.jsexactly as in.ts— put it above a call or assignment that must fail; the compiler flags the directive itself if the line stops erroring.Done when checking reports zero unintended errors and every
@ts-expect-errorline genuinely fails without its directive.
Casts, satisfies, const
/** @type {T} */ (expr)— the only cast syntax available in.js(noasoperator); parenthesizeexpr./** @satisfies {T} */ (expr)— checks againstTwithout wideningexpr's own inferred type, same as thesatisfiesoperator./** @type {const} */ (expr)— JSDoc equivalent ofas const.
Reference
Tag-by-tag syntax, legacy Closure type synonyms, patterns JSDoc supports that TypeScript doesn't (and vice versa), and a symptom → fix table: REFERENCE.md.
04 同仓库更多 Skills
unslop
Use when writing or editing prose a person will read, or when text sounds AI-generated.
show-me
Use when asked to show, diagram, or walk through how code fits together or what a change does, or before explaining a multi-file flow in prose.
pr
Use when writing or updating a pull request description, or before running `gh pr create`.
commit
Use when writing a commit message, or before running `git commit`.
write-specs
Spec a feature's observable behavior. Use when asked for requirements, when a request says what the system should do but not how, or to capture what a built system already guarantees. Not for how to build it (write-plan).
write-skills
Write, fix, or audit a skill's frontmatter, trigger description, and body. Use when a skill is asked for, never fires, or fires at the wrong moment. Not for a hook (write-hooks) or the plugin manifest and catalog.