{"id":13395,"library":"jsdoc-type-pratt-parser","title":"JSDoc Type Pratt Parser","description":"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.","status":"active","version":"7.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/jsdoc-type-pratt-parser/jsdoc-type-pratt-parser","tags":["javascript","jsdoc","pratt","parser","typescript"],"install":[{"cmd":"npm install jsdoc-type-pratt-parser","lang":"bash","label":"npm"},{"cmd":"yarn add jsdoc-type-pratt-parser","lang":"bash","label":"yarn"},{"cmd":"pnpm add jsdoc-type-pratt-parser","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This library is primarily designed for ESM consumption, though modern Node.js environments can interoperate with CJS via `import`.","wrong":"const { parse } = require('jsdoc-type-pratt-parser')","symbol":"parse","correct":"import { parse } from 'jsdoc-type-pratt-parser'"},{"note":"Both `parse` and `stringify` are named exports from the main package entry point.","wrong":"import stringify from 'jsdoc-type-pratt-parser/stringify'","symbol":"stringify","correct":"import { stringify } from 'jsdoc-type-pratt-parser'"},{"note":"When importing only types, use `import type` for clarity and better tree-shaking in modern TypeScript environments.","wrong":"import { JsdocType } from 'jsdoc-type-pratt-parser'","symbol":"JsdocType","correct":"import { type JsdocType } from 'jsdoc-type-pratt-parser'"}],"quickstart":{"code":"import { parse, stringify, type JsdocType } from 'jsdoc-type-pratt-parser';\n\nasync function main() {\n  // Parse a complex JSDoc type expression using the TypeScript grammar\n  const typeExpression = 'Promise<Array<string | number> | {name: string, age?: number}>';\n  console.log(`Parsing: \"${typeExpression}\"`);\n  const ast: JsdocType = parse(typeExpression, 'typescript');\n  console.log('Parsed AST (simplified):', JSON.stringify(ast, null, 2));\n\n  // Accessing parts of the AST (e.g., the top-level type)\n  if (ast.type === 'JsdocTypeUnion' && ast.elements) {\n    console.log('First element of union:', JSON.stringify(ast.elements[0], null, 2));\n  }\n\n  // Stringify the AST back to a type expression\n  const stringified = stringify(ast);\n  console.log(`Stringified AST: \"${stringified}\"`);\n\n  // Example of parsing a JSDoc-specific type, like a callback\n  const jsdocCallbackType = 'function(this: MyClass, ...args: Array<any>): Promise<void>';\n  console.log(`\\nParsing JSDoc callback: \"${jsdocCallbackType}\"`);\n  const callbackAst = parse(jsdocCallbackType, 'jsdoc');\n  console.log('Parsed callback AST (type):', callbackAst.type);\n}\n\nmain().catch(console.error);","lang":"typescript","description":"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."},"warnings":[{"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.","message":"Version 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`.","severity":"breaking","affected_versions":">=7.0.0"},{"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')`).","message":"It 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"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.","error":"TypeError: (0 , jsdoc_type_pratt_parser__WEBPACK_IMPORTED_MODULE_0__.parse) is not a function"},{"fix":"Specify the `'typescript'` grammar when parsing type expressions that utilize TypeScript-specific syntax: `parse(typeExpression, 'typescript');`.","cause":"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.","error":"SyntaxError: Unexpected token '?'"},{"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.","cause":"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.","error":"Error: Cannot find module 'jsdoc-type-pratt-parser'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null}