Microsoft/TypeScript

JSDoc comments for async_hooks are confusing/misleading

Open

#62967 opened on Jan 9, 2026

View on GitHub
 (2 comments) (0 reactions) (0 assignees)TypeScript (48,455 stars) (6,726 forks)batch import
Experience EnhancementHelp WantedSuggestion

Description

Acknowledgement

  • I acknowledge that issues using this template may be closed without further explanation at the maintainer's discretion.

Comment

The JSDoc comments from the async_hooks module state not to use the module, and then go on to immediately suggest an "alternative" that is in the module itself.

We strongly discourage the use of the async_hooks API

  • AsyncLocalStorage

If you look at the node.js docs, it makes sense because these two things are on separate pages, but in TS, this warning is shown on import { AsyncLocalStorage } from 'node:async_hooks';

This might be a larger codegen/docs issue as well for other modules that have multiple doc pages.

Contributor guide

Tech stack
typescriptnodejs
Domain
documentation
Issue type
documentation
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
2
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
under 1 hour
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
fresh
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
clear
Prerequisites
TypeScript basicsNode.js async hooks knowledge
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
85
Research direction
Start by examining the type definitions for async hooks in the TypeScript repository (likely in lib/node/async hooks.d.ts). Compare the JSDoc comments with the official Node.js documentation to identify the misleading parts. Check if there are any existing discussions or PRs related to this issue. Consider whether the fix should be applied to the type definitions or if the issue originates from the code generation process.