parse-statements

1.0.12 verified Sat Apr 25 auth: no javascript

Versatile parser for extracting non-overlapping statements from source code in any programming language. Current stable version is 1.0.12 (released October 2022), with no updates since. It enables definition of statement patterns as sequences of token strings, which are internally compiled to regular expressions with gmu flags. Comments can be defined separately and can appear between tokens. The parser supports custom callbacks for parse success, errors, and comments. Callbacks can return a custom end index for each statement, allowing manual extension or truncation. It ships TypeScript type definitions and has zero dependencies. Compared to full AST parsers, this is lightweight and language-agnostic, but requires manual token pattern definition and does not produce an abstract syntax tree.

Common errors

error TypeError: parseStatements is not a function ↓

cause Using default import instead of named import (import parseStatements from 'parse-statements')

fix

Use named import: import { parseStatements } from 'parse-statements'

error SyntaxError: Unexpected token 'export' ↓

cause Using require() to load ESM-only module.

fix

Switch to ESM: add 'type': 'module' in package.json or use import syntax.

error Error: Token ';' is not defined ↓

cause Semicolon token defined as regexp in tokens but used as literal string in statement tokens array.

fix

Define a token entry for ';' or use a regexp pattern directly in the tokens array.

Warnings

breaking parse-statements is ESM-only; using require() will throw an error. ↓

fix Use import syntax or dynamic import().

gotcha Token strings are used to create regexps with gmu flags by default; double-escape backslashes. ↓

fix Use \\ for literal backslashes in token patterns.

gotcha Statements cannot overlap; if tokens match overlapping regions, only the first match is captured. ↓

fix Ensure token patterns are mutually exclusive or order them intentionally.

gotcha Custom end index in onParse callback does not automatically parse comments in the extended region. ↓

fix Manually invoke comment parsing for the extended segment.

Install

npm install parse-statements

yarn add parse-statements

pnpm add parse-statements

Imports

parseStatements

wrong

const parseStatements = require('parse-statements')

correct

import { parseStatements } from 'parse-statements'

Module is ESM-only; CJS require will fail or require default export handling.

StatementParser
```
import { StatementParser } from 'parse-statements'
```
TypeScript type for the parser instance, useful for advanced usage.

ParseOptions

import type { ParseOptions } from 'parse-statements'

Type-only import for configuration object.

Quickstart

Parses function and const declarations from JavaScript-like code using custom token patterns and callbacks.

import { parseStatements } from 'parse-statements';

const code = `function hello() {
  console.log('Hello, world!');
}
const x = 42;`;

const parser = parseStatements({
  statements: [
    {
      tokens: ['function', 'identifier', 'parens', 'parens', 'block'],
      onParse: (ctx, src, tokens) => {
        console.log('Found function:', tokens[1].value);
      },
      onError: (ctx, src, tokens) => {
        console.log('Incomplete function');
      }
    },
    {
      tokens: ['const', 'identifier', '=', 'value', ';'],
      onParse: (ctx, src, tokens) => {
        console.log('Found const:', tokens[1].value);
      }
    }
  ],
  tokens: {
    identifier: /[a-zA-Z_$][a-zA-Z0-9_$]*/,
    parens: /[\(\)]/,
    block: /\{[^}]*\}/,
    value: /[^;]+/,
    ';': ';'
  },
  comments: {
    line: /\/\/.*/
  }
});

parser.parse(code);