In a JavaScript file that TypeScript is checking, how do you annotate a function's parameters and return type, declare a reusable named object type, and make a function generic — using only JSDoc?

## Why JSDoc types exist A `.js` file cannot carry type syntax — `function f(x: string)` is a JavaScript syntax error. So TypeScript reads types out of comments instead. The braces in a JSDoc tag do not contain "JSDoc types" in some parallel dialect: they contain **TypeScript type expressions**, checked with the same rules. Unions, generics, `keyof`, template literal types, `Partial<T>` — all of it is available, just written inside a comment. None of this changes the file at runtime; comments are comments. What changes is what the checker knows. ## Annotating a function ```js /** * @param {string} label * @param {number} [count] optional parameter * @param {"asc" | "desc"} [order="asc"] with a default * @returns {string} */ export function format(label, count, order) { return `${label} ${count ?? 0} ${order}`; } ``` `@param` names must match the real parameter names. Square brackets mark a parameter optional. The type expression is ordinary TypeScript, so the union above is a genuine union and passing `"up"` is an error. ## Annotating a declaration, and casting `@type` attaches a type to the declaration below it: ```js /** @type {Map<string, number>} */ const counts = new Map(); ``` Without the tag the inferred type would be `Map<any, any>`. `@type` is also the cast form, applied to a *parenthesised* expression — the parentheses are required: ```js const input = /** @type {HTMLInputElement} */ (document.getElementById("name")); ``` This is the JSDoc spelling of `as`. Like `as`, it is an assertion the checker trusts, not a runtime conversion: nothing verifies the element really is an input, and if it is not, the belief is simply wrong at runtime. `/** @type {any} */ (x)` is the escape hatch of last resort. ## Declaring reusable named types `@typedef` gives a type a name that other tags — and other files — can reference. Two spellings: ```js /** * @typedef {{ id: string, retries: number, tags?: string[] }} Job */ ``` ```js /** * @typedef {Object} Job * @property {string} id * @property {number} retries * @property {string[]} [tags] optional */ ``` The first is compact; the second gives each member its own documentation line. Either way `Job` is now a type name usable in `@param {Job}`, `@type {Job}` and so on. `@callback` does the same job for function types. A `@typedef` in one file is visible to another via an import type, and — this is the important interop point — the same syntax reaches into TypeScript sources: ```js /** @type {import('./types.js').Config} */ const config = loadConfig(); ``` So a JavaScript file can consume types declared in a `.ts` or `.d.ts` file, which is what lets a mixed codebase share one set of type definitions. ## Generics with @template ```js /** * @template T * @param {T[]} items * @param {(item: T) => boolean} predicate * @returns {T | undefined} */ export function findFirst(items, predicate) { for (const item of items) { if (predicate(item)) return item; } return undefined; } ``` `@template` declares the type parameter; every other tag in the same comment can then use it. Constraints are written on the tag, `@template {object} T`, and multiple parameters get multiple tags or one comma-separated list. ## @satisfies JSDoc also has a `@satisfies` tag, mirroring the `satisfies` operator: it checks the value against a type without widening the value's own inferred type, so literal members stay literal while still being validated. It is the right tag for a config object you want both validated and precisely inferred. ```js /** @satisfies {Record<string, string>} */ const routes = { home: "/", about: "/about" }; ``` ## The realistic tradeoffs JSDoc typing is genuinely capable — most of the type system is reachable, including conditional and mapped types written inside a `@typedef`. What you pay for it is verbosity and a weaker feedback loop: the annotation sits away from the parameter it describes, a renamed parameter can leave its `@param` orphaned, and the comment is easy to skip in review. It is worth it in exactly the situation it was designed for — a codebase that cannot take `.ts` files yet, or a published package that wants types without a build step — and less worth it once the file could simply be renamed. One last practical note: none of these tags do anything unless the file is actually being checked. Add `// @ts-check` at the top or turn on `checkJs`, otherwise you have written documentation, not types.