Google Closure Compiler and JSDoc Type Expression Parser

Common errors

• TypeError: catharsis.parse is not a function

  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.
  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(...);`

• Error: Unable to parse [...]

  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.
  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.

Warnings

• gotcha 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.
  Fix: Pass `{ jsdoc: true }` as the second argument to `catharsis.parse()` for JSDoc-specific expressions.
• breaking 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).
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install catharsis npm
• yarn add catharsis yarn
• pnpm add catharsis pnpm

Imports

• catharsis
  wrong:

  import { catharsis } from 'catharsis';

  correct:

  import catharsis from 'catharsis';

  The package exports a single object containing all methods. For CommonJS environments, use `const catharsis = require('catharsis');`
• parse
  wrong:

  import { parse } from 'catharsis';

  correct:

  import catharsis from 'catharsis';
  catharsis.parse(typeExpression, options);

  `parse` is a method of the default exported `catharsis` object, not a direct named export. Access it via the imported `catharsis` object.
• stringify
  wrong:

  import { stringify } from 'catharsis';

  correct:

  import catharsis from 'catharsis';
  catharsis.stringify(parsedType, options);

  `stringify` is a method of the default exported `catharsis` object, not a direct named export. Access it via the imported `catharsis` object.
• describe
  wrong:

  import { describe } from 'catharsis';

  correct:

  import catharsis from 'catharsis';
  catharsis.describe(parsedType);

  `describe` is a method of the default exported `catharsis` object, not a direct named export. Access it via the imported `catharsis` object.

Quickstart

Demonstrates parsing both Closure Compiler and JSDoc-style type expressions, then stringifying and describing the results, including HTML-safe output.

import catharsis from 'catharsis';

// --- Closure Compiler Style Parsing ---
const closureType = '!Object';
let parsedClosureType;
try {
  parsedClosureType = catharsis.parse(closureType);
  console.log('Parsed Closure Type:', JSON.stringify(parsedClosureType));
  console.log('Stringified:', catharsis.stringify(parsedClosureType));
  console.log('Description:', catharsis.describe(parsedClosureType).simple);
} catch (e) {
  console.error(`Unable to parse '${closureType}':`, e.message);
}

// --- JSDoc Style Parsing (requires 'jsdoc: true') ---
const jsdocType = 'string[]'; // Equivalent to Closure Compiler's Array<string>
let parsedJsdocType;
try {
  parsedJsdocType = catharsis.parse(jsdocType, { jsdoc: true });
  console.log('Parsed JSDoc Type:', JSON.stringify(parsedJsdocType));
  console.log('Stringified:', catharsis.stringify(parsedJsdocType));
  console.log('Description:', catharsis.describe(parsedJsdocType).simple);
} catch (e) {
  console.error(`Unable to parse '${jsdocType}':`, e.message);
}

// --- HTML-safe Stringification ---
const typeWithGenerics = 'Array<number>';
const parsedGenerics = catharsis.parse(typeWithGenerics);
console.log('HTML-safe stringify:', catharsis.stringify(parsedGenerics, { htmlSafe: true }));