{"id":10614,"library":"catharsis","title":"Google Closure Compiler and JSDoc Type Expression Parser","description":"Catharsis is a JavaScript library designed for parsing and manipulating type expressions used by Google Closure Compiler and JSDoc. It provides robust capabilities to convert these expressions into a structured Abstract Syntax Tree (AST), and then back into a string or a human-readable description. The current stable version is 0.11.0, last published about a year ago, indicating an irregular or maintenance-focused release cadence. Key differentiators include its high accuracy, backed by a Peggy grammar and a comprehensive test suite, and its flexibility in handling both standard Closure Compiler syntax and JSDoc-specific extensions like `string[]` for `Array<string>`. This library is primarily used by tools and systems that need to interpret or generate type annotations, offering programmatic access to the structure and meaning of complex type expressions.","status":"maintenance","version":"0.11.0","language":"javascript","source_language":"en","source_url":"https://github.com/hegemonic/catharsis","tags":["javascript"],"install":[{"cmd":"npm install catharsis","lang":"bash","label":"npm"},{"cmd":"yarn add catharsis","lang":"bash","label":"yarn"},{"cmd":"pnpm add catharsis","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The package exports a single object containing all methods. For CommonJS environments, use `const catharsis = require('catharsis');`","wrong":"import { catharsis } from 'catharsis';","symbol":"catharsis","correct":"import catharsis from 'catharsis';"},{"note":"`parse` is a method of the default exported `catharsis` object, not a direct named export. Access it via the imported `catharsis` object.","wrong":"import { parse } from 'catharsis';","symbol":"parse","correct":"import catharsis from 'catharsis';\ncatharsis.parse(typeExpression, options);"},{"note":"`stringify` is a method of the default exported `catharsis` object, not a direct named export. Access it via the imported `catharsis` object.","wrong":"import { stringify } from 'catharsis';","symbol":"stringify","correct":"import catharsis from 'catharsis';\ncatharsis.stringify(parsedType, options);"},{"note":"`describe` is a method of the default exported `catharsis` object, not a direct named export. Access it via the imported `catharsis` object.","wrong":"import { describe } from 'catharsis';","symbol":"describe","correct":"import catharsis from 'catharsis';\ncatharsis.describe(parsedType);"}],"quickstart":{"code":"import catharsis from 'catharsis';\n\n// --- Closure Compiler Style Parsing ---\nconst closureType = '!Object';\nlet parsedClosureType;\ntry {\n  parsedClosureType = catharsis.parse(closureType);\n  console.log('Parsed Closure Type:', JSON.stringify(parsedClosureType));\n  console.log('Stringified:', catharsis.stringify(parsedClosureType));\n  console.log('Description:', catharsis.describe(parsedClosureType).simple);\n} catch (e) {\n  console.error(`Unable to parse '${closureType}':`, e.message);\n}\n\n// --- JSDoc Style Parsing (requires 'jsdoc: true') ---\nconst jsdocType = 'string[]'; // Equivalent to Closure Compiler's Array<string>\nlet parsedJsdocType;\ntry {\n  parsedJsdocType = catharsis.parse(jsdocType, { jsdoc: true });\n  console.log('Parsed JSDoc Type:', JSON.stringify(parsedJsdocType));\n  console.log('Stringified:', catharsis.stringify(parsedJsdocType));\n  console.log('Description:', catharsis.describe(parsedJsdocType).simple);\n} catch (e) {\n  console.error(`Unable to parse '${jsdocType}':`, e.message);\n}\n\n// --- HTML-safe Stringification ---\nconst typeWithGenerics = 'Array<number>';\nconst parsedGenerics = catharsis.parse(typeWithGenerics);\nconsole.log('HTML-safe stringify:', catharsis.stringify(parsedGenerics, { htmlSafe: true }));","lang":"typescript","description":"Demonstrates parsing both Closure Compiler and JSDoc-style type expressions, then stringifying and describing the results, including HTML-safe output."},"warnings":[{"fix":"Pass `{ jsdoc: true }` as the second argument to `catharsis.parse()` for JSDoc-specific expressions.","message":"Parsing JSDoc-style type expressions requires explicitly enabling the `jsdoc` option in the `parse()` method. Without it, JSDoc-specific syntax like `string[]` will fail to parse correctly.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Ensure your code relies on the generated string from `stringify()` and remove any usage of `options.cssClass`. If caching was previously performed, implement external caching as Catharsis no longer caches return values internally.","message":"Since version 0.11.0, the `stringify()` method now always re-stringifies the parsed type object rather than potentially returning the original input string. Additionally, the `options.cssClass` property for `stringify()` and `describe()` methods has been removed (it was deprecated in 0.8.0).","severity":"breaking","affected_versions":">=0.11.0"},{"fix":"Manually escape or sanitize name expressions if they are derived from untrusted input and are intended for HTML output, even when `htmlSafe` is enabled.","message":"When using `stringify()` with `options.htmlSafe: true`, only angle brackets (`<` and `>`) are escaped. Characters within name expressions (e.g., `MyClass<string>`) are not escaped, which might lead to unexpected rendering if names contain special HTML characters.","severity":"gotcha","affected_versions":">=0.10.0"},{"fix":"Consider the long-term support implications for projects requiring ongoing feature enhancements or rapid adaptation to new language features in JSDoc/Closure Compiler. Ensure the existing functionality meets all project requirements.","message":"The `catharsis` package currently appears to be in maintenance mode. While functional and stable, active feature development or frequent updates should not be expected. The latest version was published over a year ago.","severity":"gotcha","affected_versions":">=0.11.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 importing the default export object and accessing its methods: `import catharsis from 'catharsis'; catharsis.parse(...);` or for CommonJS: `const catharsis = require('catharsis'); catharsis.parse(...);`","cause":"The `catharsis` module was imported incorrectly, leading to its methods not being accessible on the imported object. This often happens when attempting named imports (`import { parse } from 'catharsis';`) for a package that only provides a default export object.","error":"TypeError: catharsis.parse is not a function"},{"fix":"Review the type expression for syntax errors. If parsing JSDoc-specific syntax (e.g., `string[]`, `function`), ensure `catharsis.parse(expression, { jsdoc: true })` is used.","cause":"The provided type expression does not conform to either Google Closure Compiler or JSDoc type expression syntax, or the `jsdoc: true` option was not enabled for JSDoc-specific syntax.","error":"Error: Unable to parse [...]"}],"ecosystem":"npm"}