catharsis

library0.11.0jsnpmunverified

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.

serialization data

npm install catharsis

github ↗package ↗

INSTALL

IMPORT

SIG · CATHARSIS

catharsis

serializationjavascriptv0.11.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

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 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

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

catharsis

✓ import catharsis from 'catharsis';

✗ import { catharsis } from 'catharsis';

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

parse

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

✗ import { parse } from 'catharsis';

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

stringify

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

✗ import { stringify } from 'catharsis';

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

describe

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

✗ import { describe } from 'catharsis';

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

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 }));

Debug

Known issues

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

affects: >=0.1.0

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

affects: >=0.11.0

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

affects: >=0.10.0

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

affects: >=0.11.0

Errors

Common errors & fixes

TypeError: catharsis.parse is not a function

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

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.

Upgrade

Version history

0.11.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

17 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/hegemonic/catharsis ↗

packagehttps://www.npmjs.com/package/catharsis ↗