Registry / serialization / jsdoc-type-pratt-parser

jsdoc-type-pratt-parser

JSON →
library7.2.0jsnpmunverified

jsdoc-type-pratt-parser is a robust library designed for parsing JSDoc type expressions into an Abstract Syntax Tree (AST). It offers support for three distinct grammars: 'jsdoc', 'closure', and 'typescript', allowing it to handle a wide range of type syntaxes. Unlike older parsing solutions such as `catharsis` or `jsdoctypeparser` that might rely on tools like PEG.js, this library is built as a Pratt parser, which is a powerful and flexible approach for handling operator precedence in expressions. The package is actively maintained, with frequent releases (e.g., v7.2.0 released in April 2026), and ships with full TypeScript type definitions. Beyond parsing, it provides utilities for transforming and stringifying ASTs, enabling developers to customize the output based on specific requirements, making it a versatile tool for any project dealing with JSDoc type analysis or manipulation. Its key differentiators include its Pratt parser architecture, explicit grammar support, and comprehensive TypeScript integration.

npm install jsdoc-type-pratt-parser
INSTALL
IMPORT
SIG · JSDOC-TYPE-PRATT-P
J
jsdoc-type-pratt-parser
serializationjavascriptv7.2.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
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 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

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

parse
import { parse } from 'jsdoc-type-pratt-parser'
const { parse } = require('jsdoc-type-pratt-parser')
This library is primarily designed for ESM consumption, though modern Node.js environments can interoperate with CJS via `import`.
stringify
import { stringify } from 'jsdoc-type-pratt-parser'
import stringify from 'jsdoc-type-pratt-parser/stringify'
Both `parse` and `stringify` are named exports from the main package entry point.
JsdocType
import { type JsdocType } from 'jsdoc-type-pratt-parser'
import { JsdocType } from 'jsdoc-type-pratt-parser'
When importing only types, use `import type` for clarity and better tree-shaking in modern TypeScript environments.

This quickstart demonstrates parsing a complex TypeScript-style JSDoc type expression into an AST, inspecting a part of the AST, stringifying it back, and then parsing a JSDoc-specific callback type, showcasing the different grammar options.

import { parse, stringify, type JsdocType } from 'jsdoc-type-pratt-parser'; async function main() { // Parse a complex JSDoc type expression using the TypeScript grammar const typeExpression = 'Promise<Array<string | number> | {name: string, age?: number}>'; console.log(`Parsing: "${typeExpression}"`); const ast: JsdocType = parse(typeExpression, 'typescript'); console.log('Parsed AST (simplified):', JSON.stringify(ast, null, 2)); // Accessing parts of the AST (e.g., the top-level type) if (ast.type === 'JsdocTypeUnion' && ast.elements) { console.log('First element of union:', JSON.stringify(ast.elements[0], null, 2)); } // Stringify the AST back to a type expression const stringified = stringify(ast); console.log(`Stringified AST: "${stringified}"`); // Example of parsing a JSDoc-specific type, like a callback const jsdocCallbackType = 'function(this: MyClass, ...args: Array<any>): Promise<void>'; console.log(`\nParsing JSDoc callback: "${jsdocCallbackType}"`); const callbackAst = parse(jsdocCallbackType, 'jsdoc'); console.log('Parsed callback AST (type):', callbackAst.type); } main().catch(console.error);
Debug
Known issues
breakingVersion 7.0.0 introduced a breaking change regarding `infer` in generic argument lists. The `infer: boolean` property on generics was removed in favor of a new root-level `InferResult`.
fix
Review existing code that relies on `infer` within generic argument lists. Adapt to the new `InferResult` structure at the root level of the AST for infer types.
affects: >=7.0.0
gotchaIt is critical to select the correct grammar ('jsdoc', 'closure', or 'typescript') when calling `parse()`. Parsing a TypeScript-specific type expression with the 'jsdoc' grammar, or vice-versa, will likely result in a `SyntaxError` or an incorrectly parsed AST.
fix
Always explicitly specify the `grammar` argument in `parse()` based on the syntax of the JSDoc type expression you are processing (e.g., `parse(typeString, 'typescript')`).
affects: >=1.0.0
gotchaThe AST structure can be deeply nested and complex, especially for intricate type expressions. While API documentation exists, it's noted as incomplete. Direct inspection of the parsed AST is often necessary to understand its exact structure.
fix
Utilize `console.log(JSON.stringify(ast, null, 2))` to pretty-print and inspect the generated AST for specific type expressions, particularly when working with complex or custom type structures.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: (0 , jsdoc_type_pratt_parser__WEBPACK_IMPORTED_MODULE_0__.parse) is not a function
This typically occurs in a JavaScript environment when attempting to use CommonJS `require()` syntax with a package that is primarily designed for ESM (ES Modules), or when using incorrect named import syntax.
fix
Ensure you are using ESM `import` statements: `import { parse } from 'jsdoc-type-pratt-parser';`. If in a CommonJS context, Node.js v20+ typically supports dynamic `import()` or ensures your build system correctly transpiles ESM to CJS.
SyntaxError: Unexpected token '?'
This error, or similar `SyntaxError` messages, often indicates that a type expression using modern TypeScript features (like optional properties `?` or `typeof` operators) is being parsed with an incompatible grammar, such as `'jsdoc'` or `'closure'`. These grammars do not understand TypeScript-specific syntax.
fix
Specify the `'typescript'` grammar when parsing type expressions that utilize TypeScript-specific syntax: `parse(typeExpression, 'typescript');`.
Error: Cannot find module 'jsdoc-type-pratt-parser'
The package is not installed, or the module resolution path is incorrect, or you are attempting to import it in an environment that doesn't correctly resolve `node_modules` or ESM imports.
fix
First, ensure the package is installed: `npm install jsdoc-type-pratt-parser`. Verify your `tsconfig.json` (for TypeScript) or build configuration allows for correct module resolution, especially for ESM packages.
Upgrade
Version history
7.2.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
4 hits · last 30 days
node
4
Resources
jsdoc-type-pratt-parser — npm install jsdoc-type-pratt-parser · libregistry