Registry / testing / jsdoc3-parser

jsdoc3-parser

JSON →
library3.0.0jsnpmunverified

jsdoc3-parser is a utility designed to extract the Abstract Syntax Tree (AST) from JavaScript files by leveraging JSDoc's internal parser. It operates by invoking the JSDoc CLI with the `-X` option, which outputs the parsed documentation as JSON, and then processes this output. As of its last major release, version 3.0.0, published approximately three years ago, this package offered a workaround for the absence of a direct programmatic API for JSDoc's parser. However, the official JSDoc project now provides `@jsdoc/parse` which offers a direct, programmatic approach. Consequently, `jsdoc3-parser` has seen no recent updates and its core method of operation is now largely superseded, making its release cadence effectively ceased. Its key differentiator was its ability to provide JSDoc's parsed output programmatically at a time when no official library existed for this purpose.

testing
npm install jsdoc3-parser
github ↗package ↗
INSTALL
IMPORT
SIG · JSDOC3-PARSER
J
jsdoc3-parser
testingjavascriptv3.0.0
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

parser
✓ const parser = require('jsdoc3-parser');
✗ import parser from 'jsdoc3-parser';
The package was last updated in 2023 and primarily supports CommonJS `require()` syntax. There is no indication of official ESM support.

This example demonstrates how to parse a JavaScript file containing JSDoc comments to retrieve its AST (doclets) using `jsdoc3-parser`. It writes a temporary file, parses it, and then logs parts of the resulting JSDoc AST.

const parser = require('jsdoc3-parser'); const path = require('path'); const fs = require('fs'); const tempJsFile = path.join(__dirname, 'tempFileForParsing.js'); const jsContent = ` /** * Represents a point in 2D space. * @class * @param {number} x - The x-coordinate. * @param {number} y - The y-coordinate. */ function Point(x, y) { /** * The x-coordinate. * @type {number} */ this.x = x; /** * The y-coordinate. * @type {number} */ this.y = y; } /** * Calculates the distance from this point to another point. * @param {Point} otherPoint - The other point. * @returns {number} The distance between the two points. */ Point.prototype.distance = function(otherPoint) { const dx = this.x - otherPoint.x; const dy = this.y - otherPoint.y; return Math.sqrt(dx * dx + dy * dy); }; `; fs.writeFileSync(tempJsFile, jsContent); parser(tempJsFile, function(error, ast) { if (error) { console.error('Error parsing file:', error); return; } console.log('Successfully parsed JSDoc AST for:', tempJsFile); // The AST is an array of JSDoc doclets console.log(JSON.stringify(ast[0], null, 2)); console.log(JSON.stringify(ast[1], null, 2)); console.log(JSON.stringify(ast[2], null, 2)); fs.unlinkSync(tempJsFile); // Clean up temp file });
Debug
Known issues
breakingThis package relies on the internal `-X` option of the JSDoc CLI. Future versions of JSDoc may change the format of this output or remove the option entirely, which would break `jsdoc3-parser` functionality without a corresponding update.
fix
Migrate to `@jsdoc/parse` for official and stable programmatic JSDoc parsing, or carefully pin JSDoc CLI version.
affects: >=3.0.0
gotchaThe package requires the JSDoc CLI tool to be installed globally or available in the system's PATH. It does not manage the JSDoc dependency itself, leading to potential 'command not found' errors if JSDoc is not set up correctly.
fix
Ensure JSDoc is installed and globally accessible (e.g., `npm install -g jsdoc`) or configured in your environment's PATH.
affects: >=1.0.0
deprecatedThe fundamental premise of this package—providing programmatic access to JSDoc's parser via CLI scraping—is now deprecated. The official JSDoc project offers `@jsdoc/parse` as a direct, npm-installable library for parsing JSDoc comments programmatically.
fix
Transition to using `@jsdoc/parse` for modern, stable, and direct programmatic JSDoc parsing. Consider alternatives like `jsdoc-parse` or `jsdoctypeparser` for specific AST needs.
affects: >=3.0.0
gotchaThis package, last updated three years ago, is unlikely to fully support modern JavaScript syntax (ESM, newer language features) in its parsing capabilities without updates to the underlying JSDoc CLI version it was designed to interact with.
fix
For projects using modern JavaScript, consider `@jsdoc/parse` or other actively maintained AST parsers that are kept up-to-date with ECMAScript specifications.
affects: >=3.0.0
Errors
Common errors & fixes
Error: Command failed: jsdoc -X
The JSDoc command-line tool is not found in the system's PATH or is not installed.
fix
Install JSDoc globally: `npm install -g jsdoc`, or ensure its executable path is correctly configured in your environment.
TypeError: parser is not a function
Attempting to use `jsdoc3-parser` with ESM `import` syntax or incorrect CommonJS usage, when the package is designed for CommonJS `require()` and exports a function directly.
fix
Ensure you are using CommonJS `const parser = require('jsdoc3-parser');` and calling `parser(filePath, callback)` as shown in the quickstart.
JSDoc -X output format changed, cannot parse
An updated version of the JSDoc CLI has altered the structure of its `-X` command's JSON output, which `jsdoc3-parser` expects in a specific format.
fix
Pin your JSDoc CLI version to the one compatible with `jsdoc3-parser` (likely an older JSDoc 3.x version from ~2023), or migrate to `@jsdoc/parse` for more robust parsing.
Upgrade
Version history
3.0.0latest on npm
Audit
Dependencies
jsdocrequiredThis package is a wrapper around the JSDoc command-line interface, specifically using its `-X` option to get AST output. JSDoc must be installed and accessible in the system's PATH, though it is not a direct npm dependency of `jsdoc3-parser`.
Agent activity
8 hits · last 30 days
node
8
Resources
githubhttps://github.com/mrjoelkemp/jsdoc3-parser ↗
packagehttps://www.npmjs.com/package/jsdoc3-parser ↗