cst

library1.2.0jsnpmunverified

The `cst` package provides a Concrete Syntax Tree (CST) implementation for JavaScript, distinguishing itself from Abstract Syntax Trees (ASTs) by preserving all source code information, including whitespace, comments, and punctuation. This makes it particularly useful for applications requiring precise code transformation, refactoring, linting, and style enforcement, where original formatting must be maintained. The library aims for 100% compatibility with the ESTree AST specification, ensuring that its `Node` structures align with standard AST representations. A core principle is that the tree always remains valid, protecting against structural inconsistencies during modifications. The current stable version is 0.4.10, but its last publish date was over six years ago, indicating that it is in a maintenance state with no active development or new releases. Despite this, its core functionality for detailed source code representation and manipulation remains sound. Key differentiators include its complete representation of the source text, ESTree AST compatibility, and robust mutation methods designed to preserve code integrity and formatting.

serialization devops http-networking

npm install cst

github ↗package ↗

INSTALL

IMPORT

SIG · CST

cst

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

parse

✓ import { parse } from 'cst';

✗ const parse = require('cst').parse;

The primary function to convert a JavaScript string into a CST. Uses named export.

Node

✓ import { Node } from 'cst';

✗ import Node from 'cst';

Represents AST-like structures within the CST, extending the base Element class. Used for type checking and structural traversal.

Token

✓ import { Token } from 'cst';

✗ import { CSTToken } from 'cst';

Represents the atomic lexical units (like identifiers, operators, whitespace, comments) of the source code. Essential for fine-grained manipulation.

Demonstrates parsing JavaScript code into a CST, traversing the tree to find a specific string literal token, and then modifying that token's value while preserving surrounding whitespace and comments.

import { parse, Token, Node } from 'cst'; const code = ` function greet(name) { // Say hello to someone console.log('Hello, ' + name + '!'); } greet('World'); // We'll change this `; // Parse the code into a CST const tree = parse(code); console.log('Original Code:\n', tree.getSourceCode()); let worldToken: Token | undefined; // Find the 'World' string literal token tree.childElements.forEach(element => { if (element.isNode && (element as Node).type === 'ExpressionStatement') { const callExpr = element.childElements.find(c => c.isNode && (c as Node).type === 'CallExpression') as Node; if (callExpr) { const literalNode = callExpr.childElements.find(c => c.isNode && (c as Node).type === 'Literal') as Node; if (literalNode) { const tokenChild = literalNode.getFirstToken(); if (tokenChild && tokenChild.value === "'World'") { worldToken = tokenChild; } } } } }); if (worldToken) { const parentOfWorldToken = worldToken.parentElement; if (parentOfWorldToken) { // Create a new token for 'CST User' const newUserToken = new Token('String', "'CST User'"); // Replace the old token within its parent Node parentOfWorldToken.replaceChildren(newUserToken, worldToken, worldToken); console.log('\nModified Code (Changed String Literal):\n', tree.getSourceCode()); } } else { console.log('\nCould not find "World" token to modify.'); }

Debug

Known issues

breakingSupport for JavaScript Comprehensions (an older, non-standardized feature) was removed. Code relying on parsing or manipulating comprehensions will break.

fix

Update code to use standard JavaScript array/generator syntax or ensure input does not contain comprehensions.

affects: >=0.0.11

gotchaThe `Token.cloneElement` method had a bug that was fixed in v0.0.11. If you were relying on specific (potentially incorrect) behavior of cloning tokens in older versions, this fix might subtly change outcomes.

fix

Review any code that uses `Token.cloneElement` (or its inherited version) to ensure it behaves as expected after the fix.

affects: >=0.0.11

gotchaCST modification primarily occurs by replacing `Element`s (Nodes or Tokens) within their parent's children. Direct modification of `value` properties on `Token` instances is not supported, as tokens are generally immutable. You must create a new `Token` and replace the old one.

fix

Always use methods like `parent.replaceChildren(newElement, oldElementRef, oldElementRef)` to perform modifications, constructing new `Node` or `Token` instances as needed.

affects: >=0.0.1

Errors

Common errors & fixes

SyntaxError: Unexpected token (X:Y)

The input JavaScript string provided to `parse()` contains a syntax error or an unsupported language feature.

fix

Ensure the input string is valid JavaScript code compatible with the parser's grammar (ES5/ES6+). Check the exact line and column indicated in the error message.

TypeError: someElement.replaceChildren is not a function

Attempting to call `replaceChildren` or similar mutation methods on an `Element` that does not support it (e.g., a `Token` which cannot have children, or an `Element` not yet attached to a tree).

fix

Verify that `someElement` is a `Node` and is the parent of the `Element`s you intend to replace. Ensure the parent element is part of a valid CST structure.

TypeError: Cannot read properties of undefined (reading 'getSourceCode')

This usually indicates that the `tree` object (or an `Element` within it) is `undefined` or `null`, potentially because `parse()` failed or a traversal path led to an invalid element.

fix

Add error handling around `parse()` calls and null checks when traversing the CST, especially after operations that might return `undefined`.

Upgrade

Version history

1.2.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

13 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/cst/cst ↗

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