{"id":14651,"library":"jsdoctypeparser","title":"JSDoc Type Expression Parser","description":"The `jsdoctypeparser` library provides a strict parser for various JavaScript type expression syntaxes, including JSDoc, Closure Compiler, and a subset of TypeScript types. It is currently at version 9.0.0. The library transforms these type expressions into a detailed Abstract Syntax Tree (AST), enabling programmatic analysis and manipulation. It also offers a `publish` function to stringify an AST back into a type expression, with capabilities for custom stringification via a publisher API. Additionally, a `traverse` function allows for AST navigation with `onEnter` and `onLeave` handlers. This tool is crucial for projects needing to deeply understand, validate, or transform JSDoc-style type annotations, serving as a foundational component for linters, documentation generators, and code transformation tools. Its differentiators lie in its strict parsing capabilities across multiple dialects and its comprehensive AST manipulation utilities, which allow for a high degree of control over type expression processing. The project maintains an active development status, focusing on robustness and specification adherence.","status":"active","version":"9.0.0","language":"javascript","source_language":"en","source_url":"git://github.com/jsdoctypeparser/jsdoctypeparser","tags":["javascript","jsdoc","type expression","parser"],"install":[{"cmd":"npm install jsdoctypeparser","lang":"bash","label":"npm"},{"cmd":"yarn add jsdoctypeparser","lang":"bash","label":"yarn"},{"cmd":"pnpm add jsdoctypeparser","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The package primarily exports CommonJS modules. Direct named ESM imports (e.g., `import { parse } from 'jsdoctypeparser';`) may not work as expected without a bundler or Node.js module interop configuration. If using ESM, try `import * as JSDocParser from 'jsdoctypeparser'; const { parse } = JSDocParser;`","wrong":"import { parse } from 'jsdoctypeparser';","symbol":"parse","correct":"const { parse } = require('jsdoctypeparser');"},{"note":"This function is a named export. Attempting a default import will fail. Refer to the `parse` import note for general CommonJS/ESM usage considerations.","wrong":"import publish from 'jsdoctypeparser';","symbol":"publish","correct":"const { publish } = require('jsdoctypeparser');"},{"note":"All public APIs are exposed directly from the main package entry point. Importing from internal paths (`/dist/traverse`) is not supported and may break across versions.","wrong":"import { traverse } from 'jsdoctypeparser/dist/traverse';","symbol":"traverse","correct":"const { traverse } = require('jsdoctypeparser');"},{"note":"While the latter `require` syntax might work, destructuring (`const { ... } = require(...)`) is the idiomatic and recommended way to import named exports in CommonJS.","wrong":"const createDefaultPublisher = require('jsdoctypeparser').createDefaultPublisher;","symbol":"createDefaultPublisher","correct":"const { createDefaultPublisher } = require('jsdoctypeparser');"}],"quickstart":{"code":"const { parse, publish, traverse } = require('jsdoctypeparser');\n\n// 1. Parse a complex JSDoc type expression into an AST\nconst typeExpression = 'Array<{ key1: function(number): string, key2: A.B.C | null }>';\nconsole.log(`Parsing: ${typeExpression}`);\nconst ast = parse(typeExpression);\nconsole.log('Generated AST (partial):', JSON.stringify(ast, null, 2).substring(0, 200) + '...');\n\n// 2. Traverse the AST to log node types and their parentage\nconsole.log('\\n--- Traversing AST ---');\ntraverse(ast,\n  (node, parentKey, parentNode) => {\n    const parentInfo = parentNode ? `${parentNode.type} (key: ${parentKey})` : 'none';\n    console.log(`  Enter: ${node.type} (parent: ${parentInfo})`);\n  },\n  (node) => console.log(`  Leave: ${node.type}`)\n);\nconsole.log('--- End Traversal ---\\n');\n\n// 3. Stringify the AST back into a type expression\nconst stringified = publish(ast);\nconsole.log(`Stringified AST back to: ${stringified}`);\n\n// Example with a simpler AST for publishing\nconst simpleAst = { type: 'NAME', name: 'MySimpleType' };\nconsole.log(`\\nStringifying simple AST: ${JSON.stringify(simpleAst)} -> ${publish(simpleAst)}`);","lang":"javascript","description":"This quickstart demonstrates how to parse a JSDoc type expression into an AST, traverse the generated AST, and then stringify it back using `parse`, `traverse`, and `publish` functions."},"warnings":[{"fix":"Consult the project's changelog or release notes for specific AST changes in each major version, and adapt AST processing logic accordingly. Be prepared for adjustments when upgrading.","message":"The Abstract Syntax Tree (AST) structure generated by `parse()` may undergo breaking changes in major version releases. Consumers of the AST should test thoroughly when upgrading to a new major version, as node types, property names, or overall tree shape might be altered to support new syntax or improve internal representation.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Always test with your specific type expressions. For ambiguous or complex types, simplify them if possible or consult the library's source/tests to understand its interpretation. The [live demo](https://jsdoctypeparser.github.io) is an excellent tool to quickly test expressions and view the resulting AST.","message":"`jsdoctypeparser` supports JSDoc, Closure Compiler, and some TypeScript types, but full compatibility with all nuances of each specification, especially TypeScript, is not guaranteed. Subtle differences in how each standard defines or interprets certain expressions might lead to unexpected ASTs or parsing failures for very specific edge cases.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"When creating custom publishers, ensure comprehensive coverage for all `NodeType`s (inspect `lib/NodeType.js`). For AST modification and subsequent publishing, validate published output against expected string representations, especially after manual changes to the AST structure.","message":"While `publish()` can stringify ASTs, direct manipulation of the AST and then publishing might not always produce the exact original string unless the modifications are well-understood. Custom publishers created with `createDefaultPublisher` require handlers for *all* node types, which can be verbose and error-prone if not all types are explicitly handled, leading to unexpected output or errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Integrate with a separate type-checking solution (e.g., TypeScript, Closure Compiler, or custom linters) for semantic validation. Use `jsdoctypeparser` for understanding the *structure* of type annotations and enabling transformations, not for their runtime or compile-time validity.","message":"`jsdoctypeparser` is a lexical and syntactical parser; it converts type expressions into a structured Abstract Syntax Tree. It does not perform semantic analysis, type validation, or type checking against an actual codebase. It cannot determine if a parsed type 'exists' or is 'correct' in the context of your project.","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":"Install the package using your preferred package manager: `npm install jsdoctypeparser` or `yarn add jsdoctypeparser`. Double-check the module name in your code.","cause":"The package is not installed in your project's `node_modules` directory, or there's a typo in the module name in your `require()` or `import` statement.","error":"Error: Cannot find module 'jsdoctypeparser'"},{"fix":"Ensure you are using the correct CommonJS destructuring: `const { parse } = require('jsdoctypeparser');`. If you are in an ESM context, you might need `import * as JSDocParser from 'jsdoctypeparser'; const { parse } = JSDocParser;` or ensure your build tools (e.g., Webpack, Rollup) are configured for CommonJS interop.","cause":"Attempting to use `parse` (or other named exports) as a default import or accessing it incorrectly from the `require()` call, especially when trying to use ESM-style imports (`import { parse } from '...'`) with this CommonJS-first library without proper tooling.","error":"TypeError: parse is not a function"},{"fix":"Review your type expression for grammatical correctness based on JSDoc, Closure Compiler, or the supported TypeScript type subset. Test the problematic expression directly in the [jsdoctypeparser live demo](https://jsdoctypeparser.github.io) to quickly identify the exact parsing error and expected AST.","cause":"The input type expression provided to the `parse()` function contains a syntax error or uses syntax that is not supported by `jsdoctypeparser`.","error":"Error: Failed to parse the type expression: [Your Expression]"}],"ecosystem":"npm"}