{"id":15824,"library":"shift-parser","title":"Shift Parser","description":"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`.","status":"active","version":"8.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/shapesecurity/shift-parser-js","tags":["javascript","Shift","AST","node","parser","SpiderMonkey","Parser","API","parse"],"install":[{"cmd":"npm install shift-parser","lang":"bash","label":"npm"},{"cmd":"yarn add shift-parser","lang":"bash","label":"yarn"},{"cmd":"pnpm add shift-parser","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Internal data structure for mapping keys to multiple values.","package":"multimap","optional":false},{"reason":"Core dependency for defining and working with Shift-format AST nodes.","package":"shift-ast","optional":false},{"reason":"Utility for traversing and transforming Shift ASTs.","package":"shift-reducer","optional":false},{"reason":"Handles regular expression parsing and validation.","package":"shift-regexp-acceptor","optional":false}],"imports":[{"note":"This is the default export for generic parsing, which infers script or module mode. Since v8, ESM imports are preferred.","wrong":"import { parse } from 'shift-parser';","symbol":"parse","correct":"import parse from 'shift-parser';"},{"note":"Explicitly parse code as a script or a module. For modern Node.js and browser environments, ESM `import` is standard.","wrong":"const { parseScript, parseModule } = require('shift-parser');","symbol":"parseScript, parseModule","correct":"import { parseScript, parseModule } from 'shift-parser';"},{"note":"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.","wrong":"const { parseScriptWithLocation } = require('shift-parser'); // CJS style, less common in new projects","symbol":"parseScriptWithLocation, parseModuleWithLocation","correct":"import { parseScriptWithLocation, parseModuleWithLocation } from 'shift-parser';"}],"quickstart":{"code":"import { parseModuleWithLocation } from 'shift-parser';\n\nconst code = `\n  // This is a comment\n  import { add } from './math.js';\n  function calculate(a, b) {\n    const result = add(a, b);\n    return result; // Another comment\n  }\n  console.log(calculate(5, 3));\n`;\n\ntry {\n  const { tree, locations, comments } = parseModuleWithLocation(code);\n\n  console.log('Parsed AST root type:', tree.type);\n  console.log('Number of top-level statements:', tree.statements.length);\n\n  // Accessing a specific node and its location\n  const functionDeclaration = tree.statements[2]; // Assuming 'function calculate' is the third statement\n  if (functionDeclaration && locations.has(functionDeclaration)) {\n    const loc = locations.get(functionDeclaration);\n    console.log(`'calculate' function starts at line ${loc.start.line}, column ${loc.start.column}`);\n  }\n\n  // Logging comments\n  console.log('Found comments:', comments.map(c => c.text));\n\n} catch (e) {\n  if (e instanceof SyntaxError) {\n    console.error('Parsing failed:', e.message);\n  } else {\n    console.error('An unexpected error occurred:', e);\n  }\n}","lang":"typescript","description":"Demonstrates parsing an ECMAScript module, accessing the AST, retrieving location data for nodes, and extracting comments."},"warnings":[{"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.","message":"The 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always use `parseModule` for ECMAScript modules (files with `import`/`export` statements) and `parseScript` for standard scripts to avoid parsing errors related to context.","message":"Incorrectly 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"The `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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Use `import { parseModule } from 'shift-parser';` or `import { parseModuleWithLocation } from 'shift-parser';` for code containing `import`/`export` statements.","cause":"Attempting to parse an ECMAScript module using the `parseScript` function.","error":"SyntaxError: Unexpected token 'import'"},{"fix":"Review the input JavaScript code for syntax errors. `shift-parser` performs strict parsing and will throw an error on malformed code.","cause":"The input string provided to the parser contains invalid ECMAScript syntax.","error":"SyntaxError: Invalid or unexpected token"},{"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.","cause":"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`.","error":"TypeError: Cannot read properties of undefined (reading 'get') or 'locations' is undefined"}],"ecosystem":"npm"}