JavaScript Parsing

/**
 * Parse JavaScript code into an AST
 * @param code - JavaScript source code to parse
 * @param options - Optional parsing configuration
 * @param delegate - Optional visitor function called for each AST node
 * @returns ESTree-compliant Program node
 */
function parse(code: string, options?: ParseOptions, delegate?: NodeVisitor): Program;

interface ParseOptions {
  /** Include character index ranges in AST nodes */
  range?: boolean;
  /** Include line and column location information in AST nodes */
  loc?: boolean;
  /** Source filename for location tracking */
  source?: string;
  /** Include array of tokens in the result */
  tokens?: boolean;
  /** Include array of comments in the result */
  comment?: boolean;
  /** Attach comments to related AST nodes */
  attachComment?: boolean;
  /** Enable error tolerance mode (continue parsing after errors) */
  tolerant?: boolean;
  /** Enable JSX syntax support */
  jsx?: boolean;
  /** Parsing mode: 'script' for traditional JS, 'module' for ES6 modules */
  sourceType?: 'script' | 'module';
}

type NodeVisitor = (node: Node, metadata: any) => void;

import { parse } from "esprima";

// Basic parsing
const ast = parse("const x = 5;");

// Parsing with location information
const astWithLoc = parse("function test() { return 42; }", {
  range: true,
  loc: true,
  source: "example.js"
});

// Parsing with tokens and comments
const fullAst = parse("/* comment */ var y = 10;", {
  tokens: true,
  comment: true,
  attachComment: true
});

// JSX parsing
const jsxAst = parse("<div>Hello World</div>", { jsx: true });

// Tolerant parsing (continues despite errors)
const tolerantAst = parse("var broken = ;", { tolerant: true });
console.log(tolerantAst.errors); // Array of parsing errors

/**
 * Parse JavaScript code as a script
 * @param code - JavaScript source code to parse
 * @param options - Optional parsing configuration (sourceType forced to 'script')
 * @param delegate - Optional visitor function called for each AST node
 * @returns Program node with sourceType: 'script'
 */
function parseScript(code: string, options?: ParseOptions, delegate?: NodeVisitor): Program;

import { parseScript } from "esprima";

// Parse as script (allows global declarations)
const scriptAst = parseScript(`
  var global = true;
  function helper() { return global; }
`);

// Script with options
const scriptWithTokens = parseScript("console.log('Hello');", {
  tokens: true,
  range: true
});

/**
 * Parse JavaScript code as a module
 * @param code - JavaScript source code to parse
 * @param options - Optional parsing configuration (sourceType forced to 'module')
 * @param delegate - Optional visitor function called for each AST node
 * @returns Program node with sourceType: 'module'
 */
function parseModule(code: string, options?: ParseOptions, delegate?: NodeVisitor): Program;

import { parseModule } from "esprima";

// Parse as module (allows import/export)
const moduleAst = parseModule(`
  import { helper } from './utils';
  export const result = helper();
`);

// Module with location tracking
const moduleWithLoc = parseModule("export default function() {}", {
  loc: true,
  range: true
});

interface Program {
  type: 'Program';
  body: Statement[];
  sourceType: 'script' | 'module';
  range?: [number, number];
  loc?: SourceLocation;
  comments?: Comment[];
  tokens?: Token[];
  errors?: ParseError[];
}

interface SourceLocation {
  start: Position;
  end: Position;
  source?: string;
}

interface Position {
  line: number;
  column: number;
}

interface Comment {
  type: 'Line' | 'Block';
  value: string;
  range?: [number, number];
  loc?: SourceLocation;
}

interface ParseError {
  name: string;
  message: string;
  index: number;
  lineNumber: number;
  column: number;
  description: string;
}

/**
 * Visitor function called for each AST node during parsing
 * @param node - Current AST node being processed
 * @param metadata - Additional metadata about the node
 */
type NodeVisitor = (node: Node, metadata: any) => void;

import { parse } from "esprima";

const nodes: string[] = [];
parse("function test() { var x = 1; }", {}, (node, metadata) => {
  nodes.push(node.type);
});
console.log(nodes); // ['Program', 'FunctionDeclaration', 'BlockStatement', ...]

import { parse } from "esprima";

try {
  const ast = parse("var x = ;"); // Syntax error
} catch (error) {
  console.log(error.message); // "Unexpected token ;"
  console.log(error.lineNumber); // 1
  console.log(error.column); // 8
}

import { parse } from "esprima";

const ast = parse("var x = ; var y = 2;", { tolerant: true });
console.log(ast.errors[0].message); // "Unexpected token ;"
console.log(ast.body.length); // 2 (both statements parsed despite error)