ts-pegjs

4.2.1 verified Sat Apr 25 auth: no javascript

TS PEG.js is a TypeScript code generation plugin for peggy parser generator (v3+). Current stable version is 4.2.1, compatible with peggy ^3.0.2. It generates TypeScript parsers from PEG grammars, supporting custom headers, return type annotations, and various options for type computation. Key differentiators: first-class TypeScript output, supports both CommonJS and ESM formats, and integrates seamlessly with peggy's CLI and API. Previously supported pegjs, now exclusively peggy. Notable breaking changes in v3.0.0 include renaming exported interfaces (dropping 'I' prefix) and changing the default error name from SyntaxError to PeggySyntaxError.

Common errors

error Error: Cannot find module 'peggy' ↓

cause Missing peer dependency peggy

fix

Run 'npm install peggy' or 'yarn add peggy' to install the required peggy parser.

error TypeError: peggy.generate is not a function ↓

cause Incorrect import: peggy module does not export generate directly; must use default import or require

fix

Use: import peggy from 'peggy'; then peggy.generate(...)

error Error: Plugin is not a function or does not have a use method ↓

cause Passing ts-pegjs incorrectly; plugin must be an object with a use method

fix

Ensure tspegjs is imported correctly: const tspegjs = require('ts-pegjs'); or import tspegjs from 'ts-pegjs';

error TypeScript error: 'ParseOptions' is not exported from 'ts-pegjs' ↓

cause Using v3+ with old interface names that had 'I' prefix

fix

Use the new names: ParseOptions, Cached, TraceEvent, EndExpectation, OtherExpectation.

error Error: The 'tspegjs' option must be an object ↓

cause Passing tspegjs options directly instead of under tspegjs key

fix

Nest options under a 'tspegjs' property: { tspegjs: { customHeader: '...' } }

Warnings

breaking In v3.0.0, default errorName changed from SyntaxError to PeggySyntaxError ↓

fix Update code that catches SyntaxError to catch PeggySyntaxError, or set errorName option back to 'SyntaxError'.

breaking In v3.0.0, exported interfaces renamed without 'I' prefix (e.g., IParseOptions -> ParseOptions) ↓

fix Update import statements to use new interface names: ParseOptions, Cached, TraceEvent, EndExpectation, OtherExpectation.

deprecated Support for pegjs (v1 and v2) has been removed; only peggy is supported ↓

fix Migrate from pegjs to peggy and update grammars if needed.

gotcha If skipTypeComputation is true, returnTypes option is ignored ↓

fix Either set skipTypeComputation to false (default) or manually provide all return types via returnTypes.

gotcha CamelCase conversion of type names applies by default; use doNotCamelCaseTypes to disable ↓

fix If your grammar uses camelCase rule names, set doNotCamelCaseTypes: true to preserve original casing.

gotcha Plugin options must be passed under tspegjs key in peggy config object ↓

fix Ensure all ts-pegjs options are nested under tspegjs: { ... } in the peggy.generate options object.

breaking Version 2.0.0 dropped support for pegjs and introduced peggy as peer dependency ↓

fix Install peggy instead of pegjs and update import paths.

Install

npm install ts-pegjs

yarn add ts-pegjs

pnpm add ts-pegjs

Imports

tspegjs (default import)
wrong
```
const tspegjs = require('ts-pegjs');
```
correct
```
import tspegjs from 'ts-pegjs';
```
ESM-only since v3; CommonJS require works but not recommended.
tspegjs plugin object
```
const tspegjs = require('ts-pegjs');
```
For CommonJS environments; the module exports the plugin object directly.

TypeScript types

wrong

import { ParseOptions } from 'ts-pegjs';

correct

import type { ParseOptions, SourceNode } from 'ts-pegjs';

Type-only imports are supported; types are available in d.ts files.

Quickstart

Generates a TypeScript parser from a simple arithmetic grammar using peggy and ts-pegjs plugin, with return type annotations.

import peggy from 'peggy';
import tspegjs from 'ts-pegjs';

const grammar = `
  expr = additive
  additive = multiplicative ("+" multiplicative / "-" multiplicative)*
  multiplicative = primary ("*" primary / "/" primary)*
  primary = number / "(" expr ")"
  number = digits:[0-9]+ { return parseInt(digits.join(''), 10); }
`;

const source = peggy.generate(grammar, {
  output: 'source',
  format: 'commonjs',
  plugins: [tspegjs],
  tspegjs: {
    customHeader: '// Generated parser',
    returnTypes: {
      expr: 'number',
      additive: 'number',
      multiplicative: 'number',
      primary: 'number',
      number: 'number'
    }
  }
});

console.log(source);