peggy

library5.1.0jsnpmunverified

Peggy is a robust, open-source parser generator for JavaScript that serves as the successor to the popular PEG.js project. It enables developers to define grammars using a simple and expressive syntax based on parsing expression grammar (PEG) formalism, which is more powerful than traditional LL(k) and LR(k) parsers. Peggy integrates both lexical and syntactical analysis and produces fast parsers with excellent error reporting capabilities. The current stable version is 5.1.0, with regular patch and minor releases, and major versions released less frequently. Key differentiators include its superior error reporting, integration of lexical and syntactical analysis, and being usable across various environments: browsers (via an online tool), command line, and as a JavaScript API. It also provides source map support and ships with TypeScript definitions, making it well-suited for modern JavaScript and TypeScript development workflows. It requires Node.js version 20 or higher.

devops web-framework

npm install peggy

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PEGGY

peggy

devopsjavascriptv5.1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

generate

✓ import { generate } from 'peggy';

✗ const generate = require('peggy').generate;

The primary function for compiling a PEG grammar string into a parser. CommonJS `require` is still supported but ESM `import` is preferred for modern Node.js environments.

SyntaxError

✓ import { SyntaxError } from 'peggy';

✗ import { PeggySyntaxError } from 'peggy';

The custom error class thrown by generated parsers when input does not match the grammar. While exported, it's typically caught from the parser's `parse` method.

cli

✓ import { cli } from 'peggy';

For programmatic access to Peggy's command-line interface functionalities, useful for custom build tools. Most users will invoke `peggy` directly from the command line.

This quickstart demonstrates how to define a simple arithmetic grammar, generate a parser using `peggy.generate`, and then use the generated parser to process an input string. It also illustrates how to catch and handle `SyntaxError` instances thrown by the parser.

import { generate } from 'peggy'; const grammar = ` start = expression expression = term (('+' / '-') term)* term = factor (('*' / '/') factor)* factor = number / '(' expression ')' number 'number' = [0-9]+ { return parseInt(text()); } `; try { const parser = generate(grammar, { output: 'parser', format: 'es' }); const result = parser.parse('1 + 2 * (3 - 4)'); console.log('Parse successful:', result); // Example of a syntax error parser.parse('1 +'); } catch (e: any) { if (e.name === 'SyntaxError') { console.error(`Syntax Error at line ${e.location.start.line}, column ${e.location.start.column}: ${e.message}`); } else { console.error('An unexpected error occurred:', e); } }

peggy --version

Debug

Known issues

breakingPeggy v5.0.0 and later no longer supports ES5 for generated parser code. Generated code now requires ES2020 features (e.g., `const`, `let`). If you need to support earlier runtimes, you must use a transpiler like Babel.

fix

Transpile your generated parser code using Babel or a similar tool if targeting environments older than ES2020, or update your runtime to Node.js >=20.

affects: >=5.0.0

gotchaWhen migrating from PEG.js, all `require('pegjs')` or `import ... from 'pegjs'` statements must be updated to `require('peggy')` or `import ... from 'peggy'`. Similarly, any command-line usage of `pegjs` should be replaced with `peggy`.

fix

Replace all instances of `pegjs` with `peggy` in your code and build scripts.

affects: >=1.0.0

breakingAs of v5.0.6, Peggy switched from `tsc` and `rollup` to `tsup` for its own code generation. This change might be user-visible as `tsup` injects different polyfills, potentially affecting the runtime behavior of Peggy itself if you rely on specific polyfills in a custom build pipeline.

fix

Review your build pipeline and any polyfill assumptions if you encounter unexpected runtime issues after upgrading to v5.0.6 or later, especially if you use Peggy programmatically.

affects: >=5.0.6

gotchaPeggy requires Node.js version 20 or higher. Running Peggy with older Node.js versions will result in errors.

fix

Ensure your development and production environments are running Node.js version 20 or newer.

affects: <5.1.0

gotchaPrevious versions (e.g., 5.0.1, 5.0.2) had TypeScript definition issues related to `SyntaxError` constructor and return types. While fixed in later patches, if you're stuck on an older 5.x patch, you might encounter type-checking problems.

fix

Upgrade to the latest `5.x.x` patch release to benefit from TypeScript definition fixes, such as `5.1.0` or newer.

affects: 5.0.0 - 5.0.2

Errors

Common errors & fixes

Error: Cannot find module 'pegjs'

You have migrated from PEG.js but have not updated all `require` or `import` statements to reference `peggy` instead.

fix

Globally replace `pegjs` with `peggy` in your project's source code and configuration files.

ReferenceError: require is not defined

You are attempting to use CommonJS `require()` syntax for Peggy imports within an ES Module (ESM) context in Node.js, or your generated parser code (pre-v5) is being run in an ESM context without proper transpilation.

fix

For Peggy imports, use `import ... from 'peggy';`. For generated parsers in v5+, ensure your project is configured for ESM or transpile the output if targeting an older CJS environment or browser.

SyntaxError: 'SyntaxError' constructor should not have a return type.

This specific TypeScript error indicates an incompatibility with older `peggy.d.ts` definitions (e.g., from v5.0.1 or v5.0.2) when using TypeScript to compile code that imports `SyntaxError` from 'peggy'.

fix

Update Peggy to the latest `5.x.x` patch version (e.g., 5.1.0) to get the corrected TypeScript definitions.

TypeError: Cannot read properties of undefined (reading 'text')

This often occurs within semantic actions (`{ return text(); }`) in your grammar when `text()` is called outside a rule that has matched any input or if the `text()` function isn't available in the current scope for some reason.

fix

Ensure `text()` is called within a rule's action block and that the rule has successfully matched some input. Verify that the `text()` function is correctly defined and accessible in the context of your generated parser's actions.

Upgrade

Version history

5.1.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/peggyjs/peggy ↗

packagehttps://www.npmjs.com/package/peggy ↗

homepagehttps://peggyjs.org ↗