Course contentsShow
← TypeScript
Lesson 1640 of 1,79637. Migrating JavaScript to TypeScriptFree lesson

JSDoc Limitations vs Native TypeScript

Understand what type features JSDoc cannot express and when converting to .ts becomes necessary.

JSDoc Limitations vs Native TypeScript

What you'll learn: You'll understand which type features JSDoc cannot express and when converting to .ts files becomes necessary for full type safety.

The Fundamental Constraint

JSDoc was designed as a documentation tool that TypeScript cleverly adapted for type-checking. But because it lives inside comments, JSDoc has architectural limits. Think of it like describing a painting with only words versus actually seeing the painting — sometimes the description just can't capture everything.

When using JSDoc in .js files, you're working within JavaScript's syntax plus what can be expressed in comment strings. Native TypeScript in .ts files has no such constraint — types are first-class citizens.

What JSDoc Cannot Express

Conditional types are impossible in JSDoc. You can't write type logic like T extends U ? X : Y in a comment string.

Mapped types with key remapping don't work. Complex transformations over object keys require native TypeScript syntax.

Template literal types are not supported. You can't construct type-safe string patterns like `on${Capitalize<T>}` in JSDoc.

The infer keyword doesn't exist in JSDoc. You cannot extract types from other types conditionally.

Branded/opaque types cannot be properly created since they rely on unique symbols or complex intersections.

Recursive type aliases are extremely limited or unsupported in JSDoc.

Advanced generic constraints with multiple interdependent type parameters often fail or require workarounds.

Type-level programming patterns — treating types like functions that compute other types — are essentially off the table.

When Migration Becomes Necessary

If you find yourself needing discriminated unions with complex narrowing, exhaustive checks with never, or any of the advanced patterns from later in your TypeScript journey, JSDoc will block you. Documentation comments can describe what types you wish you had, but they can't compute or transform types the way native TypeScript can.

Key Takeaway: JSDoc is powerful for gradual migration and adding basic type safety to JavaScript, but advanced type features like conditionals, mapped types, template literals, and infer require full .ts files — when your types need to do computation, it's time to convert.