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

npm install shift-parser

github ↗package ↗

INSTALL

IMPORT

SIG · SHIFT-PARSER

shift-parser

serializationjavascriptv8.0.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 'shift-parser';

✗ import { parse } from 'shift-parser';

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

parseScript, parseModule

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

✗ const { parseScript, parseModule } = require('shift-parser');

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

parseScriptWithLocation, parseModuleWithLocation

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

✗ const { parseScriptWithLocation } = require('shift-parser'); // CJS style, less common in new projects

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.

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 issues

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.

fix

Assume broader modern ECMAScript feature support (up to ES2019) than stated in the README for `shift-parser` v8.x. Always test with specific features if uncertain.

affects: >=1.0.0

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.

fix

Always use `parseModule` for ECMAScript modules (files with `import`/`export` statements) and `parseScript` for standard scripts to avoid parsing errors related to context.

affects: >=1.0.0

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.

fix

Ensure that the JavaScript environment where `shift-parser` is executed supports `WeakMap` if location tracking is a critical feature. For most modern Node.js and browser targets, this is not an issue.

affects: >=1.0.0

Errors

Common errors & fixes

SyntaxError: Unexpected token 'import'

Attempting to parse an ECMAScript module using the `parseScript` function.

fix

Use `import { parseModule } from 'shift-parser';` or `import { parseModuleWithLocation } from 'shift-parser';` for code containing `import`/`export` statements.

SyntaxError: Invalid or unexpected token

The input string provided to the parser contains invalid ECMAScript syntax.

fix

Review the input JavaScript code for syntax errors. `shift-parser` performs strict parsing and will throw an error on malformed code.

TypeError: Cannot read properties of undefined (reading 'get') or 'locations' is undefined

Attempting to access `locations.get()` or the `locations` object itself when using `parseScript` or `parseModule` (which do not return location data) instead of their `WithLocation` counterparts, or in an environment without `WeakMap`.

fix

To retrieve location and comment information, ensure you are using `parseScriptWithLocation` or `parseModuleWithLocation`. Verify `WeakMap` support in your runtime environment if this error persists.

Upgrade

Version history

8.0.0latest on npm

Audit

Dependencies

multimaprequiredInternal data structure for mapping keys to multiple values.

shift-astrequiredCore dependency for defining and working with Shift-format AST nodes.

shift-reducerrequiredUtility for traversing and transforming Shift ASTs.

shift-regexp-acceptorrequiredHandles regular expression parsing and validation.

Agent activity

6 hits · last 30 days

node

Resources

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

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