shift-parser

library8.0.0jsnpmunverified

shift-parser is an ECMAScript parser that generates an Abstract Syntax Tree (AST) conforming to the Shift format. Currently at version 8.0.0, the library provides distinct functions for parsing ECMAScript scripts and modules, offering capabilities for static analysis and code transformation. Although its README suggests support for ECMA-262, version 6 (ES2015), the underlying Shift AST Specification, which `shift-parser` implements, states support for ECMAScript 2019. This indicates the parser likely handles features up to ES2019. The package is generally stable, with major versions released periodically rather than on a strict cadence. A key differentiator is its adherence to the machine-readable Shift AST format, which promotes consistency across various JavaScript tooling. It also offers an extended interface for capturing detailed location and comment information using `WeakMap`.

serialization

github ↗package ↗

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

This is the default export for generic parsing, which infers script or module mode. Since v8, ESM imports are preferred.

import parse from 'shift-parser';

Explicitly parse code as a script or a module. For modern Node.js and browser environments, ESM `import` is standard.

import { parseScript, parseModule } from 'shift-parser';

These functions return the AST along with a `WeakMap` of location data for each node and an array of comments. Preferred for tooling requiring source mapping.

import { parseScriptWithLocation, parseModuleWithLocation } from 'shift-parser';

Demonstrates parsing an ECMAScript module, accessing the AST, retrieving location data for nodes, and extracting comments.

import { parseModuleWithLocation } from 'shift-parser'; const code = ` // This is a comment import { add } from './math.js'; function calculate(a, b) { const result = add(a, b); return result; // Another comment } console.log(calculate(5, 3)); `; try { const { tree, locations, comments } = parseModuleWithLocation(code); console.log('Parsed AST root type:', tree.type); console.log('Number of top-level statements:', tree.statements.length); // Accessing a specific node and its location const functionDeclaration = tree.statements[2]; // Assuming 'function calculate' is the third statement if (functionDeclaration && locations.has(functionDeclaration)) { const loc = locations.get(functionDeclaration); console.log(`'calculate' function starts at line ${loc.start.line}, column ${loc.start.column}`); } // Logging comments console.log('Found comments:', comments.map(c => c.text)); } catch (e) { if (e instanceof SyntaxError) { console.error('Parsing failed:', e.message); } else { console.error('An unexpected error occurred:', e); } }

Debug

Known footguns

gotchaThe package's README currently states support for ECMA-262 version 6 (ES2015). However, the Shift AST Specification, which shift-parser implements, explicitly supports ECMAScript 2019. Users should be aware that the parser likely handles features up to ES2019 despite the outdated documentation.

gotchaIncorrectly using `parseScript` for code that contains module-specific syntax (like `import` or `export` declarations) will result in a `SyntaxError`. Conversely, `parseModule` may enforce strict mode or other module-specific behaviors.

gotchaThe `parseScriptWithLocation` and `parseModuleWithLocation` functions return location data via a `WeakMap`. While modern environments generally support `WeakMap`, older or highly constrained environments might not, leading to unexpected behavior if location data is relied upon.

Upgrade

Version history

Breaking-change detection hasn't run for this library yet.

Audit

Security & dependencies

CVE tracking and dependency tree are planned for a later release.

Agent activity

0 hits · last 30 days

No traffic data recorded yet.

Resources

githubhttps://github.com/shapesecurity/shift-parser-js ↗

packagehttps://www.npmjs.com/package/shift-parser ↗