TypeScript Parser Combinator

Common errors

• TypeError: Cannot read properties of undefined (reading 'parse')

  cause Attempting to call `.parse()` on a lexer or parser object that hasn't been properly initialized or assigned.
  fix Ensure `buildLexer` is correctly initialized with token definitions and that `rule.setPattern()` has been called for all rules before invoking `.parse()` on them.

• SyntaxError: Expected EOF

  cause The parser successfully consumed a prefix of the input, but unexpected tokens remained at the end, indicating the grammar did not consume the entire input string.
  fix Review your grammar rules to ensure they can consume the entire expected input. Utilize `expectEOF()` appropriately at the end of the top-level parser to enforce full input consumption.

Warnings

• breaking As a pre-1.0 library (current version 0.3.4), the API is considered unstable and may introduce breaking changes in minor or even patch versions. Developers should pin exact versions and review release notes carefully for updates.
  Fix: Pin `typescript-parsec` to a specific version (e.g., `"typescript-parsec": "0.3.4"`) and review GitHub release notes/changelogs before upgrading.
• gotcha For very large input strings or highly complex/ambiguous grammars, unoptimized parser combinators can lead to performance bottlenecks or stack overflow errors due to excessive recursion and backtracking. The library might not include automatic memoization.
  Fix: For performance-critical applications, consider optimizing grammar rules, introducing manual memoization, or breaking down large parsing tasks into smaller, manageable steps.
• gotcha The default error messages generated by parser combinators can sometimes be generic, making it challenging to debug complex parsing failures in production. Pinpointing the exact location and nature of a syntax error might require custom error handling.
  Fix: Implement custom error recovery logic or augment default error messages with more contextual information by wrapping parser results or extending core functionalities.

Install

• npm install typescript-parsec npm
• yarn add typescript-parsec yarn
• pnpm add typescript-parsec pnpm

Imports

• buildLexer
  wrong:

  const { buildLexer } = require('typescript-parsec');

  correct:

  import { buildLexer } from 'typescript-parsec';

  While functional, CommonJS 'require' syntax is generally less common for this TypeScript-first library.
• rule
  wrong:

  import rule from 'typescript-parsec';

  correct:

  import { rule } from 'typescript-parsec';

  `rule` is a named export, not a default export.
• alt, seq, apply
  wrong:

  import { alt, seq } from 'typescript-parsec/dist/parser';

  correct:

  import { alt, seq, apply } from 'typescript-parsec';

  Most core parser combinators are directly exported from the main package path.

Quickstart

Demonstrates how to define a simple arithmetic expression parser using `typescript-parsec`, including lexer definition, parser rules for terms, factors, and expressions, and the evaluation of an example string.

import { buildLexer, expectEOF, expectSingleResult, rule, Token } from 'typescript-parsec';
import { alt, apply, kmid, lrec_sc, seq, str, tok } from 'typescript-parsec';

enum TokenKind {
    Number,
    Add,
    Sub,
    Mul,
    Div,
    LParen,
    RParen,
    Space
}

const lexer = buildLexer([
    [true, /^\d+(\.\d+)?/g, TokenKind.Number],
    [true, /^\+/g, TokenKind.Add],
    [true, /^-/g, TokenKind.Sub],
    [true, /^\*/g, TokenKind.Mul],
    [true, /^\//g, TokenKind.Div],
    [true, /^\(/g, TokenKind.LParen],
    [true, /^\)/g, TokenKind.RParen],
    [false, /^\s+/g, TokenKind.Space]
]);

function applyNumber(value: Token<TokenKind.Number>): number {
    return +value.text;
}

function applyUnary(value: [Token<TokenKind>, number]): number {
    switch (value[0].text) {
        case '+': return +value[1];
        case '-': return -value[1];
        default: throw new Error(`Unknown unary operator: ${value[0].text}`);
    }
}

function applyBinary(first: number, second: [Token<TokenKind>, number]): number {
    switch (second[0].text) {
        case '+': return first + second[1];
        case '-': return first - second[1];
        case '*': return first * second[1];
        case '/': return first / second[1];
        default: throw new Error(`Unknown binary operator: ${second[0].text}`);
    }
}

const TERM = rule<TokenKind, number>();
const FACTOR = rule<TokenKind, number>();
const EXP = rule<TokenKind, number>();

TERM.setPattern(
    alt(
        apply(tok(TokenKind.Number), applyNumber),
        apply(seq(alt(str('+'), str('-')), TERM), applyUnary),
        kmid(str('('), EXP, str(')'))
    )
);

FACTOR.setPattern(
    lrec_sc(TERM, seq(alt(str('*'), str('/')), TERM), applyBinary)
);

EXP.setPattern(
    lrec_sc(FACTOR, seq(alt(str('+'), str('-')), FACTOR), applyBinary)
);

function evaluate(expr: string): number {
    return expectSingleResult(expectEOF(EXP.parse(lexer.parse(expr))));
}

console.log(`(1 + 2) * (3 + 4) = ${evaluate('(1 + 2) * (3 + 4)')}`);